Newly Optimized RF24Network Layer  v1.0.7
2014-2015 - Optimized RF24 Network Layer for NRF24L01 radios
Classes | List of all members
RF24Network Class Reference

2014-2015 - Optimized Network Layer for RF24 Radios More...

#include <RF24Network.h>

Public Member Functions

Primary Interface

These are the main methods you need to operate the network

 RF24Network (RF24 &_radio)
 Construct the network. More...
 
void begin (uint16_t _node_address)
 Bring up the network using the current radio frequency/channel. More...
 
uint8_t update (void)
 Main layer loop. More...
 
bool available (void)
 Test whether there is a message available for this node. More...
 
uint16_t peek (RF24NetworkHeader &header)
 Read the next available header. More...
 
uint16_t read (RF24NetworkHeader &header, void *message, uint16_t maxlen)
 Read a message. More...
 
bool write (RF24NetworkHeader &header, const void *message, uint16_t len)
 Send a message. More...
 
Advanced Operation

For advanced operation of the network

void failures (uint32_t *_fails, uint32_t *_ok)
 Return the number of failures and successes for all transmitted payloads, routed or sent directly. More...
 
bool multicast (RF24NetworkHeader &header, const void *message, uint16_t len, uint8_t level)
 Send a multicast message to multiple nodes at once Allows messages to be rapidly broadcast through the network. More...
 
bool write (RF24NetworkHeader &header, const void *message, uint16_t len, uint16_t writeDirect)
 Writes a direct (unicast) payload. More...
 
bool sleepNode (unsigned int cycles, int interruptPin)
 Sleep this node - For AVR devices only. More...
 
uint16_t parent () const
 This node's parent address. More...
 
uint16_t addressOfPipe (uint16_t node, uint8_t pipeNo)
 Provided a node address and a pipe number, will return the RF24Network address of that child pipe for that node. More...
 
bool is_valid_address (uint16_t node)
 
Deprecated

Maintained for backwards compatibility

void begin (uint8_t _channel, uint16_t _node_address)
 Bring up the network on a specific radio frequency/channel. More...
 

Advanced Configuration

For advanced configuration of the network

bool multicastRelay
 Enabling this will allow this node to automatically forward received multicast frames to the next highest multicast level. More...
 
uint32_t txTimeout
 Network timeout value. More...
 
uint16_t routeTimeout
 This only affects payloads that are routed by one or more nodes. More...
 
 RF24Network (RF24 &_radio, RF24 &_radio1)
 Construct the network in dual head mode using two radio modules. More...
 
void multicastLevel (uint8_t level)
 By default, multicast addresses are divided into levels. More...
 
void setup_watchdog (uint8_t prescalar)
 Set up the watchdog timer for sleep mode using the number 0 through 10 to represent the following time periods:
wdt_16ms = 0, wdt_32ms, wdt_64ms, wdt_128ms, wdt_250ms, wdt_500ms, wdt_1s, wdt_2s, wdt_4s, wdt_8s. More...
 

External Applications/Systems

Interface for External Applications and Systems ( RF24Mesh, RF24Ethernet )

uint8_t frame_buffer [MAX_FRAME_SIZE]
 The raw system frame buffer of received data. More...
 
RF24NetworkFramefrag_ptr
 Linux
Data with a header type of EXTERNAL_DATA_TYPE will be loaded into a separate queue. More...
 
bool returnSysMsgs
 Variable to determine whether update() will return after the radio buffers have been emptied (DEFAULT), or whether to return immediately when (most) system types are received. More...
 
uint8_t networkFlags
 Network Flags allow control of data flow. More...
 

Detailed Description

2014-2015 - Optimized Network Layer for RF24 Radios

This class implements an OSI Network Layer using nRF24L01(+) radios driven by RF24 library.

Constructor & Destructor Documentation

RF24Network::RF24Network ( RF24 &  _radio)

Construct the network.

Parameters
_radioThe underlying radio driver instance
RF24Network::RF24Network ( RF24 &  _radio,
RF24 &  _radio1 
)

Construct the network in dual head mode using two radio modules.

Note
Not working on RPi. Radios will share MISO, MOSI and SCK pins, but require separate CE,CS pins.
RF24 radio(7,8);
RF24 radio1(4,5);
RF24Network(radio.radio1);
Parameters
_radioThe underlying radio driver instance
_radio1The second underlying radio driver instance

Member Function Documentation

void RF24Network::begin ( uint16_t  _node_address)
inline

Bring up the network using the current radio frequency/channel.

Calling begin brings up the network, and configures the address, which designates the location of the node within RF24Network topology.

Note
Node addresses are specified in Octal format, see RF24Network Addressing for more information.
Warning
Be sure to 'begin' the radio first.

Example 1: Begin on current radio channel with address 0 (master node)

network.begin(00);

Example 2: Begin with address 01 (child of master)

network.begin(01);

Example 3: Begin with address 011 (child of 01, grandchild of master)

network.begin(011);
See also
begin(uint8_t _channel, uint16_t _node_address )
Parameters
_node_addressThe logical address of this node
uint8_t RF24Network::update ( void  )

Main layer loop.

This function must be called regularly to keep the layer going. This is where payloads are re-routed, received, and all the action happens.

See also
Returns
Returns the type of the last received payload.
bool RF24Network::available ( void  )

Test whether there is a message available for this node.

Returns
Whether there is a message available for this node
uint16_t RF24Network::peek ( RF24NetworkHeader header)

Read the next available header.

Reads the next available header without advancing to the next incoming message. Useful for doing a switch on the message type

If there is no message available, the header is not touched

Parameters
[out]headerThe header (envelope) of the next message
uint16_t RF24Network::read ( RF24NetworkHeader header,
void *  message,
uint16_t  maxlen 
)

Read a message.

while ( network.available() ) {
uint32_t time;
network.peek(header);
if(header.type == 'T'){
network.read(header,&time,sizeof(time));
Serial.print("Got time: ");
Serial.println(time);
}
}
Parameters
[out]headerThe header (envelope) of this message
[out]messagePointer to memory where the message should be placed
maxlenThe largest message size which can be held in message
Returns
The total number of bytes copied into message
bool RF24Network::write ( RF24NetworkHeader header,
const void *  message,
uint16_t  len 
)

Send a message.

Note
RF24Network now supports fragmentation for very long messages, send as normal. Fragmentation may need to be enabled or configured by editing the RF24Network_config.h file. Default max payload size is 120 bytes.
uint32_t time = millis();
uint16_t to = 00; // Send to master
RF24NetworkHeader header(to, 'T'); // Send header type 'T'
network.write(header,&time,sizeof(time));
Parameters
[in,out]headerThe header (envelope) of this message. The critical thing to fill in is the to_node field so we know where to send the message. It is then updated with the details of the actual header sent.
messagePointer to memory where the message is located
lenThe size of the message
Returns
Whether the message was successfully received
void RF24Network::multicastLevel ( uint8_t  level)

By default, multicast addresses are divided into levels.

Nodes 1-5 share a multicast address, nodes n1-n5 share a multicast address, and nodes n11-n55 share a multicast address.

This option is used to override the defaults, and create custom multicast groups that all share a single address.
The level should be specified in decimal format 1-6

See also
multicastRelay
Parameters
levelLevels 1 to 6 are available. All nodes at the same level will receive the same messages if in range. Messages will be routed in order of level, low to high by default, with the master node (00) at multicast Level 0
void RF24Network::setup_watchdog ( uint8_t  prescalar)

Set up the watchdog timer for sleep mode using the number 0 through 10 to represent the following time periods:
wdt_16ms = 0, wdt_32ms, wdt_64ms, wdt_128ms, wdt_250ms, wdt_500ms, wdt_1s, wdt_2s, wdt_4s, wdt_8s.

setup_watchdog(7); // Sets the WDT to trigger every second
Parameters
prescalarThe WDT prescaler to define how often the node will wake up. When defining sleep mode cycles, this time period is 1 cycle.
void RF24Network::failures ( uint32_t *  _fails,
uint32_t *  _ok 
)

Return the number of failures and successes for all transmitted payloads, routed or sent directly.

Note
This needs to be enabled via #define ENABLE_NETWORK_STATS in RF24Network_config.h
bool fails, success;
network.failures(&fails,&success);
bool RF24Network::multicast ( RF24NetworkHeader header,
const void *  message,
uint16_t  len,
uint8_t  level 
)

Send a multicast message to multiple nodes at once Allows messages to be rapidly broadcast through the network.

Multicasting is arranged in levels, with all nodes on the same level listening to the same address Levels are assigned by network level ie: nodes 01-05: Level 1, nodes 011-055: Level 2

See also
multicastLevel
multicastRelay
Parameters
messagePointer to memory where the message is located
lenThe size of the message
levelMulticast level to broadcast to
Returns
Whether the message was successfully sent
bool RF24Network::write ( RF24NetworkHeader header,
const void *  message,
uint16_t  len,
uint16_t  writeDirect 
)

Writes a direct (unicast) payload.

This allows routing or sending messages outside of the usual routing paths. The same as write, but a physical address is specified as the last option. The payload will be written to the physical address, and routed as necessary by the recipient

bool RF24Network::sleepNode ( unsigned int  cycles,
int  interruptPin 
)

Sleep this node - For AVR devices only.

Note
NEW - Nodes can now be slept while the radio is not actively transmitting. This must be manually enabled by uncommenting the #define ENABLE_SLEEP_MODE in RF24Network_config.h
Setting the interruptPin to 255 will disable interrupt wake-ups
The watchdog timer should be configured in setup() if using sleep mode. This function will sleep the node, with the radio still active in receive mode.

The node can be awoken in two ways, both of which can be enabled simultaneously:

  1. An interrupt - usually triggered by the radio receiving a payload. Must use pin 2 (interrupt 0) or 3 (interrupt 1) on Uno, Nano, etc.
  2. The watchdog timer waking the MCU after a designated period of time, can also be used instead of delays to control transmission intervals.
    if(!network.available()){ network.sleepNode(1,0); } //Sleeps the node for 1 second or a payload is received
    Other options:
    network.sleepNode(0,0); // Sleep this node for the designated time period, or a payload is received.
    network.sleepNode(1,255); // Sleep this node for 1 cycle. Do not wake up until then, even if a payload is received ( no interrupt )
    See also
    setup_watchdog()
    Parameters
    cyclesThe node will sleep in cycles of 1s. Using 2 will sleep 2 WDT cycles, 3 sleeps 3WDT cycles...
    interruptPinThe interrupt number to use (0,1) for pins two and three on Uno,Nano. More available on Mega etc.
    Returns
    True if sleepNode completed normally, after the specified number of cycles. False if sleep was interrupted
uint16_t RF24Network::parent ( ) const

This node's parent address.

Returns
This node's parent address, or -1 if this is the base
uint16_t RF24Network::addressOfPipe ( uint16_t  node,
uint8_t  pipeNo 
)

Provided a node address and a pipe number, will return the RF24Network address of that child pipe for that node.

bool RF24Network::is_valid_address ( uint16_t  node)
Note
Addresses are specified in octal: 011, 034
Returns
True if a supplied address is valid
void RF24Network::begin ( uint8_t  _channel,
uint16_t  _node_address 
)

Bring up the network on a specific radio frequency/channel.

Note
Use radio.setChannel() to configure the radio channel

Example 1: Begin on channel 90 with address 0 (master node)

network.begin(90,0);

Example 2: Begin on channel 90 with address 01 (child of master)

network.begin(90,01);

Example 3: Begin on channel 90 with address 011 (child of 01, grandchild of master)

network.begin(90,011);
Parameters
_channelThe RF channel to operate on
_node_addressThe logical address of this node

Member Data Documentation

bool RF24Network::multicastRelay

Enabling this will allow this node to automatically forward received multicast frames to the next highest multicast level.

Duplicate frames are filtered out, so multiple forwarding nodes at the same level should not interfere. Forwarded payloads will also be received.

See also
multicastLevel
uint32_t RF24Network::txTimeout

Network timeout value.

Note
: This value is automatically assigned based on the node address to reduce errors and increase throughput of the network.

Sets the timeout period for individual payloads in milliseconds at staggered intervals. Payloads will be retried automatically until success or timeout Set to 0 to use the normal auto retry period defined by radio.setRetries()

uint16_t RF24Network::routeTimeout

This only affects payloads that are routed by one or more nodes.

This specifies how long to wait for an ack from across the network. Radios sending directly to their parent or children nodes do not utilize this value.Timeout for routed payloads

uint8_t RF24Network::frame_buffer[MAX_FRAME_SIZE]

The raw system frame buffer of received data.

RF24NetworkFrame* RF24Network::frag_ptr

Linux
Data with a header type of EXTERNAL_DATA_TYPE will be loaded into a separate queue.

The data can be accessed as follows:

while(network.external_queue.size() > 0){
f = network.external_queue.front();
uint16_t dataSize = f.message_size;
//read the frame message buffer
memcpy(&myBuffer,&f.message_buffer,dataSize);
network.external_queue.pop();
}

ARDUINO
The frag_ptr is only used with Arduino (not RPi/Linux) and is mainly used for external data systems like RF24Ethernet. When an EXTERNAL_DATA payload type is received, and returned from network.update(), the frag_ptr will always point to the starting memory location of the received frame.
This is used by external data systems (RF24Ethernet) to immediately copy the received data to a buffer, without using the user-cache.

See also
RF24NetworkFrame
uint8_t return_type = network.update();
if(return_type == EXTERNAL_DATA_TYPE){
uint16_t size = network.frag_ptr->message_size;
memcpy(&myDataBuffer,network.frag_ptr->message_buffer,network.frag_ptr->message_size);
}

Linux devices (defined as RF24_LINUX) currently cache all payload types, and do not utilize frag_ptr.

bool RF24Network::returnSysMsgs

Variable to determine whether update() will return after the radio buffers have been emptied (DEFAULT), or whether to return immediately when (most) system types are received.

As an example, this is used with RF24Mesh to catch and handle system messages without loading them into the user cache.

The following reserved/system message types are handled automatically, and not returned.

System Message Types
(Not Returned)
NETWORK_ADDR_RESPONSE
NETWORK_ACK
NETWORK_PING
NETWORK_POLL
(With multicast enabled)
NETWORK_REQ_ADDRESS
uint8_t RF24Network::networkFlags

Network Flags allow control of data flow.

Incoming Blocking: If the network user-cache is full, lets radio cache fill up. Radio ACKs are not sent when radio internal cache is full.
This behaviour may seem to result in more failed sends, but the payloads would have otherwise been dropped due to the cache being full.

FLAGS Value Description
FLAG_HOLD_INCOMING1(bit_1) INTERNAL: Set automatically when a fragmented payload will exceed the available cache
FLAG_BYPASS_HOLDS2(bit_2) EXTERNAL: Can be used to prevent holds from blocking. Note: Holds are disabled & re-enabled by RF24Mesh when renewing addresses. This will cause data loss if incoming data exceeds the available cache space
FLAG_FAST_FRAG4(bit_3) INTERNAL: Replaces the fastFragTransfer variable, and allows for faster transfers between directly connected nodes.
FLAG_NO_POLL8(bit_4) EXTERNAL/USER: Disables NETWORK_POLL responses on a node-by-node basis.