Network Data Structures

These classes are used to structure/store the payload data for wireless network transactions.

Added in version 2.1.0.

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:
to_node: int | None = None

The Logical Address designating the message’s destination.

message_type: str | int | None = None

A 1-byte int representing the message_type. If a str is passed, then the first character’s numeric ASCII representation is used.

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 a str, this attribute’s int value is derived from the ASCII number of the string’s first character (see ord()). Non-ASCII characters’ values are truncated to 1 byte (see str.isascii()). A blank str sets this attribute’s value to 0.

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 for MESH_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.

Parameters:
buffer

The buffer to unpack. All resulting data is stored in the objects attributes accordingly.

Returns:

True if successful; otherwise False.

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:
header: RF24NetworkHeader | None = None

The header describing the frame’s message.

message: bytearray | bytes | None = None

The actual message containing the payload or a fragment of a payload.

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’s message.

RF24NetworkFrame.message : bytes | bytearray

The entire message or a fragment of a message allocated to the frame.

This attribute is typically a bytearray or bytes object.

RF24NetworkFrame.unpack(buffer: bytes | bytearray) → bool[source]

Decode the header & message from a buffer.

This function is meant for library internal usage.

Parameters:
buffer: bytes | bytearray

The buffer to unpack. All resulting data is stored in the objects attributes accordingly.

Returns:

True if successful; otherwise False.

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’s max_queue_size attribute.

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.

Returns:

True if the frame was added to the queue, or False if it was not.

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 a node_address or to_node destination. Otherwise, this function returns False.

Warning

Please note that this function also allows the value 0o100 to validate because it is used as the NETWORK_MULTICAST_ADDR for multicasted messages. Technically, 0o100 is an invalid address.