python-mobius 0.10.0__tar.gz → 0.10.2__tar.gz

{python_mobius-0.10.0 → python_mobius-0.10.2}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 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
+  large to be relayed. The schedule and scenes are now read in requests
+  of their own, as the app does.
+
 ## 0.10.0
 
 - Added `set_time_zone()`; the batched polls now include the device's time

{python_mobius-0.10.0 → python_mobius-0.10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-mobius
-Version: 0.10.0
+Version: 0.10.2
 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.0 → python_mobius-0.10.2}/documentation/09-thread-coap-relay.md

@@ -156,6 +156,21 @@ A gateway can lose its route to a single target while everything else
 keeps working. The protocol has no command to rebuild the mesh; switching
 to another device as gateway is the practical recovery.
 
+## Reply size
+
+A relayed reply that is too large never arrives: the request times out
+as if the target were unreachable, while smaller requests to the same
+target keep working. Seen with a Radion XR15 G6 relayed through a VorTech
+MP40: a poll batch whose reply was about 2 KB (schedule, scenes and
+metadata together) always timed out, the same data read in three requests
+arrived. The limit is somewhere above 1.1 KB (a 25-point light schedule
+alone, about 1.05 KB of data, arrives).
+
+The app reads the schedule (and the Insolation schedule and driver
+information) in a request of its own, and everything else together; the
+Insolation table even takes 8 requests. `get_full_poll_batch()` does the
+same with the schedule and `ConfiguredScenes`.
+
 ## Writes and the mesh
 
 A relayed Set reaches only its target. A Set sent with the reserved

{python_mobius-0.10.0 → python_mobius-0.10.2}/documentation/17-configuration-checksums.md

@@ -62,6 +62,10 @@ To read scenes and a schedule only when they changed:
    kept one, the kept data is current.
 3. If it differs, or can't be read, read the data and its checksum again.
 
+Read each data attribute in a request of its own: a light's schedule or
+scenes are close to the largest reply a relay carries
+([09](./09-thread-coap-relay.md#reply-size)).
+
 The key is the device's own value, so this works without computing
 anything and also catches changes made by other clients (the app, or
 this client's own writes). Include `SupportedAttributesCRC` in the poll: a

{python_mobius-0.10.0 → python_mobius-0.10.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-mobius"
-version = "0.10.0"
+version = "0.10.2"
 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.0 → python_mobius-0.10.2}/src/mobius/__init__.py

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

{python_mobius-0.10.0 → python_mobius-0.10.2}/src/mobius/device.py

@@ -169,26 +169,18 @@ def _schedule_checksum_attr(which: int) -> C2Attribute:
     return C2Attribute.Schedule1Checksum if which == 1 else C2Attribute.Schedule2Checksum
 
 
-def _configuration_requests(
+def _configuration_checksum_requests(
     configuration: tuple, cache: Optional[ConfigurationCache], supported_attribute_ids: set,
-) -> tuple[list, set]:
-    """
-    Poll requests for each (data attribute, checksum attribute) of
-    `configuration`: the checksum alone when `cache` holds the data, else
-    the data (plus the checksum, to store with it). Returns (requests,
-    data attributes requested).
-    """
-    requests, data_read = [], set()
-    for data_attr, checksum_attr in configuration:
-        checksum_usable = cache is not None and checksum_attr in supported_attribute_ids
-        if checksum_usable and data_attr in cache.entries:
-            requests.append((checksum_attr, 0, 1))
-            continue
-        requests.append((data_attr, 0, ALL_ELEMENTS))
-        data_read.add(data_attr)
-        if checksum_usable:
-            requests.append((checksum_attr, 0, 1))
-    return requests, data_read
+) -> list:
+    """The checksum request of each (data attribute, checksum attribute) of
+    `configuration` that the cache can use. The data itself is never part
+    of the poll batch (see _read_configuration())."""
+    if cache is None:
+        return []
+    return [
+        (checksum_attr, 0, 1) for _data_attr, checksum_attr in configuration
+        if checksum_attr in supported_attribute_ids
+    ]
 
 
 def _apply_static_cache(cache: ConfigurationCache, by_attr_id: dict, static_read: bool) -> None:
@@ -1850,7 +1842,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
@@ -1860,10 +1852,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)
 
@@ -1872,6 +1866,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] = []
@@ -1890,7 +1886,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
@@ -1904,7 +1900,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)
@@ -1912,8 +1909,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])
 
@@ -1936,18 +1940,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,
@@ -2506,10 +2527,12 @@ class MobiusDevice:
         get_device_info(), get_metadata_batch() and
         get_light_poll_batch() or get_pump_schedule()/get_pump_telemetry().
 
-        `cache` (one per device, kept by the caller): ConfiguredScenes and
-        the schedule are then read only when their checksum changed since
-        the previous poll (see ConfigurationCache); a changed checksum
-        costs a second, smaller request. With its static_refresh_interval
+        The schedule and ConfiguredScenes are read in requests of their
+        own after the batch, as the app does: combined with the rest, a
+        light's reply is too large to be relayed. `cache` (one per device,
+        kept by the caller): they are then read only when their checksum,
+        part of the batch, changed since the previous poll (see
+        ConfigurationCache). With its static_refresh_interval
         set, the STATIC_POLL_ATTRIBUTES are also read only that often.
         Used by the batched path only.
         """
@@ -2537,7 +2560,7 @@ class MobiusDevice:
             (schedule_attr, _schedule_checksum_attr(which)),
             (C2Attribute.ConfiguredScenes, C2Attribute.ConfiguredScenesChecksum),
         )
-        configuration_requests, data_read = _configuration_requests(configuration, cache, supported_attribute_ids)
+        configuration_requests = _configuration_checksum_requests(configuration, cache, supported_attribute_ids)
         if cache is not None:
             configuration_requests.append((C2Attribute.SupportedAttributesCRC, 0, 1))
         requests = _DEVICE_INFO_REQUESTS + _METADATA_REQUESTS + configuration_requests + [
@@ -2558,9 +2581,7 @@ class MobiusDevice:
             )
             if attribute_table_changed:
                 cache.invalidate_static()
-            data_read |= await self._apply_configuration_cache(
-                by_attr_id, cache, configuration, data_read, supported_attribute_ids,
-            )
+        data_read = await self._read_configuration(by_attr_id, cache, configuration, supported_attribute_ids)
 
         def first(attr_id, index=0):
             return _first_value(by_attr_id, attr_id, index)
@@ -2621,38 +2642,44 @@ class MobiusDevice:
             static_read=static_read,
         )
 
-    async def _apply_configuration_cache(
-        self, by_attr_id: dict, cache: ConfigurationCache,
-        configuration: tuple, data_read: set, supported_attribute_ids: set,
+    async def _read_configuration(
+        self, by_attr_id: dict, cache: Optional[ConfigurationCache],
+        configuration: tuple, supported_attribute_ids: set,
     ) -> set:
         """
-        After the poll batch: stores data read with its checksum, fills in
-        cached data whose checksum is unchanged, and reads the rest in a
-        second batch. Returns the attributes read by that second batch.
+        Fills each data attribute of `configuration` (the schedule, the
+        scenes) into `by_attr_id`: from `cache` when the checksum in the
+        poll batch matches the cached one, else with a request of its own
+        (plus its checksum, stored in the cache with it). Returns the
+        attributes read.
+
+        Each gets its own request, as in the app: a light's schedule or
+        scenes alone are close to the largest reply a relay carries, and
+        together with the rest of the poll a relayed reply is too large
+        and never arrives.
         """
-        stale = []
+        read = set()
         for data_attr, checksum_attr in configuration:
-            if data_attr not in supported_attribute_ids or checksum_attr not in supported_attribute_ids:
+            if data_attr not in supported_attribute_ids:
                 continue
-            reported = _unpack(_first_value(by_attr_id, checksum_attr), "<H")
-            if data_attr in data_read:
-                _store_configuration(cache, data_attr, reported, by_attr_id)
-                continue
-            cached = cache.entries.get(data_attr)
-            if cached is not None and reported is not None and reported == cached[0]:
-                by_attr_id[data_attr] = cached[1]
-            else:
-                stale.append((data_attr, checksum_attr))
-        if not stale:
-            return set()
-        second = await self._read_supported_batch(
-            [r for data_attr, checksum_attr in stale for r in ((data_attr, 0, ALL_ELEMENTS), (checksum_attr, 0, 1))],
-            supported_attribute_ids,
-        )
-        for data_attr, checksum_attr in stale:
-            by_attr_id[data_attr] = second.get(data_attr, [])
-            _store_configuration(cache, data_attr, _unpack(_first_value(second, checksum_attr), "<H"), second)
-        return {data_attr for data_attr, _checksum_attr in stale}
+            checksum_usable = cache is not None and checksum_attr in supported_attribute_ids
+            if checksum_usable:
+                reported = _unpack(_first_value(by_attr_id, checksum_attr), "<H")
+                cached = cache.entries.get(data_attr)
+                if cached is not None and reported is not None and reported == cached[0]:
+                    by_attr_id[data_attr] = cached[1]
+                    continue
+            requests = [(data_attr, 0, ALL_ELEMENTS)]
+            if checksum_usable:
+                requests.append((checksum_attr, 0, 1))
+            response = await self._read_supported_batch(requests, supported_attribute_ids)
+            by_attr_id[data_attr] = response.get(int(data_attr), [])
+            if checksum_usable:
+                _store_configuration(
+                    cache, data_attr, _unpack(_first_value(response, checksum_attr), "<H"), response,
+                )
+            read.add(data_attr)
+        return read
 
     async def _get_full_poll_via_individual_reads(
         self, primitive: PrimitiveType, model: Optional[Model],

{python_mobius-0.10.0 → python_mobius-0.10.2}/tests/test_configuration_cache.py

@@ -60,6 +60,14 @@ def _requested(pump, attr, batch=-1):
     return int(attr) in pump.batches[batch]
 
 
+def _requested_in_any(pump, attr, batches):
+    return any(int(attr) in batch for batch in batches)
+
+
+SCHEDULE_ALONE = [int(C2Attribute.Schedule1), int(C2Attribute.Schedule1Checksum)]
+SCENES_ALONE = [int(C2Attribute.ConfiguredScenes), int(C2Attribute.ConfiguredScenesChecksum)]
+
+
 @pytest.mark.asyncio
 async def test_first_poll_reads_the_data_with_its_checksums():
     pump, cache = FakePump(), ConfigurationCache()
@@ -67,7 +75,10 @@ async def test_first_poll_reads_the_data_with_its_checksums():
     result = await pump.poll(cache)
 
     assert result.configuration_read == ("Schedule1", "ConfiguredScenes")
-    assert len(pump.batches) == 1
+    # The poll batch, then the schedule and the scenes each on their own.
+    assert pump.batches[1:] == [SCHEDULE_ALONE, SCENES_ALONE]
+    assert not _requested(pump, C2Attribute.Schedule1, batch=0)
+    assert not _requested(pump, C2Attribute.ConfiguredScenes, batch=0)
     assert cache.entries[int(C2Attribute.Schedule1)][0] == 0x1111
     assert cache.entries[int(C2Attribute.ConfiguredScenes)][0] == 0x2222
     assert result.pump_schedule_points[0].pump.params[PumpParam.MaxSpeed] == 500
@@ -80,7 +91,7 @@ async def test_unchanged_checksums_skip_the_data():
 
     result = await pump.poll(cache)
 
-    assert len(pump.batches) == 2
+    assert len(pump.batches) == 4  # one request for this poll
     assert not _requested(pump, C2Attribute.Schedule1)
     assert not _requested(pump, C2Attribute.ConfiguredScenes)
     assert _requested(pump, C2Attribute.Schedule1Checksum)
@@ -90,7 +101,7 @@ async def test_unchanged_checksums_skip_the_data():
 
 
 @pytest.mark.asyncio
-async def test_changed_checksum_reads_that_data_in_a_second_request():
+async def test_changed_checksum_reads_that_data_in_a_request_of_its_own():
     pump, cache = FakePump(), ConfigurationCache()
     await pump.poll(cache)
     pump.set(C2Attribute.Schedule1, [_point(700)])
@@ -98,8 +109,9 @@ async def test_changed_checksum_reads_that_data_in_a_second_request():
 
     result = await pump.poll(cache)
 
-    assert len(pump.batches) == 3
-    assert pump.batches[-1] == [int(C2Attribute.Schedule1), int(C2Attribute.Schedule1Checksum)]
+    # This poll: the batch, then the schedule alone; the scenes are cached.
+    assert len(pump.batches) == 5
+    assert pump.batches[-1] == SCHEDULE_ALONE
     assert result.configuration_read == ("Schedule1",)
     assert result.pump_schedule_points[0].pump.params[PumpParam.MaxSpeed] == 700
     assert cache.entries[int(C2Attribute.Schedule1)][0] == 0x3333
@@ -124,8 +136,7 @@ async def test_without_checksum_support_the_data_is_read_every_poll():
 
     result = await pump.poll(cache)
 
-    assert _requested(pump, C2Attribute.Schedule1)
-    assert _requested(pump, C2Attribute.ConfiguredScenes)
+    assert pump.batches[-2:] == [[int(C2Attribute.Schedule1)], [int(C2Attribute.ConfiguredScenes)]]
     assert result.configuration_read == ("Schedule1", "ConfiguredScenes")
     assert cache.entries == {}
 
@@ -141,13 +152,13 @@ async def test_attribute_table_change_is_reported_once():
 
 
 @pytest.mark.asyncio
-async def test_without_a_cache_nothing_changes():
+async def test_without_a_cache_the_data_is_read_in_its_own_requests():
     pump = FakePump()
     await pump.poll(None)
 
-    assert _requested(pump, C2Attribute.Schedule1)
-    assert not _requested(pump, C2Attribute.Schedule1Checksum)
-    assert not _requested(pump, C2Attribute.SupportedAttributesCRC)
+    assert pump.batches[1:] == [[int(C2Attribute.Schedule1)], [int(C2Attribute.ConfiguredScenes)]]
+    assert not _requested_in_any(pump, C2Attribute.Schedule1Checksum, pump.batches)
+    assert not _requested_in_any(pump, C2Attribute.SupportedAttributesCRC, pump.batches)
 
 
 @pytest.mark.asyncio
@@ -256,4 +267,23 @@ async def test_pump_operation_state_is_part_of_the_batch():
     result = await pump.poll(cache)
 
     assert result.operation_state == OperationState(2)
-    assert len(pump.batches) == 1
+    assert _requested(pump, C2Attribute.OperationState, batch=0)
+
+
+@pytest.mark.asyncio
+async def test_poll_batch_stays_small_with_a_large_schedule_and_scenes():
+    """A relay only carries replies up to a limit: the schedule and scenes
+    must never share a request with each other or with the rest."""
+    light, cache = FakePump(), ConfigurationCache()
+    light.set(C2Attribute.Schedule1, [_point(500)] * 25)
+    light.set(C2Attribute.ConfiguredScenes, [SCENE] * 10)
+
+    await light.device.get_full_poll_batch(
+        primitive=PrimitiveType.VisualV1, supported_attribute_ids=light.supported, cache=cache, minute_of_day=0,
+    )
+
+    big = {int(C2Attribute.Schedule1), int(C2Attribute.ConfiguredScenes)}
+    for batch in light.batches:
+        assert len(big & set(batch)) <= 1
+        if big & set(batch):
+            assert len(batch) <= 2  # the data and its checksum only

{python_mobius-0.10.0 → python_mobius-0.10.2}/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"]