RF24Network API

RF24Network class

class pyrf24.RF24Network

Basic RF24Network API

__init__(radio: RF24)

Create a RF24Network object.

Parameters:
radio : RF24

The RF24 object used to control the radio transceiver.

begin(node_address: int)
begin(channel: int, node_address: int) None

Give the instantiated network node a Logical Address.

Parameters:
node_address : int

This is a Logical Address (typically an octal integer).

channel : int

The desired channel used by the network. Using this parameter is the deprecated form of this function.

See Also

Use channel attribute to change the radio channel.

update() int

Keep the network layer current. This function should be called regularly in the application. For applications that have a long-running operations in 1 “loop”/iteration, then it is advised to call this function more than once.

Returns:

The int of the last received header’s type

available() bool
Returns:

True if there is a frame in the queue, otherwise False.

peek(header: RF24NetworkHeader) int
peek(maxlen: int = MAX_PAYLOAD_SIZE) tuple[RF24NetworkHeader, bytearray]

To fetch the next available frame’s header received by the network node, the parameter and return type is as follows:

Parameters:
header : RF24NetworkHeader

The object to save the header information to.

Returns:

The frame’s message size (not including the 8-byte header saved to the header parameter).

To fetch the next available frame received by the network node, the parameter and return type is as follows:

Parameters:
maxlen : int

The maximum length of the message to fetch. If this parameter is unspecified or greater than the actual frame’s message size, then only the frame’s full message size is used. Defaults to MAX_PAYLOAD_SIZE.

Returns:

A 2-tuple containing the frame’s header (of type RF24NetworkHeader) and the frame’s message (of type bytearray).

read(maxlen: int = MAX_PAYLOAD_SIZE) tuple[RF24NetworkHeader, bytearray]

Fetch the next available frame received by the network node. This differs from peek() as it removes the frame from the queue.

Parameters:
maxlen : int

The maximum length of the frame’s message to be returned. If this parameter is unspecified or greater than the actual frame’s message size, then only the frame’s full message size is used. Defaults to MAX_PAYLOAD_SIZE.

Returns:

A tuple in which

write(header: RF24NetworkHeader, buf: bytes | bytearray, write_direct: int = 0o70) bool

Send an outgoing frame over the network.

Parameters:
header : RF24NetworkHeader

The outgoing frame’s RF24NetworkHeader about the outgoing message.

buf : bytes,bytearray

The outgoing frame’s message (AKA buffer).

write_direct : int

An optional parameter to route the message directly to a specified node. The default value will invoke automatic routing.

Returns:

True if the frame was successfully sent or otherwise False.

node_address

The instantiated network node’s Logical Address. This is a 2-byte integer in octal format.

Advanced RF24Network API

multicast(header: RF24NetworkHeader, buf: bytes | bytearray, level: int = 7) bool

Broadcast a message to all nodes in a network level.

Parameters:
header : RF24NetworkHeader

The outgoing frame’s header. The only value of this object that is not overridden by this function is the RF24NetworkHeader.type attribute.

buf : bytes,bytearray

The outgoing frame’s message (AKA buffer).

level : int

The network level to broadcast the message to. If this parameter is not specified, then the current network level of the instantiated node is used (see multicast_level).

Returns:

This function will always return True as multicasted messages do not use the radio’s auto-ack feature.

is_address_valid(address: int) bool

Use this function to verify if an integer can be used as a valid Logical Address for network nodes.

Parameters:
address : int

The integer to validate.

Returns:

True if the given integer is a valid Logical Address, otherwise False.

multicast_relay

This bool attribute determines if any received multicasted messages should be forwarded to the next highest network level. Defaults to False.

tx_timeout

The timeout int value (in milliseconds) to ensure a frame is properly sent. Defaults to 25.

route_timeout

The timeout int value (in milliseconds) used to wait for a Network ACK message. Defaults to 75.

multicast_level

The network level of the instantiated network node used for multicasted frames. Setting this attribute will override the default value set by begin() or node_address.

External Systems or Applications

RF24Network.return_sys_msgs

This bool attribute is used by RF24Mesh to force update() to return when handling a frame containing a system message.

When this attribute is enabled, the following system messages are not returned because they are handled internally.

Message Name

Numeric Value

Additional Context

NETWORK_ADDR_RESPONSE

128

NETWORK_ACK

193

NETWORK_PING

130

NETWORK_POLL

194

With multicast enabled (which is enabled by default)

NETWORK_REQ_ADDRESS

195

See Also

There’s a more complete list (with behavioral descriptions) of the Reserved System Message Types.

RF24Network.network_flags

A 4-bit integer used to indicate special system behavior. Currently only bit positions 2 and 3 are used.

Flags

Value

Description

FLAG_FAST_FRAG

4 (bit 2 asserted)

INTERNAL: 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.

RF24NetworkHeader class

Hint

The RF24NetworkHeader class supports the python “magic method” repr(). So, you can easily pass an instantiated RF24NetworkHeader object to the print() function.

class pyrf24.RF24NetworkHeader
to_node

The destination of the frame. This is a Logical Address (set in octal format).

type

The type of frame sent. Users are encouraged to use an integer in range [0, 127] because integers in range [128, 255] are reserved for system usage.

from_node

The origin of the frame. This is a Logical Address (set in octal format).

id

The sequential identifying number of the frame. This is not incremented on fragmented messages (see reserved attribute).

reserved

A single byte reserved for system usage. This will be the sequential identifying number for fragmented frames. On the last fragment, this attribute will contain the actual frame’s type.

to_string = <instancemethod to_string>
class property next_id

The next sequential identifying number used for the next created header’s id.

Constants

The following are predefined module-level constants that can be used for comparisons and code readability.

pyrf24.MAX_USER_DEFINED_HEADER_TYPE = 127

The maximum of user defined message types.

pyrf24.MAX_PAYLOAD_SIZE = 1514

Maximum size of fragmented network frames and fragmentation cache.

Reserved System Message Types

The network will determine whether to automatically acknowledge payloads based on their general RF24NetworkHeader.type.

  • User types (1 - 127) 1 - 64 will NOT be acknowledged

  • System types (128 - 255) 192 - 255 will NOT be acknowledged

System types can also contain message data.

pyrf24.NETWORK_ADDR_RESPONSE = 128

A NETWORK_ADDR_RESPONSE type is utilized to manually route custom messages containing a single RF24Network address.

Used by RF24Mesh

If a node receives a message of this type that is directly addressed to it, it will read the included message, and forward the payload on to the proper recipient.

This allows nodes to forward multicast messages to the master node, receive a response, and forward it back to the requester.

pyrf24.NETWORK_PING = 130

Messages of type NETWORK_PING will be dropped automatically by the recipient. A NETWORK_ACK or automatic radio-ack will indicate to the sender whether the payload was successful. The time it takes to successfully send a NETWORK_PING is the round-trip-time.

pyrf24.EXTERNAL_DATA_TYPE = 131

External data types are used to define messages that will be passed to an external data system. This allows RF24Network to route and pass any type of data, such as TCP/IP frames, while still being able to utilize standard RF24Network messages etc.

pyrf24.NETWORK_FIRST_FRAGMENT = 148

Messages of this type designate the first of two or more message fragments, and will be re-assembled automatically.

pyrf24.NETWORK_MORE_FRAGMENTS = 149

Messages of this type indicate a fragmented payload with two or more message fragments.

pyrf24.NETWORK_LAST_FRAGMENT = 150

Messages of this type indicate the last fragment in a sequence of message fragments. Messages of this type do not receive a NETWORK_ACK.

pyrf24.NETWORK_ACK = 193

Messages of this type signal the sender that a network-wide transmission has been completed.

  • Not fool-proof

    RF24Network does not directly have a built-in transport layer protocol, so message delivery is not 100% guaranteed. Messages can be lost via corrupted dynamic payloads, or a NETWORK_ACK can fail (despite successful transmission of the message).

  • Traffic analysis

    NETWORK_ACK messages can be utilized as a traffic/flow control mechanism. Transmitting nodes that emit NETWORK_ACK qualifying messages will be forced to wait, before sending additional data, until the payload is transmitted across the network and acknowledged.

  • Different from Radio ACK Packets

    In the event that the transmitting device will be sending directly to a parent or child node, a NETWORK_ACK is not required. This is because the radio’s auto-ack feature is utilized for connections between directly related network nodes. For example: nodes 0o1 and 0o11 use the radio’s auto-ack feature for transmissions between them, but nodes 0o1 and 0o2 do not use the radio’s auto-ack feature for transmissions between them as messages will be routed through other nodes.

    Multicasted messages do use the radio’s auto-ack feature because of the hardware limitations of nRF24L01 transceivers. This applies to all multicasted messages (directly related nodes or otherwise).

Hint

Remember, user messages types with a decimal value of 64 or less will not be acknowledged across the network via NETWORK_ACK messages.

Note

NETWORK_ACK messages are only sent by the last node in the route to a target node. ie: When node 0o0 sends an instigating message to node 0o11, node 0o1 will send the NETWORK_ACK message to 0o0 upon successful delivery of instigating message to node 0o11.

pyrf24.NETWORK_POLL = 194

Used by RF24Mesh.

Messages of this type are used with multi-casting, to find active/available nodes. Any node receiving a NETWORK_POLL sent to a multicast address will respond directly to the sender with a blank message, indicating the address of the available node via the header.

pyrf24.NETWORK_REQ_ADDRESS = 195

Used by RF24Mesh

Messages of this type are used to request information from the master node, generally via a unicast (direct) write. Any (non-master) node receiving a message of this type will manually forward it to the master node using a normal network write.

Network flag mnemonics

pyrf24.FLAG_FAST_FRAG = 4

This flag (when asserted in network_flags) prevents repetitively configuring the radio during transmission of fragmented messages.

pyrf24.FLAG_NO_POLL = 8

This flag (when asserted in network_flags) prevents a node from responding to mesh nodes looking to connect to the network. Calling set_child() uses this flag accordingly.