#include <RF24Mesh.h>

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

Public Member Functions
RF24Mesh
The mesh library and class documentation is currently in active development and usage may change.
	ESBMesh (radio_t &_radio, network_t &_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

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 ()

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.

bool	releaseAddress (uint16_t address)

Detailed Description

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

Template Parameters

network_t	The `network` object's type. Defaults to `RF24Network` 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.

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 71 of file RF24Mesh.h.

Constructor & Destructor Documentation

◆ ESBMesh()

template<class network_t , class radio_t >

ESBMesh< network_t, radio_t >::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: v2.0 supports nrf_to_nrf Arduino library for nrf52 chips' internal radio.

Parameters

_radio	The underlying radio driver instance
_network	The underlying network instance

Definition at line 14 of file RF24Mesh.cpp.

Member Function Documentation

◆ begin()

template<class network_t , class radio_t >

bool ESBMesh< network_t, radio_t >::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 26 of file RF24Mesh.cpp.

◆ update()

template<class network_t , class radio_t >

uint8_t ESBMesh< network_t, radio_t >::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 63 of file RF24Mesh.cpp.

◆ write() [1/2]

template<class network_t , class radio_t >

bool ESBMesh< network_t, radio_t >::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 114 of file RF24Mesh.cpp.

◆ setNodeID()

template<class network_t , class radio_t >

void ESBMesh< network_t, radio_t >::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

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

Definition at line 456 of file RF24Mesh.cpp.

◆ renewAddress()

template<class network_t , class radio_t >

uint16_t ESBMesh< network_t, radio_t >::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 322 of file RF24Mesh.cpp.

◆ DHCP()

template<class network_t , class radio_t >

void ESBMesh< network_t, radio_t >::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.

Definition at line 550 of file RF24Mesh.cpp.

◆ getNodeID()

template<class network_t , class radio_t >

int16_t ESBMesh< network_t, radio_t >::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 234 of file RF24Mesh.cpp.

◆ checkConnection()

template<class network_t , class radio_t >

bool ESBMesh< network_t, radio_t >::checkConnection ( )

Tests connectivity of this node to the mesh.

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

The current behavior will only ping this node's parent to validate connection to mesh. Previously, this function would validate connection by looking up this node's assigned address with the master node's RF24Mesh::addrList. The old behavior can be mandated by changing RF24MESH_CONN_CHECK_TYPE in RF24Mesh_config.h, although a large mesh network might suffer a performance cost using the old behavior.

Returns

True if connected.
False if not connected, mesh is not responding, or this node is the master node.

Definition at line 155 of file RF24Mesh.cpp.

◆ releaseAddress() [1/2]

template<class network_t , class radio_t >

bool ESBMesh< network_t, radio_t >::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 291 of file RF24Mesh.cpp.

◆ getAddress()

template<class network_t , class radio_t >

int16_t ESBMesh< network_t, radio_t >::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 196 of file RF24Mesh.cpp.

◆ write() [2/2]

template<class network_t , class radio_t >

bool ESBMesh< network_t, radio_t >::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 103 of file RF24Mesh.cpp.

◆ setChannel()

template<class network_t , class radio_t >

void ESBMesh< network_t, radio_t >::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 137 of file RF24Mesh.cpp.

◆ setChild()

template<class network_t , class radio_t >

void ESBMesh< network_t, radio_t >::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 147 of file RF24Mesh.cpp.

◆ setCallback()

template<class network_t , class radio_t >

void ESBMesh< network_t, radio_t >::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

meshCallback The name of a function to call. This function should consume no required input parameters.

Definition at line 641 of file RF24Mesh.cpp.

◆ setAddress()

template<class network_t , class radio_t >

void ESBMesh< network_t, radio_t >::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 473 of file RF24Mesh.cpp.

◆ saveDHCP()

template<class network_t , class radio_t >

void ESBMesh< network_t, radio_t >::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 535 of file RF24Mesh.cpp.

◆ loadDHCP()

template<class network_t , class radio_t >

void ESBMesh< network_t, radio_t >::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 511 of file RF24Mesh.cpp.

◆ setStaticAddress()

template<class network_t , class radio_t >

void ESBMesh< network_t, radio_t >::setStaticAddress	(	uint8_t	nodeID,
		uint16_t	address )

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

Definition at line 465 of file RF24Mesh.cpp.

◆ releaseAddress() [2/2]

template<class network_t , class radio_t >

bool ESBMesh< network_t, radio_t >::releaseAddress ( uint16_t address )

Releases the specified address if leased to a mesh node's ID.

This is specific to master nodes, so network administrators can manage assigned addresses without notifying the nodes that might be appropriating them.

Parameters

address The address to release from any mesh node.

Returns: True if successfully released, otherwise false.

Definition at line 307 of file RF24Mesh.cpp.

Member Data Documentation

◆ mesh_address

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

uint16_t ESBMesh< network_t, radio_t >::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 217 of file RF24Mesh.h.

◆ _nodeID

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

uint8_t ESBMesh< network_t, radio_t >::_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 321 of file RF24Mesh.h.

◆ addrList

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

addrListStruct* ESBMesh< network_t, radio_t >::addrList

A array of addrListStruct elements for assigned addresses.

See also: addrListStruct class reference

Definition at line 350 of file RF24Mesh.h.

◆ addrListTop

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

uint8_t ESBMesh< network_t, radio_t >::addrListTop

The number of entries in the addrListStruct of assigned addresses.

Definition at line 352 of file RF24Mesh.h.

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

Classes

Public Member Functions

Public Attributes

Advanced Operation

Address list struct

Detailed Description

Constructor & Destructor Documentation

◆ ESBMesh()

Member Function Documentation

◆ begin()

◆ update()

◆ write() [1/2]

◆ setNodeID()

◆ renewAddress()

◆ DHCP()

◆ getNodeID()

◆ checkConnection()

◆ releaseAddress() [1/2]

◆ getAddress()

◆ write() [2/2]

◆ setChannel()

◆ setChild()

◆ setCallback()

◆ setAddress()

◆ saveDHCP()

◆ loadDHCP()

◆ setStaticAddress()

◆ releaseAddress() [2/2]

Member Data Documentation

◆ mesh_address

◆ _nodeID

◆ addrList

◆ addrListTop