RF24Mesh API

RF24Mesh class

class pyrf24.RF24Mesh

Basic RF24Mesh API

__init__(radio: RF24, network: RF24Network)

Create a RF24Mesh object.

Parameters:
radio : RF24

The RF24 object used to control the radio.

network : RF24Network

The RF24Network object used to provide the base networking layer.

begin(channel: int = 97, data_rate: rf24_datarate_e = RF24_1MBPS, timeout: int = 7500) bool
Parameters:
channel : int

The channel to use for the network.

data_rate : rf24_datarate_e

The data_rate to use for the network.

timeout : int

The timeout to use when connecting to the mesh network. This value is equivalent to the timeout parameter in renew_address()

Returns:

True if the radio’s hardware was properly initalized and the node successfully connected to the mesh network.

See Also

Use renew_address() in the event that the node becomes disconnected from the mesh network.

update() int

Keep the mesh network layer current. This function should be called regularly in the application. For applications that have a long-running operations in 1 “loop”/iteration, then it is advised to call this function more than once.

Returns:

the int of the last received header’s type

write(buf: bytes | bytearray, message_type: int, to_node_id: int = 0) bool
write(to_node_address: int, buf: bytes | bytearray, message_type: int) bool
Parameters:
buf : bytes,bytearray

The message to transmit.

message_type : int

The type to be used in the frame’s header.

Returns:

True if the message was successfully sent, otherwise False

Transmit a message to a unique node_id of a mesh network node, use the following parameter:

Parameters:
to_node_id : int

The destination node’s unique node_id. If this parameter is not specified, then the message is sent to the mesh network’s master node.

When the network node’s Logical Address is already known, use the following parameter:

Parameters:
to_node_address : int

The destination node’s Logical Address.

node_id

The instantiated RF24Mesh object’s unique identifying number. This value must range [0, 255].

renew_address(timeout: int = 7500) int

Attempt to get a new Logical Address assigned from the mesh network’s master node.

Parameters:
timeout : int

The maximum amount of time (in milliseconds) spent while attempting to communicate with the mesh network’s master node.

Returns:
  • If successful, this function returns the newly assigned Logical Address.

  • If unsuccessful, the returned integer will be the default address used by any node not connected to the mesh network. This default address is 0o4444 (or 2340 in decimal).

Advanced RF24Mesh API

check_connection() bool

Check for connectivity with the mesh network.

See Also

Use renew_address() to reconnect to the mesh network.

Returns:

True if connected, otherwise False

mesh_address

The assigned Logical Address (in octal) given to the node by the mesh network’s master node.

release_address() bool
release_address(address: int) bool

Use this function from a child node (without a parameter) to manually expire a leased Logical Address from the mesh network’s master node.

Tip

This function allows re-use of the assigned address for other mesh network nodes. Call this function from mesh network nodes that are going offline (or to sleep).

Returns:
  • True if the mesh network’s master node received the request to de-allocate the assigned address.

  • False means the wireless transaction did not complete.

When called from the master node, this function takes a parameter and returns without using wireless transactions.

Hint

This overloaded function signature is specific to master nodes, so network administrators can manage assigned Logical Addresses without notifying the nodes that might be appropriating them.

Parameters:
address: int

The Logical Address to release from any mesh node.

Returns:
  • True if successfully released the specified address.

  • False if the specified address was not assigned to any child node.

get_node_id(address: int = 0xFFFF) int

Translates a node_id into the corresponding mesh_address

Parameters:
address : int

The Logical Address for which to the node_id is assigned.

Returns:
  • A positive int that represents the assigned address.

  • A negative int that represents a transaction failure.

    • -1 means the given does not have an assigned node_id.

    • -2 means the mesh network’s master node could not be reached to fetch the data.

get_address(node_id: int) int

Translates a node_id into the corresponding mesh_address

Parameters:
node_id : int

The identifying number of the mesh node for which to fetch the corresponding node_address.

Returns:
  • A positive int that represents the assigned address.

  • A negative int that represents a transaction failure.

    • -1 means the node_id does not have an assigned address.

    • -2 means the mesh network’s master node could not be reached to fetch the data.

set_address(node_id: int, address: int, search_by_address: bool = False)

Only call this function on a mesh network’s master node to manually assign a logical address to a unique node_id. This function is meant to include RF24Network nodes in mesh networks’ addr_list list.

# Set a static address for node 0o2, with nodeID 23, since it will just be
# a static routing node for example running on an ATTiny chip.
mesh.setAddress(23, 0o2);
# Change or set the nodeID for an existing address
address = 0o12;
mesh.setAddress(3, address, True);
Parameters:
node_id : int

The unique identifying number for the connected node.

address : int

The Logical Address for the connected node.

search_by_address : bool

Set this parameter to True traverse the list of assigned addresses by address. The default value of False traverses the list of assigned addresses by node_id.

set_channel(channel: int)

This function controls the radio’s configured channel (AKA frequency).

Parameters:
channel : int

The desired channel to be used for the network.

set_child(allow: bool)

Control the node’s ability to have child nodes connect to it.

Parameters:
allow : bool

Allow or disallow (True/False) the instantiated mesh network node to respond to other mesh network nodes attempting to connect to the network.

addr_list

The read-only attribute returns a list of addresses assigned to nodes’ ID numbers. Each element is a AddrListStruct object. This attribute should only be used on the master node.

Important

Altering any values for elements contained in this list is prohibited. Use set_address() instead.

AddrListStruct class

The properties of this class are read-only because they can only be set by the master node upon successful connection to a child node.

Hint

The AddrListStruct class supports the python “magic method” repr(). So, you can easily pass an instantiated AddrListStruct object to the print() function.

class pyrf24.AddrListStruct
node_id

This (read-only) int attribute represents a node’s unique ID number.

address

This (read-only) int represents the assigned Logical Address corresponding to the AddrListStruct.node_id.

Mesh Constants

These are the pre-defined constants provided for convenience and code readability.

pyrf24.MESH_DEFAULT_ADDRESS = 2340

A reserved valid address for use with RF24Mesh (when a mesh node requests an assigned address)

Reserved System Message Types

pyrf24.MESH_ADDR_LOOKUP = 196

This message type is used to fetch (from the master node) an allocated Logical Address (mesh_address) corresponding to specified a mesh node’s node_id.

This is exclusively used by get_address().

pyrf24.MESH_ID_LOOKUP = 198

This message type is used to fetch (from the master node) a mesh node’s node_id corresponding to an specified Logical Address (mesh_address).

This is exclusively used by get_node_id().

pyrf24.MESH_ADDR_RELEASE = 197

This message type is used when mesh nodes are consciously disconnecting from the network. It is used to unassign the Logical Address allocated the mesh node’s node_id.

This is exclusively used by release_address().