python-mobius 0.1.1__tar.gz → 0.1.2__tar.gz

{python_mobius-0.1.1 → python_mobius-0.1.2}/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## 0.1.1
+## 0.1.2
 
 - Added `manufacturer_for_model()` / `MODEL_MANUFACTURER` (ported from
   `M.Model.getManufacturer()`) — surfaces "EcoTech Marine" /
@@ -16,6 +16,29 @@
   non-printable-ASCII edge case not yet observed. Found while building the
   Home Assistant integration on top of this library -- the hex-encoded
   serial was producing unnecessarily long/ugly entity IDs.
+- `get_pump_telemetry()` now includes a confirmed `"speed_percent"` field
+  alongside the existing raw `"speed"`. `MotorSpeed` is confirmed (via the
+  decompiled app's own display code) to be a percentage of max pump power
+  in tenths of a percent, NOT RPM -- `String.format("%.0f%%",
+  Math.abs(currentSpeed / 10.0f))` is literally what the app does to this
+  exact value. `speed_percent` is that same `abs(speed)/10` conversion;
+  `speed` is still returned raw since its sign encodes rotation direction
+  (reverse), which `speed_percent` discards.
+- Fixed a real connection leak in `MobiusDevice.connect()`: if
+  `start_notify()` failed after the BLE connection was already
+  established (a known common flaky point right after a fresh connection),
+  the exception propagated out of `connect()` (`__aenter__`) -- and per the
+  async context manager protocol, a raising `__aenter__` means `__aexit__`
+  (and therefore `disconnect()`) is never called by the caller's `async
+  with` block. The already-open connection was left orphaned on the
+  adapter. Since callers like Home Assistant coordinators retry
+  periodically, this leak compounded over repeated failures, plausibly
+  exhausting a real adapter's connection-slot pool over time even with no
+  other integration competing for it and without any range/signal issue.
+  `connect()` now cleans up (disconnects) before re-raising if anything
+  fails after the connection is established. Added regression tests
+  confirming both the cleanup-on-failure and no-spurious-disconnect-on-
+  success behavior.
 
 ## 0.1.0 — initial release
 

{python_mobius-0.1.1 → python_mobius-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-mobius
-Version: 0.1.1
+Version: 0.1.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
@@ -24,6 +24,7 @@ Requires-Python: >=3.9
 Requires-Dist: bleak>=0.21
 Provides-Extra: dev
 Requires-Dist: bleak-retry-connector>=3.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Provides-Extra: retry
 Requires-Dist: bleak-retry-connector>=3.0; extra == 'retry'

{python_mobius-0.1.1 → python_mobius-0.1.2}/documentation/03-attributes-and-opcodes.md

@@ -87,7 +87,7 @@ against real pumps and lights returned correctly-structured, sane data.
 | `ErrorState` | 107 | See [04-device-identity.md](./04-device-identity.md) |
 | `CurrentScene` | 401 | Set to `sceneId(u16 LE) + durationMinutes(u16 LE)` to start a scene |
 | `Schedule1` / `Schedule2` | 500 / 503 | The programmed point-schedule — see 06/07 |
-| `MotorSpeed` | 700 | Live pump speed (int16) |
+| `MotorSpeed` | 700 | Live pump speed (int16). Confirmed NOT RPM -- percentage of max power in tenths of a percent (abs(value)/10 = %); sign encodes rotation direction. Confirmed via the app's own display code, `String.format("%.0f%%", Math.abs(currentSpeed / 10.0f))`. |
 | `SupportedColorChannels` | 901 | Static list of a light's channels |
 
 See `src/mobius/constants.py` for the complete implemented list.

{python_mobius-0.1.1 → python_mobius-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-mobius"
-version = "0.1.1"
+version = "0.1.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" }
@@ -35,7 +35,7 @@ dependencies = [
 
 [project.optional-dependencies]
 retry = ["bleak-retry-connector>=3.0"]
-dev = ["pytest>=7.0", "bleak-retry-connector>=3.0"]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.23", "bleak-retry-connector>=3.0"]
 
 [project.scripts]
 mobius-scan = "mobius.cli:main"
@@ -50,3 +50,4 @@ packages = ["src/mobius"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+asyncio_mode = "auto"

{python_mobius-0.1.1 → python_mobius-0.1.2}/src/mobius/__init__.py

@@ -41,7 +41,7 @@ from .discovery import (
     scan_for_mobius_devices, scan_for_mobius_devices_with_info, group_by_pan_id,
 )
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"
 
 __all__ = [
     "__version__",

{python_mobius-0.1.1 → python_mobius-0.1.2}/src/mobius/device.py

@@ -131,8 +131,29 @@ class MobiusDevice:
                     if attempt == 2:
                         raise
                     await asyncio.sleep(2.0)
-        await self._client.start_notify(CHAR_RX_DATA, self._on_rx_data)
-        await self._client.start_notify(CHAR_RX_FINAL, self._on_rx_final)
+
+        # IMPORTANT: from here on, self._client holds a real, already-open
+        # BLE connection. If anything below fails, connect() (== __aenter__)
+        # raises -- and per the async context manager protocol, a raising
+        # __aenter__ means __aexit__/disconnect() is NEVER called by the
+        # caller's `async with` block. Without this try/except, a failure
+        # here would leak an orphaned open connection on the adapter every
+        # single time it happens -- and since coordinators retry on a timer,
+        # that leak compounds over repeated failures until the adapter's
+        # real connection-slot pool is exhausted, independent of range or
+        # any other integration. Confirmed as the likely cause of "no
+        # available connection slot" errors appearing over time rather than
+        # immediately, reported against real hardware.
+        try:
+            await self._client.start_notify(CHAR_RX_DATA, self._on_rx_data)
+            await self._client.start_notify(CHAR_RX_FINAL, self._on_rx_final)
+        except Exception:
+            try:
+                if self._client.is_connected:
+                    await self._client.disconnect()
+            except Exception:
+                pass  # best-effort cleanup; the original error is what matters
+            raise
 
     async def disconnect(self):
         if self._client and self._client.is_connected:
@@ -345,12 +366,24 @@ class MobiusDevice:
 
     async def get_pump_telemetry(self) -> dict:
         """
-        Returns {"speed": int, "gph": int}. Both are genuinely read live from
-        the device -- confirmed via FlowRange.java, which is what the app's
-        dashboard actually queries for the pump gauge widget.
+        Returns {"speed": int, "speed_percent": float, "gph": int}. speed
+        and gph are genuinely read live from the device -- confirmed via
+        FlowRange.java, which is what the app's dashboard actually queries
+        for the pump gauge widget.
 
         "gph" comes from PhysicalValues/GallonsPerHour (int32 LE).
-        "speed" comes from MotorSpeed directly (int16).
+
+        "speed" comes from MotorSpeed directly (int16). CONFIRMED (not
+        inferred) to be a percentage of max pump power in tenths of a
+        percent, not RPM: the app's own display code does
+        `String.format("%.0f%%", Math.abs(currentSpeed / 10.0f))` on this
+        exact value (FlowFragment.java/WidgetViewCell.java). "speed_percent"
+        is that same abs(speed)/10 conversion, provided as a convenience --
+        the sign of the raw "speed" value encodes rotation direction
+        (reverse), matching the same convention as the schedule's MaxSpeed
+        parameter (see PumpPrimitiveValue), so check the sign of "speed"
+        yourself if direction matters; speed_percent is always non-negative.
+
         MotorRPM is defined in the protocol but never queried anywhere in the
         app -- not included here since it's unconfirmed whether firmware
         actually populates it.
@@ -361,7 +394,8 @@ class MobiusDevice:
         )
         speed = struct.unpack("<h", speed_raw[0])[0] if speed_raw else None
         gph = struct.unpack("<i", gph_raw[0])[0] if gph_raw else None
-        return {"speed": speed, "gph": gph}
+        speed_percent = abs(speed) / 10 if speed is not None else None
+        return {"speed": speed, "speed_percent": speed_percent, "gph": gph}
 
     # ---- light schedule (Radion/XR15 etc.) --------------------------------
 

python_mobius-0.1.2/tests/test_connection_cleanup.py

@@ -0,0 +1,107 @@
+"""
+Regression test for a real leak: if start_notify() fails after the BLE
+connection is already established, connect() (== __aenter__) must clean up
+the connection before re-raising -- otherwise a raising __aenter__ means
+__aexit__/disconnect() is never called by the caller's `async with` block,
+leaking an orphaned open connection on the adapter every time it happens.
+"""
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from bleak.backends.device import BLEDevice
+
+from mobius.device import MobiusDevice
+
+
+def _fake_ble_device():
+    return BLEDevice("AA:BB:CC:DD:EE:FF", "MOBIUS", {})
+
+
+@pytest.mark.asyncio
+async def test_failed_start_notify_disconnects_before_raising():
+    fake_client = MagicMock()
+    fake_client.is_connected = True
+    fake_client.disconnect = AsyncMock()
+    fake_client.start_notify = AsyncMock(side_effect=RuntimeError("GATT notify setup failed"))
+
+    async def fake_establish_connection(*args, **kwargs):
+        return fake_client
+
+    with patch("mobius.device.establish_connection", side_effect=fake_establish_connection), \
+         patch("mobius.device._HAVE_RETRY_CONNECTOR", True):
+        device = MobiusDevice(_fake_ble_device())
+        with pytest.raises(RuntimeError, match="GATT notify setup failed"):
+            await device.connect()
+
+    # The key assertion: even though connect() raised, the already-open
+    # connection was cleaned up rather than left orphaned.
+    fake_client.disconnect.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_successful_connect_does_not_disconnect():
+    fake_client = MagicMock()
+    fake_client.is_connected = True
+    fake_client.disconnect = AsyncMock()
+    fake_client.start_notify = AsyncMock(return_value=None)
+
+    async def fake_establish_connection(*args, **kwargs):
+        return fake_client
+
+    with patch("mobius.device.establish_connection", side_effect=fake_establish_connection), \
+         patch("mobius.device._HAVE_RETRY_CONNECTOR", True):
+        device = MobiusDevice(_fake_ble_device())
+        await device.connect()
+
+    fake_client.disconnect.assert_not_awaited()
+    assert device._client is fake_client
+
+
+@pytest.mark.asyncio
+async def test_pump_telemetry_speed_percent_matches_app_formula():
+    """
+    Confirmed (not inferred) against the decompiled app's own display code:
+    FlowFragment.java / WidgetViewCell.java format MotorSpeed as
+    String.format("%.0f%%", Math.abs(currentSpeed / 10.0f)) -- i.e. speed is
+    a percentage of max power in tenths of a percent, not RPM, with sign
+    encoding rotation direction. Uses real captured values from a live
+    VorTech pump (speed=447 -> 44.7%).
+    """
+    fake_client = MagicMock()
+    fake_client.is_connected = True
+    fake_client.disconnect = AsyncMock()
+    fake_client.start_notify = AsyncMock(return_value=None)
+
+    device = MobiusDevice(_fake_ble_device())
+    device._client = fake_client
+
+    async def fake_get_attribute(attr_id, index=0, count=1):
+        if attr_id == 700:  # MotorSpeed
+            return [(447).to_bytes(2, "little", signed=True)]
+        return [(2272).to_bytes(4, "little", signed=True)]  # GallonsPerHour
+
+    device.get_attribute = fake_get_attribute
+    telemetry = await device.get_pump_telemetry()
+
+    assert telemetry["speed"] == 447
+    assert telemetry["speed_percent"] == 44.7
+    assert telemetry["gph"] == 2272
+
+
+@pytest.mark.asyncio
+async def test_pump_telemetry_speed_percent_is_always_nonnegative():
+    """A negative raw speed (reverse rotation) should still give a
+    non-negative speed_percent."""
+    device = MobiusDevice(_fake_ble_device())
+
+    async def fake_get_attribute(attr_id, index=0, count=1):
+        if attr_id == 700:
+            return [(-447).to_bytes(2, "little", signed=True)]
+        return [(2272).to_bytes(4, "little", signed=True)]
+
+    device.get_attribute = fake_get_attribute
+    telemetry = await device.get_pump_telemetry()
+
+    assert telemetry["speed"] == -447
+    assert telemetry["speed_percent"] == 44.7