python-mobius 0.4.3__tar.gz → 0.5.0__tar.gz

{python_mobius-0.4.3 → python_mobius-0.5.0}/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 0.5.0
+
+- get_pump_telemetry() now returns gph_reliable/minimum_gph/maximum_gph
+  -- confirmed via the app's own logic that a raw gph reading isn't
+  trustworthy without a supported flow range (a real AI Axis 20
+  reported ~8x its own rated max flow).
+- Added support for AquaIllumination devices' own BLE company ID
+  (0x0001, alongside EcoTech Marine's 0x0202) -- confirmed via a real
+  AI Axis 20 capture. BREAKING: MOBIUS_COMPANY_ID renamed to
+  MOBIUS_COMPANY_ID_ECOTECH.
+- Added get_lunar_phase_info(): the device's own firmware-computed
+  lunar state, confirmed against real hardware, wired into
+  --dump-schedule for comparing against the calculated lunar value.
+- Fixed get_lunar_phase_info() silently returning None on a real read
+  failure (indistinguishable from "unsupported") -- now only an empty
+  response does that; an actual failure propagates.
+- Documented a confirmed bug in the app itself (double timezone
+  application) that can make its own displayed lunar value roll over
+  to the next day early -- this library's own calculation is correct
+  and unaffected.
+- Added get_advanced_features(): VorTech's "Local Control"/"Led Auto
+  Dim" and Radion's "Max Fan Speed"/"Fan Shutdown".
+- Added motor_power_watts to get_pump_telemetry() (Vectra/NYOS Quantum).
+- Added get_vectra_info() and get_coffee_info() (Vectra/NYOS Quantum
+  settings, no real hardware to verify against).
+- Fixed get_firmware_versions() showing raw internal names instead of
+  proper labels for AquaIllumination devices (Orbit/Axis, Prime/Hydra).
+- RelayedMobiusDevice now fails fast on later reads in the same poll
+  cycle after one relay timeout, instead of each one separately
+  waiting out its own timeout.
+- Added set_time_to_now() -- writes Epoch with group=1, confirmed
+  against real hardware to propagate to the rest of a tank's mesh.
+- Added reboot() -- soft-reboots a device (Reset attribute), matching
+  the app's own "Restart" button. Confirmed against real hardware
+  directly connected.
+
+## 0.4.4
+
+- Filled in the rest of the device model list (EcoTech Marine,
+  AquaIllumination, Neptune Systems, NYOS), previously a curated
+  subset. Also corrects Model.VersaVX1, mismarked as AquaIllumination;
+  it's an EcoTech Marine product.
+- Several Model entries are now named for their real product (e.g.
+  Model.Axis40, Model.Blade, Model.Quantum160) instead of the app's
+  own internal placeholder codename (Turtle2, Saddle, Coffee1).
+- Fixed the lunar-phase-scaled light intensity sometimes disagreeing
+  with the app for hours at a stretch. The lunar calculation now uses
+  the gateway device's own reported date instead of the local
+  system's, matching what the app itself actually does.
+
 ## 0.4.3
 
 - Fixed relayed devices (anything reached through a gateway over the
@@ -230,9 +280,8 @@
 
 - **`get_hardware_info()` now decodes `Color`/`ProductType`/`RadioType`/
   `MotorType` into confirmed display labels**, instead of returning raw
-  bytes. Each is itself a confirmed enum with confirmed labels
-  (`M.Color`/`M.ProductType`/`M.RadioType`/`M.MotorType` in the
-  decompile) -- added `Color`, `RadioType`, `MotorType`, `ProductType`
+  bytes. Each is itself a confirmed enum with confirmed labels --
+  added `Color`, `RadioType`, `MotorType`, `ProductType`
   enums plus their `*_LABELS` dicts to `mobius.constants`. An
   unrecognized value falls back to `"Unknown (N)"` rather than raising.
   `Revision`/`Segments` still have no confirmed enum meaning -- returned

{python_mobius-0.4.3 → python_mobius-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-mobius
-Version: 0.4.3
+Version: 0.5.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
@@ -49,12 +49,18 @@ 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
+telemetry, pump schedules, light schedules, device discovery/grouping
+(both EcoTech Marine's and AquaIllumination's own BLE company IDs), and
+Thread/CoAP relay (reading a non-gateway tank member through the
+gateway's own connection) are implemented and verified against real
+hardware (two VorTech MP40QD pumps, two Radion XR15 G6 Pro lights, one
+AquaIllumination Axis 20 pump). Two write operations are also confirmed
+against real hardware: rebooting a device, and syncing a device's own
+clock to the current time. 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).
+for what isn't covered yet (dosers, environmental sensors) or is
+implemented but not yet verified against real hardware (Vectra/NYOS
+Quantum-specific settings).
 
 ## Install
 
@@ -96,14 +102,28 @@ mobius-scan --adapter hci0
 - **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.
+  state, error state, and (Vectra/NYOS Quantum pumps) motor power in watts.
 - **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).
+- **Read device-specific settings**: VorTech's own "Local Control"/"Led
+  Auto Dim" and Radion's own "Max Fan Speed"/"Fan Shutdown"
+  (`get_advanced_features()`), plus Vectra and NYOS Quantum settings
+  (`get_vectra_info()`/`get_coffee_info()` — no real hardware to verify
+  either against, see
+  [known gaps](./documentation/10-known-gaps-and-open-questions.md)).
 - **Control scenes**: start feed mode, resume the normal schedule, or any
   other configured scene.
+- **Fix a desynced device clock** (`set_time_to_now()`) — a WRITE.
+  Writing to one device appears to propagate to the rest of its Thread
+  mesh too, confirmed against real hardware — see
+  [09-thread-coap-relay.md](./documentation/09-thread-coap-relay.md)
+  for what's confirmed and what isn't yet.
+- **Reboot a device** (`reboot()`) — a WRITE, matching the app's own
+  "Restart" button exactly. Confirmed against real hardware directly
+  connected; not yet confirmed via relay.
 - **Low-level protocol access** (`build_frame`, `get_attribute`,
   `set_attribute`, ...) if you want to go beyond what's wrapped in
   `MobiusDevice`.
@@ -113,13 +133,22 @@ mobius-scan --adapter hci0
 | PrimitiveType | Support | Notes |
 |---|---|---|
 | `VisualV1` (Radion, Prime, Hydra, etc.) | ✅ Verified | Lights |
-| `VorTechV1`, `PumpV1`, `VectraV1`, `AlpacaV1`, `TurtleV1` | ✅ Verified | Pumps |
+| `VorTechV1`, `TurtleV1` (AquaIllumination Axis) | ✅ Verified | Pumps -- confirmed against real hardware directly (VorTech MP40QD, AquaIllumination Axis 20) |
+| `PumpV1`, `VectraV1`, `AlpacaV1` (AquaIllumination Orbit) | ✅ Verified | Pumps -- same wire format as the primitives above, not independently confirmed against their own real hardware |
 | `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).
 
+"Verified" above is about core telemetry/schedule parsing. The
+Vectra/NYOS Quantum-specific settings methods
+(`get_vectra_info()`/`get_coffee_info()`) and `motor_power_watts` are
+newer, implemented from the decompiled source alone, and not verified
+against real Vectra or NYOS Quantum hardware regardless of the table
+above — see
+[known gaps](./documentation/10-known-gaps-and-open-questions.md).
+
 ## Development
 
 ```bash

{python_mobius-0.4.3 → python_mobius-0.5.0}/README.md

@@ -17,12 +17,18 @@ 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
+telemetry, pump schedules, light schedules, device discovery/grouping
+(both EcoTech Marine's and AquaIllumination's own BLE company IDs), and
+Thread/CoAP relay (reading a non-gateway tank member through the
+gateway's own connection) are implemented and verified against real
+hardware (two VorTech MP40QD pumps, two Radion XR15 G6 Pro lights, one
+AquaIllumination Axis 20 pump). Two write operations are also confirmed
+against real hardware: rebooting a device, and syncing a device's own
+clock to the current time. 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).
+for what isn't covered yet (dosers, environmental sensors) or is
+implemented but not yet verified against real hardware (Vectra/NYOS
+Quantum-specific settings).
 
 ## Install
 
@@ -64,14 +70,28 @@ mobius-scan --adapter hci0
 - **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.
+  state, error state, and (Vectra/NYOS Quantum pumps) motor power in watts.
 - **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).
+- **Read device-specific settings**: VorTech's own "Local Control"/"Led
+  Auto Dim" and Radion's own "Max Fan Speed"/"Fan Shutdown"
+  (`get_advanced_features()`), plus Vectra and NYOS Quantum settings
+  (`get_vectra_info()`/`get_coffee_info()` — no real hardware to verify
+  either against, see
+  [known gaps](./documentation/10-known-gaps-and-open-questions.md)).
 - **Control scenes**: start feed mode, resume the normal schedule, or any
   other configured scene.
+- **Fix a desynced device clock** (`set_time_to_now()`) — a WRITE.
+  Writing to one device appears to propagate to the rest of its Thread
+  mesh too, confirmed against real hardware — see
+  [09-thread-coap-relay.md](./documentation/09-thread-coap-relay.md)
+  for what's confirmed and what isn't yet.
+- **Reboot a device** (`reboot()`) — a WRITE, matching the app's own
+  "Restart" button exactly. Confirmed against real hardware directly
+  connected; not yet confirmed via relay.
 - **Low-level protocol access** (`build_frame`, `get_attribute`,
   `set_attribute`, ...) if you want to go beyond what's wrapped in
   `MobiusDevice`.
@@ -81,13 +101,22 @@ mobius-scan --adapter hci0
 | PrimitiveType | Support | Notes |
 |---|---|---|
 | `VisualV1` (Radion, Prime, Hydra, etc.) | ✅ Verified | Lights |
-| `VorTechV1`, `PumpV1`, `VectraV1`, `AlpacaV1`, `TurtleV1` | ✅ Verified | Pumps |
+| `VorTechV1`, `TurtleV1` (AquaIllumination Axis) | ✅ Verified | Pumps -- confirmed against real hardware directly (VorTech MP40QD, AquaIllumination Axis 20) |
+| `PumpV1`, `VectraV1`, `AlpacaV1` (AquaIllumination Orbit) | ✅ Verified | Pumps -- same wire format as the primitives above, not independently confirmed against their own real hardware |
 | `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).
 
+"Verified" above is about core telemetry/schedule parsing. The
+Vectra/NYOS Quantum-specific settings methods
+(`get_vectra_info()`/`get_coffee_info()`) and `motor_power_watts` are
+newer, implemented from the decompiled source alone, and not verified
+against real Vectra or NYOS Quantum hardware regardless of the table
+above — see
+[known gaps](./documentation/10-known-gaps-and-open-questions.md).
+
 ## Development
 
 ```bash

{python_mobius-0.4.3 → python_mobius-0.5.0}/documentation/03-attributes-and-opcodes.md

@@ -79,14 +79,18 @@ against real pumps and lights returned correctly-structured, sane data.
 |---|---|---|
 | `Model` | 4 | See [04-device-identity.md](./04-device-identity.md) |
 | `Name` | 5 | User-assigned device name |
+| `Reset` | 6 | Write `ResetType.Soft` (0) to reboot -- see [09-thread-coap-relay.md](./09-thread-coap-relay.md) |
 | `PrimitiveType` | 8 | Device class (pump/light/etc) — see 04 |
-| `PhysicalValues` | 101 | Sub-indexed by `PhysicalValueID`; used for live pump GPH |
+| `PhysicalValues` | 101 | Sub-indexed by `PhysicalValueID`; used for live pump GPH and (Vectra/NYOS Quantum) `MotorPower`/watts -- see [11-device-status-attributes.md](./11-device-status-attributes.md) |
 | `MACAddress` | 103 | Observed unpopulated (empty response) on all devices tested |
 | `OperationState` | 104 | `OOB`/`LiveDemo`/`Scene`/`Schedule` |
 | `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). 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))`. |
+| `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 formatting. |
+| `LocalControlEnabled` / `AutoDimTimeout` / `MaxFanSpeed` / `FanShutdownEnabled` | 300 / 301 / 910 / 1203 | VorTech/Radion advanced feature settings — see 11 |
+| `PowerOnDelay` / `ClosedLoop` / `FeedModeReturnDelay` | 800 / 801 / 802 | Vectra settings — see 11 |
+| `CoffeeLedOn` / `CoffeeStatusIntensity` / `CoffeeFeedModeReturnDelay` / `CoffeePowerOnDelay` | 717 / 4100 / 4101 / 4102 | NYOS Quantum settings — see 11 |
 | `SupportedColorChannels` | 901 | Static list of a light's channels |
 
 See `src/mobius/constants.py` for the complete implemented list.

{python_mobius-0.4.3 → python_mobius-0.5.0}/documentation/04-device-identity.md

@@ -22,7 +22,7 @@ way to tell devices apart over BLE (they all advertise the same local name,
 
 ### `PRIMITIVE_SIZE` — schedule-point primitive byte size, per type
 
-Confirmed from `M.PrimitiveType.size()`. For `VisualV1` this is a
+Confirmed from the app's own per-primitive size lookup. For `VisualV1` this is a
 per-channel repeating unit (3 bytes: `VisualID` + `u16` intensity), not a
 fixed total. For everything else, it's the exact fixed size of that
 primitive type's data.

{python_mobius-0.4.3 → python_mobius-0.5.0}/documentation/05-scenes.md

@@ -5,7 +5,7 @@ override the normal schedule temporarily or permanently.
 
 ## `SceneID`
 
-Confirmed literal values from `M.SceneID`:
+Confirmed literal values:
 
 | Value | Name |
 |---|---|
@@ -45,7 +45,7 @@ back to schedule-driven.
 
 ## `OperationState`
 
-Confirmed literal values from `M.OperationState`:
+Confirmed literal values:
 
 | Value | Name |
 |---|---|

{python_mobius-0.4.3 → python_mobius-0.5.0}/documentation/06-light-schedule.md

@@ -165,19 +165,17 @@ point. In practice this covers essentially the whole night, *except*
 the two transition segments themselves: dusk (start point not yet
 night-flagged) and the sunrise segment (start point flagged `SUNRISE`).
 
-**Confirmed directly against the raw bytecode, not the decompiled Java.**
-An earlier decompilation attempt for this
-exact method was unreliable -- a real signal, not noise: the decompiled Java had this
-condition's first check inverted (`!point.has(NIGHT)` instead of the
-actual `point.has(NIGHT)`), which an earlier version of this port
-carried forward uncorrected. Found via real hardware testing: a light
-in a `23:00[NIGHT,SUNSET] -> 23:27[NIGHT]` segment showed a value
-consistent with the schedule-intensity scalar from this library, while
-the real app displayed a noticeably lower, lunar-consistent value at
-the same moment -- mathematically impossible to explain by
-schedule-intensity alone within that segment's raw-value range, which
-is what prompted re-examining the raw bytecode instead of trusting the
-decompiled Java a second time.
+**Confirmed directly against the raw bytecode, not the decompiled
+source.** The decompiled source for this exact method is unreliable --
+a real signal, not noise: it has this condition's first check inverted
+(`!point.has(NIGHT)` instead of the actual `point.has(NIGHT)`). Found
+via real hardware testing: a light in a `23:00[NIGHT,SUNSET] ->
+23:27[NIGHT]` segment showed a value consistent with the schedule-
+intensity scalar from this library, while the real app displayed a
+noticeably lower, lunar-consistent value at the same moment --
+mathematically impossible to explain by schedule-intensity alone within
+that segment's raw-value range, which is what prompted re-examining the
+raw bytecode instead of trusting the decompiled source a second time.
 
 **Acclimation ramp** (`AcclimationInfo`): a linear intensity ramp from
 `start_intensity` (0-1000 permille) up to full (1000) over `period_days`,
@@ -189,6 +187,36 @@ completed yet.
 `get_current_light_intensities()` fetches and applies all of this
 automatically -- no separate calls needed for the common case.
 
+**`get_lunar_phase_info()`**: reads `LunarPhasesCurrentDay`/
+`LunarPhasesCurrentScalar` directly off the device -- its own
+firmware-computed lunar state, confirmed against real hardware to
+match `LUNAR_CYCLE_SCALERS[current_day]` exactly, even though the app
+itself never reads either attribute (it always computes the
+equivalent value client-side, the same way this library does). Useful
+as an independent cross-check against this library's own calculated
+value.
+
+**A confirmed bug in the app itself, not in this library**: the app's
+own `date`-to-calendar-day conversion
+(`LunarInfo.jdFromGregorianDate()`) applies the phone's own local
+timezone via `Calendar.getInstance()` on top of a value
+(`Tank.getDateTime().date()`) that's already timezone-adjusted once
+(the device's own `Epoch`-to-`LocalTime` offset). This double
+application means the app's own displayed lunar value rolls over to
+the next calendar day exactly one UTC-offset early, relative to the
+device's true local midnight (assuming the phone and device agree on
+timezone, the common case) -- confirmed via the exact arithmetic and
+via the general symptom matching (a real, reported case of the app
+showing the next day's value visibly before midnight, on a
+device/phone at UTC+1, consistent with this mechanism). The precise
+one-hour timing itself is a derived prediction from the arithmetic,
+not something separately checked against a clock. This library's own calculation (and the device's own
+firmware, per `get_lunar_phase_info()` above) doesn't have this bug --
+both correctly roll over at true local midnight. A mismatch between
+this library's own calculated lunar value and the app's own displayed
+one, specifically around midnight, is expected and doesn't indicate
+anything wrong with this library.
+
 ## Insolation detection (flagged, not implemented)
 
 Insolation itself is not implemented (see below), but

{python_mobius-0.4.3 → python_mobius-0.5.0}/documentation/07-pump-schedule.md

@@ -3,8 +3,8 @@
 ## Same attribute, same `Point` framing, different primitive and different semantics
 
 Pumps use the exact same `Schedule1`/`Schedule2` attributes and the exact
-same `time + flags + primitiveData` point framing as lights (confirmed:
-`Schedule.checkSupport()` only checks whether `Schedule1` is a supported
+same `time + flags + primitiveData` point framing as lights (confirmed: the
+app's own support check only checks whether `Schedule1` is a supported
 attribute at all — it isn't gated by `PrimitiveType`). What differs:
 
 - `primitiveData` decodes as a **`PumpPrimitive`**, not a `LightPrimitive`.
@@ -27,7 +27,7 @@ params (variable, depends on mode)
 
 ### `PumpMode`
 
-Confirmed literal values from `M.PumpMode` (note the gap: value `11` is
+Confirmed literal values (note the gap: value `11` is
 genuinely unused in the source):
 
 | Value | Name |
@@ -51,9 +51,9 @@ genuinely unused in the source):
 
 ### Parameters per mode
 
-Ported directly from `M.PumpMode.parameters()` — which fields are present,
-and in what order (byte offset is cumulative, starting right after the mode
-byte):
+Ported directly from the app's own pump-mode parameter logic — which fields
+are present, and in what order (byte offset is cumulative, starting right
+after the mode byte):
 
 | Mode | Parameters |
 |---|---|
@@ -97,7 +97,7 @@ matters for your use case.
 
 ### `RampType`
 
-Confirmed literal values from `M.RampType`:
+Confirmed literal values:
 
 | Value | Name |
 |---|---|

{python_mobius-0.4.3 → python_mobius-0.5.0}/documentation/08-manufacturer-data.md

@@ -6,8 +6,22 @@ required.** This is the fastest way to discover and group devices.
 
 ## Company ID
 
-`0x0202`, confirmed via `bleak`'s `AdvertisementData.manufacturer_data`
-dict against all four devices tested.
+Two confirmed, via `bleak`'s `AdvertisementData.manufacturer_data` dict:
+
+- `0x0202` (514) — EcoTech Marine devices, confirmed against all four
+  original test devices (two VorTech pumps, two Radion lights).
+- `0x0001` (1) — AquaIllumination devices, confirmed against a real
+  captured AI Axis 20 pump advertisement: the decoded `model` field
+  (261) matches `Model.Axis20` exactly (the app's own internal enum
+  name for it is `Turtle1`), and the decoded serial matched the
+  device's own GATT-read serial. Whether Neptune Systems/NYOS (also
+  EcoTech-family brands) share `0x0202` or use their own separate ID
+  is inferred, not directly confirmed — no advertisement from either
+  has actually been captured and checked.
+
+Both confirmed company IDs use the exact same 23-byte payload format
+described below — `parse_manufacturer_data()` doesn't need to know or
+care which company ID a payload came from.
 
 ## Payload format
 
@@ -17,10 +31,12 @@ library's `parse_manufacturer_data()` takes the already-stripped 23-byte
 `bleak` payload directly, which corresponds to `javaBArr[2:]`.
 
 The decompile has several format branches keyed by total length and a
-"version" byte; **only the branch actually observed on real hardware is
-implemented** (23-byte `bleak` payload / 25-byte original Java `bArr`
-length, "version 2"). Payloads of any other length return `None` rather
-than guessing at an unimplemented branch.
+"version" byte (the company ID's own low byte -- see "Company ID" above);
+**only the branch actually observed on real hardware is implemented**
+(23-byte `bleak` payload / 25-byte original Java `bArr` length) --
+confirmed identical for both company IDs' own "version 1"/"version 2"
+variant of this specific length. Payloads of any other length return
+`None` rather than guessing at an unimplemented branch.
 
 ```
 offset  size   field                          maps to bleak payload offset
@@ -55,13 +71,22 @@ payload, i.e. what `parse_manufacturer_data()` actually receives.)
   `MobiusAdvertisement.device_specific_data` for completeness/future use.
 - **The unused byte at offset 2**: genuinely dead — grepped the entire
   decompile for any code path reading this offset (in either the "version
-  1" or "version 2" format branch) and found none. Constant `0x01` in every
-  sample. Not exposed as a field since there's nothing to name it.
+  1" or "version 2" format branch) and found none for the EcoTech-family
+  branch; the AquaIllumination branch does read it into a local variable
+  (`b2`) but never uses it afterward either. Constant `0x01` in every
+  sample observed, EcoTech and AquaIllumination alike. Not exposed as a
+  field since there's nothing to name it.
 
 ## "Flags" — deliberately not exposed
 
-The decompile's version-2 branch also builds a `Flags` object from
-`javaBArr[1]` — but in this format, that byte is actually the company ID's
-*high byte* (`0x02`, constant), not real payload data. Decoding "flags"
-here would just be re-decoding the company ID and calling it something
-else, so this library doesn't expose it.
+`javaBArr[1]` is the company ID's own *high byte* — for EcoTech Marine
+(`0x0202`) that's a constant `0x02`; for AquaIllumination (`0x0001`)
+it's a constant `0x00`. The decompile still gives this byte its own,
+different treatment per company ID: the EcoTech branch just wraps it
+in an opaque `Flags` object with no further use shown; the
+AquaIllumination branch reads it as `pendingNotifications = byte > 0`
+(always `False`, since the byte is a constant `0x00`). Either way,
+it's not independent payload data — decoding "flags" here would just
+be re-decoding a constant part of the company ID and calling it
+something else, so this library doesn't expose it for either company
+ID.

{python_mobius-0.4.3 → python_mobius-0.5.0}/documentation/09-thread-coap-relay.md

@@ -121,6 +121,83 @@ carries its own CRC, which is what's actually checked.
 frame without waiting for its confirm, and awaits the token-matched
 indication with a timeout.
 
+Retries exactly once on a timeout (confirmed via reverse engineering the
+app's own request-timeout handling -- it never treats a single timed-out
+relay round-trip as a real failure) before actually raising. After both
+attempts have timed out, every later call on that SAME
+`RelayedMobiusDevice` instance fails immediately instead of repeating
+the same two-attempt wait -- a fresh instance is created each poll
+cycle, and a caller like `get_device_summary()` makes several separate
+attribute reads against one instance in immediate succession; if the
+mesh route to that target is down, it's down for all of them, not just
+whichever one happened to be tried first.
+
+## Time sync (`set_time_to_now()`) -- writing to one device propagates to the rest of the mesh
+
+`set_time_to_now()` writes `Epoch` to a single device, with the frame's
+own reserved-byte "group" field set to 1 (see `make_reserved()`) --
+confirmed via the app's own source to be set unconditionally on every
+time-related write it ever sends. Confirmed against real hardware:
+`group=1` is required for the write to be accepted at all -- `group=0`
+fails the write entirely, even on the device it targets directly.
+
+This single write appears to genuinely propagate to OTHER devices on
+the same mesh that were never written to directly -- confirmed via real
+test data: three mesh peers (read via relay, none of them the device
+actually written to) disagreed with each other by 1 second before the
+write; seconds after a single write to a fourth, different device, all
+three read back an identical timestamp, despite each having a different
+amount of real time elapsed since its own prior read. Independent
+clocks coincidentally landing on the exact same value, with different
+elapsed times each, isn't a plausible explanation for that -- this is
+strong evidence of real propagation, not just normal ticking.
+
+Not confirmed: reliability across different mesh topologies or mesh
+sizes, behavior under real-world conditions (e.g. a peer briefly
+unreachable when propagation happens), or whether writing via
+`RelayedMobiusDevice` (rather than directly, as tested) behaves the
+same way -- see `set_time_to_now()`'s own docstring for the full
+breakdown.
+
+## Device control (`reboot()`) -- targeted, no mesh-wide propagation
+
+`reboot()` writes `ResetType.Soft` (0) to `Reset` (6) -- confirmed via
+the app's own source to be exactly what its own "Restart" button
+sends. Unlike `set_time_to_now()`, this is a plain, ungrouped write
+(no reserved-byte `group` field involved at all) -- it targets exactly
+the device it's sent to, nothing else, even though (like any other
+request) it can still be relayed through a gateway to reach that
+target in the first place.
+
+Confirmed against real hardware, directly connected. Confirmed via the
+app's own request-routing logic that a `Reset` write isn't
+special-cased at all -- it goes through the exact same generic routing
+every other Get/Set uses, including the same relay branch for a target
+that isn't the directly-connected device (the app wraps the request's
+own raw FSCI payload, `Set` opcode included, inside a CoAP request
+addressed to the target's mesh address, and sends that to the
+gateway). This library's own `RelayedMobiusDevice` already implements
+that same mechanism, and `reboot()` is built on it transparently, the
+same way every other high-level method is -- reasoned to work via
+relay for the same structural reason, but not itself confirmed against
+real hardware via relay yet (`RelayedMobiusDevice`'s own reads are
+confirmed against real hardware extensively; no write through it, this
+one or `set_time_to_now()`, has actually been tried against real
+hardware yet).
+
+Also confirmed via the app's own source: the device sends a normal
+FSCI success response BEFORE actually rebooting (the app's own
+handler just disconnects client-side once that confirm arrives,
+rather than waiting for the device to drop the connection on its
+own) -- `reboot()` returning successfully means the device
+ACKNOWLEDGED the request, not necessarily that it has already
+finished rebooting.
+
+Only `ResetType.Soft` is exposed -- see that method's own docstring
+for why the app's other `Reset` values (`Factory`, `PowerLoss`,
+`PowerRecovery`, `Calibration`) deliberately aren't wired up to
+anything.
+
 ## Address discovery
 
 A device's Thread mesh-local RLOC (Routing Locator) IPv6 address:

{python_mobius-0.4.3 → python_mobius-0.5.0}/documentation/10-known-gaps-and-open-questions.md

@@ -18,6 +18,42 @@ included as a starting point.
 
 ## Experimental / unverified
 
+- **`reboot()` via relay**: confirmed against real hardware directly
+  connected. Not confirmed via `RelayedMobiusDevice` -- no write
+  through it, this one or `set_time_to_now()`, has been tried against
+  real hardware yet. See
+  [09-thread-coap-relay.md](./09-thread-coap-relay.md).
+
+- **`set_time_to_now()` via `RelayedMobiusDevice`, and across different
+  mesh topologies/sizes**: the write itself and its propagation to
+  other mesh members are confirmed against real hardware (one tank,
+  writing directly to a connected device) -- see
+  [09-thread-coap-relay.md](./09-thread-coap-relay.md). Not tested:
+  writing via relay to a non-gateway member, larger meshes, or
+  real-world conditions like a peer being briefly unreachable when
+  propagation happens.
+
+- **`get_advanced_features()`** (`AdvancedFeatures`): implemented from
+  the decompile; not checked against real VorTech or Radion hardware
+  specifically for these four attributes (`LocalControlEnabled`/
+  `AutoDimTimeout`/`MaxFanSpeed`/`FanShutdownEnabled`), unlike the rest
+  of this library's pump/light support.
+- **`get_vectra_info()`/`get_coffee_info()`** (`VectraInfo`/
+  `CoffeeInfo`): no real Vectra or NYOS Quantum hardware was available
+  to verify either against -- implemented from the decompile alone.
+  Both also each have one attribute ID (`PowerOnDelay`/
+  `CoffeeStatusIntensity`) that needed external confirmation, since
+  they resolve in the decompile through third-party Android library
+  constants (an animation library, an AndroidX SDK constant
+  respectively) rather than plain literals in the app's own code --
+  see [11-device-status-attributes.md](./11-device-status-attributes.md)
+  for the full confirmation.
+- **`motor_power_watts`** (`get_pump_telemetry()`): confirmed via the
+  app's own gauge-widget logic to be the value it falls back to,
+  relabeled "watts", for Vectra/NYOS Quantum pumps specifically when
+  its own flow-range display object isn't populated for that device --
+  but not checked against real Vectra/NYOS Quantum hardware. Purely
+  additive; doesn't affect `speed`/`gph` for any device.
 - **`CoffeeV1` (NYOS Quantum skimmers/dosers)**: shares the exact declared
   primitive size (13 bytes) with pump-class devices, so this library
   applies the pump parser automatically — but this has never been tested