python-mobius 0.8.4__tar.gz → 0.9.0__tar.gz

python_mobius-0.9.0/CHANGELOG.md

@@ -0,0 +1,237 @@
+# Changelog
+
+## 0.9.0
+
+- **Breaking:** `RelayedMobiusDevice` writes now raise an error when the
+  device rejects them, like direct writes already did.
+- Added helpers shared with ha-mobius: `enum_or_none()`,
+  `primitive_type_from_name()`, `support_tier()`, `parse_advertisement()`,
+  `schedule_capacity()`/`min_schedule_capacity()`, `format_mesh_address()`,
+  `pump_params_to_dict()`, `Scene.is_empty` and `PUMP_PRIMITIVES`.
+- Added pump battery settings: `set_battery_backup_speed()` (limited to the
+  pump's battery backup max speed) and `set_boosted_battery()` (only while
+  running on battery), with the `--set-battery-backup-speed` and
+  `--set-boosted-battery-*` options.
+- Added `get_operation_mode()` and the `OperationMode` enum; pump telemetry
+  now includes `operation_mode` (`"BatteryBackup"` while running on
+  battery).
+- `get_full_poll_batch()` now includes the battery settings
+  (`battery_backup`, `boosted_battery`) and the operation mode.
+- The boosted battery power is permille (0-100 %) and its on/off times are
+  seconds.
+- `mobius-scan`: the debug mesh listing now shows peer age as unsigned, like
+  the library.
+- **Breaking:** fixed the running scene's remaining time: it's now read from
+  `SceneTimer`, so it counts down, and `ActiveScene.timeout_seconds` holds
+  the scene's total time. `get_current_scene()` returns None when no scene
+  is running.
+- Starting a scene, returning to the schedule and restarting all devices now
+  use the tank's group, like the app (`get_tank_group()`, `tank_group()`).
+  **Breaking:** `resume_schedule()` now ends the scene on every device of
+  the tank with one write (`broadcast=False` for one device only).
+- **Breaking:** `set_pump_schedule()` now rejects parameters outside the
+  ranges the app allows (for example a Short Pulse time of 0), before
+  writing. Added `pump_param_range()` and `pump_param_errors()`.
+- Internal cleanup: removed duplicated code and simplified comments.
+
+## 0.8.4
+
+- Added `LightPollResult.lunar_enabled` and `lunar_phase_day`, valid at any
+  time of day (the matching `diagnostics` keys are only set at night).
+
+## 0.8.3
+
+- Added `set_lunar_enabled(enabled)`: the value the app's Lunar chip
+  writes.
+
+## 0.8.2
+
+- Added `LightPollResult.schedule_intensity`: the schedule intensity
+  setting (unlike `diagnostics["scalar"]`, which is the lunar reduction at
+  night).
+
+## 0.8.1
+
+- Added `get_pump_reverse(primitive_type, params)`: whether a pump
+  point's speed means reverse rotation (AlpacaV1 only).
+- Added `reboot_all()`: restarts every device of the tank, like the app's
+  "Restart all Devices".
+
+## 0.8.0
+
+- Added `supported_pump_modes(primitive_type, closed_loop=None)`: the pump
+  modes each pump supports (see `documentation/07-pump-schedule.md`,
+  "Modes per pump").
+- Added schedule writing: `set_light_schedule()`, `set_pump_schedule()`,
+  `GroupBitmap` (`group_mask`), and the `--dump-schedule-file` /
+  `--load-schedule-file` options.
+- Added `.mob` template files: export and import for light and pump
+  schedules, and the `--dump-mob-file` / `--load-mob-file` options.
+- Loading a schedule into a light now also writes every light in its
+  schedule group, after checking the group's smallest capacity.
+- `get_pump_telemetry()` now includes every other sensor value the pump
+  reports (`extra_physical_values`).
+- Added `get_extra_physical_values()`, also shown for lights in
+  `get_device_summary()`.
+- Added `get_fan_thresholds()`.
+
+## 0.7.2
+
+- `get_full_poll_batch()` now includes the scenes.
+- `start_scene()` / `start_feed_mode()` now apply to the whole tank by
+  default; `broadcast=False` writes one device only.
+
+## 0.7.1
+
+- Added scenes: `get_configured_scenes()`, `get_current_scene()`,
+  `start_scene()`.
+- Fixed `get_current_scene()` failing on user-created scenes.
+- `start_scene()`'s duration is in seconds (it was documented as minutes).
+
+## 0.7.0
+
+- Added `get_full_poll_batch()`: everything a poll needs in one request,
+  2-2.6× faster.
+- Added `get_light_poll_batch()`: a light's schedule and intensity inputs
+  in one request.
+- `get_current_pump_block()` accepts an already-read schedule (`points`).
+
+## 0.6.0
+
+- Added `get_metadata_batch()`: settings, calibration, firmware, hardware,
+  channels, error state and clock in one request (6-14× faster over the
+  relay), with a fallback to individual reads (`used_batch`,
+  `force_individual_reads`).
+- Added `get_attributes_batch()`: several attributes in one request.
+- Added attribute dumps: `get_supported_attributes()`,
+  `dump_attributes()`, `enrich_attribute_dump()` and the
+  `--dump-attributes` / `--parse-dump` options.
+- Added `set_advanced_features()` and the `--set-local-control-enabled`,
+  `--set-auto-dim-timeout`, `--set-max-fan-speed` and
+  `--set-fan-shutdown-enabled` options.
+- The lunar calculation now uses the same date as the app, so the values
+  match what the app shows.
+- Fixed `RelayedMobiusDevice` not relaying `get_supported_attributes()`
+  and `get_attributes_batch()`.
+- Fixed `--dump-attributes` and `--set-time-to-now` ignoring
+  `--relay-target`.
+
+## 0.5.0
+
+- `get_pump_telemetry()` now returns `gph_reliable`, `minimum_gph` and
+  `maximum_gph`; flow is only reliable when the pump reports a flow range.
+- Added `motor_power_watts` to `get_pump_telemetry()` (Vectra, NYOS
+  Quantum).
+- Added support for AquaIllumination devices (company ID `0x0001`).
+  **Breaking:** `MOBIUS_COMPANY_ID` is now `MOBIUS_COMPANY_ID_ECOTECH`.
+- Added `get_lunar_phase_info()` (the device's own lunar state) and show
+  it in `--dump-schedule`. Read errors are now raised instead of
+  returning `None`.
+- Added `get_advanced_features()`, `get_vectra_info()` and
+  `get_coffee_info()`.
+- Added `set_time_to_now()` (sets the clock of the whole tank) and
+  `reboot()`.
+- Fixed firmware labels for AquaIllumination devices.
+- A relayed device that timed out now fails its other reads in the same
+  poll immediately.
+
+## 0.4.4
+
+- The device model list is now complete (EcoTech Marine,
+  AquaIllumination, Neptune Systems, NYOS). `Model.VersaVX1` is now listed
+  under EcoTech Marine.
+- Several models are now named after their product (e.g. `Model.Axis40`,
+  `Model.Blade`, `Model.Quantum160`).
+- Fixed the lunar-dimmed light intensity disagreeing with the app for
+  hours at a time.
+
+## 0.4.3
+
+- Relayed reads are retried once before failing, like the app does.
+
+## 0.4.2
+
+- Fixed `MeshPeer.age` being read as signed. It is the time since the peer
+  was last heard on the mesh, so it can go down.
+- Fixed `mobius-scan --dump-schedule` failing for pumps.
+
+## 0.4.1
+
+- Fixed `discover_tank()` sometimes listing the connected device twice.
+
+## 0.4.0
+
+- Added mesh discovery through `NetworkedThreadDevices`, which works
+  without an MXM hub: `discover_networked_thread_devices()`, `MeshPeer.age`
+  and `mesh_local_prefix_from_mlprefix()`.
+- Added `discover_mesh_peers_auto()`, the recommended way to discover the
+  tank's devices.
+- Added `Tank` and `discover_tank()`: every device of a tank with its mesh
+  address and age.
+- `mobius-scan` now lists devices by tank and connects to one device to
+  show the tank's mesh addresses; `--scan-only` skips connecting,
+  `--full-summaries` connects to every device and `--dump-tanks` shows
+  every tank.
+
+## 0.3.1
+
+- Fixed the Brightness channel not dimming the other channels, which
+  made light intensities too high.
+
+## 0.3.0
+
+- Fixed lunar dimming being applied to the wrong part of the night.
+- `get_hardware_info()` now returns labels for colour, product, radio and
+  motor type, and is included in `get_device_summary()`.
+
+## 0.2.1
+
+- Fixed lists that the device returns in several parts being cut short
+  (for example some firmware versions were missing).
+
+## 0.2.0
+
+- Added relaying through the Thread mesh: `RelayedMobiusDevice` reaches
+  every device of a tank through one BLE connection. Added `mobius.coap`
+  and `mobius.mesh_address`.
+- Added mesh discovery: `get_own_mesh_address()`,
+  `discover_mesh_peers()` (MXM hub) and
+  `discover_mesh_peers_via_direct_connect()`.
+- Added the `mobius-scan` options `--dump-mesh-peers`, `--relay-target`,
+  `--debug-relay`, `--build-peer-map` and `--dump-schedule`.
+- Added `get_device_time_info()` (clock drift).
+- `get_current_light_intensities()` now reports how its result was
+  computed in `.diagnostics`.
+
+## 0.1.4
+
+- Added `MobiusDevice.is_connected`.
+
+## 0.1.3
+
+- Devices are now identified by serial number instead of BLE address,
+  which can change: `find_device_by_serial()`, `dedupe_by_serial()`,
+  `MobiusDevice(serial=...)` and `mobius-scan --by-serial`.
+- Added `get_firmware_versions()` and `get_hardware_info()`.
+- Added `get_group_info()`, `get_calibration_info()` and
+  `get_maintenance_info()`.
+- Added `get_pump_flow_range()`, `get_pump_override_mode()`,
+  `get_battery_backup_info()` and `get_boosted_battery_info()`, included
+  in `get_device_summary()`.
+- Light intensities now include the schedule intensity, lunar phases,
+  acclimation and hyperdrive (`get_current_light_percentages()`), and flag
+  Insolation (not supported).
+
+## 0.1.2
+
+- Added `manufacturer_for_model()` / `MODEL_MANUFACTURER`.
+- Serial numbers are returned as text instead of hex.
+- `get_pump_telemetry()` now includes `speed_percent`.
+- Fixed a connection left open when subscribing to notifications failed.
+
+## 0.1.0
+
+- First release: framing, CRC and attribute get/set; scenes; pump
+  telemetry and schedules; light schedules and current intensities;
+  device identity and `get_device_summary()`; discovery and tank grouping
+  from advertisements; the `mobius-scan` command.

python_mobius-0.9.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.5
+Name: python-mobius
+Version: 0.9.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-asyncio>=0.23; 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 Python client for the Bluetooth protocol of "Mobius" aquarium devices:
+EcoTech Marine (VorTech and Vectra pumps, Radion lights),
+AquaIllumination (Prime, Hydra, Orbit, Axis), Neptune Systems and NYOS.
+Built on [`bleak`](https://github.com/hbldh/bleak).
+
+**Not affiliated with or endorsed by any of these companies.** This is an
+independent implementation of the protocol for interoperability with
+hardware you own, based on reverse engineering of the Mobius app and
+public community research. The protocol is documented in
+[`documentation/`](./documentation/00-overview.md), in enough detail to
+implement it in another language.
+
+## Features
+
+- **Discovery without connecting**: model, serial number and tank (pan_id)
+  from BLE advertisements.
+- **Lights**: channels, schedules, and the current intensity computed the
+  way the app does it (schedule intensity, lunar phases, acclimation,
+  hyperdrive).
+- **Pumps**: speed, flow, motor power and other sensor values; schedules
+  and the active mode; battery backup settings and whether the pump runs
+  on battery.
+- **Schedules**: read and write, as editable JSON or as the app's `.mob`
+  template files; light schedule groups are handled.
+- **Scenes**: list, start (whole tank) and cancel.
+- **Settings and commands**: advanced features (Local Control, LED auto
+  dim, fan speed, fan shutdown), lunar phases, schedule intensity, time
+  sync, reboot, restart all.
+- **One connection per tank**: every other device of the tank is reached
+  through it over the Thread mesh (`RelayedMobiusDevice`).
+- **Batched polling**: everything a poll needs in one request.
+- **Diagnostics**: attribute dumps, firmware and hardware information,
+  Thread and clock diagnostics.
+- **`mobius-scan`** command line tool.
+
+## Supported devices
+
+| PrimitiveType | Devices | Support |
+|---|---|---|
+| `VisualV1` | Radion, Prime, Hydra | Tested |
+| `VorTechV1`, `TurtleV1` | VorTech, Axis | Tested |
+| `PumpV1`, `VectraV1`, `AlpacaV1` | Nero, Vectra, Orbit | Same format as the tested pumps; not tested |
+| `CoffeeV1` | NYOS Quantum | Experimental: decoded with the pump format, not tested |
+| `DoseV1`, `HotSauceV1` | Dosers, sensors | Identity only |
+
+See [known gaps](./documentation/10-known-gaps-and-open-questions.md) for
+what isn't covered or tested.
+
+## Install
+
+```bash
+pip install python-mobius
+# recommended: more reliable connections
+pip install "python-mobius[retry]"
+```
+
+Python 3.9 or newer.
+
+## 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"  {info.serial}  {info.model.name if info.model else info.model_raw}")
+
+    device, info = found[0]
+    async with MobiusDevice(device, serial=info.serial) as d:
+        print(await d.get_device_summary())
+
+asyncio.run(main())
+```
+
+Reaching the rest of the tank through one connection:
+
+```python
+from mobius import RelayedMobiusDevice
+
+async with MobiusDevice(serial="00000000000002") as gateway:
+    for peer in await gateway.discover_mesh_peers_auto():
+        print(await RelayedMobiusDevice(gateway, peer).get_device_info())
+```
+
+Command line:
+
+```bash
+mobius-scan                                  # list devices by tank
+mobius-scan --by-serial SERIAL --dump-schedule
+mobius-scan --by-serial SERIAL --relay-target OTHER_SERIAL
+mobius-scan --help
+```
+
+The full API and every CLI option are described in
+[documentation/16-python-library.md](./documentation/16-python-library.md).
+
+## Development
+
+```bash
+git clone https://code.r3pek.org/r3pek/python-mobius
+cd python-mobius
+pip install -e ".[dev]"
+pytest
+```
+
+Tests use captured packets and advertisements from real devices where
+possible.
+
+## Related
+
+[ha-mobius](https://code.r3pek.org/r3pek/ha-mobius) is a Home Assistant
+integration built on this library.
+
+## License
+
+GPLv2, see [`LICENSE`](./LICENSE).
+
+## Acknowledgments
+
+The Reef2Reef thread "Controlling Mobius enabled VorTech pump using 0-10V
+and BLE" and the `danmrossi/MobiusControl` project, whose work this
+builds on. The reverse engineering and implementation were done with
+substantial help from Claude (Anthropic).

python_mobius-0.9.0/README.md

@@ -0,0 +1,129 @@
+# python-mobius
+
+A Python client for the Bluetooth protocol of "Mobius" aquarium devices:
+EcoTech Marine (VorTech and Vectra pumps, Radion lights),
+AquaIllumination (Prime, Hydra, Orbit, Axis), Neptune Systems and NYOS.
+Built on [`bleak`](https://github.com/hbldh/bleak).
+
+**Not affiliated with or endorsed by any of these companies.** This is an
+independent implementation of the protocol for interoperability with
+hardware you own, based on reverse engineering of the Mobius app and
+public community research. The protocol is documented in
+[`documentation/`](./documentation/00-overview.md), in enough detail to
+implement it in another language.
+
+## Features
+
+- **Discovery without connecting**: model, serial number and tank (pan_id)
+  from BLE advertisements.
+- **Lights**: channels, schedules, and the current intensity computed the
+  way the app does it (schedule intensity, lunar phases, acclimation,
+  hyperdrive).
+- **Pumps**: speed, flow, motor power and other sensor values; schedules
+  and the active mode; battery backup settings and whether the pump runs
+  on battery.
+- **Schedules**: read and write, as editable JSON or as the app's `.mob`
+  template files; light schedule groups are handled.
+- **Scenes**: list, start (whole tank) and cancel.
+- **Settings and commands**: advanced features (Local Control, LED auto
+  dim, fan speed, fan shutdown), lunar phases, schedule intensity, time
+  sync, reboot, restart all.
+- **One connection per tank**: every other device of the tank is reached
+  through it over the Thread mesh (`RelayedMobiusDevice`).
+- **Batched polling**: everything a poll needs in one request.
+- **Diagnostics**: attribute dumps, firmware and hardware information,
+  Thread and clock diagnostics.
+- **`mobius-scan`** command line tool.
+
+## Supported devices
+
+| PrimitiveType | Devices | Support |
+|---|---|---|
+| `VisualV1` | Radion, Prime, Hydra | Tested |
+| `VorTechV1`, `TurtleV1` | VorTech, Axis | Tested |
+| `PumpV1`, `VectraV1`, `AlpacaV1` | Nero, Vectra, Orbit | Same format as the tested pumps; not tested |
+| `CoffeeV1` | NYOS Quantum | Experimental: decoded with the pump format, not tested |
+| `DoseV1`, `HotSauceV1` | Dosers, sensors | Identity only |
+
+See [known gaps](./documentation/10-known-gaps-and-open-questions.md) for
+what isn't covered or tested.
+
+## Install
+
+```bash
+pip install python-mobius
+# recommended: more reliable connections
+pip install "python-mobius[retry]"
+```
+
+Python 3.9 or newer.
+
+## 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"  {info.serial}  {info.model.name if info.model else info.model_raw}")
+
+    device, info = found[0]
+    async with MobiusDevice(device, serial=info.serial) as d:
+        print(await d.get_device_summary())
+
+asyncio.run(main())
+```
+
+Reaching the rest of the tank through one connection:
+
+```python
+from mobius import RelayedMobiusDevice
+
+async with MobiusDevice(serial="00000000000002") as gateway:
+    for peer in await gateway.discover_mesh_peers_auto():
+        print(await RelayedMobiusDevice(gateway, peer).get_device_info())
+```
+
+Command line:
+
+```bash
+mobius-scan                                  # list devices by tank
+mobius-scan --by-serial SERIAL --dump-schedule
+mobius-scan --by-serial SERIAL --relay-target OTHER_SERIAL
+mobius-scan --help
+```
+
+The full API and every CLI option are described in
+[documentation/16-python-library.md](./documentation/16-python-library.md).
+
+## Development
+
+```bash
+git clone https://code.r3pek.org/r3pek/python-mobius
+cd python-mobius
+pip install -e ".[dev]"
+pytest
+```
+
+Tests use captured packets and advertisements from real devices where
+possible.
+
+## Related
+
+[ha-mobius](https://code.r3pek.org/r3pek/ha-mobius) is a Home Assistant
+integration built on this library.
+
+## License
+
+GPLv2, see [`LICENSE`](./LICENSE).
+
+## Acknowledgments
+
+The Reef2Reef thread "Controlling Mobius enabled VorTech pump using 0-10V
+and BLE" and the `danmrossi/MobiusControl` project, whose work this
+builds on. The reverse engineering and implementation were done with
+substantial help from Claude (Anthropic).

python_mobius-0.9.0/documentation/00-overview.md

@@ -0,0 +1,90 @@
+# Mobius BLE protocol
+
+This directory describes the Bluetooth Low Energy protocol spoken by
+"Mobius" aquarium devices: EcoTech Marine (VorTech and Vectra pumps,
+Radion lights, MXM hub), AquaIllumination (Prime and Hydra lights, Orbit
+and Axis pumps), Neptune Systems and NYOS (Quantum). It is written so the
+protocol can be implemented in any language; Python-specific notes are
+kept in [16-python-library.md](./16-python-library.md).
+
+The protocol was worked out through reverse engineering of the official
+Mobius app, public community research (the Reef2Reef thread
+["Controlling Mobius enabled VorTech pump using 0-10V and BLE"](https://www.reef2reef.com/threads/controlling-mobius-enabled-vortech-pump-using-0-10v-and-ble.814921/)
+and the `danmrossi/MobiusControl` project) and testing on real devices.
+
+## Where to start
+
+| If you want to... | Read |
+|---|---|
+| Connect and exchange a first message | [01](./01-ble-transport.md), [02](./02-framing-and-crc.md), [03](./03-attributes-and-opcodes.md) |
+| Find devices and group them by tank without connecting | [08](./08-manufacturer-data.md), [12](./12-device-identity-and-address-stability.md) |
+| Identify what kind of device you are talking to | [04](./04-device-identity.md) |
+| Look up an attribute ID, its encoding or an enum value | [14](./14-attribute-reference.md) |
+| Show what a light is doing right now | [06](./06-light-schedule.md) |
+| Show what a pump is doing right now | [07](./07-pump-schedule.md), [11](./11-device-status-attributes.md) |
+| Read or write schedules | [06](./06-light-schedule.md), [07](./07-pump-schedule.md), [15](./15-mob-template-format.md) |
+| Start or stop scenes (feed mode, ...) | [05](./05-scenes.md) |
+| Reach many devices through one BLE connection | [09](./09-thread-coap-relay.md) |
+| Read settings, diagnostics or send commands (reboot, set time) | [11](./11-device-status-attributes.md) |
+| Dump every attribute of a device | [13](./13-attribute-dump.md) |
+| Know what is not covered or not tested | [10](./10-known-gaps-and-open-questions.md) |
+
+## Document map
+
+| File | Covers |
+|---|---|
+| [01-ble-transport.md](./01-ble-transport.md) | GATT service and characteristics, fragmentation, connection notes |
+| [02-framing-and-crc.md](./02-framing-and-crc.md) | Frame layout, opGroups, the reserved field, CRC16, message IDs, status codes |
+| [03-attributes-and-opcodes.md](./03-attributes-and-opcodes.md) | Get/Set attribute, multi-element values, batched reads, listing supported attributes, group writes |
+| [04-device-identity.md](./04-device-identity.md) | `PrimitiveType`, `Model`, support tiers, `ErrorState`, firmware and hardware info |
+| [05-scenes.md](./05-scenes.md) | Configured scenes, starting and cancelling a scene |
+| [06-light-schedule.md](./06-light-schedule.md) | Light schedule format, computing the current intensity, lunar and acclimation modifiers, hyperdrive, writing, schedule groups |
+| [07-pump-schedule.md](./07-pump-schedule.md) | Pump schedule format, modes and parameters, supported modes per pump, writing |
+| [08-manufacturer-data.md](./08-manufacturer-data.md) | Advertisement contents: model, serial and pan_id without connecting |
+| [09-thread-coap-relay.md](./09-thread-coap-relay.md) | Thread mesh addressing, peer discovery, relaying requests through a connected device |
+| [10-known-gaps-and-open-questions.md](./10-known-gaps-and-open-questions.md) | Unimplemented features, untested areas, open questions |
+| [11-device-status-attributes.md](./11-device-status-attributes.md) | Pump telemetry, settings, calibration, maintenance, clock, diagnostics, commands |
+| [12-device-identity-and-address-stability.md](./12-device-identity-and-address-stability.md) | Why devices are identified by serial number, not BLE address |
+| [13-attribute-dump.md](./13-attribute-dump.md) | Reading every supported attribute; dump file formats |
+| [14-attribute-reference.md](./14-attribute-reference.md) | Every known attribute ID and enum value |
+| [15-mob-template-format.md](./15-mob-template-format.md) | The app's `.mob` schedule template file |
+| [16-python-library.md](./16-python-library.md) | How this Python library maps onto the protocol; CLI |
+
+## Conventions
+
+- All multi-byte integers are **little-endian** unless stated otherwise.
+- `u8`/`u16`/`u32`/`u64` are unsigned, `i8`/`i16`/`i32`/`i64` signed.
+- **Permille**: many percentages are sent as tenths of a percent
+  (0-1000 = 0.0-100.0 %).
+- Times of day in schedules are **minutes since midnight** (0-1439).
+- Absolute times are **Unix seconds** unless stated otherwise.
+- Strings are UTF-8 (or ASCII), padded with `0x00` to their field size.
+- "Attribute 500" means the attribute with ID 500; names are those used in
+  [14-attribute-reference.md](./14-attribute-reference.md).
+
+## Glossary
+
+| Term | Meaning |
+|---|---|
+| FSCI / C2CI | Framing layer (FSCI) and the attribute get/set command set on top of it (C2CI) |
+| Attribute | A numbered value on the device (read with Get, written with Set), optionally with several elements addressed by index |
+| Element / index | One value of a multi-value attribute (a schedule point, a firmware component, ...) |
+| Primitive | The device-type-specific payload of a schedule point or scene (channel intensities, pump mode and parameters) |
+| Tank | The set of devices sharing one Thread mesh (same pan_id and mesh prefix) |
+| Gateway | The device a client is connected to over BLE, used to reach the other devices of the tank over Thread |
+| Relayed device | A device reached through the gateway instead of its own BLE connection |
+
+## Verification status
+
+Statements about the protocol come from the app's behaviour and, where
+noted, from tests on real hardware (VorTech MP40 pumps, Radion XR15 G6
+lights, an AquaIllumination Axis pump). Parts that were never exercised on
+real hardware are listed in
+[10-known-gaps-and-open-questions.md](./10-known-gaps-and-open-questions.md).
+
+## Legal and scope
+
+This is independent reverse engineering for interoperability with hardware
+you own. No vendor code is reproduced; only the protocol facts needed to
+interoperate (wire formats, constants, byte layouts). Not affiliated with
+or endorsed by EcoTech Marine, AquaIllumination, Neptune Systems or NYOS.

python_mobius-0.9.0/documentation/01-ble-transport.md

@@ -0,0 +1,67 @@
+# BLE transport
+
+## Service and characteristics
+
+Every device exposes one GATT service with four characteristics:
+
+| UUID | Name | Direction | Properties |
+|---|---|---|---|
+| `01ff0100-ba5e-f4ee-5ca1-eb1e5e4b1ce0` | Service | | |
+| `01ff0101-ba5e-f4ee-5ca1-eb1e5e4b1ce0` | `RX_DATA` | device → client | notify: fragment |
+| `01ff0102-ba5e-f4ee-5ca1-eb1e5e4b1ce0` | `RX_FINAL` | device → client | notify: last fragment |
+| `01ff0103-ba5e-f4ee-5ca1-eb1e5e4b1ce0` | `TX_DATA` | client → device | write without response: fragment |
+| `01ff0104-ba5e-f4ee-5ca1-eb1e5e4b1ce0` | `TX_FINAL` | client → device | write without response: last fragment |
+
+Subscribe to notifications on both `RX_DATA` and `RX_FINAL` before sending
+anything.
+
+## Fragmentation
+
+A frame ([02-framing-and-crc.md](./02-framing-and-crc.md)) is split into
+chunks no larger than the ATT payload size:
+
+```
+chunks = split(frame, mtu_payload)          # at least one chunk
+for chunk in chunks[:-1]: write(TX_DATA, chunk)
+write(TX_FINAL, chunks[-1])                 # the device processes the message now
+```
+
+Receiving is symmetric: append every `RX_DATA` notification to a buffer;
+an `RX_FINAL` notification appends its bytes and completes the frame. Parse
+the buffer and clear it.
+
+20 bytes (the BLE 4.0 default ATT payload) always works; a larger
+negotiated MTU only reduces the number of writes.
+
+## Several requests in flight
+
+Responses are matched to requests by message ID
+([02](./02-framing-and-crc.md#message-id)); relayed responses by CoAP token
+([09](./09-thread-coap-relay.md)). A client can therefore keep several
+requests outstanding, although sending them one at a time is simpler and
+is what the app does in practice.
+
+## Advertising
+
+Devices advertise the local name `MOBIUS` (compare case-insensitively) and
+the service UUID above. Model, serial number and pan_id are in the
+manufacturer data. The manufacturer data has been observed only in scan
+responses: a passive scan of a Radion saw only the name and the UUID. See
+[08-manufacturer-data.md](./08-manufacturer-data.md).
+
+## Connection notes
+
+These are client-side observations, not protocol rules:
+
+- A device connected to a phone running the Mobius app usually stops
+  advertising and can't be connected to until the phone disconnects.
+- On Linux/BlueZ the first connection attempt fails fairly often; retrying
+  (for example with `bleak-retry-connector`) is reliable.
+- Connecting through a device object obtained from a recent scan, instead
+  of a bare address that triggers a new scan, avoids BlueZ forgetting the
+  device between scan and connect.
+- The BLE address is not a stable identity; see
+  [12-device-identity-and-address-stability.md](./12-device-identity-and-address-stability.md).
+- Holding a connection to every device leaves the app nothing to connect
+  to; keeping one connection per tank and relaying to the rest
+  ([09](./09-thread-coap-relay.md)) avoids that.