A Python module that wraps the RF24Network C++ library’s API
- class pyrf24.rf24_network.RF24Network¶
Basic RF24Network API¶
- __init__(radio: RF24)¶
Create a RF24Network object.
- begin(node_address: int)¶
- begin(channel: int, node_address: int) None
Give the instantiated network node a Logical Address.
- 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.
- 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:
The frame’s message size (not including the 8-byte header saved to the
To fetch the next available frame received by the network node, the parameter and return type is as follows:
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.
write(header: RF24NetworkHeader, buf: bytes | bytearray, write_direct: int =
0o70) bool ¶
Send an outgoing frame over the network.
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.
- header : RF24NetworkHeader¶
The outgoing frame’s header. The only value of this object that is not overridden by this function is the
- 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
This function will always return
Trueas 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.
intvalue (in milliseconds) to ensure a frame is properly sent. Defaults to 25.
intvalue (in milliseconds) used to wait for a Network ACK message. Defaults to 75.
External Systems or Applications¶
When this attribute is enabled, the following system messages are not returned because they are handled internally.
With multicast enabled (which is enabled by default)
There’s a more complete list (with behavioral descriptions) of the Reserved System Message Types.
A 4-bit integer used to indicate special system behavior. Currently only bit positions 2 and 3 are used.
4 (bit 2 asserted)
INTERNAL: Allows for faster transfers between directly connected nodes.
8 (bit 3 asserted)
NETWORK_POLLresponses on a node-by-node basis.
- class pyrf24.rf24_network.RF24NetworkHeader¶
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.
The sequential identifying number of the frame. This is not incremented on fragmented messages (see
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
The following are predefined module-level constants that can be used for comparisons and code readability.
The maximum of user defined message types.
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
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.
NETWORK_ADDR_RESPONSEtype 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.
Messages of type
NETWORK_PINGwill be dropped automatically by the recipient. A
NETWORK_ACKor automatic radio-ack will indicate to the sender whether the payload was successful. The time it takes to successfully send a
NETWORK_PINGis the round-trip-time.
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.
Messages of this type designate the first of two or more message fragments, and will be re-assembled automatically.
Messages of this type indicate a fragmented payload with two or more message fragments.
Messages of this type indicate the last fragment in a sequence of message fragments. Messages of this type do not receive a
Messages of this type signal the sender that a network-wide transmission has been completed.
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_ACKcan fail (despite successful transmission of the message).
NETWORK_ACKmessages can be utilized as a traffic/flow control mechanism. Transmitting nodes that emit
NETWORK_ACKqualifying 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_ACKis not required. This is because the radio’s auto-ack feature is utilized for connections between directly related network nodes. For example: nodes
0o11use the radio’s auto-ack feature for transmissions between them, but nodes
0o2do 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).
Remember, user messages types with a decimal value of
64or less will not be acknowledged across the network via
NETWORK_ACKmessages are only sent by the last node in the route to a target node. ie: When node
0o0sends an instigating message to node
0o1will send the
0o0upon successful delivery of instigating message to node
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.
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¶
This flag (when asserted in
network_flags) prevents repetitively configuring the radio during transmission of fragmented messages.