ESBNetwork class¶

typedef ESBNetwork<RF24> RF24Network¶

A type definition of the template class ESBNetwork to maintain backward compatibility.

RF24 radio(7, 8);

RF24Network network(radio);
// is equivalent to
ESBNetwork<RF24> network(radio);

template<class radio_t = RF24> class ESBNetwork¶

Template Parameters:¶

class radio_t = RF24 ¶: 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.

ESBNetwork::ESBNetwork(radio_t &_radio)¶

Construct the network

v2.0 supports a backward compatible constructor:

RF24 radio(7, 8);
RF24Network network(radio); // for nRF24L01

nrf_to_nrf radio1;
RF52Network network(radio1); // for nRF52xxx family

See also

v2.0 supports nrf_to_nrf Arduino library for nrf52 chips’ internal radio.

Parameters:

radio_t &_radio¶: The underlying radio driver instance

Basic API¶

inline void ESBNetwork::begin(uint16_t _node_address)¶

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.

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

Note

Node addresses are specified in Octal format, see RF24Network Addressing for more information. The address 04444 is reserved for RF24Mesh usage (when a mesh node is connecting to the network).

Warning

Be sure to first call RF24::begin() to initialize the radio properly.

Parameters:

uint16_t _node_address¶: The logical address of this node.

See Also

RF24::begin()

uint8_t ESBNetwork::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.

Returns:: Returns the RF24NetworkHeader::type of the last received payload.

bool ESBNetwork::available(void)¶

Test whether there is a message available for this node

Returns:: Whether there is a message available for this node

uint16_t ESBNetwork::read(RF24NetworkHeader &header, void *message, uint16_t maxlen = MAX_PAYLOAD_SIZE)¶

Read a message

Note

This function assumes there is a frame in the queue.

while (network.available()) {
  RF24NetworkHeader header;
  uint32_t time;
  uint16_t msg_size = network.peek(header);
  if (header.type == 'T') {
    network.read(header, &time, sizeof(time));
    Serial.print("Got time: ");
    Serial.println(time);
  }
}

Parameters:

RF24NetworkHeader &header¶: [out] The RF24NetworkHeader (envelope) of this message
void *message¶: [out] Pointer to memory where the message should be placed
uint16_t maxlen = MAX_PAYLOAD_SIZE ¶: The largest message size which can be held in message . If this parameter is left unspecified, the entire length of the message is fetched. Hint: Use peek(RF24NetworkHeader &) to get the length of next available message in the queue.

Returns:

The total number of bytes copied into message

bool ESBNetwork::write(RF24NetworkHeader &header, const void *message, uint16_t len)¶

Send a message

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

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.

Parameters:

RF24NetworkHeader &header¶: [inout] The 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.
const void *message¶: Pointer to memory where the message is located
uint16_t len¶: The size of the message

Returns:

Whether the message was successfully received

uint16_t ESBNetwork::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.

Parameters:

RF24NetworkHeader &header¶: [out] The RF24NetworkHeader (envelope) of the next message. If there is no message available, the referenced header object is not touched

Returns:

The length of the next available message in the queue.

void ESBNetwork::peek(RF24NetworkHeader &header, void *message, uint16_t maxlen = MAX_PAYLOAD_SIZE)¶

Read the next available payload

Reads the next available payload without advancing to the next incoming message. Useful for doing a transparent packet manipulation layer on top of RF24Network.

Parameters:

RF24NetworkHeader &header¶: [out] The RF24NetworkHeader (envelope) of this message
void *message¶: [out] Pointer to memory where the message should be placed
uint16_t maxlen = MAX_PAYLOAD_SIZE ¶: Amount of bytes to copy to message . If this parameter is left unspecified, the entire length of the message is fetched. Hint: Use peek(RF24NetworkHeader) to get the length of next available message in the queue.

Advanced API¶

void ESBNetwork::failures(uint32_t *_fails, uint32_t *_ok)¶

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

bool fails, success;
network.failures(&fails, &success);

Note

This needs to be enabled via #define ENABLE_NETWORK_STATS in RF24Network_config.h

bool ESBNetwork::multicast(RF24NetworkHeader &header, const void *message, uint16_t len, uint8_t level = 7)¶

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:

RF24NetworkHeader &header¶: reference to the RF24NetworkHeader object used for this message
const void *message¶: Pointer to memory where the message is located
uint16_t len¶: The size of the message
uint8_t level = 7¶: Multicast level to broadcast to. If this parameter is unspecified, then the node’s current multicastLevel() is used.

Returns:

Whether the message was successfully sent

bool ESBNetwork::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 ESBNetwork::sleepNode(unsigned int cycles, int interruptPin, uint8_t INTERRUPT_MODE = 0)¶

Sleep this node - For AVR devices only

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

An interrupt - usually triggered by the radio receiving a payload. Must use pin 2 (interrupt 0) or 3 (interrupt 1) on Uno, Nano, etc.
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); // Sleep 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 )

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

Note

The watchdog timer should be configured in the sketch’s setup() if using sleep mode. This function will sleep the node, with the radio still active in receive mode. See setup_watchdog().

Parameters:

unsigned int cycles¶

The node will sleep in cycles of 1s. Using 2 will sleep 2 WDT cycles, 3 sleeps 3WDT cycles…

int interruptPin¶

The interrupt number to use (0, 1) for pins 2 and 3 on Uno & Nano. More available on Mega etc. Setting this parameter to 255 will disable interrupt wake-ups.

uint8_t INTERRUPT_MODE = 0¶

an identifying number to indicate what type of state for which the interrupt_pin will be used to wake up the radio.

`INTERRUPT_MODE`	type of state
0	LOW
1	RISING
2	FALLING
3	CHANGE

Returns:

True if sleepNode completed normally, after the specified number of cycles. False if sleep was interrupted

uint16_t ESBNetwork::parent() const¶

This node’s parent address

Returns:: This node’s parent address, or 65535 (-1 when casted to a signed int16_t) if this is the master node.

uint16_t ESBNetwork::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 ESBNetwork::is_valid_address(uint16_t node)¶

Validate a network address as a proper logical address

Remark

This function will validate an improper address of 0100 as it is the reserved NETWORK_MULTICAST_ADDRESS used for multicasted messages.

Note

Addresses are specified in octal form, ie 011, 034. Review RF24Network addressing for more information.

Parameters:

uint16_t node¶: The specified logical address of a network node.

Returns:

True if the specified node address is a valid network address, otherwise false.

Configuration API¶

bool ESBNetwork::multicastRelay¶

Enabling this will allow this node to automatically forward received multicast frames to the next highest multicast level. Forwarded frames will also be enqueued on the forwarding node as a received frame.

This is disabled by default.

See also

multicastLevel()

uint32_t ESBNetwork::txTimeout¶

Network timeout value.

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

Note

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

uint16_t ESBNetwork::routeTimeout¶

Timeout for routed payloads.

This only affects payloads that are routed through 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.

void ESBNetwork::multicastLevel(uint8_t level)¶

By default, multicast addresses are divided into 5 network levels:

The master node is the only node on level 0 (the lowest level)
Nodes 01-05 (level 1) share a multicast address
Nodes 0n1-0n5 (level 2) share a multicast address
Nodes 0n11-0n55 (level 3) share a multicast address
Nodes 0n111-0n555 (level 4) share a multicast address

Notice “n” (used in the list above) stands for an octal digit in range [0, 5]

This optional function is used to override the default level set when a node’s logical address changes, and it can be used to create custom multicast groups that all share a single address.

See also

Parameters:

uint8_t level¶: Levels 0 to 4 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.

void ESBNetwork::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:

uint8_t prescalar¶: The WDT prescaler to define how often the node will wake up. When defining sleep mode cycles, this time period is 1 cycle.

External Applications/Systems¶

Interface for External Applications and Systems (RF24Mesh, RF24Ethernet)

uint8_t ESBNetwork::frame_buffer[MAX_FRAME_SIZE]¶

The raw system frame buffer.

This member can be accessed to retrieve the latest received data just after it is enqueued. This buffer is also used for outgoing data.

Note

The first 8 bytes of this buffer is latest handled frame’s RF24NetworkHeader data.

Warning

Conditionally, this buffer may only contain fragments of a message (either outgoing or incoming).

std::queue<RF24NetworkFrame> ESBNetwork::external_queue¶

Linux platforms only

Data with a header type of EXTERNAL_DATA_TYPE will be loaded into a separate queue. The data can be accessed as follows:

RF24NetworkFrame f;
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();
}

RF24NetworkFrame *ESBNetwork::frag_ptr¶

ARDUINO platforms only

The frag_ptr is only used with Arduino (not RPi/Linux) and is mainly used for external data systems like RF24Ethernet. When a payload of type EXTERNAL_DATA_TYPE is received, and returned from 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.

uint8_t return_type = network.update();
if(return_type == EXTERNAL_DATA_TYPE) {
    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.

See also

RF24NetworkFrame

bool ESBNetwork::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 ESBNetwork::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_FAST_FRAG	4 (bit 2 asserted)	INTERNAL: Replaces the fastFragTransfer variable, and allows for faster transfers between directly connected nodes.
FLAG_NO_POLL	8 (bit 3 asserted)	EXTERNAL/USER: Disables NETWORK_POLL responses on a node-by-node basis.

Note

Bit posistions 0 & 1 in the networkFlags byte are no longer used as they once were during experimental development.

Protected Members¶

These members are accessible by ESBNetwork derivatives.

uint8_t ESBNetwork::_multicast_level¶

The current node’s network level (used for multicast TX/RX-ing).

See also

Use multicastLevel() to adjust this when needed.

uint16_t ESBNetwork::node_address¶: Logical node address of this unit, typically in range [0, 2925] (that’s [0, 05555] in octal).

Note

The values 0 represents the network master node. Additionally, the value 1 is occupied when using RF24Ethernet layer.