RF24Mesh API¶

RF24MeshNoMaster class¶

class circuitpython_nrf24l01.rf24_mesh.RF24MeshNoMaster(spi, csn_pin, ce_pin, node_id, spi_frequency=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’ contructor documentation.

RF24Mesh class¶

class circuitpython_nrf24l01.rf24_mesh.RF24Mesh(spi, csn_pin, ce_pin, node_id, spi_frequency=10000000)[source]¶

Bases: circuitpython_nrf24l01.rf24_mesh.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’ contructor documentation.

Basic API¶

RF24Mesh.send(to_node: int, message_type, message) → 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

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.

message_type : str,int

The int that describes the frame header’s message_type.

to_node_id : int

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

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.node_id¶

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: int = 7.5)¶

Connect to the mesh network and request a new node_address.

Parameters

timeout : float,int

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

• If successful: The node_address that was set to the newly assigned Logical Address.

• If unsuccessful: None, and the node_address attribute will be set to NETWORK_DEFAULT_ADDR (0o4444 in octal or 2340 in decimal).

Advanced API¶

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

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

Parameters

address : int

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: Optional[int] = None) → int[source]¶

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

Parameters

node_id : int

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, message) → bool¶

Send a message to a network node_address.

Parameters

to_node_address : 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 : str,int

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() → bool¶

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

RF24Mesh.release_address() → bool¶

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.

RF24Mesh.allow_children¶

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

RF24Mesh.block_less_callback¶

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().

RF24Mesh.dhcp_dict¶

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.

• The keys in this dict are the unique node_id of a mesh network node.

• The values in this dict (corresponding to each key) are the node_address assigned to the node_id.

RF24Mesh.save_dhcp(filename: str = 'dhcp.json')[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

The name of the json file to be used. This value should end in a “.json”

RF24Mesh.load_dhcp(filename: str = 'dhcp.json')[source]¶

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

Parameters

filename : str

The name of the json file to be used. This value should end in a “.json”

Warning

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

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

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