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.

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