python-mobius 0.1.0__py3-none-any.whl

mobius/manufacturer.py

@@ -0,0 +1,53 @@
+"""
+Manufacturer-data parsing (panId/model/serial from BLE advertisements, no
+GATT connection required) -- ported from Peripheral.parseManufactureData.
+
+Verified byte-for-byte against real devices: decoded model and serial from
+the advertisement match GATT-read values exactly. Company ID confirmed as
+0x0202 via bleak. Only the "version 2, length 25" branch (Java's bArr
+length; i.e. bleak's payload length 23, since bleak strips the 2-byte
+company-ID prefix Java's parser expects) is implemented, since that's the
+only one actually observed on real hardware -- the decompile has other
+branches for other manufacturer-data format versions/lengths that are not
+implemented here. See documentation/08-manufacturer-data.md.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+from typing import Optional
+
+from .constants import Model
+
+MOBIUS_COMPANY_ID = 0x0202
+
+
+@dataclass
+class MobiusAdvertisement:
+    model_raw: int
+    model: Optional[Model]
+    pan_id: int
+    device_specific_data: int
+    serial: str
+
+
+def parse_manufacturer_data(payload: bytes) -> Optional[MobiusAdvertisement]:
+    """
+    `payload` is bleak's AdvertisementData.manufacturer_data[MOBIUS_COMPANY_ID]
+    (i.e. WITHOUT the 2-byte company ID prefix -- bleak already strips it).
+    Only handles the 23-byte payload / Java-bArr-length-25 "version 2" format
+    actually observed on real hardware; returns None for anything else
+    rather than guessing at other branches.
+    """
+    if len(payload) != 23:
+        return None
+    model_val = struct.unpack_from("<H", payload, 0)[0]
+    try:
+        model = Model(model_val)
+    except ValueError:
+        model = None
+    device_specific = struct.unpack_from("<I", payload, 3)[0]
+    pan_id = struct.unpack_from("<H", payload, 7)[0]
+    serial = payload[9:23].decode("ascii", errors="replace")
+    return MobiusAdvertisement(model_val, model, pan_id, device_specific, serial)

mobius/schedule.py

@@ -0,0 +1,212 @@
+"""
+Schedule point parsing for both lights and pumps -- they share the exact
+same Schedule1/Schedule2 attribute and Point wire framing
+(time + flags + primitiveData), but interpret primitiveData differently and
+combine points differently:
+
+  - Lights (LightPrimitive): continuous curve. The app fetches the whole
+    schedule and linearly interpolates between the two bracketing points for
+    "now" -- there's no live "current intensity" read from the device at
+    all. See interpolate_light_schedule().
+
+  - Pumps (PumpPrimitive): discrete blocks. Point.getEnd() in the decompile
+    literally returns "the next point's start time" -- each point's mode
+    and parameters are active verbatim from its own start time until the
+    next point starts. See get_active_pump_block().
+
+See documentation/06-light-schedule.md and documentation/07-pump-schedule.md.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+from typing import Optional
+
+from .constants import (
+    VisualID, PumpMode, RampType, PumpParam,
+    PUMP_PARAM_SIZE, PUMP_MODE_PARAMS, PUMP_TIME_OFFSET_PARAMS, PUMP_TIME_OFFSET,
+)
+
+
+# --------------------------------------------------------------------------
+# Lights
+# --------------------------------------------------------------------------
+
+@dataclass
+class LightPrimitive:
+    """A set of (channel -> intensity 0-1000 permille) pairs. Wire format:
+    repeating [VisualID(u8), intensity(u16 LE)] triplets."""
+    channels: dict  # VisualID -> int (0-1000)
+
+    @classmethod
+    def parse(cls, data: bytes) -> "LightPrimitive":
+        channels = {}
+        for i in range(0, len(data) - 2, 3):
+            raw_id = data[i]
+            try:
+                vid = VisualID(raw_id)
+            except ValueError:
+                vid = VisualID.Unknown
+            intensity = struct.unpack_from("<H", data, i + 1)[0]
+            channels[vid] = intensity
+        return cls(channels)
+
+    def get(self, vid: VisualID) -> int:
+        return self.channels.get(vid, 0)
+
+
+@dataclass
+class SchedulePoint:
+    """Wire format: time(u16 LE, minutes-since-midnight) + flags(u8) + primitiveData."""
+    time_minutes: int
+    flags: int
+    light: LightPrimitive
+
+    FLAG_ACTIVE = 1
+    FLAG_NIGHT = 2
+    FLAG_SUNRISE = 6
+    FLAG_SUNSET = 10
+
+    @classmethod
+    def parse(cls, data: bytes) -> Optional["SchedulePoint"]:
+        if len(data) < 3:
+            return None
+        time_minutes = struct.unpack_from("<H", data, 0)[0]
+        flags = data[2]
+        if (flags & cls.FLAG_ACTIVE) != cls.FLAG_ACTIVE:
+            return None
+        return cls(time_minutes, flags, LightPrimitive.parse(data[3:]))
+
+    def has(self, flag: int) -> bool:
+        return (self.flags & flag) == flag
+
+
+def interpolate_light_schedule(points: list[SchedulePoint], minute_of_day: int) -> dict:
+    """
+    Port of PointSchedule.getIntensitiesAtTime(). Given the full set of
+    schedule points and a target time (0-1439, minutes since midnight),
+    returns {VisualID: intensity_permille} by linearly interpolating between
+    the two points that bracket that time, wrapping around midnight.
+    """
+    if not points:
+        return {}
+    pts = sorted(points, key=lambda p: p.time_minutes)
+    n = len(pts)
+    minute_of_day %= 1440
+
+    for i in range(n):
+        p1 = pts[i]
+        p2 = pts[(i + 1) % n]
+        t1 = p1.time_minutes
+        t2 = p2.time_minutes
+        if (i + 1) % n == 0:
+            # wrapping from the last point back to the first: treat the
+            # first point's time as being on "the next day"
+            t2 += 1440
+
+        m = minute_of_day if minute_of_day >= t1 else minute_of_day + 1440
+        if t1 <= m <= t2:
+            span = (t2 - t1) or 1
+            frac = (m - t1) / span
+            result = {}
+            all_channels = set(p1.light.channels) | set(p2.light.channels)
+            for ch in all_channels:
+                v1 = p1.light.get(ch)
+                v2 = p2.light.get(ch)
+                result[ch] = v1 + (v2 - v1) * frac
+            return result
+    return {}
+
+
+# --------------------------------------------------------------------------
+# Pumps
+# --------------------------------------------------------------------------
+
+@dataclass
+class PumpPrimitiveValue:
+    mode: PumpMode
+    params: dict  # PumpParam -> int, or RampType for the RampType param, or bytes for Master
+
+    @classmethod
+    def parse(cls, data: bytes) -> "PumpPrimitiveValue":
+        mode_byte = data[0] if data else 0
+        try:
+            mode = PumpMode(mode_byte)
+        except ValueError:
+            mode = PumpMode.Undefined
+        params = {}
+        offset = 1
+        for p in PUMP_MODE_PARAMS.get(mode, []):
+            size = PUMP_PARAM_SIZE[p]
+            raw = data[offset:offset + size]
+            offset += size
+            if len(raw) < size:
+                continue
+            if p == PumpParam.RampType:
+                try:
+                    params[p] = RampType(raw[0])
+                except ValueError:
+                    params[p] = raw[0]
+            elif p == PumpParam.Master:
+                # last-8-bytes BLE address of the master pump this one syncs to
+                params[p] = raw
+            elif size == 2:
+                val = struct.unpack("<h", raw)[0]
+                # negative values on MaxSpeed/MinSpeed encode reverse rotation
+                # direction -- reported as-is here rather than replicating the
+                # app's separate abs()/getReverse() split, so check the sign
+                # yourself if it matters.
+                if p in PUMP_TIME_OFFSET_PARAMS:
+                    val += PUMP_TIME_OFFSET
+                params[p] = val
+            elif size == 4:
+                val = struct.unpack("<i", raw)[0]
+                if p in PUMP_TIME_OFFSET_PARAMS:
+                    val += PUMP_TIME_OFFSET
+                params[p] = val
+        return cls(mode, params)
+
+
+@dataclass
+class PumpSchedulePoint:
+    """Wire format identical to SchedulePoint: time(u16 LE) + flags(u8) + primitiveData,
+    just with primitiveData decoded as a PumpPrimitive instead of a LightPrimitive."""
+    time_minutes: int
+    flags: int
+    pump: PumpPrimitiveValue
+
+    @classmethod
+    def parse(cls, data: bytes) -> Optional["PumpSchedulePoint"]:
+        if len(data) < 3:
+            return None
+        time_minutes = struct.unpack_from("<H", data, 0)[0]
+        flags = data[2]
+        if (flags & SchedulePoint.FLAG_ACTIVE) != SchedulePoint.FLAG_ACTIVE:
+            return None
+        return cls(time_minutes, flags, PumpPrimitiveValue.parse(data[3:]))
+
+
+def get_active_pump_block(points: list[PumpSchedulePoint], minute_of_day: int) -> Optional[PumpSchedulePoint]:
+    """
+    Unlike interpolate_light_schedule(), this does a block lookup, not a
+    blend: finds whichever point's [start, next_point_start) range contains
+    minute_of_day, wrapping at midnight. That point's mode+params are simply
+    "the currently active setting" -- no interpolation involved.
+    """
+    if not points:
+        return None
+    pts = sorted(points, key=lambda p: p.time_minutes)
+    n = len(pts)
+    minute_of_day %= 1440
+    for i in range(n):
+        p = pts[i]
+        nxt = pts[(i + 1) % n]
+        start = p.time_minutes
+        end = nxt.time_minutes
+        if (i + 1) % n == 0:
+            end += 1440
+        m = minute_of_day if minute_of_day >= start else minute_of_day + 1440
+        if start <= m < end:
+            return p
+    return pts[0]

python_mobius-0.1.0.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: python-mobius
+Version: 0.1.0
+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
+Project-URL: Issues, https://code.r3pek.org/r3pek/python-mobius/issues
+Author: r3pek
+License: GPL-2.0-only
+License-File: LICENSE
+Keywords: aquarium,ble,bleak,bluetooth,ecotech,fsci,mobius,radion,reef,vortech
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.9
+Requires-Dist: bleak>=0.21
+Provides-Extra: dev
+Requires-Dist: bleak-retry-connector>=3.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: retry
+Requires-Dist: bleak-retry-connector>=3.0; extra == 'retry'
+Description-Content-Type: text/markdown
+
+# python-mobius
+
+A reverse-engineered Python client for the BLE protocol used by "Mobius
+Ready" aquarium equipment — EcoTech Marine (VorTech pumps, Radion lights),
+AquaIllumination (Prime, Hydra), Neptune Systems, and NYOS.
+
+Built on [`bleak`](https://github.com/hbldh/bleak) for cross-platform BLE.
+
+**Not affiliated with or endorsed by any of these companies.** This is an
+independent reimplementation of the wire protocol for interoperability with
+hardware you own, derived from public community reverse-engineering work
+and analysis of the publicly-distributed Mobius Android app. See
+[`documentation/`](./documentation) for the full protocol writeup, with
+every field marked as either directly confirmed or explicitly flagged as
+inferred/experimental.
+
+## Status
+
+Alpha. Core protocol (framing, CRC, attribute get/set, scenes), pump
+telemetry, pump schedules, light schedules, and device discovery/grouping
+are implemented and verified against real hardware (two VorTech MP40QD
+pumps, two Radion XR15 G6 Pro lights). See
+[`documentation/10-known-gaps-and-open-questions.md`](./documentation/10-known-gaps-and-open-questions.md)
+for what isn't covered yet (dosers, environmental sensors, Thread/CoAP
+device relay).
+
+## Install
+
+```bash
+pip install python-mobius
+# or, for more robust BLE connection retries (recommended):
+pip install python-mobius[retry]
+```
+
+## Quick start
+
+```python
+import asyncio
+from mobius import scan_for_mobius_devices_with_info, group_by_pan_id, MobiusDevice
+
+async def main():
+    found = await scan_for_mobius_devices_with_info()
+    for pan_id, members in group_by_pan_id(found).items():
+        print(f"tank {pan_id:#06x}:")
+        for device, info in members:
+            print(f"  {device.address}  {info.model.name}  {info.serial}")
+
+    device, _info = found[0]
+    async with MobiusDevice(device) as d:
+        summary = await d.get_device_summary()
+        print(summary)
+
+asyncio.run(main())
+```
+
+Or from the command line:
+
+```bash
+mobius-scan --adapter hci0
+```
+
+## What you can do
+
+- **Discover devices** and group them by tank/mesh (`pan_id`), reading
+  model/serial straight from BLE advertisements — no connection required.
+- **Read pump telemetry**: current speed, estimated flow (GPH), operation
+  state, error state.
+- **Read pump schedules**: which mode (constant speed, tidal swell, pulse,
+  etc.) is active at any given time, exactly as programmed.
+- **Read light schedules**: per-channel intensity at any given time,
+  replicating the app's own client-side interpolation (there's no "current
+  intensity" attribute — lights only expose the programmed curve).
+- **Control scenes**: start feed mode, resume the normal schedule, or any
+  other configured scene.
+- **Low-level protocol access** (`build_frame`, `get_attribute`,
+  `set_attribute`, ...) if you want to go beyond what's wrapped in
+  `MobiusDevice`.
+
+## Supported device types
+
+| PrimitiveType | Support | Notes |
+|---|---|---|
+| `VisualV1` (Radion, Prime, Hydra, etc.) | ✅ Verified | Lights |
+| `VorTechV1`, `PumpV1`, `VectraV1`, `AlpacaV1`, `TurtleV1` | ✅ Verified | Pumps |
+| `CoffeeV1` (NYOS Quantum) | ⚠️ Experimental | Same wire structure as pumps per the protocol, untested against real hardware |
+| `DoseV1`, `HotSauceV1` | ❌ Unsupported | Different primitive format; identity info only |
+
+`MobiusDevice.get_device_summary()` always tells you which tier applies via
+its `"support"` field — see [`documentation/04-device-identity.md`](./documentation/04-device-identity.md).
+
+## Development
+
+```bash
+git clone https://code.r3pek.org/r3pek/python-mobius
+cd python-mobius
+pip install -e ".[dev]"
+pytest
+```
+
+Tests are validated against real captured packets and real device
+manufacturer-data/serials where possible — see `tests/`.
+
+## License
+
+GPLv2 — see [`LICENSE`](./LICENSE).
+
+## Acknowledgments
+
+The protocol reverse-engineering and implementation in this library were
+carried out with substantial assistance from Claude (Anthropic), used to
+analyze a decompiled copy of the official Mobius Android app (JADX) and
+cross-reference it against prior public community research (notably the
+Reef2Reef "Controlling Mobius enabled VorTech pump using 0-10V and BLE"
+thread and the `danmrossi/MobiusControl` project), then to design, write,
+and test the Python implementation itself. See
+[`documentation/00-overview.md`](./documentation/00-overview.md) for the
+full methodology and confirmation-strength notes on every protocol
+detail.

python_mobius-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+mobius/__init__.py,sha256=wtCy-JKP5KhFr3dq_C0V4458R-msyZt2EP96vH16Tr8,3281
+mobius/cli.py,sha256=uhGZIDrhpTp8LkTGOl4BZVQWgJYHbaIVH2HzX3RFCCs,2642
+mobius/constants.py,sha256=9OtNEOU4FXXhdgayGrz5e_T8s6M20UE31B6GQ-mywnY,12022
+mobius/crc.py,sha256=WwIfUXGN_UKdsv-_Q303-L1-L1Rc1fvJnB5176ftzqU,2669
+mobius/device.py,sha256=CbCQQjmLQmg-zFufRufcRPkA3PlO_18AkeCP_eDE0EA,19993
+mobius/discovery.py,sha256=4MjGwpd0bUK-koiZ-a2Cvq-gCTImAKAQ4lZ-9vOge3Q,2290
+mobius/frame.py,sha256=zG2vh8PceJHD8R43MwZiJnm0Ge1dr8nFcKsJR9_c9LM,6135
+mobius/manufacturer.py,sha256=8-vBzckN8xmsPSMj5EWtOCXenbyQueoY5pnZHePgb_k,1937
+mobius/schedule.py,sha256=kHr684TIKPZ2BplIySoeD-Yn1Xa_2bE6rfGUs-waWMQ,7483
+python_mobius-0.1.0.dist-info/METADATA,sha256=pwoXT7fGt7RyDQKMvRzjvNJZaaFtzENzOUWI_OwmELs,5907
+python_mobius-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+python_mobius-0.1.0.dist-info/entry_points.txt,sha256=Q2hlcek-bWm70zvd12v32essflPgC2su-dKDHAqbPoE,48
+python_mobius-0.1.0.dist-info/licenses/LICENSE,sha256=7a72Msu2Q-TnoiFxemxEGkwafJGObk1W3rw9hzmyM_Y,17984
+python_mobius-0.1.0.dist-info/RECORD,,

python_mobius-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

python_mobius-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mobius-scan = mobius.cli:main