meshcore 2.3.7__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.7 → meshcore-2.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshcore
-Version: 2.3.7
+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.7 → meshcore-2.3.8}/pyproject.toml

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

{meshcore-2.3.7 → 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.
@@ -52,6 +58,27 @@ class BLEConnection:
         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)."""
@@ -190,6 +217,10 @@ class BLEConnection:
         if self.reader is not None:
             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")
@@ -199,8 +230,24 @@ class BLEConnection:
         if not self.rx_char:
             logger.error("RX characteristic not found")
             return False
+        # 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 self.client.write_gatt_char(self.rx_char, bytes(data), response=True)
+            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:

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

@@ -57,6 +57,64 @@ 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:
     """Base class for command handlers.
 
@@ -299,34 +357,73 @@ class CommandHandlerBase:
         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")
-            return Event(EventType.ERROR, {"reason": "contact_not_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.7 → meshcore-2.3.8}/src/meshcore/commands/messaging.py

@@ -307,30 +307,41 @@ class MessagingCommands(CommandHandlerBase):
 
         return await self.send(cmd_data, [EventType.MSG_SENT, EventType.ERROR])
 
-    async def send_raw_data(self, payload: bytes) -> Event:
+    async def send_raw_data(self, payload: bytes, path: bytes = b"") -> Event:
         """N09: Send raw data via CMD_SEND_RAW_DATA (25).
 
-        Sends an arbitrary payload through the mesh network.
+        Sends an arbitrary raw-data payload directly (no flood support yet).
+
+        Command format:
+            0x19 | path_len(1) | path(path_len bytes) | payload(>=4 bytes)
 
         Args:
-            payload: Raw bytes to send.
+            payload: Raw bytes to send (minimum 4 bytes).
+            path:    Optional path bytes for intermediate hops (default: empty = zero-hop direct).
 
         Returns:
-            Event with MSG_SENT or ERROR.
+            Event with OK or ERROR.
         """
         if not isinstance(payload, (bytes, bytearray)):
             raise TypeError("payload must be bytes-like")
-        data = b"\x19" + bytes(payload)
-        return await self.send(data, [EventType.MSG_SENT, EventType.ERROR])
+        if len(payload) < 4:
+            raise ValueError("payload must be at least 4 bytes")
+        path = bytes(path)
+        data = bytes([0x19, len(path)]) + path + bytes(payload)
+        return await self.send(data, [EventType.OK, EventType.ERROR])
 
-    async def set_flood_scope(self, scope):
+    async def set_flood_scope(self, scope, force_unscoped=False):
         if scope is None:
             logger.debug(f"Resetting scope")
             scope_key = b"\0"*16
         elif isinstance (scope, str):
-            if scope == "0" or scope == "None" or scope == "*" or scope == "": # disable
+            if scope == "0" or scope == "None" or scope == "": # revert to default
                 logger.debug(f"Resetting scope")
                 scope_key = b"\0"*16
+                logger.debug("revert to default_scope")
+            elif scope == "*":
+                force_unscoped = True
+                logger.debug("forcing unscoped msgs")
             else:
                 logger.debug(f"Setting scope from string {scope}")
                 if scope[0] != "#":     # no hashtag as first char
@@ -342,14 +353,28 @@ class MessagingCommands(CommandHandlerBase):
         else:
             raise TypeError(f"set_flood_scope: unsupported scope type {type(scope).__name__}")
 
-        logger.debug(f"Setting scope to {scope_key.hex()}")
+        if force_unscoped:
+            logger.debug("Forcing unscoped messages")
+        elif scope_key is None:
+            logger.debug(f"Resetting scope")
+        else:
+            logger.debug(f"Setting scope to {scope_key.hex()}")
 
         cmd_data = bytearray([CommandType.SET_FLOOD_SCOPE.value])
-        cmd_data.extend(b"\0")
-        cmd_data.extend(scope_key)
+        if force_unscoped:
+            cmd_data.append(0x01)
+        else:
+            cmd_data.extend(b"\0")
+            cmd_data.extend(scope_key)
 
         return await self.send(cmd_data, [EventType.OK, EventType.ERROR])
 
+    async def reset_flood_scope(self):
+        return await self.set_flood_scope(b"")
+
+    async def force_unscoped(self):
+        return await self.set_flood_scope(b"", force_unscoped=True)
+
     async def set_default_flood_scope(self, scope):
         if scope is None:
             logger.debug(f"Resetting default scope")
@@ -378,6 +403,9 @@ class MessagingCommands(CommandHandlerBase):
 
         return await self.send(cmd_data, [EventType.OK, EventType.ERROR])
 
+    async def reset_default_flood_scope(self):
+        return await self.set_default_flood_scope(None)
+
     async def get_default_flood_scope(self):
         logger.debug(f"Getting default flood scope")
         cmd_data = bytearray([CommandType.GET_DEFAULT_FLOOD_SCOPE.value])

{meshcore-2.3.7 → meshcore-2.3.8}/src/meshcore/events.py

@@ -14,6 +14,7 @@ class EventType(Enum):
     SELF_INFO = "self_info"
     CONTACT_MSG_RECV = "contact_message"
     CHANNEL_MSG_RECV = "channel_message"
+    CHANNEL_DATA_RECV = "channel_data"
     CURRENT_TIME = "time_update"
     NO_MORE_MSGS = "no_more_messages"
     CONTACT_URI = "contact_uri"

{meshcore-2.3.7 → meshcore-2.3.8}/src/meshcore/packets.py

@@ -105,6 +105,7 @@ class PacketType(Enum):
     STATS = 24
     AUTOADD_CONFIG = 25
     ALLOWED_REPEAT_FREQ = 26
+    CHANNEL_DATA_RECV = 27
     DEFAULT_FLOOD_SCOPE = 28
 
     # Push notifications

{meshcore-2.3.7 → meshcore-2.3.8}/src/meshcore/reader.py

@@ -112,7 +112,17 @@ class MessageReader:
                 else:
                     c["out_path_hash_mode"] = plen >> 6 
                     c["out_path_len"] = plen & 0x3F # 6 LSB
-                c["out_path"] = dbuf.read(64).replace(b"\0", b"").hex()
+                # The field is a fixed 64 bytes, NUL-padded past the real path.
+                # Take exactly the bytes the path occupies rather than stripping
+                # NULs: a hop hash may legitimately contain 0x00, and dropping
+                # those shortens the path and shifts every hop after it.
+                # (PATH_DISCOVERY_RESPONSE below already reads opl*opl_hlen.)
+                path_bytes = dbuf.read(64)
+                if c["out_path_len"] > 0:
+                    used = c["out_path_len"] * (c["out_path_hash_mode"] + 1)
+                    c["out_path"] = path_bytes[:used].hex()
+                else:
+                    c["out_path"] = ""
                 c["adv_name"] = dbuf.read(32).decode("utf-8", "ignore").replace("\0", "")
                 c["last_advert"] = int.from_bytes(dbuf.read(4), byteorder="little")
                 c["adv_lat"] = (
@@ -184,8 +194,13 @@ class MessageReader:
 
             elif packet_type_value == PacketType.DEFAULT_FLOOD_SCOPE.value:
                 res = {}
-                res["scope_name"] = dbuf.read(31).decode("utf-8", "ignore").replace("\0", "")
-                res["scope_key"] = dbuf.read(16).hex()
+                # Firmware emits a 48-byte frame when a scope is configured,
+                # or a 1-byte sentinel frame (just the response code) when no
+                # scope is set. Gate the 31+16 byte read so the sentinel
+                # dispatches an empty payload instead of empty-string fields.
+                if len(data) >= 48:
+                    res["scope_name"] = dbuf.read(31).decode("utf-8", "ignore").replace("\0", "")
+                    res["scope_key"] = dbuf.read(16).hex()
                 await self.dispatcher.dispatch(Event(EventType.DEFAULT_FLOOD_SCOPE, res))
 
             elif packet_type_value == PacketType.MSG_SENT.value:
@@ -332,6 +347,41 @@ class MessageReader:
                     Event(EventType.CHANNEL_MSG_RECV, res, attributes)
                 )
 
+            elif packet_type_value == PacketType.CHANNEL_DATA_RECV.value:
+                # Group-channel binary data (PAYLOAD_TYPE_GRP_DATA), companion-v1.15.0+.
+                # Fixed 9-byte header (including the code byte) + variable payload:
+                #   code(1) + snr(1) + reserved(2) + channel_idx(1)
+                #   + path_len(1) + data_type(2) + data_len(1) = 9 bytes
+                # The first six post-code bytes share CHANNEL_MSG_RECV_V3's framing;
+                # data_type is a 16-bit little-endian field (widened from uint8 in
+                # firmware, so the high byte may be non-zero).
+                if len(data) < 9:
+                    logger.debug(f"CHANNEL_DATA_RECV frame too short ({len(data)} bytes < 9), skipping parse")
+                    return
+                res = {}
+                res["SNR"] = int.from_bytes(dbuf.read(1), byteorder="little", signed=True) / 4
+                dbuf.read(2)  # reserved
+                res["channel_idx"] = dbuf.read(1)[0]
+                plen = dbuf.read(1)[0]
+                if plen == 255:  # direct message
+                    res["path_hash_mode"] = -1
+                    res["path_len"] = plen
+                else:
+                    res["path_hash_mode"] = plen >> 6
+                    res["path_len"] = plen & 0x3F
+                res["data_type"] = int.from_bytes(dbuf.read(2), byteorder="little")
+                res["data_len"] = dbuf.read(1)[0]
+                res["payload"] = dbuf.read(res["data_len"]).hex()
+
+                attributes = {
+                    "channel_idx": res["channel_idx"],
+                    "data_type": res["data_type"],
+                }
+
+                await self.dispatcher.dispatch(
+                    Event(EventType.CHANNEL_DATA_RECV, res, attributes)
+                )
+
             elif packet_type_value == PacketType.CURRENT_TIME.value:
                 time_value = int.from_bytes(dbuf.read(4), byteorder="little")
                 result = {"time": time_value}
@@ -491,7 +541,12 @@ class MessageReader:
 
                 res = {}
                 res["config"] = dbuf.read(1)[0]
-                await self.dispatcher.dispatch(Event(EventType.AUTOADD_CONFIG, res, res))            
+                # `max_hops` trailing byte added in companion-v1.14.0
+                # (firmware commit 00566741). Pre-v1.14.0 firmware emits a
+                # 1-byte response; read defensively to remain compatible.
+                if len(data) >= 3:
+                    res["max_hops"] = dbuf.read(1)[0]
+                await self.dispatcher.dispatch(Event(EventType.AUTOADD_CONFIG, res, res))
 
             elif packet_type_value == PacketType.CHANNEL_INFO.value:
                 logger.debug(f"received channel info response: {data.hex()}")
@@ -533,6 +588,12 @@ class MessageReader:
 
                 if len(data) >= 5:
                     ack_data["code"] = dbuf.read(4).hex()
+                # `trip_time` (round-trip latency in ms) has been on the wire
+                # since companion-v1.0.0a (firmware commit d9dc76f1, Jan 2025).
+                # Read defensively so legacy frames without this field still
+                # dispatch correctly.
+                if len(data) >= 9:
+                    ack_data["trip_time"] = int.from_bytes(dbuf.read(4), "little")
 
                 attributes = {"code": ack_data.get("code", "")}
 
@@ -546,7 +607,8 @@ class MessageReader:
                 res = {}
                 res["SNR"] = int.from_bytes(dbuf.read(1), byteorder="little", signed=True) / 4
                 res["RSSI"] = int.from_bytes(dbuf.read(1), byteorder="little", signed=True)
-                res["payload"] = dbuf.read(4).hex()
+                dbuf.read(1)  # skip reserved byte (0xFF, possibly path_len in future)
+                res["payload"] = dbuf.read().hex()  # read all remaining payload bytes
                 logger.debug("Received raw data")
                 logger.debug(res)
                 await self.dispatcher.dispatch(Event(EventType.RAW_DATA, res))
@@ -560,8 +622,19 @@ class MessageReader:
                     res["is_admin"] = (perms & 1) == 1  # Check if admin bit is set
                 if len(data) > 7:
                     res["pubkey_prefix"] = dbuf.read(6).hex()
-                    
+
                     attributes = {"pubkey_prefix": res.get("pubkey_prefix")}
+                # The following trailing fields are emitted only by the new-
+                # style RESP_SERVER_LOGIN_OK path. server_timestamp landed in
+                # firmware commit 0e90b731 (companion-v1.10.0); acl_permissions
+                # in 7947e8a2; fw_ver_level in 418ae08b (also companion-v1.10.0).
+                # Per-field length gates handle every firmware-version tier.
+                if len(data) >= 12:
+                    res["server_timestamp"] = int.from_bytes(dbuf.read(4), "little")
+                if len(data) >= 13:
+                    res["acl_permissions"] = dbuf.read(1)[0]
+                if len(data) >= 14:
+                    res["fw_ver_level"] = dbuf.read(1)[0]
 
                 await self.dispatcher.dispatch(
                     Event(EventType.LOGIN_SUCCESS, res, attributes)