RF24Network API¶
New in version 2.1.0.
See also
Documentation for:
RF24NetworkRoutingOnly class¶
-
class circuitpython_nrf24l01.rf24_network.RF24NetworkRoutingOnly(spi: busio.SPI, csn_pin: digitalio.DigitalInOut, ce_pin: digitalio.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 toRF24Network
except that it has noRF24Network.write()
orRF24Network.send()
functions. This is meant to be the python equivalent to TMRh20’sDISABLE_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: busio.SPI, csn_pin: digitalio.DigitalInOut, ce_pin: digitalio.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¶
- RF24Network.node_address : int¶
The node’s Logical Address.
Setting this attribute will alter
The Physical Addresses used on the radio’s data pipes
The
parent
attributeThe
multicast_level
attribute’s default value.
Warning
If this attribute is set to an invalid network Logical Address, then nothing is done and the invalid address is ignored.
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 forRF24Mesh
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 thequeue
, but rather it is only gotten from the messages handled during the function’s operation.
- RF24Network.peek() RF24NetworkFrame | None ¶
Get (from
queue
) the next available frame.- Returns
A
RF24NetworkFrame
object. However, the data returned is not removed from thequeue
. If there is nothing in thequeue
, this method will returnNone
.
- 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 thequeue
.- Returns
A
RF24NetworkFrame
object. If there is nothing in thequeue
, this method will returnNone
.
- 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’sto_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) iffragmentation
is disabled. Iffragmentation
is enabled (it is by default), then the message’s size must be less thanmax_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 anint
in range [65, 127]. This will invoke aNETWORK_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
- 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 haveauto_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 anint
in range [65, 127]. This will invoke aNETWORK_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 theframe
has been transmitted. This does not necessarily describe if the message has been received at its target destination.False
if theframe
has failed to transmit.
Note
This function will always return
True
if thetraffic_direct
parameter is set to anything other than its default value. Using thetraffic_direct
parameter assumes there is a reliable/open connection to thenode_address
passed totraffic_direct
.Tip
To ensure a message has been delivered to its target destination, set the frame’s header’s
message_type
to anint
in range [65, 127]. This will invoke aNETWORK_ACK
response message.
- 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 to72
(as per TMRh20’s RF24Network library default behavior).Configuring the
fragmentation
attribute will automatically change the value thatmax_message_length
attribute is set to.
- RF24Network.fragmentation : bool¶
Enable/disable (
True
/False
) the message fragmentation feature.Changing this attribute’s state will also appropriately changes the type of
FrameQueue
(orFrameQueueFrag
) object used for storing incoming network packets. Disabling fragmentation can save some memory (not as much as TMRh20’s RF24Network library’sDISABLE_FRAGMENTATION
macro), butmax_message_length
will be limited to24
bytes (MAX_FRAG_SIZE
) maximum. Enabling this attribute will setmax_message_length
attribute to144
bytes.
- 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.
- 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
) multicastingThis attribute affects
the Physical Address translation (for data pipe 0) when setting the
node_address
all incoming multicasted frames (including
multicast_relay
behavior).
- 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.