RF24Network API

New in version 2.1.0.

See Also

Documentation for:

  1. Network Topology

  2. Shared Networking API

  3. Network Data Structures

  4. Network Constants

RF24NetworkRoutingOnly class

class circuitpython_nrf24l01.rf24_network.RF24NetworkRoutingOnly(spi: SPI, csn_pin: DigitalInOut, ce_pin: DigitalInOut, node_address: int, spi_frequency=10000000)[source]

A minimal Networking implementation for nodes that are meant for strictly routing data amidst a network of nodes.

This class is a minimal variant of the RF24Network class. The API is almost identical to RF24Network except that it has no RF24Network.write() or RF24Network.send() functions. This is meant to be the python equivalent to TMRh20’s DISABLE_USER_PAYLOADS macro in the C++ RF24Network library.

Parameters:
node_address: int

The octal int for this node’s Logical Address

See Also

For all other parameters’ descriptions, see the RF24 class’ constructor documentation.

RF24Network class

class circuitpython_nrf24l01.rf24_network.RF24Network(spi: SPI, csn_pin: DigitalInOut, ce_pin: DigitalInOut, node_address: int, spi_frequency=10000000)[source]

Bases: RF24NetworkRoutingOnly

The object used to instantiate the nRF24L01 as a network node.

Parameters:
node_address: int

The octal int for this node’s Logical Address

See Also

For all other parameters’ descriptions, see the RF24 class’ constructor documentation.

Basic API

property RF24Network.node_address : int

The node’s Logical Address.

Setting this attribute will alter

  1. The Physical Addresses used on the radio’s data pipes

  2. The parent attribute

  3. The multicast_level attribute’s default value.

Warning

  1. If this attribute is set to an invalid network Logical Address, then nothing is done and the invalid address is ignored.

  2. A RF24Mesh object cannot set this attribute because the Logical Address is assigned by the mesh network’s master node. Therefore, this attribute is read-only for RF24Mesh objects.

    See Also

    Please review the tip documented in RF24Mesh.node_id for more details.

RF24Network.update() → int

This function is used to keep the network layer current.

Important

It is imperative that this function be called at least once during the application’s main loop. For applications that perform long operations on each iteration of its main loop, it is encouraged to call this function more than once when possible.

Returns:

The latest received message’s message_type. The returned value is not gotten from frame’s in the queue, but rather it is only gotten from the messages handled during the function’s operation.

RF24Network.available() → bool
Returns:

A bool describing if there is a frame waiting in the queue.

RF24Network.peek() → RF24NetworkFrame | None

Get (from queue) the next available frame.

Returns:

A RF24NetworkFrame object. However, the data returned is not removed from the queue. If there is nothing in the queue, this method will return None.

RF24Network.read() → RF24NetworkFrame | None

Get (from queue) the next available frame.

This function differs from peek() because this function also removes the header & message from the queue.

Returns:

A RF24NetworkFrame object. If there is nothing in the queue, this method will return None.

RF24Network.send(header: RF24NetworkHeader, message: bytes | bytearray) → bool[source]

Deliver a message according to the header information.

Parameters:
header : RF24NetworkHeader

The outgoing frame’s header. It is important to have the header’s to_node attribute set to the target network node’s Logical Address.

message : bytes,bytearray

The outgoing frame’s message.

Note

Be mindful of the message’s size as this cannot exceed MAX_FRAG_SIZE (24 bytes) if fragmentation is disabled. If fragmentation is enabled (it is by default), then the message’s size must be less than max_message_length

Returns:

A bool describing if the message has been transmitted. This does not necessarily describe if the message has been received at its target destination.

Tip

To ensure a message has been delivered to its target destination, set the frame’s header’s message_type to an int in range [65, 127]. This will invoke a NETWORK_ACK response message.

Advanced API

RF24Network.multicast(message: bytes | bytearray, message_type: str | int, level: int | None = None) → bool

Broadcast a message to all nodes on a certain network level.

Parameters:
message: bytes | bytearray

The outgoing frame’s message.

message_type: str | int

The outgoing frame’s message_type.

level: int | None = None

The network level of nodes to broadcast to. If this optional parameter is not specified, then the node’s multicast_level is used.

See Also

multicast_level, multicast_relay, and allow_multicast

Returns:

A bool describing if the message has been transmitted. This does not necessarily describe if the message has been received at its target destination.

Note

For multicasted messages, the radio’s auto_ack feature is not used.

This function will always return True if a message is directed to a node’s pipe that does not have auto_ack enabled (which will likely be pipe 0 in most network contexts).

Tip

To ensure a message has been delivered to its target destination, set the header’s message_type to an int in range [65, 127]. This will invoke a NETWORK_ACK response message.

RF24Network.write(frame: RF24NetworkFrame, traffic_direct: int = 56) → bool[source]

Deliver a network frame.

Hint

This function can be used to transmit entire frames accumulated in a user-defined FrameQueue object.

from circuitpython_nrf24l01.network.structs import FrameQueue, RF24NetworkFrame, RF24NetworkHeader

my_q = FrameQueue()
for i in range(my_q.max_queue_size):
    my_q.enqueue(
        RF24NetworkFrame(
            RF24NetworkHeader(0, "1"), bytes(range(i + 5))
        )
    )

# when it's time to send the queue
while len(my_q):
    # let `nrf` be the instantiated RF24Network object
    nrf.write(my_q.dequeue())
Parameters:
frame: RF24NetworkFrame

The complete frame to send. It is important to have the header’s to_node attribute set to the target network node’s address.

traffic_direct: int = 56

The specified direction of the frame. By default, this will invoke the automatic routing mechanisms. However, this parameter can be set to a network node’s Logical Address for direct transmission to the specified node - meaning the transmission’s automatic routing will begin at the network node that is specified with this parameter instead of being automatically routed from the actual origin of the transmission.

Returns:

  • True if the frame has been transmitted. This does not necessarily describe if the message has been received at its target destination.

  • False if the frame has failed to transmit.

Note

This function will always return True if the traffic_direct parameter is set to anything other than its default value. Using the traffic_direct parameter assumes there is a reliable/open connection to the node_address passed to traffic_direct.

Tip

To ensure a message has been delivered to its target destination, set the frame’s header’s message_type to an int in range [65, 127]. This will invoke a NETWORK_ACK response message.

property RF24Network.parent : int

Get address for the parent node (read-only).

Returns 0 if called on the network’s master node.

Configuration API

RF24Network.max_message_length : int

The maximum length of a frame’s message.

By default this is set to 144. If a network node is driven by the TMRh20 RF24Network library on a ATTiny-based board, set this to 72 (as per TMRh20’s RF24Network library default behavior).

Configuring the fragmentation attribute will automatically change the value that max_message_length attribute is set to.

property RF24Network.fragmentation : bool

Enable/disable (True/False) the message fragmentation feature.

Changing this attribute’s state will also appropriately changes the type of FrameQueue (or FrameQueueFrag) object used for storing incoming network packets. Disabling fragmentation can save some memory (not as much as TMRh20’s RF24Network library’s DISABLE_FRAGMENTATION macro), but max_message_length will be limited to 24 bytes (MAX_FRAG_SIZE) maximum. Enabling this attribute will set max_message_length attribute to 144 bytes.

property RF24Network.multicast_relay : bool

Enabling this attribute will automatically forward received multicasted frames to the next highest network level.

Forwarded frames will also be enqueued on the forwarding node as a received frame.

property RF24Network.multicast_level : int

Override the default multicasting network level which is set by the node_address attribute.

Setting this attribute will also change the physical address on the radio’s RX data pipe 0.

See Also

The network levels are explained in more detail on the topology document.

RF24Network.allow_multicast : bool

enable/disable (True/False) multicasting

This attribute affects

RF24Network.tx_timeout : int

The timeout (in milliseconds) to wait for successful transmission.

Defaults to 25.

RF24Network.route_timeout : int

The timeout (in milliseconds) to wait for transmission’s NETWORK_ACK.

Defaults to 75.