Skip to content

Commit

Permalink
update check_connection()
Browse files Browse the repository at this point in the history
  • Loading branch information
2bndy5 committed Jun 28, 2024
1 parent c3ce23c commit 685ced7
Show file tree
Hide file tree
Showing 2 changed files with 41 additions and 6 deletions.
22 changes: 16 additions & 6 deletions circuitpython_nrf24l01/rf24_mesh.py
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@
NETWORK_DEFAULT_ADDR,
NETWORK_MULTICAST_ADDR,
NETWORK_POLL,
NETWORK_PING,
MESH_ADDR_RELEASE,
MESH_ADDR_LOOKUP,
MESH_ID_LOOKUP,
Expand Down Expand Up @@ -162,14 +163,23 @@ def _lookup_2_master(self, number: int, lookup_type: int) -> int:
return struct.unpack("<H", self.frame_buf.message[:2])[0]
return self.frame_buf.message[0]

def check_connection(self, attempts: int = 3) -> bool:
def check_connection(self, attempts: int = 3, ping_master: bool = False) -> bool:
"""Check for network connectivity (not for use on master node)."""
if not self._parent:
return True
if self.node_address == NETWORK_DEFAULT_ADDR:
return False
for _ in range(attempts):
result = self.lookup_address(self._id)
if result in (-2, 0):
return False
if result == self.node_address:
return True
if ping_master:
result = self.lookup_address(self._id)
if result == -2:
return False
if result == self.node_address:
return True

Check warning on line 178 in circuitpython_nrf24l01/rf24_mesh.py

View check run for this annotation

Codecov / codecov/patch

circuitpython_nrf24l01/rf24_mesh.py#L168-L178

Added lines #L168 - L178 were not covered by tests
else: # ping parent
result = self.write(self._parent, NETWORK_PING, b"")
if result:
return True
return False

Check warning on line 183 in circuitpython_nrf24l01/rf24_mesh.py

View check run for this annotation

Codecov / codecov/patch

circuitpython_nrf24l01/rf24_mesh.py#L180-L183

Added lines #L180 - L183 were not covered by tests

def update(self) -> int:
Expand Down
25 changes: 25 additions & 0 deletions docs/network_docs/mesh_api.rst
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,31 @@ Advanced API

.. automethod:: circuitpython_nrf24l01.rf24_mesh.RF24Mesh.check_connection

:param attempts: The number of attempts to test for active connection to the mesh network.
:param ping_master: 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.

.. versionchanged:: 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.

.. automethod:: circuitpython_nrf24l01.rf24_mesh.RF24Mesh.release_address

:param address: The address to release.
Expand Down

0 comments on commit 685ced7

Please sign in to comment.