meshcore 2.3.6__tar.gz → 2.3.8__tar.gz

meshcore-2.3.8/.github/funding.yml

@@ -0,0 +1,2 @@
+buy_me_a_coffee: fdlamotte
+github: meshcore-dev

{meshcore-2.3.6 → meshcore-2.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshcore
-Version: 2.3.6
+Version: 2.3.8
 Summary: Base classes for communicating with meshcore companion radios
 Project-URL: Homepage, https://github.com/fdlamotte/meshcore_py
 Project-URL: Issues, https://github.com/fdlamotte/meshcore_py/issues

{meshcore-2.3.6 → meshcore-2.3.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "meshcore"
-version = "2.3.6"
+version = "2.3.8"
 authors = [
   { name="Florent de Lamotte", email="florent@frizoncorrea.fr" },
   { name="Alex Wolden", email="awolden@gmail.com" },

{meshcore-2.3.6 → meshcore-2.3.8}/src/meshcore/ble_cx.py

@@ -4,6 +4,7 @@ mccli.py : CLI interface to MeschCore BLE companion app
 
 import asyncio
 import logging
+from typing import Optional
 
 
 # Make bleak optional - only fail if BLE operations are attempted
@@ -27,6 +28,11 @@ UART_RX_CHAR_UUID = "6E400002-B5A3-F393-E0A9-E50E24DCCA9E"
 UART_TX_CHAR_UUID = "6E400003-B5A3-F393-E0A9-E50E24DCCA9E"
 
 class BLEConnection:
+    # Upper bound on a single write (lock acquisition included). Healthy writes
+    # measured 0.06-0.17s against real hardware; observed stalls ran 20s to
+    # minutes, so this preempts them rather than waiting for CoreBluetooth.
+    WRITE_TIMEOUT = 10.0
+
     def __init__(self, address=None, device=None, client=None, pin=None):
         """
         Constructor: specify address or an existing BleakClient.
@@ -51,6 +57,35 @@ class BLEConnection:
         self.pin = pin
         self.rx_char = None
         self._disconnect_callback = None
+        self._background_tasks: set[asyncio.Task] = set()
+        self._write_lock_obj: Optional[asyncio.Lock] = None
+
+    @property
+    def _write_lock(self) -> asyncio.Lock:
+        """Serialises write_gatt_char().
+
+        Two overlapping writes to the same characteristic drop the link outright
+        (observed on macOS/CoreBluetooth: "BLE write failed: 19", connection
+        gone). Nothing above this layer guarantees callers are sequential --
+        schedulers, health checks and user commands all issue independently --
+        so the transport has to enforce it.
+
+        Lazily created so it binds to the running loop, mirroring the
+        _mesh_request_lock property in commands/base.py. Read through getattr so
+        an instance built without __init__ still works.
+        """
+        lock = getattr(self, "_write_lock_obj", None)
+        if lock is None:
+            lock = asyncio.Lock()
+            self._write_lock_obj = lock
+        return lock
+
+    def _spawn_background(self, coro) -> asyncio.Task:
+        """Create a tracked background task (prevents GC of fire-and-forget tasks)."""
+        task = asyncio.create_task(coro)
+        self._background_tasks.add(task)
+        task.add_done_callback(self._background_tasks.discard)
+        return task
 
     async def connect(self):
         """
@@ -116,9 +151,12 @@ class BLEConnection:
                     await self.client.pair()
                     logger.info("BLE pairing successful")
                 except Exception as e:
-                    logger.warning(f"BLE pairing failed: {e}")
-                    # Don't fail the connection if pairing fails, as the device
-                    # might already be paired or not require pairing
+                    logger.error(f"BLE pairing failed: {e}")
+                    # A failed pairing leaves the transport in a half-usable
+                    # state — re-raise so the caller gets a clean failure
+                    # instead of a silently degraded connection.
+                    await self.client.disconnect()
+                    raise
                     
         except BleakDeviceNotFoundError:
             return None
@@ -154,8 +192,19 @@ class BLEConnection:
         self.client = self._user_provided_client
         self.device = self._user_provided_device
 
+        # Re-register disconnect callback on the reset client so subsequent
+        # disconnects after a reconnect cycle are still detected.
+        if self.client is not None and hasattr(self.client, 'set_disconnected_callback'):
+            try:
+                self.client.set_disconnected_callback(self.handle_disconnect)
+            except Exception:
+                # set_disconnected_callback may not be available on all bleak
+                # versions; the next connect() call will re-create the client
+                # with the callback anyway.
+                pass
+
         if self._disconnect_callback:
-            asyncio.create_task(self._disconnect_callback("ble_disconnect"))
+            self._spawn_background(self._disconnect_callback("ble_disconnect"))
 
     def set_disconnect_callback(self, callback):
         """Set callback to handle disconnections."""
@@ -166,16 +215,44 @@ class BLEConnection:
 
     def handle_rx(self, _: BleakGATTCharacteristic, data: bytearray):
         if self.reader is not None:
-            asyncio.create_task(self.reader.handle_rx(data))
+            self._spawn_background(self.reader.handle_rx(data))
+
+    async def _write_locked(self, data):
+        async with self._write_lock:
+            await self.client.write_gatt_char(self.rx_char, bytes(data), response=True)
 
     async def send(self, data):
         if not self.client:
             logger.error("Client is not connected")
+            if self._disconnect_callback:
+                await self._disconnect_callback("ble_transport_lost")
             return False
         if not self.rx_char:
             logger.error("RX characteristic not found")
             return False
-        await self.client.write_gatt_char(self.rx_char, bytes(data), response=True)
+        # Bound the whole acquire-plus-write. A stalled write has been seen to
+        # hang for minutes, and CommandHandler's own timeout does not cover this
+        # -- it starts only after _sender_func returns -- so without a bound the
+        # serialising lock would queue every other command behind the stall
+        # indefinitely, with nothing logged and no disconnect raised. Turning one
+        # hung command into a silent whole-client stall would be worse than the
+        # overlap the lock exists to prevent.
+        try:
+            await asyncio.wait_for(self._write_locked(data), timeout=self.WRITE_TIMEOUT)
+        except asyncio.TimeoutError:
+            # Do not simply release and carry on: the underlying write may still
+            # be in flight, and a second write racing it re-creates the exact
+            # overlap that kills the link. Tear the connection down so the
+            # reconnect path takes over -- bounded and self-healing.
+            logger.warning(f"BLE write timed out after {self.WRITE_TIMEOUT}s")
+            if self._disconnect_callback:
+                await self._disconnect_callback("ble_write_timeout")
+            return False
+        except Exception as exc:
+            logger.warning(f"BLE write failed: {exc}")
+            if self._disconnect_callback:
+                await self._disconnect_callback(f"ble_write_failed: {exc}")
+            return False
 
     async def disconnect(self):
         """Disconnect from the BLE device."""

{meshcore-2.3.6 → meshcore-2.3.8}/src/meshcore/commands/base.py

@@ -57,18 +57,91 @@ def _validate_destination(dst: DestinationType, prefix_length: int = 6) -> bytes
         )
 
 
+# Size of the server-side reply_path buffer (uint8_t reply_path[64] in
+# simple_repeater/MyMesh.h). It is memcpy'd into without a length check.
+MAX_REPLY_PATH_BYTES = 64
+# reply_path_len is the low 6 bits of the header byte.
+MAX_REPLY_PATH_HOPS = 63
+
+
+def encode_reply_path(out_path_len: int, out_path_hex: str, out_path_hash_mode: int) -> bytes:
+    """Encode the reply path a server should use when answering us.
+
+    The leading byte packs two fields, which the server unpacks as:
+
+        reply_path_len       = byte & 63
+        reply_path_hash_size = (byte >> 6) + 1
+
+    so the hash mode has to travel in the top two bits. Omitting it makes the
+    server read a hash size of 1 regardless of the real mode, take the wrong
+    number of bytes per hop, and route its reply to hops that do not exist.
+
+    The path itself is reversed by *hop*, not by byte: a return path visits the
+    same hops in the opposite order, and each hop's multi-byte hash must stay
+    intact. (For single-byte hops the two are indistinguishable, which is most
+    of why this went unnoticed - mode 0 is the default.)
+    """
+    hash_mode = max(out_path_hash_mode, 0)      # -1 means "flood", i.e. no path
+    if hash_mode > 2:
+        # The server computes hash_size = mode + 1, and Packet::isValidPathLen
+        # rejects 4-byte hops outright, so such a path is unusable on the wire.
+        logger.warning(
+            f"Unsupported out_path_hash_mode {out_path_hash_mode}; "
+            "requesting a zero-hop reply path instead"
+        )
+        return b"\x00"
+    hash_size = hash_mode + 1
+    # Saturate rather than mask: `& 63` would silently wrap a 64-hop path to
+    # zero hops, i.e. a zero-hop reply for a distant node.
+    hops = min(max(out_path_len, 0), MAX_REPLY_PATH_HOPS)
+
+    raw = bytes.fromhex(out_path_hex or "")
+    # Never read past what the contact actually carries; a truncated or padded
+    # field would otherwise yield short trailing hops.
+    hops = min(hops, len(raw) // hash_size)
+    # The server memcpys into a fixed 64-byte reply_path with no bounds check
+    # (simple_repeater/MyMesh.cpp), so never describe more than fits.
+    max_hops = min(MAX_REPLY_PATH_HOPS, MAX_REPLY_PATH_BYTES // hash_size)
+    if hops > max_hops:
+        logger.warning(
+            f"Reply path of {hops} hops x {hash_size}B exceeds the "
+            f"{MAX_REPLY_PATH_BYTES}B the server can hold; truncating to {max_hops}"
+        )
+        hops = max_hops
+
+    path = b"".join(
+        raw[i * hash_size:(i + 1) * hash_size] for i in range(hops - 1, -1, -1)
+    )
+    return bytes([hops | (hash_mode << 6)]) + path
+
+
 class CommandHandlerBase:
-    DEFAULT_TIMEOUT = 5.0
+    """Base class for command handlers.
+
+    .. note::
+        The internal ``asyncio.Lock`` is created lazily on first access
+        so that it binds to the correct running event loop (required for
+        Python 3.9/3.10 compatibility).
+    """
+
+    DEFAULT_TIMEOUT = 15.0
 
     def __init__(self, default_timeout: Optional[float] = None):
         self._sender_func: Optional[Callable[[bytes], Coroutine[Any, Any, None]]] = None
         self._reader: Optional[MessageReader] = None
         self.dispatcher: Optional[EventDispatcher] = None
-        self._mesh_request_lock = asyncio.Lock()
+        self.__mesh_request_lock: Optional[asyncio.Lock] = None
         self.default_timeout = (
             default_timeout if default_timeout is not None else self.DEFAULT_TIMEOUT
         )
 
+    @property
+    def _mesh_request_lock(self) -> asyncio.Lock:
+        """Lazy-init lock so it binds to the running loop, not import-time."""
+        if self.__mesh_request_lock is None:
+            self.__mesh_request_lock = asyncio.Lock()
+        return self.__mesh_request_lock
+
     def set_connection(self, connection: Any) -> None:
         async def sender(data: bytes) -> None:
             await connection.send(data)
@@ -90,6 +163,14 @@ class CommandHandlerBase:
         expected_events: Optional[Union[EventType, List[EventType]]] = None,
         timeout: Optional[float] = None,
     ) -> Event:
+        """Wait for the first of *expected_events* to arrive.
+
+        Returns the first matched ``Event``.  When ``EventType.ERROR`` is
+        among the expected types, the caller **must** check
+        ``result.is_error()`` before accessing command-specific payload
+        keys — an ERROR payload is ``{"reason": "..."}`` and will
+        ``KeyError`` on any other key.
+        """
         try:
             # Convert single event to list if needed
             if not isinstance(expected_events, list):
@@ -129,9 +210,6 @@ class CommandHandlerBase:
             logger.debug(f"Command error: {e}")
             return Event(EventType.ERROR, {"error": str(e)})
 
-        return Event(EventType.ERROR, {})
-
-
     async def send(
         self,
         data: bytes,
@@ -151,7 +229,14 @@ class CommandHandlerBase:
             timeout: Timeout in seconds, or None to use default_timeout
 
         Returns:
-            Event: The full event object that was received in response to the command
+            Event: The full event object that was received in response to
+            the command.
+
+        Important:
+            When ``EventType.ERROR`` is included in *expected_events*, the
+            returned event may be an error response.  Callers **must**
+            check ``result.is_error()`` before accessing command-specific
+            payload keys to avoid ``KeyError``.
         """
         if not self.dispatcher:
             raise RuntimeError("Dispatcher not set, cannot send commands")
@@ -170,7 +255,7 @@ class CommandHandlerBase:
             futures: List[asyncio.Future] = []
             subscriptions = []
 
-            loop = asyncio.get_event_loop()
+            loop = asyncio.get_running_loop()
             for event_type in expected_events:
                 future = loop.create_future()
 
@@ -243,49 +328,102 @@ class CommandHandlerBase:
         logger.debug(f"Binary request to {dst_bytes.hex()}")
         data = b"\x32" + dst_bytes + request_type.value.to_bytes(1, "little", signed=False) + (data if data else b"")
 
-        result = await self.send(data, [EventType.MSG_SENT, EventType.ERROR])
-        
-        # Register the request with the reader if we have both reader and request_type
-        if (result.type == EventType.MSG_SENT and 
-            self._reader is not None and 
-            request_type is not None):
-            
-            exp_tag = result.payload["expected_ack"].hex()
-            # Use provided timeout or fallback to suggested timeout (with 5s default)
-            actual_timeout = timeout if timeout is not None and timeout > 0 else result.payload.get("suggested_timeout", 4000) / 800.0
+        # Pre-register a placeholder binary request before send() to close the race
+        # window where a BINARY_RESPONSE could arrive between send() returning and
+        # registration. The placeholder tag is patched to the real tag once MSG_SENT
+        # returns. If send() fails, the placeholder is cleaned up.
+        placeholder_tag = None
+        if self._reader is not None and request_type is not None:
+            placeholder_tag = f"_pending_{id(data)}"
+            actual_timeout = timeout if timeout is not None and timeout > 0 else self.default_timeout
             actual_timeout = min_timeout if actual_timeout < min_timeout else actual_timeout
-            self._reader.register_binary_request(pubkey_prefix.hex(), exp_tag, request_type, actual_timeout, context=context)
+            self._reader.register_binary_request(pubkey_prefix.hex(), placeholder_tag, request_type, actual_timeout, context=context)
+
+        result = await self.send(data, [EventType.MSG_SENT, EventType.ERROR])
+
+        # Patch the placeholder tag with the real tag from MSG_SENT, or clean up on failure
+        if placeholder_tag is not None and self._reader is not None:
+            # Remove the placeholder entry
+            self._reader.pending_binary_requests.pop(placeholder_tag, None)
+            if (result.type == EventType.MSG_SENT and
+                    request_type is not None):
+                exp_tag = result.payload["expected_ack"].hex()
+                # Use suggested_timeout from the result if available
+                actual_timeout = timeout if timeout is not None and timeout > 0 else result.payload.get("suggested_timeout", 4000) / 800.0
+                actual_timeout = min_timeout if actual_timeout < min_timeout else actual_timeout
+                # Register with the real tag
+                self._reader.register_binary_request(pubkey_prefix.hex(), exp_tag, request_type, actual_timeout, context=context)
 
         return result
 
     async def send_anon_req(self, dst: DestinationType, request_type: AnonReqType, data: Optional[bytes] = None, context={}, timeout=None, min_timeout=0) -> Event:
+        """Send an anonymous request to *dst*.
+
+        *dst* need not be a known contact. When it is, that contact's out path is
+        used as the reply path; otherwise a zero-hop direct reply path is
+        requested (see the comment below).
+
+        Note: *data* is currently ignored -- the request body is the reply path,
+        which is derived here rather than supplied by the caller.
+        """
         dst_bytes = _validate_destination(dst, prefix_length=32)
         pubkey_prefix = _validate_destination(dst, prefix_length=6)
         logger.debug(f"Anon Binary request to {dst_bytes.hex()}")
 
-        contact = self._get_contact_by_prefix(dst_bytes.hex()) # need a contact for return path
-        if contact is None:
-            logger.error("No contact found")
+        # The contact is consulted only to build the reply path appended to the
+        # request; it is not required to send one. Companion firmware from
+        # FIRMWARE_VER_CODE 13 synthesises a transient anon contact for an unknown
+        # pubkey (out_path_len = 0, zero-hop direct), so an unknown destination is
+        # reachable as long as we ask it to reply zero-hop. Refusing here would
+        # block probing any node the client has not already added - for instance
+        # asking a freshly discovered neighbour for its regions.
+        contact = self._get_contact_by_prefix(dst_bytes.hex())
 
         zero_hop = False
-        if contact["out_path_len"] == -1: 
-            logger.info("No path set trying zero hop")
-            zero_hop = True
-            await self.change_contact_path(contact, "")
+        if contact is None:
+            logger.debug("No contact found, requesting a zero-hop direct reply path")
+            out_path_len = 0
+            reply_path = encode_reply_path(0, "", 0)
+        else:
+            if contact["out_path_len"] == -1:
+                logger.info("No path set trying zero hop")
+                zero_hop = True
+                path_res = await self.change_contact_path(contact, "")
+                if path_res is not None and path_res.type == EventType.ERROR:
+                    # The device still has this contact as flood, so sendAnonReq
+                    # will flood the request -- and the server gates REGIONS,
+                    # OWNER and BASIC behind isRouteDirect(), silently dropping
+                    # it. Better to fail here than to wait out a full timeout
+                    # for a reply that cannot come.
+                    logger.error("Could not set zero-hop path, aborting anon request")
+                    return Event(EventType.ERROR, {"reason": "path_reset_failed"})
+            # update_contact() normally reflects the change back onto the dict, so
+            # out_path_len reads 0 here. Clamp anyway: if that call failed (e.g. the
+            # device query inside it errored) the dict is still -1, and the unsigned
+            # to_bytes below would raise OverflowError -- which would skip the
+            # reset_path at the end of this method and leave the contact pinned to
+            # zero-hop on the device. Zero is the right value to send regardless,
+            # since zero-hop is exactly what we just asked for.
+            out_path_len = max(contact["out_path_len"], 0)
+            reply_path = encode_reply_path(
+                out_path_len,
+                contact["out_path"],
+                contact.get("out_path_hash_mode", 0),
+            )
 
-        data = contact["out_path_len"].to_bytes(1, "little") + bytes.fromhex(contact["out_path"])[::-1]
-        data = b"\x39" + dst_bytes + request_type.value.to_bytes(1, "little", signed=False) + (data if data else b"")
+        data = b"\x39" + dst_bytes + request_type.value.to_bytes(1, "little", signed=False) + reply_path
 
         result = await self.send(data, [EventType.MSG_SENT, EventType.ERROR])
-        
+
         # Register the request with the reader if we have both reader and request_type
-        if (result.type == EventType.MSG_SENT and 
-            self._reader is not None and 
+        if (result.type == EventType.MSG_SENT and
+            self._reader is not None and
             request_type is not None):
-            
+
             exp_tag = result.payload["expected_ack"].hex()
             # Use provided timeout or fallback to suggested timeout (with 5s default)
-            result.payload["suggested_timeout"] = result.payload.get("suggested_timeout", 4000) * (contact["out_path_len"] + 1) # update timeout from path_len
+            emitted_hops = reply_path[0] & 63   # what actually went on the wire
+            result.payload["suggested_timeout"] = result.payload.get("suggested_timeout", 4000) * (emitted_hops + 1) # update timeout from path_len
             actual_timeout = timeout if timeout is not None and timeout > 0 else result.payload.get("suggested_timeout", 4000) / 800.0
             actual_timeout = min_timeout if actual_timeout < min_timeout else actual_timeout
             self._reader.register_binary_request(pubkey_prefix.hex(), exp_tag, request_type, actual_timeout, context=context, is_anon=True)

{meshcore-2.3.6 → meshcore-2.3.8}/src/meshcore/commands/binary.py

@@ -73,10 +73,6 @@ class BinaryCommandHandler(CommandHandlerBase):
 
             return telem_event.payload["lpp"] if telem_event else None
 
-    async def req_mma(self, contact, timeout=0, min_timeout=0):
-        logger.error("*** please consider using req_mma_sync instead of req_mma") 
-        return await self.req_mma_sync(contact, start, end, timeout,min_timeout)
-
     async def req_mma_sync(self, contact, start, end, timeout=0,min_timeout=0):
         async with self._mesh_request_lock:
             req = (

{meshcore-2.3.6 → meshcore-2.3.8}/src/meshcore/commands/contact.py

@@ -43,13 +43,17 @@ class ContactCommands(CommandHandlerBase):
                     logger.debug("Timeout while getting contacts")
                     for future in pending: # cancel all futures
                         future.cancel()
-                    return None
+                    return Event(EventType.ERROR, {"reason": "timeout waiting for contacts"})
 
                 for future in done:
                     event = await future
-                    if event is None or event.type != EventType.NEXT_CONTACT:
-                        for future in pending:
-                            future.cancel()
+                    if event is None:
+                        for f in pending:
+                            f.cancel()
+                        return Event(EventType.ERROR, {"reason": "no event received during contacts retrieval"})
+                    if event.type != EventType.NEXT_CONTACT:
+                        for f in pending:
+                            f.cancel()
                         return event
 
                 futures = []
@@ -64,7 +68,7 @@ class ContactCommands(CommandHandlerBase):
     
         except asyncio.TimeoutError:
             logger.debug(f"Timeout receiving contacts")
-            return None
+            return Event(EventType.ERROR, {"reason": "asyncio timeout receiving contacts"})
         except Exception as e:
             logger.debug(f"Command error: {e}")
             return Event(EventType.ERROR, {"error": str(e)})
@@ -116,7 +120,9 @@ class ContactCommands(CommandHandlerBase):
                     path_hash_mode = int(path.split(":")[1])
                     path = path.split(":")[0].replace(":","")
                 else: # use device one by default
-                    path_hash_mode = contact["out_path_len"] >> 6 # would fallback to previous val
+                    # out_path_len is pre-masked (& 0x3F) in reader.py, so high bits are always 0;
+                    # the actual path_hash_mode is fetched from the device query below.
+                    path_hash_mode = 0
                     res = await self.send_device_query()
                     if not res is None and res.type != EventType.ERROR:
                         if "path_hash_mode" in res.payload:
@@ -185,6 +191,24 @@ class ContactCommands(CommandHandlerBase):
         data = b"\x3B"
         return await self.send(data, [EventType.AUTOADD_CONFIG, EventType.ERROR])
 
+    async def get_contact_by_key(self, pubkey: bytes) -> Event:
+        """N09: Retrieve a single contact by its public key (CMD 30).
+
+        Args:
+            pubkey: 32-byte public key of the contact.
+
+        Returns:
+            Event with the contact data (same format as CONTACT/NEXT_CONTACT),
+            or ERROR if not found.
+        """
+        if not isinstance(pubkey, (bytes, bytearray)):
+            raise TypeError("pubkey must be bytes-like")
+        # Truncate or pad to 32 bytes
+        key_bytes = bytes(pubkey[:32])
+        logger.debug(f"Getting contact by key: {key_bytes.hex()}")
+        data = b"\x1e" + key_bytes
+        return await self.send(data, [EventType.NEXT_CONTACT, EventType.ERROR])
+
     async def get_advert_path(self, key: DestinationType) -> Event:
         key_bytes = _validate_destination(key, prefix_length=32)
         logger.debug(f"getting advert path for: {key} {key_bytes.hex()}")