RF24Mesh - Automated Networking for nrf24L01 radios v1.1.8
TMRh20 2020 - A user friendly mesh overlay for sensor neworks using RF24Network
No Matches
Classes | Public Attributes | List of all members
RF24Mesh Class Reference

#include <RF24Mesh.h>


struct  addrListStruct
 A struct for storing a nodeID and an address in a single element of the RF24Mesh::addrList array. More...

Public Member Functions


The mesh library and class documentation is currently in active development and usage may change.

 RF24Mesh (RF24 &_radio, RF24Network &_network)
bool begin (uint8_t channel=MESH_DEFAULT_CHANNEL, rf24_datarate_e data_rate=RF24_1MBPS, uint32_t timeout=MESH_RENEWAL_TIMEOUT)
uint8_t update ()
bool write (const void *data, uint8_t msg_type, size_t size, uint8_t nodeID=0)
void setNodeID (uint8_t nodeID)
uint16_t renewAddress (uint32_t timeout=MESH_RENEWAL_TIMEOUT)
 Reconnect to the mesh and renew the current RF24Network address.
void DHCP ()

Methods provided for backwards compatibility with old/testing code.

void setStaticAddress (uint8_t nodeID, uint16_t address)

Public Attributes

uint8_t _nodeID
Address list struct

helping members for managing the list of assigned addresses

See also
the addrListStruct struct reference
 A array of addrListStruct elements for assigned addresses.
uint8_t addrListTop
 The number of entries in the addrListStruct of assigned addresses.

Advanced Operation

For advanced configuration and usage of the mesh

uint16_t mesh_address
int16_t getNodeID (uint16_t address=MESH_BLANK_ID)
bool checkConnection ()
bool releaseAddress ()
int16_t getAddress (uint8_t nodeID)
 Convert a nodeID into an RF24Network address.
bool write (uint16_t to_node, const void *data, uint8_t msg_type, size_t size)
 Write to a specific node by RF24Network address.
void setChannel (uint8_t _channel)
void setChild (bool allow)
void setCallback (void(*meshCallback)(void))
void setAddress (uint8_t nodeID, uint16_t address, bool searchBy=false)
void saveDHCP ()
void loadDHCP ()

Detailed Description

RF24Mesh_Example.cpp, RF24Mesh_Example.ino, RF24Mesh_Example_Master.cpp, RF24Mesh_Example_Master.ino, RF24Mesh_Example_Node2Node.ino, RF24Mesh_Example_Node2NodeExtra.ino, RF24Mesh_Ncurses_Master.cpp, and RF24Mesh_SerialConfig.ino.

Definition at line 59 of file RF24Mesh.h.

Constructor & Destructor Documentation

◆ RF24Mesh()

RF24Mesh::RF24Mesh ( RF24 &  _radio,
RF24Network &  _network 

Construct the mesh:

RF24 radio(7, 8);
RF24Network network(radio);
RF24Mesh mesh(radio, network);
_radioThe underlying radio driver instance
_networkThe underlying network instance

Definition at line 16 of file RF24Mesh.cpp.

Member Function Documentation

◆ begin()

bool RF24Mesh::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.


This may take a few moments to complete.

The following parameters are optional:

channelThe radio channel (0 - 125). Default is 97.
data_rateThe data rate (RF24_250KBPS, RF24_1MBPS, RF24_2MBPS). Default is RF24_1MBPS.
timeoutHow long to attempt address renewal in milliseconds. Default is 7500.

Definition at line 28 of file RF24Mesh.cpp.

◆ update()

uint8_t RF24Mesh::update ( )

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


Definition at line 64 of file RF24Mesh.cpp.

◆ write() [1/2]

bool RF24Mesh::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.

Including the nodeID parameter will result in an automatic address lookup being performed.
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.
dataSend any type of data of any length (maximum length determined by RF24Network layer).
msg_typeThe user-defined (1 - 127) message header_type to send. Used to distinguish between different types of data being transmitted.
sizeThe size of the data being sent
nodeIDOptional: The nodeID of the recipient if not sending to master.
True if success; false if failed

Definition at line 117 of file RF24Mesh.cpp.

◆ setNodeID()

void RF24Mesh::setNodeID ( uint8_t  nodeID)

Set a unique nodeID for this node.

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

If using RF24Gateway and/or RF24Ethernet, nodeIDs 0 & 1 are used by the master node.
nodeIDCan be any unique value ranging from 1 to 255 (reserving 0 for the master node).

Definition at line 404 of file RF24Mesh.cpp.

◆ renewAddress()

uint16_t RF24Mesh::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).

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.
timeoutHow long to attempt address renewal in milliseconds. Default is 7500
The newly assigned RF24Network address. If the connecting process fails, then MESH_DEFAULT_ADDRESS is returned because all consciously unconnected nodes use that address.

Definition at line 273 of file RF24Mesh.cpp.

◆ DHCP()

void RF24Mesh::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.

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

Definition at line 493 of file RF24Mesh.cpp.

◆ getNodeID()

int16_t RF24Mesh::getNodeID ( uint16_t  address = MESH_BLANK_ID)

Convert an RF24Network address into a nodeId.

addressIf no address is provided, returns the local nodeID, otherwise a lookup request is sent to the master node
The unique identifier of the node in the range [1, 255] or -1 if node was not found.

Definition at line 205 of file RF24Mesh.cpp.

◆ checkConnection()

bool RF24Mesh::checkConnection ( )

Tests connectivity of this node to the mesh.

If this function fails, address renewal should typically be done.
1 if connected, 0 if mesh not responding

Definition at line 155 of file RF24Mesh.cpp.

◆ releaseAddress()

bool RF24Mesh::releaseAddress ( )

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

Nodes should ensure that addresses are released successfully prior to going offline.
True if successfully released, otherwise false.

Definition at line 259 of file RF24Mesh.cpp.

◆ getAddress()

int16_t RF24Mesh::getAddress ( uint8_t  nodeID)

Convert a nodeID into an RF24Network address.

If printing or displaying the address, it needs to be converted to octal format:
Serial.println(address, OCT);

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

nodeIDThe unique identifier of the node in the range [1, 255].
The RF24Network address of the node, -2 if successful but not in list, -1 if failed.

Definition at line 168 of file RF24Mesh.cpp.

◆ write() [2/2]

bool RF24Mesh::write ( uint16_t  to_node,
const void *  data,
uint8_t  msg_type,
size_t  size 

Write to a specific node by RF24Network address.

Definition at line 107 of file RF24Mesh.cpp.

◆ setChannel()

void RF24Mesh::setChannel ( uint8_t  _channel)

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

_channelThe value passed to RF24::setChannel()

Definition at line 139 of file RF24Mesh.cpp.

◆ setChild()

void RF24Mesh::setChild ( bool  allow)

Allow child nodes to discover and attach to this node.

allowTrue to allow children, False to prevent children from attaching automatically.

Definition at line 148 of file RF24Mesh.cpp.

◆ setCallback()

void RF24Mesh::setCallback ( void(*)(void)  meshCallback)

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;
meshCallbackThe name of a function to call. This function should consume no required input parameters.

Definition at line 583 of file RF24Mesh.cpp.

◆ setAddress()

void RF24Mesh::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);
nodeIDThe nodeID to assign
addressThe octal RF24Network address to assign
searchByOptional parameter. Default is search by nodeID and set the address. True allows searching by address and setting nodeID.

Definition at line 419 of file RF24Mesh.cpp.

◆ saveDHCP()

void RF24Mesh::saveDHCP ( )

Save the addrList to a binary file named "dhcplist.txt".

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

Definition at line 479 of file RF24Mesh.cpp.

◆ loadDHCP()

void RF24Mesh::loadDHCP ( )

Load the addrList from a binary file named "dhcplist.txt".

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

Definition at line 456 of file RF24Mesh.cpp.

◆ setStaticAddress()

void RF24Mesh::setStaticAddress ( uint8_t  nodeID,
uint16_t  address 
For backward compatibility with older code. Use the synonymous setAddress() instead.

Definition at line 412 of file RF24Mesh.cpp.

Member Data Documentation

◆ mesh_address

uint16_t RF24Mesh::mesh_address

The assigned RF24Network (Octal) address of this node

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

Definition at line 192 of file RF24Mesh.h.

◆ _nodeID

uint8_t RF24Mesh::_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.

Definition at line 296 of file RF24Mesh.h.

◆ addrList

addrListStruct* RF24Mesh::addrList

A array of addrListStruct elements for assigned addresses.

See also
addrListStruct class reference

Definition at line 325 of file RF24Mesh.h.

◆ addrListTop

uint8_t RF24Mesh::addrListTop

The number of entries in the addrListStruct of assigned addresses.

Definition at line 327 of file RF24Mesh.h.

The documentation for this class was generated from the following files: