python-mobius 0.10.1__tar.gz → 0.10.3__tar.gz

{python_mobius-0.10.1 → python_mobius-0.10.3}/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.10.3
+
+- Frames that fail to parse or fail their CRC are logged at debug level.
+
+## 0.10.2
+
+- Mesh peer discovery can raise its error (`raise_errors=True`) instead
+  of returning an empty list on failure.
+
 ## 0.10.1
 
 - Fixed lights not being read through a gateway: the poll's reply was too

{python_mobius-0.10.1 → python_mobius-0.10.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-mobius
-Version: 0.10.1
+Version: 0.10.3
 Summary: Reverse-engineered Python client for the Mobius BLE protocol (EcoTech Marine VorTech/Radion, AquaIllumination, Neptune Systems, NYOS)
 Project-URL: Homepage, https://code.r3pek.org/r3pek/python-mobius
 Project-URL: Documentation, https://code.r3pek.org/r3pek/python-mobius/src/branch/main/documentation

{python_mobius-0.10.1 → python_mobius-0.10.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-mobius"
-version = "0.10.1"
+version = "0.10.3"
 description = "Reverse-engineered Python client for the Mobius BLE protocol (EcoTech Marine VorTech/Radion, AquaIllumination, Neptune Systems, NYOS)"
 readme = "README.md"
 license = { text = "GPL-2.0-only" }

{python_mobius-0.10.1 → python_mobius-0.10.3}/src/mobius/__init__.py

@@ -87,7 +87,7 @@ from .mob import (
     MAX_PUMP_PRIMITIVE_SIZE,
 )
 
-__version__ = "0.10.1"
+__version__ = "0.10.3"
 
 __all__ = [
     "__version__",

{python_mobius-0.10.1 → python_mobius-0.10.3}/src/mobius/device.py

@@ -12,6 +12,7 @@ from __future__ import annotations
 import asyncio
 import datetime
 import struct
+import logging
 import time
 from dataclasses import dataclass, field
 from typing import Optional, Callable, Any
@@ -79,6 +80,8 @@ CHAR_TX_DATA = "01ff0103-ba5e-f4ee-5ca1-eb1e5e4b1ce0"   # write: app -> device,
 CHAR_TX_FINAL = "01ff0104-ba5e-f4ee-5ca1-eb1e5e4b1ce0"  # write: app -> device, last fragment
 
 # count=0xFFFF requests every element of a list attribute.
+_LOGGER = logging.getLogger(__name__)
+
 ALL_ELEMENTS = 0xFFFF
 
 # Write fragment size when the ATT MTU is unknown or the minimum (23).
@@ -87,6 +90,23 @@ DEFAULT_WRITE_SIZE = 20
 MTU_WRITE_OVERHEAD = 5
 
 
+def _log_bad_frame(raw: bytes, frame, trace: list[tuple[str, int]]) -> None:
+    """Debug details of a received frame that doesn't parse or fails its
+    CRC: what was received against what its header declares, and the
+    notifications it was assembled from (D = RX_DATA, F = RX_FINAL)."""
+    if not _LOGGER.isEnabledFor(logging.DEBUG):
+        return
+    declared = struct.unpack_from("<H", raw, 7)[0] + 11 if len(raw) >= 9 else None
+    pieces = " ".join(f"{kind}{length}" for kind, length in trace)
+    _LOGGER.debug(
+        "Received a frame that %s: %d bytes, header declares %s; op_group=%s op_code=%s msg_id=%s; "
+        "%d notifications [%s]; first bytes %s; last bytes %s",
+        "doesn't parse" if frame is None else "fails its CRC", len(raw), declared,
+        f"{frame.op_group:#04x}" if frame else "?", frame.op_code if frame else "?",
+        frame.message_id if frame else "?", len(trace), pieces, raw[:24].hex(), raw[-24:].hex(),
+    )
+
+
 def write_size_for_mtu(att_mtu: Optional[int]) -> int:
     """Write fragment size for a negotiated ATT MTU: `att_mtu` minus 5, as
     the app does, or DEFAULT_WRITE_SIZE when it is unknown or not above the
@@ -917,6 +937,9 @@ class MobiusDevice:
         self.adapter = adapter
         self._client: Optional[BleakClient] = None
         self._rx_buffer = bytearray()
+        # ("D"/"F", length) of each notification of the frame being
+        # received, logged when it fails its CRC.
+        self._rx_trace: list[tuple[str, int]] = []
         # Pending direct requests, keyed by FSCI message ID.
         self._pending: dict[int, asyncio.Future] = {}
         # Pending relayed requests, keyed by CoAP token (see mobius.relay).
@@ -1014,12 +1037,18 @@ class MobiusDevice:
 
     def _on_rx_data(self, _handle, data: bytearray):
         self._rx_buffer.extend(data)
+        self._rx_trace.append(("D", len(data)))
 
     def _on_rx_final(self, _handle, data: bytearray):
         self._rx_buffer.extend(data)
+        self._rx_trace.append(("F", len(data)))
         raw = bytes(self._rx_buffer)
+        trace = self._rx_trace
         self._rx_buffer.clear()
+        self._rx_trace = []
         frame = parse_frame(raw)
+        if frame is None or not frame.crc_ok:
+            _log_bad_frame(raw, frame, trace)
         if frame is None:
             return
         if self.on_any_frame is not None:
@@ -1842,7 +1871,7 @@ class MobiusDevice:
             return None
         return raw
 
-    async def discover_mesh_peers(self) -> list[MeshPeer]:
+    async def discover_mesh_peers(self, raise_errors: bool = False) -> list[MeshPeer]:
         """
         Mesh peers from the ShortAddressArray/SerialNumberArray/
         DeviceModelArray (3700/3701/3702) parallel arrays, with addresses
@@ -1852,10 +1881,12 @@ class MobiusDevice:
         UnsupportedAttribute and this returns []. Whether the connected
         device lists itself is not known. Empty slots (serial
         "00000000000000") and short entries are skipped. Returns [] on any
-        failure.
+        failure, or raises it with raise_errors=True.
         """
         own_address = await self.get_own_mesh_address()
         if own_address is None:
+            if raise_errors:
+                raise IOError("own mesh address (MeshLocalAddresses) not readable")
             return []
         prefix = mesh_local_prefix_from_own_address(own_address)
 
@@ -1864,6 +1895,8 @@ class MobiusDevice:
             models_raw = await self.get_attribute(C2Attribute.DeviceModelArray, index=0, count=ALL_ELEMENTS)
             shorts_raw = await self.get_attribute(C2Attribute.ShortAddressArray, index=0, count=ALL_ELEMENTS)
         except Exception:
+            if raise_errors:
+                raise
             return []
 
         peers: list[MeshPeer] = []
@@ -1882,7 +1915,7 @@ class MobiusDevice:
             ))
         return peers
 
-    async def discover_networked_thread_devices(self) -> list[MeshPeer]:
+    async def discover_networked_thread_devices(self, raise_errors: bool = False) -> list[MeshPeer]:
         """
         Every device on this device's Thread mesh, including itself, from
         MLPrefix (2128) and NetworkedThreadDevices (1001). Supported more
@@ -1896,7 +1929,8 @@ class MobiusDevice:
           12-13  model id, i16 LE
           14-27  serial, ASCII
         Empty slots are all zeros and are skipped, as are entries of any
-        other length. Returns [] on any failure.
+        other length. Returns [] on any failure, or raises it with
+        raise_errors=True.
         """
         try:
             mlprefix_raw = await self.get_attribute(C2Attribute.MLPrefix)
@@ -1904,8 +1938,15 @@ class MobiusDevice:
                 C2Attribute.NetworkedThreadDevices, index=0, count=ALL_ELEMENTS,
             )
         except Exception:
+            if raise_errors:
+                raise
             return []
         if not mlprefix_raw or len(mlprefix_raw[0]) != 24:
+            if raise_errors:
+                raise IOError(
+                    f"unexpected MLPrefix: {mlprefix_raw[0].hex() if mlprefix_raw else 'empty'} "
+                    f"(expected 24 bytes)"
+                )
             return []
         prefix = mesh_local_prefix_from_mlprefix(mlprefix_raw[0])
 
@@ -1928,18 +1969,35 @@ class MobiusDevice:
             ))
         return peers
 
-    async def discover_mesh_peers_auto(self) -> list[MeshPeer]:
+    async def discover_mesh_peers_auto(self, raise_errors: bool = False) -> list[MeshPeer]:
         """
         discover_networked_thread_devices(), falling back to
         discover_mesh_peers() when it finds nothing. The recommended entry
         point. mobius.discovery.discover_mesh_peers_via_direct_connect() is
         the remaining fallback, but it needs scan results and has to be
         called explicitly.
+
+        raise_errors=True: a failure raises instead of looking like an
+        empty mesh. The fallback is then only tried when
+        NetworkedThreadDevices can't be read (an MXM hub), and the error
+        raised names both attempts.
         """
-        peers = await self.discover_networked_thread_devices()
-        if peers:
-            return peers
-        return await self.discover_mesh_peers()
+        if not raise_errors:
+            peers = await self.discover_networked_thread_devices()
+            if peers:
+                return peers
+            return await self.discover_mesh_peers()
+
+        try:
+            return await self.discover_networked_thread_devices(raise_errors=True)
+        except Exception as networked_error:
+            try:
+                return await self.discover_mesh_peers(raise_errors=True)
+            except Exception as arrays_error:
+                raise IOError(
+                    f"NetworkedThreadDevices: {networked_error or type(networked_error).__name__}; "
+                    f"peer arrays: {arrays_error or type(arrays_error).__name__}"
+                ) from networked_error
 
     async def get_firmware_versions(self, model: Optional[Model] = None) -> dict:
         """{label: version} for every firmware component (FirmwareVersion,

{python_mobius-0.10.1 → python_mobius-0.10.3}/tests/test_networked_thread_devices.py

@@ -328,3 +328,68 @@ async def test_discover_networked_thread_devices_real_hardware_capture():
     assert p.model == Model.RadionXR15wG6Pro
     assert p.age == 8490
     assert p.short_address == 0x0400
+
+
+@pytest.mark.asyncio
+async def test_raise_errors_reports_a_failed_read_instead_of_an_empty_mesh():
+    device = MobiusDevice(_fake_ble_device())
+
+    async def fake_get_attribute(attr_id, index=0, count=1):
+        raise IOError("timed out")
+
+    device.get_attribute = fake_get_attribute
+
+    assert await device.discover_networked_thread_devices() == []
+    with pytest.raises(IOError, match="timed out"):
+        await device.discover_networked_thread_devices(raise_errors=True)
+
+
+@pytest.mark.asyncio
+async def test_raise_errors_reports_an_unexpected_mlprefix():
+    device = MobiusDevice(_fake_ble_device())
+
+    async def fake_get_attribute(attr_id, index=0, count=1):
+        if attr_id == C2Attribute.MLPrefix:
+            return [PREFIX]  # 8 bytes instead of 24
+        return []
+
+    device.get_attribute = fake_get_attribute
+
+    with pytest.raises(IOError, match="unexpected MLPrefix"):
+        await device.discover_networked_thread_devices(raise_errors=True)
+
+
+@pytest.mark.asyncio
+async def test_auto_with_raise_errors_names_both_attempts_when_both_fail():
+    device = MobiusDevice(_fake_ble_device())
+
+    async def fake_get_attribute(attr_id, index=0, count=1):
+        raise IOError(f"no answer for {int(attr_id)}")
+
+    async def no_own_address():
+        return None
+
+    device.get_attribute = fake_get_attribute
+    device.get_own_mesh_address = no_own_address
+
+    assert await device.discover_mesh_peers_auto() == []
+    with pytest.raises(IOError, match=r"NetworkedThreadDevices: no answer for 2128; peer arrays: own mesh address"):
+        await device.discover_mesh_peers_auto(raise_errors=True)
+
+
+@pytest.mark.asyncio
+async def test_auto_with_raise_errors_returns_networked_devices():
+    device = MobiusDevice(_fake_ble_device())
+    suffix = bytes.fromhex("000000fffe00") + struct.pack("<H", 0x1234)
+
+    async def fake_get_attribute(attr_id, index=0, count=1):
+        if attr_id == C2Attribute.MLPrefix:
+            return [MLPREFIX_RAW]
+        if attr_id == C2Attribute.NetworkedThreadDevices:
+            return [_entry(suffix, 42, Model.VorTechMP40wG3QD, "00000000000001")]
+        raise AssertionError("the peer arrays must not be read")
+
+    device.get_attribute = fake_get_attribute
+
+    peers = await device.discover_mesh_peers_auto(raise_errors=True)
+    assert [p.serial for p in peers] == ["00000000000001"]

{python_mobius-0.10.1 → python_mobius-0.10.3}/tests/test_relay.py

@@ -819,3 +819,17 @@ class TestRelayedMultiBlockResponse:
         versions = await relayed.get_firmware_versions(model=Model.RadionXR15wG6Pro)
         assert versions["Product OS"] == "1.0"
         assert versions["Radio Firmware"] == "1.5.103"
+
+
+def test_a_frame_failing_its_crc_is_logged_with_its_notifications(caplog):
+    caplog.set_level(logging.DEBUG, logger="mobius.device")
+    device = MobiusDevice(BLEDevice("AA:BB:CC:DD:EE:FF", "MOBIUS", {}))
+    frame = bytearray(build_frame(OPGROUP_C2CI_REQUEST, 1, b"\x00" * 30, 7))
+    frame[-1] ^= 0xFF  # corrupt the CRC
+
+    device._on_rx_data(None, frame[:20])
+    device._on_rx_final(None, frame[20:])
+
+    assert "fails its CRC" in caplog.text
+    assert "2 notifications [D20 F" in caplog.text
+    assert device._rx_trace == []