ESBMesh class¶

typedef ESBMesh<ESBNetwork<RF24>, RF24> RF24Mesh¶

A type definition of the template class ESBMesh to maintain backward compatibility.

RF24 radio(7, 8);
RF24Network network(radio);

RF24Mesh mesh(radio, network);
// is equivalent to
ESBMesh<ESBNetwork<RF24>, RF24> mesh(radio, network);

template<network_t = ESBNetwork<RF24>, radio_t = RF24> class ESBMesh¶

Template Parameters:¶

network_t

The network object’s type. Defaults to the RF24Network specialization for legacy behavior. This new abstraction is really meant for using the nRF52840 SoC as a drop-in replacement for the nRF24L01 radio. For more detail, see the nrf_to_nrf Arduino library.

radio_t

The radio object’s type. Defaults to RF24 for legacy behavior. This new abstraction is really meant for using the nRF52840 SoC as a drop-in replacement for the nRF24L01 radio. For more detail, see the nrf_to_nrf Arduino library.

ESBMesh::ESBMesh(radio_t &_radio, network_t &_network)¶

Construct the mesh.

v2.0 supports a backward compatible constructor:

RF24 radio(7, 8);
RF24Network network(radio);
RF24Mesh mesh(radio, network); // for nRF24L01

nrf_to_nrf radio1;
RF52Network network1(radio1);
RF52Mesh mesh1(network1, radio1); // for nRF52xxx family

See Also

RF24 for the radio object
RF24Network for the network object.

Basic API¶

bool ESBMesh::begin(uint8_t channel = MESH_DEFAULT_CHANNEL, rf24_datarate_e data_rate = RF24_1MBPS, uint32_t timeout = MESH_RENEWAL_TIMEOUT)¶

Call this in setup() to configure the mesh and request an address.

mesh.begin(); 

This may take a few moments to complete.

The following parameters are optional:

Parameters:

uint8_t channel = MESH_DEFAULT_CHANNEL ¶: The radio channel (0 - 125). Default is 97.
rf24_datarate_e data_rate = RF24_1MBPS ¶: The data rate (RF24_250KBPS, RF24_1MBPS, RF24_2MBPS). Default is RF24_1MBPS.
uint32_t timeout = MESH_RENEWAL_TIMEOUT ¶: How long to attempt address renewal in milliseconds. Default is 7500.

uint8_t ESBMesh::update()¶: Very similar to network.update(), it needs to be called regularly to keep the network and the mesh going.

See Also

Review RF24Network::update() for more details.

bool ESBMesh::write(const void *data, uint8_t msg_type, size_t size, uint8_t nodeID = 0)¶

Automatically construct a header and send a payload. Very similar to the standard network.write() function, which can be used directly.

Note

Including the nodeID parameter will result in an automatic address lookup being performed.

Note

Message types 1 - 64 (decimal) will NOT be acknowledged by the network, types 65 - 127 will be. Use as appropriate to manage traffic: if expecting a response, no ack is needed.

Parameters:

const void *data¶: Send any type of data of any length (maximum length determined by RF24Network layer).
uint8_t msg_type¶: The user-defined (1 - 127) message header_type to send. Used to distinguish between different types of data being transmitted.
size_t size¶: The size of the data being sent
uint8_t nodeID = 0¶: Optional: The nodeID of the recipient if not sending to master.

Returns:

True if success; false if failed

See Also

Review RF24NetworkHeader::type for more details about available message types.

uint16_t ESBMesh::renewAddress(uint32_t timeout = MESH_RENEWAL_TIMEOUT)¶

Reconnect to the mesh and renew the current RF24Network address.

This is used to re-establish a connection to the mesh network if physical location of a node or surrounding nodes has changed (or a routing node becomes unavailable).

Note

If all nodes are set to verify connectivity and reconnect at a specified period, then restarting the master (and deleting dhcplist.txt on Linux) will result in complete network/mesh re-convergence.

Parameters:

uint32_t timeout = MESH_RENEWAL_TIMEOUT ¶: How long to attempt address renewal in milliseconds. Default is 7500

Returns:

The newly assigned RF24Network address. If the connecting process fails, then MESH_DEFAULT_ADDRESS is returned because all consciously unconnected nodes use that address.

void ESBMesh::setNodeID(uint8_t nodeID)¶

Set a unique nodeID for this node.

This needs to be called before ESBMesh::begin(). The parameter value passed can be fetched via serial connection, EEPROM, etc when configuring a large number of nodes.

Note

If using RF24Gateway and/or RF24Ethernet, nodeIDs 0 & 1 are used by the master node.

Parameters:

uint8_t nodeID¶: Can be any unique value ranging from 1 to 255 (reserving 0 for the master node).

uint8_t ESBMesh::_nodeID¶

The unique identifying number used to differentiate mesh nodes’ from their assigned network address. Ideally, this is set before calling begin() or renewAddress(). It is up to the network administrator to make sure that this number is unique to each mesh/network node.

This nodeID number is typically in the range [0, 255], but remember that 0 is reserved for the master node. Other external systems may reserve other node ID numbers, for instance RF24Gateway/RF24Ethernet reserves the node ID number 1 in addition to the master node ID 0.

Advanced API¶

uint16_t ESBMesh::mesh_address¶

The assigned RF24Network (Octal) address of this node

Return:¶: An unsigned 16-bit integer containing the RF24Network address in octal format.

int16_t ESBMesh::getNodeID(uint16_t address = MESH_BLANK_ID)¶

Convert an RF24Network address into a nodeId.

Parameters:

uint16_t address = MESH_BLANK_ID ¶: If no address is provided, returns the local nodeID, otherwise a lookup request is sent to the master node

Returns:

The unique identifier of the node in the range [1, 255] or -1 if node was not found.

bool ESBMesh::checkConnection()¶

Tests connectivity of this node to the mesh.

Note

If this function fails, address renewal should typically be done.

Returns:: 1 if connected, 0 if mesh not responding

bool ESBMesh::releaseAddress()¶

Releases the currently assigned address lease. Useful for nodes that will be sleeping etc.

Note

Nodes should ensure that addresses are released successfully prior to going offline.

Returns:: True if successfully released, otherwise false.

int16_t ESBMesh::getAddress(uint8_t nodeID)¶

Convert a nodeID into an RF24Network address.

Results in a lookup request being sent to the master node.

Note

If printing or displaying the address, it needs to be converted to octal format:

Serial.println(address, OCT); 

Parameters:

uint8_t nodeID¶: The unique identifier of the node in the range [1, 255].

Returns:

The RF24Network address of the node, -2 if successful but not in list, -1 if failed.

bool ESBMesh::write(uint16_t to_node, const void *data, uint8_t msg_type, size_t size)¶: Write to a specific node by RF24Network address.

void ESBMesh::setChannel(uint8_t _channel)¶

Change the active radio channel after the mesh has been started.

Parameters:

uint8_t _channel¶: The value passed to RF24::setChannel()

See Also

RF24::setChannel()

void ESBMesh::setChild(bool allow)¶

Allow child nodes to discover and attach to this node.

Parameters:

bool allow¶: True to allow children, False to prevent children from attaching automatically.

void ESBMesh::setCallback(void (*meshCallback)(void))¶

RF24Mesh ID and Address lookups as well as address renewal can take some time. Set a callback function to enable additional processing while the mesh is working

void myCallbackFunction(){
  someValue = someOtherValue;
}
mesh.setCallback(myCallbackFunction);

Parameters:

void (*meshCallback)(void)¶: The name of a function to call. This function should consume no required input parameters.

void ESBMesh::setAddress(uint8_t nodeID, uint16_t address, bool searchBy = false)¶

Set or change a nodeID : node address (key : value) pair manually. This function is for use on the master node only.

// Set a static address for node 02, with nodeID 23, since it will just be
// a static routing node for example running on an ATTiny chip.
mesh.setAddress(23, 02);

// Change or set the nodeID for an existing address
uint16_t address = 012;
mesh.setAddress(3, address, true);

Parameters:

uint8_t nodeID¶: The nodeID to assign
uint16_t address¶: The octal RF24Network address to assign
bool searchBy = false¶: Optional parameter. Default is search by nodeID and set the address. True allows searching by address and setting nodeID.

void ESBMesh::setStaticAddress(uint8_t nodeID, uint16_t address)¶

Deprecated:: For backward compatibility with older code. Use the synonymous setAddress() instead.

void ESBMesh::DHCP()¶: This is only to be used on the master node because it manages allocation of network addresses for any requesting (non-master) node’s ID, similar to DHCP.

Warning

On master nodes, It is required to call this function immediately after calling ESBMesh::update() to ensure address requests are handled appropriately.

void ESBMesh::saveDHCP()¶: Save the addrList to a binary file named “dhcplist.txt”.

Note

This function is for use on the master node only and only on Linux or x86 platforms.

void ESBMesh::loadDHCP()¶: Load the addrList from a binary file named “dhcplist.txt”.

Note

This function is for use on the master node only and only on Linux or x86 platforms.

Address List Struct¶

addrListStruct *ESBMesh::addrList¶

A array of addrListStruct elements for assigned addresses.