Network Data Structures¶
These classes are used to structure/store the payload data for wireless network transactions.
Added in version 2.1.0.
Header¶
-
class circuitpython_nrf24l01.network.structs.RF24NetworkHeader(to_node: int | None =
None
, message_type: str | int | None =None
)[source]¶ The header information used for routing network messages.
- Parameters:
Note
These parameters can be left unspecified to create a blank object that can be augmented after instantiation.
- RF24NetworkHeader.to_node : int¶
This value is truncated to a 2-byte unsigned
int
.Describes the message destination using a Logical Address.
- RF24NetworkHeader.from_node : int¶
This value is truncated to a 2-byte unsigned
int
.Describes the message origin using a Logical Address.
- RF24NetworkHeader.message_type¶
The type of message.
This
int
must be less than 256. When set using astr
, this attribute’sint
value is derived from the ASCII number of the string’s first character (seeord()
). Non-ASCII characters’ values are truncated to 1 byte (seestr.isascii()
). A blankstr
sets this attribute’s value to0
.Hint
Users are encouraged to specify a number in range [0, 127] (basically less than or equal to
MAX_USR_DEF_MSG_TYPE
) as there are Reserved Message Types.
- RF24NetworkHeader.frame_id¶
This value is truncated to a 2-byte unsigned
int
.The sequential identifying number for the frame (relative to the originating network node). Each sequential frame’s ID is incremented, but frames containing fragmented messages have the same ID number.
- RF24NetworkHeader.reserved¶
A single byte reserved for network usage.
This will be the sequential ID number for fragmented messages, but on the last message fragment, this will be the
message_type
.RF24Mesh
will also use this attribute to hold a newly assigned network Logical Address forMESH_ADDR_RESPONSE
messages.
- RF24NetworkHeader.unpack(buffer) bool [source]¶
Decode header data from the first 8 bytes of a frame’s buffer.
This function is meant for library internal usage.
- RF24NetworkHeader.pack() bytes [source]¶
This function is meant for library internal usage.
- Returns:
The entire header as a
bytes
object.
- RF24NetworkHeader.to_string() str [source]¶
- Returns:
A
str
describing all of the header’s attributes.
Frame¶
-
class circuitpython_nrf24l01.network.structs.RF24NetworkFrame(header: RF24NetworkHeader | None =
None
, message: bytearray | bytes | None =None
)[source]¶ Structure of a single frame.
This is used for either a single fragment of an individually large message (greater than 24 bytes) or a single message that is less than 25 bytes.
- Parameters:
Note
These parameters can be left unspecified to create a blank object that can be augmented after instantiation.
- RF24NetworkFrame.header : RF24NetworkHeader¶
The
RF24NetworkHeader
about the frame’smessage
.
- RF24NetworkFrame.message : bytes | bytearray¶
The entire message or a fragment of a message allocated to the frame.
- RF24NetworkFrame.unpack(buffer: bytes | bytearray) bool [source]¶
Decode the
header
&message
from abuffer
.This function is meant for library internal usage.
- RF24NetworkFrame.pack() bytes [source]¶
This attribute is meant for library internal usage.
- Returns:
The entire object as a
bytes
object.
- RF24NetworkFrame.is_ack_type() bool [source]¶
Check if the frame is to expect a
NETWORK_ACK
message.This function is meant for library internal usage.
FrameQueue¶
-
class circuitpython_nrf24l01.network.structs.FrameQueue(queue: FrameQueue | FrameQueueFrag | None =
None
)[source]¶ A class that wraps a
list
with RF24Network Queue behavior.- Parameters:
- queue: FrameQueue | FrameQueueFrag | None =
None
¶ To move (not copy) the contents of another
FrameQueue
based object, you can pass the object to this parameter. Doing so will also copy the object’smax_queue_size
attribute.
- queue: FrameQueue | FrameQueueFrag | None =
- FrameQueue.max_queue_size : int¶
The maximum number of frames that can be enqueued at once. Defaults to 6.
- FrameQueue.enqueue(frame: RF24NetworkFrame) bool [source]¶
Add a
RF24NetworkFrame
to the queue.
- FrameQueue.dequeue() RF24NetworkFrame | None [source]¶
- Returns:
The First Out element and removes it from the queue.
- FrameQueue.peek() RF24NetworkFrame | None [source]¶
- Returns:
The First Out element without removing it from the queue.
- FrameQueue.__len__() int [source]¶
- Returns:
The number of the enqueued frames.
For use with Python’s builtin
len()
.
FrameQueueFrag¶
-
class circuitpython_nrf24l01.network.structs.FrameQueueFrag(queue: FrameQueue | FrameQueueFrag | None =
None
)[source]¶ Bases:
FrameQueue
A specialized
FrameQueue
with an additional cache for fragmented frames.Note
This class will only cache 1 fragmented message at a time. If parts of the fragmented message are missing (or duplicate fragments are received), then the fragment is discarded. If a new fragmented message is received (before a previous fragmented message is completed and reassembled), then the cache is reused for the new fragmented message to avoid memory leaks.
Logical Address Validation¶
- circuitpython_nrf24l01.network.structs.is_address_valid(address: int | None) bool [source]¶
Test if a given address is a valid Logical Address.
- Parameters:
- address: int | None¶
The Logical Address to validate.
- Returns:
True
if the given address can be used as anode_address
orto_node
destination. Otherwise, this function returnsFalse
.Warning
Please note that this function also allows the value
0o100
to validate because it is used as theNETWORK_MULTICAST_ADDR
for multicasted messages. Technically,0o100
is an invalid address.