RF24Mesh API¶
New in version 2.1.0.
See Also
Documentation for:
Shared Networking API (API common to
RF24Mesh
andRF24Network
)RF24Network API (
RF24Mesh
inherits from the same mixin class thatRF24Network
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 asRF24Mesh
class.See Also
For all parameters’ descriptions, see the
RF24
class’ constructor documentation.
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.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’sto_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 to0
(which is reserved for the master node).- message_type: int | str¶
The
int
that describes the frame header’smessage_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) iffragmentation
is disabled. Iffragmentation
is enabled (it is by default), then the message’s size must be less thanmax_message_length
.
- 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 not been transmitted.
Tip
To ensure a message has been delivered to its target destination, set the
message_type
parameter to anint
in range [65, 127]. This will invoke aNETWORK_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 samenode_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 thenode_address
is set toNETWORK_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’snode_address
.
-
RF24Mesh.renew_address(timeout: float | int =
7.5
)¶ 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.
- timeout: float | int =
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 thenode_address
attribute will be set toNETWORK_DEFAULT_ADDR
(0o4444
in octal or2340
in decimal).
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.
- address: int | None =
- Returns:
The unique
node_id
assigned to the specifiedaddress
.Error codes include
-2
means the specifiedaddress
has not been assigned a uniquenode_id
from the master node or the requesting network node’snode_address
is equal toNETWORK_DEFAULT_ADDR
.-1
means the address lookup operation failed due to no network connection or the master node has not assigned a uniquenode_id
for the specifiedaddress
.
-
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.
- node_id: int | None =
- Returns:
The Logical Address assigned to the specified
node_id
.Error codes include
-2
means the specifiednode_id
has not been assigned a Logical Address from the master node or the requesting network node’snode_address
is equal toNETWORK_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 specifiednode_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’snode_id
.- message_type: int | str¶
The
int
that describes the frame header’smessage_type
.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
.- message: bytes | bytearray¶
The frame’s
message
to be transmitted.
- 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 not been transmitted.
Tip
To ensure a message has been delivered to its target destination, set the
message_type
parameter to anint
in range [65, 127]. This will invoke aNETWORK_ACK
response message.
- 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.block_less_callback : collections.abc.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()
andlookup_node_id()
.The callback function assigned should take no positional parameters and it’s returned data (if any) is ignored. For example:
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’snode_id
.The keys in this
dict
are the uniquenode_id
of a mesh network node.The values in this
dict
(corresponding to each key) are thenode_address
assigned to thenode_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:
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:
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
andnode_address
pair in thedhcp_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 aRF24Network.node_address
.