RF24Network API¶

A Python module that wraps the RF24Network C++ library’s API

RF24Network class¶

class pyrf24.rf24_network.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

• index 0 is the frame’s RF24NetworkHeader

• index 1 is the frame’s message (as a mutable bytearray)

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¶

class pyrf24.rf24_network.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.

See Also

Reserved System Message Types

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.

rf24_network.MAX_USER_DEFINED_HEADER_TYPE = 127¶

The maximum of user defined message types.

rf24_network.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.

rf24_network.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.

rf24_network.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.

rf24_network.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.

rf24_network.NETWORK_FIRST_FRAGMENT = 148¶

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

rf24_network.NETWORK_MORE_FRAGMENTS = 149¶

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

rf24_network.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.

rf24_network.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.

rf24_network.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.

rf24_network.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¶

rf24_network.FLAG_FAST_FRAG = 4¶

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

rf24_network.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.