From bc0147e70457add4750de9ffc7ae3e173cb6add5 Mon Sep 17 00:00:00 2001
From: Brendan <2bndy5@gmail.com>
Date: Fri, 28 Jun 2024 16:23:55 -0700
Subject: [PATCH] expose new release_address() for master nodes

per nRF24/RF24Mesh#244
---
 circuitpython_nrf24l01/rf24_mesh.py | 21 +++++++++++++++++----
 docs/network_docs/mesh_api.rst      | 21 +++++++++++++++++----
 2 files changed, 34 insertions(+), 8 deletions(-)

diff --git a/circuitpython_nrf24l01/rf24_mesh.py b/circuitpython_nrf24l01/rf24_mesh.py
index 6caa5bd..cb92b9f 100644
--- a/circuitpython_nrf24l01/rf24_mesh.py
+++ b/circuitpython_nrf24l01/rf24_mesh.py
@@ -333,10 +333,7 @@ def update(self) -> int:
                     self.frame_buf.message = bytes([ret_val])
                 self._write(self.frame_buf.header.to_node, TX_NORMAL)
             elif msg_t == MESH_ADDR_RELEASE:
-                for n_id, addr in self.dhcp_dict.items():
-                    if addr == self.frame_buf.header.from_node:
-                        del self.dhcp_dict[n_id]
-                        break
+                self.release_address(self.frame_buf.header.from_node)
             self._dhcp()
         return msg_t
 
@@ -435,6 +432,22 @@ def print_details(self, dump_pipes: bool = False, network_only: bool = False):
         if dump_pipes:
             self._rf24.print_pipes()
 
+    def release_address(self, address: int = 0) -> bool:
+        """Release an assigned address from any corresponding mesh node's ID.
+
+        .. important::
+            This function is meant for use on master nodes. If the ``address``
+            parameter is not specified, then
+            `RF24MeshNoMaster.release_address()` is called.
+        """
+        if not address:
+            return super().release_address()
+        for id, addr in self.dhcp_dict.items():
+            if addr == address:
+                del self.dhcp_dict[id]
+                return True
+        return False
+
     def lookup_address(self, node_id: Optional[int] = None) -> int:
         """Convert a node's unique ID number into its corresponding
         :ref:`Logical Address <Logical Address>`."""
diff --git a/docs/network_docs/mesh_api.rst b/docs/network_docs/mesh_api.rst
index b1f1544..6005962 100644
--- a/docs/network_docs/mesh_api.rst
+++ b/docs/network_docs/mesh_api.rst
@@ -31,6 +31,15 @@ RF24MeshNoMaster class
     .. seealso:: For all parameters' descriptions, see the
         :py:class:`~circuitpython_nrf24l01.rf24.RF24` class' constructor documentation.
 
+.. automethod:: circuitpython_nrf24l01.rf24_mesh.RF24MeshNoMaster.release_address
+
+    .. 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.
+
+    :returns: `True` if the address was released, otherwise `False`.
+
 
 RF24Mesh class
 **************
@@ -170,10 +179,14 @@ Advanced API
 
 .. automethod:: circuitpython_nrf24l01.rf24_mesh.RF24Mesh.release_address
 
-    .. 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.
+    :param address: The address to release.
+    :returns: `True` if the address was released, otherwise `False`.
+
+    .. versionadded:: 2.2.0
+        Allows master nodes to forcibly release an assigned address.
+
+        This function is essentially an overload of `RF24MeshNoMaster.release_address()`
+        specifically designed for use on a master node.
 
 .. autoproperty:: circuitpython_nrf24l01.rf24_mesh.RF24Mesh.allow_children