RF24Mesh  V1.0.3b
A user friendly mesh overlay for sensor networks using RF24Network and nRF24L01 radio modules
Classes | Public Attributes | List of all members
RF24Mesh Class Reference

#include <RF24Mesh.h>

Classes

struct  addrListStruct
 

Public Member Functions

RF24Mesh

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

 RF24Mesh (RF24 &_radio, RF24Network &_network)
 Construct the mesh: More...
 
bool 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. More...
 
uint8_t update ()
 Very similar to network.update(), it needs to be called regularly to keep the network and the mesh going. More...
 
bool 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. More...
 
void setNodeID (uint8_t nodeID)
 Set a unique nodeID for this node. More...
 
void DHCP ()
 Only to be used on the master node. More...
 

Public Attributes

uint8_t _nodeID
 
addrListStructaddrList
 See the addrListStruct class reference. More...
 
uint8_t addrListTop
 The number of entries in the assigned address list. More...
 

Advanced Operation

For advanced configuration and usage of the mesh

uint16_t mesh_address
 The assigned RF24Network (Octal) address of this node. More...
 
int16_t getNodeID (uint16_t address=MESH_BLANK_ID)
 Convert an RF24Network address into a nodeId. More...
 
bool checkConnection ()
 Tests connectivity of this node to the mesh. More...
 
uint16_t renewAddress (uint32_t timeout=MESH_RENEWAL_TIMEOUT)
 Reconnect to the mesh and renew the current RF24Network address. More...
 
bool releaseAddress ()
 Releases the currently assigned address lease. More...
 
int16_t getAddress (uint8_t nodeID)
 Convert a nodeID into an RF24Network address. More...
 
bool write (uint16_t to_node, const void *data, uint8_t msg_type, size_t size)
 Write to a specific node by RF24Network address. More...
 
void setChannel (uint8_t _channel)
 Change the active radio channel after the mesh has been started. More...
 
void setChild (bool allow)
 Allow child nodes to discover and attach to this node. More...
 
void setAddress (char nodeID, uint16_t address)
 Set/change a nodeID/RF24Network Address pair manually on the master node. More...
 
void saveDHCP ()
 
void loadDHCP ()
 

Deprecated

Methods provided for backwards compabibility with old/testing code.

void setStaticAddress (char nodeID, uint16_t address)
 Calls setAddress() More...
 

Detailed Description

Examples:
RF24Mesh_Example.cpp, RF24Mesh_Example_Master.cpp, and RF24Mesh_Ncurses_Master.cpp.

Constructor & Destructor Documentation

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

Construct the mesh:

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

Member Function Documentation

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:

Parameters
channelThe radio channel (1-127) default:97
data_rateThe data rate (RF24_250KBPS,RF24_1MBPS,RF24_2MBPS) default:RF24_1MBPS
timeoutHow long to attempt address renewal in milliseconds default:60000
Examples:
RF24Mesh_Example.cpp, RF24Mesh_Example_Master.cpp, and RF24Mesh_Ncurses_Master.cpp.
uint8_t RF24Mesh::update ( )

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

Examples:
RF24Mesh_Example.cpp, RF24Mesh_Example_Master.cpp, and RF24Mesh_Ncurses_Master.cpp.
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
dataSend any type of data of any length (Max 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
Returns
True if success, False if failed
Examples:
RF24Mesh_Example.cpp.
void RF24Mesh::setNodeID ( uint8_t  nodeID)

Set a unique nodeID for this node.

This value is stored in program memory, so is saved after loss of power.

This should be called before mesh.begin(), or set via serial connection or other methods if configuring a large number of nodes...

Note
If using RF24Gateway and/or RF24Ethernet, nodeIDs 0 & 1 are used by the master node.
Parameters
nodeIDCan be any unique value ranging from 1 to 255.
Examples:
RF24Mesh_Example.cpp, RF24Mesh_Example_Master.cpp, and RF24Mesh_Ncurses_Master.cpp.
void RF24Mesh::DHCP ( )

Only to be used on the master node.

Provides automatic configuration for sensor nodes, similar to DHCP. Call immediately after calling network.update() to ensure address requests are handled appropriately

Examples:
RF24Mesh_Example_Master.cpp, and RF24Mesh_Ncurses_Master.cpp.
int16_t RF24Mesh::getNodeID ( uint16_t  address = MESH_BLANK_ID)

Convert an RF24Network address into a nodeId.

Parameters
addressIf no address is provided, returns the local nodeID, otherwise a lookup request is sent to the master node
Returns
Returns the unique identifier (1-255) or -1 if not found.
Examples:
RF24Mesh_Example.cpp.
bool RF24Mesh::checkConnection ( )

Tests connectivity of this node to the mesh.

Note
If this function fails, the radio will be put into standby mode, and will not receive payloads until the address is renewed.
Returns
Return 1 if connected, 0 if mesh not responding after up to 1 second
Examples:
RF24Mesh_Example.cpp.
uint16_t RF24Mesh::renewAddress ( uint32_t  timeout = MESH_RENEWAL_TIMEOUT)

Reconnect to the mesh and renew the current RF24Network address.

Used to re-establish a connection to the mesh if physical location etc. has changed, or a routing node goes down.

Note
Currently times out after 1 minute if address renewal fails. Network writes should not be attempted if address renewal fails.
If all nodes are set to verify connectivity/reconnect at a specified period, leaving the master offline for this length of time should result in complete network/mesh reconvergence.
Parameters
timeoutHow long to attempt address renewal in milliseconds default:60000
Returns
Returns the newly assigned RF24Network address
Examples:
RF24Mesh_Example.cpp.
bool RF24Mesh::releaseAddress ( )

Releases the currently assigned address lease.

Useful for nodes that will be sleeping etc.

Note
Nodes should ensure that addresses are releases successfully prior to renewal.
Returns
Returns 1 if successfully released, 0 if not
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 (1-255) of the node
Returns
Returns the RF24Network address of the node or -1 if not found or lookup failed.
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.

void RF24Mesh::setChannel ( uint8_t  _channel)

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

void RF24Mesh::setChild ( bool  allow)

Allow child nodes to discover and attach to this node.

Parameters
allowTrue to allow children, False to prevent children from attaching automatically.
void RF24Mesh::setAddress ( char  nodeID,
uint16_t  address 
)

Set/change a nodeID/RF24Network Address pair manually on the master node.

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.setStaticAddress(23,02);
Parameters
nodeIDThe nodeID to assign
addressThe octal RF24Network address to assign
Returns
If the nodeID exists in the list,
void RF24Mesh::saveDHCP ( )
void RF24Mesh::loadDHCP ( )
void RF24Mesh::setStaticAddress ( char  nodeID,
uint16_t  address 
)

Calls setAddress()

Member Data Documentation

uint16_t RF24Mesh::mesh_address

The assigned RF24Network (Octal) address of this node.

Returns
Returns an unsigned 16-bit integer containing the RF24Network address in octal format
uint8_t RF24Mesh::_nodeID
addrListStruct* RF24Mesh::addrList

See the addrListStruct class reference.

Examples:
RF24Mesh_Ncurses_Master.cpp.
uint8_t RF24Mesh::addrListTop

The number of entries in the assigned address list.

Examples:
RF24Mesh_Ncurses_Master.cpp.

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