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

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

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.1.1
+
+- Added `manufacturer_for_model()` / `MODEL_MANUFACTURER` (ported from
+  `M.Model.getManufacturer()`) — surfaces "EcoTech Marine" /
+  "AquaIllumination" / "Neptune Systems" / "NYOS" per device model. Now
+  included automatically in `get_device_info()`'s `"manufacturer"` field.
+  Added while building a Home Assistant integration on top of this library,
+  which needs a manufacturer string for its device registry.
+- `get_device_info()`'s `"serial"` field is now decoded as ASCII text
+  instead of hex-encoded raw bytes (e.g. `"7V4Z00F143RBED"` instead of
+  `"3756345a30304631343352424544"`). Confirmed printable ASCII on every
+  device tested, via cross-validation against the same serial parsed from
+  BLE advertisement manufacturer data. Falls back to hex for any
+  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.
+
 ## 0.1.0 — initial release
 
 - Core FSCI/C2CI wire protocol: framing, CRC16, Get/Set-attribute codec.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-mobius
-Version: 0.1.0
+Version: 0.1.1
 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.1.0 → python_mobius-0.1.1}/documentation/10-known-gaps-and-open-questions.md

@@ -34,6 +34,16 @@ included as a starting point.
 - **`MACAddress`** (attribute 103): returned empty/unpopulated on every
   device tested. Might be Thread/legacy-radio-only and simply not set on
   BLE-only-provisioned devices, or might need a different query context.
+- **The unit of `PhysicalValueID.GallonsPerHour`**: high confidence it's
+  genuinely US gallons per hour, not empirically flow-metered. Basis: (1)
+  the decompiled source's own attribute name is literally
+  `GallonsPerHour`, EcoTech's own naming, not an inference; (2) EcoTech is
+  a US company that markets VorTech flow exclusively in GPH; (3) real
+  captured values (2,272 and 2,877 GPH, both from the same partial-power
+  speed setting) land at roughly 45-65% of the MP40wQD's own published
+  4,500-5,000+ GPH max rating -- exactly the proportion expected for a
+  pump running below full power. No independent flow-meter verification
+  has been done against real hardware.
 
 ## Deliberately not implemented
 

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

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

@@ -23,7 +23,8 @@ from .frame import (
 from .constants import (
     PrimitiveType, PRIMITIVE_SIZE, LIGHT_PRIMITIVES,
     PUMP_PRIMITIVES_VERIFIED, PUMP_PRIMITIVES_EXPERIMENTAL,
-    Model, ErrorState, C2Attribute, PhysicalValueID, VisualID,
+    Model, MODEL_MANUFACTURER, manufacturer_for_model,
+    ErrorState, C2Attribute, PhysicalValueID, VisualID,
     SceneID, OperationState, FsciStatus,
     PumpMode, RampType, PumpParam, PUMP_PARAM_SIZE, PUMP_MODE_PARAMS,
 )
@@ -40,7 +41,7 @@ from .discovery import (
     scan_for_mobius_devices, scan_for_mobius_devices_with_info, group_by_pan_id,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 
 __all__ = [
     "__version__",
@@ -57,7 +58,8 @@ __all__ = [
     # constants
     "PrimitiveType", "PRIMITIVE_SIZE", "LIGHT_PRIMITIVES",
     "PUMP_PRIMITIVES_VERIFIED", "PUMP_PRIMITIVES_EXPERIMENTAL",
-    "Model", "ErrorState", "C2Attribute", "PhysicalValueID", "VisualID",
+    "Model", "MODEL_MANUFACTURER", "manufacturer_for_model",
+    "ErrorState", "C2Attribute", "PhysicalValueID", "VisualID",
     "SceneID", "OperationState", "FsciStatus",
     "PumpMode", "RampType", "PumpParam", "PUMP_PARAM_SIZE", "PUMP_MODE_PARAMS",
     # schedule

{python_mobius-0.1.0 → python_mobius-0.1.1}/src/mobius/constants.py

@@ -11,6 +11,7 @@ See documentation/ for the full derivation of each table.
 from __future__ import annotations
 
 from enum import IntEnum
+from typing import Optional
 
 
 # --------------------------------------------------------------------------
@@ -107,6 +108,65 @@ class Model(IntEnum):
     Coffee2 = 397            # "Quantum 220/300" (NYOS)
 
 
+# Ported from M.Model.getManufacturer(). The decompiled version branches on
+# enum *ordinal* against a hardcoded position list (the full ~100-entry
+# Model enum's index 1-37 range, plus a few extras, all map to "EcoTech
+# Marine"); since this library only implements a curated subset of Model,
+# this is re-derived by name pattern against that same logic instead of by
+# ordinal position -- functionally equivalent for every Model value defined
+# above, but if you add more Model entries, add their manufacturer here too.
+MODEL_MANUFACTURER: dict[Model, str] = {
+    Model.Unknown: "Unknown",
+    Model.VorTechMP10wES: "EcoTech Marine",
+    Model.VorTechMP10wQD: "EcoTech Marine",
+    Model.VorTechMP40wES: "EcoTech Marine",
+    Model.VorTechMP40wQD: "EcoTech Marine",
+    Model.VorTechMP40wG3QD: "EcoTech Marine",
+    Model.VorTechMP60wES: "EcoTech Marine",
+    Model.VorTechMP60wQD: "EcoTech Marine",
+    Model.RadionXR30w: "EcoTech Marine",
+    Model.RadionXR30wG2: "EcoTech Marine",
+    Model.RadionXR30wPro: "EcoTech Marine",
+    Model.RadionXR30wG3: "EcoTech Marine",
+    Model.RadionXR30wG3Pro: "EcoTech Marine",
+    Model.RadionXR30wG4: "EcoTech Marine",
+    Model.RadionXR30wG4Pro: "EcoTech Marine",
+    Model.RadionXR30wFWPro: "EcoTech Marine",
+    Model.RadionXR30wPrototype: "EcoTech Marine",
+    Model.RadionXR15wG3Pro: "EcoTech Marine",
+    Model.RadionXR15wFW: "EcoTech Marine",
+    Model.RadionXR15wG4Pro: "EcoTech Marine",
+    Model.RadionXR15wFWPro: "EcoTech Marine",
+    Model.RadionXR15wPrototype: "EcoTech Marine",
+    Model.RadionXR15G5Pro: "EcoTech Marine",
+    Model.RadionXR15wG5Blue: "EcoTech Marine",
+    Model.RadionXR15wG5FW: "EcoTech Marine",
+    Model.RadionXR15wG6Pro: "EcoTech Marine",
+    Model.RadionXR15wG6Blue: "EcoTech Marine",
+    Model.RadionXR30wG5Pro: "EcoTech Marine",
+    Model.RadionXR30wG5Blue: "EcoTech Marine",
+    Model.VectraM1: "EcoTech Marine",
+    Model.VectraL1: "EcoTech Marine",
+    Model.VectraS1: "EcoTech Marine",
+    Model.VectraS2: "EcoTech Marine",
+    Model.VectraM2: "EcoTech Marine",
+    Model.VectraL2: "EcoTech Marine",
+    Model.Nero5: "AquaIllumination",
+    Model.Nero3: "AquaIllumination",
+    Model.DosingPump: "AquaIllumination",
+    Model.Muffler: "Neptune Systems",   # confirmed explicitly in the decompile's manufacturer list
+    Model.Coffee1: "NYOS",               # confirmed explicitly (CoffeeV1 branch)
+    Model.Coffee2: "NYOS",
+}
+
+
+def manufacturer_for_model(model: Optional[Model]) -> Optional[str]:
+    """Returns the manufacturer name for a Model, or None if unknown/unmapped."""
+    if model is None:
+        return None
+    return MODEL_MANUFACTURER.get(model)
+
+
 class ErrorState(IntEnum):
     """Confirmed literal values from M.ErrorState (subset covering common
     pump/light fault codes -- the full enum also has dosing-pump-specific codes)."""

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

@@ -29,7 +29,7 @@ from .frame import (
 )
 from .constants import (
     C2Attribute, PrimitiveType, Model, ErrorState, SceneID, OperationState,
-    FsciStatus, PhysicalValueID, VisualID,
+    FsciStatus, PhysicalValueID, VisualID, manufacturer_for_model,
     PRIMITIVE_SIZE, LIGHT_PRIMITIVES, PUMP_PRIMITIVES_VERIFIED, PUMP_PRIMITIVES_EXPERIMENTAL,
 )
 from .schedule import (
@@ -48,6 +48,25 @@ CHAR_TX_DATA = "01ff0103-ba5e-f4ee-5ca1-eb1e5e4b1ce0"   # write: app -> device,
 CHAR_TX_FINAL = "01ff0104-ba5e-f4ee-5ca1-eb1e5e4b1ce0"  # write: app -> device, last fragment
 
 
+def _decode_serial(raw: bytes) -> str:
+    """
+    Serial numbers are printable ASCII on every device tested (confirmed by
+    cross-validating the GATT-read serial against the same serial parsed
+    from BLE advertisement manufacturer data -- see manufacturer.py and
+    documentation/08-manufacturer-data.md), so decode as text rather than
+    hex-encoding raw bytes. Falls back to hex for any non-printable-ASCII
+    edge case not yet observed, rather than raising.
+    """
+    text = raw.rstrip(b"\x00")
+    try:
+        decoded = text.decode("ascii")
+    except UnicodeDecodeError:
+        return raw.hex()
+    if decoded and all(32 <= ord(c) < 127 for c in decoded):
+        return decoded
+    return raw.hex()
+
+
 class MobiusDevice:
     """
     High-level async client for a single Mobius-protocol BLE device.
@@ -252,8 +271,9 @@ class MobiusDevice:
         return {
             "model_raw": model_val,
             "model": model.name if model is not None else (f"unknown({model_val})" if model_val is not None else None),
+            "manufacturer": manufacturer_for_model(model),
             "name": name_raw.decode("utf-8", errors="replace").rstrip("\x00") if name_raw else None,
-            "serial": serial_raw.hex() if serial_raw else None,
+            "serial": _decode_serial(serial_raw) if serial_raw else None,
             "primitive_type": PrimitiveType(primitive_raw[0]).name if primitive_raw else None,
             "error_state": error.name if error is not None else (f"unknown({error_val})" if error_val is not None else None),
             "mac_address": ":".join(f"{b:02X}" for b in mac_raw) if mac_raw else None,

python_mobius-0.1.1/tests/test_manufacturer_lookup.py

@@ -0,0 +1,26 @@
+from mobius import Model, manufacturer_for_model
+
+
+def test_vortech_is_ecotech_marine():
+    assert manufacturer_for_model(Model.VorTechMP40wG3QD) == "EcoTech Marine"
+
+
+def test_radion_is_ecotech_marine():
+    assert manufacturer_for_model(Model.RadionXR15wG6Pro) == "EcoTech Marine"
+
+
+def test_nero_is_aquaillumination():
+    assert manufacturer_for_model(Model.Nero5) == "AquaIllumination"
+
+
+def test_coffee_is_nyos():
+    assert manufacturer_for_model(Model.Coffee1) == "NYOS"
+    assert manufacturer_for_model(Model.Coffee2) == "NYOS"
+
+
+def test_muffler_is_neptune_systems():
+    assert manufacturer_for_model(Model.Muffler) == "Neptune Systems"
+
+
+def test_none_model_returns_none():
+    assert manufacturer_for_model(None) is None

python_mobius-0.1.1/tests/test_serial_decoding.py

@@ -0,0 +1,20 @@
+from mobius.device import _decode_serial
+
+
+def test_decodes_real_pump_serial_as_ascii():
+    # Real captured serial from a VorTech MP40QD pump.
+    assert _decode_serial(bytes.fromhex("3736343935323231303539303139")) == "76495221059019"
+
+
+def test_decodes_real_light_serial_as_ascii():
+    # Real captured serial from a Radion XR15 G6 Pro.
+    assert _decode_serial(bytes.fromhex("3756345a30304631343352424544")) == "7V4Z00F143RBED"
+
+
+def test_strips_trailing_nulls():
+    assert _decode_serial(b"ABC123\x00\x00\x00") == "ABC123"
+
+
+def test_falls_back_to_hex_for_non_ascii():
+    raw = bytes([0, 1, 2, 3])
+    assert _decode_serial(raw) == raw.hex()