RF24Mesh API

Added in version 2.1.0.

See Also

Documentation for:

  1. Shared Networking API (API common to RF24Mesh and RF24Network)

  2. RF24Network API (RF24Mesh inherits from the same mixin class that RF24Network inherits from)

RF24MeshNoMaster class

class circuitpython_nrf24l01.rf24_mesh.RF24MeshNoMaster(spi: SPI, csn_pin: DigitalInOut, ce_pin: DigitalInOut, node_id: int, spi_frequency: int = 10000000)[source]

A descendant of the same mixin class that RF24Network inherits from. This class adds easy Mesh networking capability (non-master nodes only).

This class exists to save memory for nodes that don’t behave like mesh network master nodes. It is the python equivalent to TMRh20’s MESH_NO_MASTER macro in the C++ RF24Mesh library. All the API is the same as RF24Mesh class.

Parameters:
node_id: int

The unique identifying node_id number for the instantiated mesh node.

See Also

For all parameters’ descriptions, see the RF24 class’ constructor documentation.

RF24MeshNoMaster.release_address() → bool[source]

Forces an address lease to expire from the master.

Hint

This should be called from a mesh network node that is disconnecting from the network. This is also recommended for mesh network nodes that are entering a powered down (or sleep) mode.

Returns:

True if the address was released, otherwise False.

RF24Mesh class

class circuitpython_nrf24l01.rf24_mesh.RF24Mesh(spi: SPI, csn_pin: DigitalInOut, ce_pin: DigitalInOut, node_id: int, spi_frequency: int = 10000000)[source]

Bases: RF24MeshNoMaster

A descendant of the base class RF24MeshNoMaster that adds algorithms needed for Mesh network master nodes.

Parameters:
node_id: int

The unique identifying node_id number for the instantiated mesh node.

See Also

For all parameters’ descriptions, see the RF24 class’ constructor documentation.

Basic API

RF24Mesh.send(to_node: int, message_type: int | str, message: bytes | bytearray) → bool

Send a message to a mesh node_id.

This function will use lookup_address() to fetch the necessary Logical Address to set the frame’s header’s to_node attribute.

Hint

If you already know the destination node’s Logical Address, then you can use write() for quicker operation.

Parameters:
to_node: int

The unique mesh network node_id of the frame’s destination. Defaults to 0 (which is reserved for the master node).

message_type: int | str

The int that describes the frame header’s message_type.

message: bytes | bytearray

The frame’s message to be transmitted.

Note

Be mindful of the message’s size as this cannot exceed MAX_FRAG_SIZE (24 bytes) if fragmentation is disabled. If fragmentation is enabled (it is by default), then the message’s size must be less than max_message_length.

Returns:

  • True if the frame has been transmitted. This does not necessarily describe if the message has been received at its target destination.

  • False if the frame has not been transmitted.

Tip

To ensure a message has been delivered to its target destination, set the message_type parameter to an int in range [65, 127]. This will invoke a NETWORK_ACK response message.

property RF24Mesh.node_id : int

The unique ID number (1 byte long) of the mesh network node.

This is not to be confused with the network node’s node_address. This attribute is meant to distinguish different mesh network nodes that may, at separate instances, use the same node_address. It is up to the developer to make sure each mesh network node uses a different ID number.

Warning

Changing this attributes value after instantiation will automatically call release_address() which disconnects the node from the mesh network. Notice the node_address is set to NETWORK_DEFAULT_ADDR when consciously not connected to the mesh network.

Tip

When a mesh node becomes disconnected from the mesh network, use renew_address() to fetch (from the master node) an assigned logical address to be used as the mesh node’s node_address.

RF24Mesh.renew_address(timeout: float | int = 7.5)[source]

Connect to the mesh network and request a new node_address.

Parameters:
timeout: float | int = 7.5

The amount of time (in seconds) to continue trying to connect and get an assigned Logical Address. Defaults to 7.5 seconds.

Note

This function automatically sets the node_address accordingly.

Returns:

Advanced API

RF24Mesh.lookup_node_id(address: int | None = None) → int[source]

Convert a node’s Logical Address into its corresponding unique ID number.

Parameters:
address: int | None = None

The Logical Address for which a unique node_id is assigned from network master node.

Returns:

  • The unique node_id assigned to the specified address.

  • Error codes include

    • -2 means the specified address has not been assigned a unique node_id from the master node or the requesting network node’s node_address is equal to NETWORK_DEFAULT_ADDR.

    • -1 means the address lookup operation failed due to no network connection or the master node has not assigned a unique node_id for the specified address.

RF24Mesh.lookup_address(node_id: int | None = None) → int[source]

Convert a node’s unique ID number into its corresponding Logical Address.

Parameters:
node_id: int | None = None

The unique node_id for which a Logical Address is assigned from network master node.

Returns:

  • The Logical Address assigned to the specified node_id.

  • Error codes include

    • -2 means the specified node_id has not been assigned a Logical Address from the master node or the requesting network node’s node_address is equal to NETWORK_DEFAULT_ADDR.

    • -1 means the address lookup operation failed due to no network connection or the master node has not assigned a Logical Address for the specified node_id.

RF24Mesh.write(to_node: int, message_type: int | str, message: bytes | bytearray) → bool

Send a message to a network node_address.

Parameters:
to_node: int

The network node’s Logical Address. of the frame’s destination. This must be the destination’s network node_address which is not be confused with a mesh node’s node_id.

message_type: int | str

The int that describes the frame header’s message_type.

Note

Be mindful of the message’s size as this cannot exceed MAX_FRAG_SIZE (24 bytes) if fragmentation is disabled. If fragmentation is enabled (it is by default), then the message’s size must be less than max_message_length.

message: bytes | bytearray

The frame’s message to be transmitted.

Returns:

  • True if the frame has been transmitted. This does not necessarily describe if the message has been received at its target destination.

  • False if the frame has not been transmitted.

Tip

To ensure a message has been delivered to its target destination, set the message_type parameter to an int in range [65, 127]. This will invoke a NETWORK_ACK response message.

RF24Mesh.check_connection(attempts: int = 3, ping_master: bool = False) → bool[source]

Check for network connectivity (not for use on master node).

Parameters:
attempts: int = 3

The number of attempts to test for active connection to the mesh network.

ping_master: bool = False

If this parameter is set to True, then this function will verify the connectivity by using lookup_address() to transact with the master node. Setting this parameter to False will simply ping the node’s parent.

Warning

Setting this parameter to True can result in performance cost when used in a large mesh network. The disadvantages in such a situation are:

  • increased load on master node

  • increased network congestion

  • unreliable connectivity information when a parent or grandparent of the current node briefly loses connection.

Returns:

  • True if connected to the mesh network (or current node is the master node).

  • False if not connected to the mesh network or mesh network is unresponsive.

Changed in version 2.2.0: Added attempts and ping_master parameters; changed return value for master nodes

Previously, this function would return False when called from a master node. This was changed to return True to help avoid erroneous user code calling renew_address() on a master node.

RF24Mesh.release_address(address: int = 0) → bool[source]

Release an assigned address from any corresponding mesh node’s ID.

Important

This function is meant for use on master nodes. If the address parameter is not specified, then RF24MeshNoMaster.release_address() is called.

Parameters:
address: int = 0

The address to release.

Returns:

True if the address was released, otherwise False.

Added in version 2.2.0: Allows master nodes to forcibly release an assigned address.

This function is essentially an overload of RF24MeshNoMaster.release_address() specifically designed for use on a master node.

property RF24Mesh.allow_children : bool

Allow/disallow child node to connect to this network node.

RF24Mesh.block_less_callback : Callable[[], Any] | None

This variable can be assigned a function to perform during long operations.

Note

Requesting a new address (via renew_address()) can take a while since it sequentially attempts to get re-assigned to the first available Logical Address on the highest possible network level.

The assigned function will be called during renew_address(), lookup_address() and lookup_node_id().

The callback function assigned should take no positional parameters and it’s returned data (if any) is ignored. For example:

In user/app code space
arbitrary_global_counter = [0]

def callback_func(kw_arg: int = 1):
    arbitrary_global_counter[0] += kw_arg

# let `mesh_node` be the instantiated RF24Mesh object
mesh_node.block_less_callback = callback_func
RF24Mesh.dhcp_dict : Dict[int, int]

A dict that enables master nodes to act as a DNS.

This dict stores the assigned Logical Addresses to the connected mesh node’s node_id.

RF24Mesh.save_dhcp(filename: str = 'dhcplist.json', as_bin: bool = False)[source]

Save the dhcp_dict to a JSON file (meant for master nodes only).

Warning

This function will likely throw a OSError on boards running CircuitPython firmware because the file system is by default read-only.

Calling this function on a Linux device (like the Raspberry Pi) will save the dhcp_dict to a JSON file located in the program’s working directory.

Parameters:
filename: str = 'dhcplist.json'

The name of the json file to be used. This value should include a file extension (like “.json” or “.txt”).

as_bin: bool = False

Set this parameter to True to save the DHCP list to a binary text file. Defaults to False which saves the DHCP list as JSON syntax.

Changed in version 2.1.1: Added as_bin parameter to make use of binary text files.

RF24Mesh.load_dhcp(filename: str = 'dhcplist.json', as_bin: bool = False)[source]

Load the dhcp_dict from a JSON file (meant for master nodes only).

Parameters:
filename: str = 'dhcplist.json'

The name of the json file to be used. This value should include a file extension (like “.json” or “.txt”).

as_bin: bool = False

Set this parameter to True to load the DHCP list from a binary text file. Defaults to False which loads the DHCP list from JSON syntax.

Warning

This function will raise an OSError exception if no file exists.

Changed in version 2.1.1: Added as_bin parameter to make use of binary text files.

RF24Mesh.set_address(node_id: int, node_address: int, search_by_address: bool = False)[source]

Set/change a node_id and node_address pair in the dhcp_dict.

This function is only meant to be called on the mesh network’s master node. Use this function to manually assign a node_id to a RF24Network.node_address.

Parameters:
node_id: int

A unique identifying number ranging [1, 255].

node_address: int

A Logical Address

search_by_address: bool = False

A flag to traverse the dhcp_dict by value instead of by key.