#include <RF24Mesh.h>

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

Public Member Functions
RF24Mesh
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 ()

Deprecated
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
addrListStruct *	addrList
	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

Examples: 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);

Parameters

_radio	The underlying radio driver instance
_network	The 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.

mesh.begin();

This may take a few moments to complete.

The following parameters are optional:

Parameters

channel	The radio channel (0 - 125). Default is 97.
data_rate	The data rate (RF24_250KBPS, RF24_1MBPS, RF24_2MBPS). Default is RF24_1MBPS.
timeout	How 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.

NO_MASTER

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.

Note: 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.

Parameters

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

Returns: 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.

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

Parameters

nodeID Can 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).

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

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.

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.

Warning: 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.

Parameters

address 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.

Definition at line 205 of file RF24Mesh.cpp.

◆ checkConnection()

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

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.

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

Returns: 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.

Note: 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.

Parameters

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.

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.

Parameters

_channel The 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.

Parameters

allow True 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;
}
mesh.setCallback(myCallbackFunction);

Parameters

meshCallback The 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);

Parameters

nodeID	The nodeID to assign
address	The octal RF24Network address to assign
searchBy	Optional 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".

Note: 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".

Note: 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
	)

Deprecated:: 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

Returns: 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:

Classes

Public Member Functions

Public Attributes

Advanced Operation

Detailed Description

Constructor & Destructor Documentation

◆ RF24Mesh()

Member Function Documentation

◆ begin()

◆ update()

◆ write() [1/2]

◆ setNodeID()

◆ renewAddress()

◆ DHCP()

◆ getNodeID()

◆ checkConnection()

◆ releaseAddress()

◆ getAddress()

◆ write() [2/2]

◆ setChannel()

◆ setChild()

◆ setCallback()

◆ setAddress()

◆ saveDHCP()

◆ loadDHCP()

◆ setStaticAddress()

Member Data Documentation

◆ mesh_address

◆ _nodeID

◆ addrList

◆ addrListTop