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

python_mobius-0.1.3/CHANGELOG.md

@@ -0,0 +1,233 @@
+# Changelog
+
+## 0.1.3
+
+- **Added firmware/hardware version reading.** `get_firmware_versions()`
+  (`FirmwareVersion`, attribute 1) with **confirmed-against-real-hardware**
+  display labels for EcoTech Marine devices (a real VorTech pump showed
+  exactly Radio/Radio Bootloader/Product OS/Product Bootloader; a real
+  Radion light showed exactly Product OS/Product Bootloader/Radio
+  Firmware/Filesystem/Radio OS/Radio/WLAN -- confirming lights use a
+  QCA4020-based radio with WiFi+BLE, unlike the simpler pump radio).
+  Ported the exact label mapping from `FirmwareType.name(Model)` in the
+  decompile. Versions are dot-joined strings built directly from the raw
+  response bytes (confirmed via `FirmwareType.format()`). Also added
+  `get_hardware_info()` (`HardwareRevision`, attribute 2, same fetch
+  pattern) -- returns raw bytes, no confirmed display format for those
+  fields. `get_device_summary()` now includes `"firmware_versions"`
+  automatically. 6 new tests.
+
+- **Fixed a real CLI bug**: passing both a scan-time `BLEDevice` and
+  `serial=` into `MobiusDevice` in the connect loop did NOT actually give
+  serial-based robustness -- a directly-provided `BLEDevice` is always
+  used on the first connect, and the CLI only calls `connect()` once per
+  device, so the serial fallback path never triggered. That scan-time
+  `BLEDevice` could be tens of seconds stale by the time the loop reaches
+  the last device in a long scan -- confirmed against real hardware as the
+  cause of `"device disappeared"` errors. Fixed: the CLI now passes
+  `serial=` alone (omitting `device`) whenever available, forcing a fresh
+  resolution immediately before each connect.
+
+- **Major fix: device identity is now serial-number-based, not BLE-address-based.**
+  Real-world testing surfaced a device whose advertised MAC address changed
+  between runs. Investigating the decompiled app's own `Peripheral` class
+  confirmed the official app never relies on address stability at all --
+  `Peripheral.equals()`/`hashCode()` are based purely on serial number, and
+  `Peripheral.update()` explicitly replaces the stored BLE address whenever
+  a new scan matches an existing device by serial. This library previously
+  assumed address stability throughout.
+  - New `find_device_by_serial()` and `dedupe_by_serial()`
+    (`mobius.discovery`).
+  - `MobiusDevice(device=None, serial=None, ...)`: `serial` is a new,
+    fully backward-compatible optional parameter. A directly-provided
+    `BLEDevice` is still used for the fast first connect, but if `serial`
+    is also set, any *subsequent* `connect()` on the same instance
+    re-resolves the current address via serial rather than assuming the
+    original address/BLEDevice is still valid. Existing address-only
+    usage is completely unchanged.
+  - `mobius-scan` CLI: applies `dedupe_by_serial()` automatically, passes
+    `serial=` when connecting, and has a new `--by-serial SERIAL` flag for
+    testing this directly against real hardware.
+  - 12 new tests. See
+    `documentation/12-device-identity-and-address-stability.md` for the
+    full evidence and rationale.
+  - Not yet applied to `ha-mobius`, which has the same address-based
+    assumption -- planned as a follow-up once this is confirmed working
+    against real hardware.
+
+- **Fixed a real bug**: `get_device_summary()` -- the "read everything"
+  entrypoint the CLI and other callers actually use -- was never updated
+  to include `get_pump_flow_range()`/`get_pump_override_mode()`/
+  `get_battery_backup_info()`/`get_boosted_battery_info()`/
+  `get_group_info()`/`get_calibration_info()`/`get_maintenance_info()`
+  after they were added. All 7 methods worked correctly in isolation with
+  their own passing tests, but nothing exercised `get_device_summary()`
+  itself, so the gap went undetected through 103 passing tests. Caught via
+  real CLI usage. Fixed, and `tests/test_device_summary.py` now exists
+  specifically so this class of gap can't go undetected again (confirmed:
+  reverting the fix makes the new test fail with a clear message pointing
+  at the missing key).
+
+- **Added group/sync, calibration, and maintenance reads.** New
+  `mobius.device_status` module. `get_group_info()` (`GroupMaster`/
+  `IsGroupMaster`, 900/911 -- confirmed dead in the app itself, zero real
+  usage beyond the enum definitions). `get_calibration_info()`
+  (`IsCalibrated`/`LastCalibrationTime`/`MinCalibratedSpeed`/
+  `MaxCalibratedSpeed`, 1300/1304/1308/1309) -- **important correction**:
+  despite "Speed"-sounding names, confirmed via the app's own UI gating
+  (`DeviceSettingsFragment.java`: `device.primitive.category() ==
+  M.DeviceCategory.Lighting`) that this is a light feature, not a pump
+  one. A separate, unrelated pump-side calibration flow exists in the app
+  (Nero-specific zero-flow/max-flow calibration) but isn't implemented and
+  doesn't apply to VorTech anyway (no physical flow sensor to calibrate).
+  `get_maintenance_info()` (`RecommendedMaintenanceInterval`/
+  `MaintenanceTimer`/`LastMaintenanceTime`/`MaintenanceDue`,
+  1400-1403 -- also confirmed dead in the app; returns raw bytes rather
+  than guessing a numeric width with zero supporting evidence). 7 new
+  tests. Renamed `documentation/11-pump-status-and-capabilities.md` to
+  `documentation/11-device-status-attributes.md` to reflect the broader
+  (not pump-only) scope.
+
+- **Added pump status/capability reads**: `get_pump_flow_range()`
+  (`MinimumGallonsPerHour`/`MaximumGallonsPerHour`, 707/708 -- confirmed
+  NOT to apply to VectraV1 pumps), `get_pump_override_mode()` (new
+  `PumpOverrideMode` enum, attribute 705 -- confidence note: confirmed
+  only as a *write* target in the decompile, never read; this library's
+  read path is a reasonable inference, not directly observed),
+  `get_battery_backup_info()` (`BatteryBackupSpeed`/`BatteryBackupMaxSpeed`,
+  706/701), `get_boosted_battery_info()` (`BoostedBatteryPower`/`OnTime`/
+  `OffTime`, 803/804/805). New `mobius.pump_status` module
+  (`PumpFlowRange`, `BatteryBackupInfo`, `BoostedBatteryInfo`). All fail
+  soft (return `None`) for unsupported/model-dependent attributes rather
+  than raising. 9 new tests. See
+  `documentation/11-device-status-attributes.md`.
+
+- **Added full hyperdrive support** (correct percentage conversion for
+  light channels boosted above their normal 100% rating). New
+  `mobius.power` module (`ChannelPowerInfo`, `channel_percent_value()`,
+  ported from `LightPowerInfo.java`) and `get_channel_power_info()`
+  (`MaxPower`/`NormalPower`, attributes 1504/1513). New
+  `get_current_light_percentages()` convenience method returns corrected
+  0-100+ percentages instead of raw permille, flagging boosted channels via
+  `.diagnostics["hyperdrive_channels"]`. Confirmed byte-identical to the
+  old `raw/10` shortcut for the common (non-boosted) case; only changes
+  results for genuinely boosted channels. `LightPowerInfo`'s Prime/Hydra-
+  specific `gm8b4()` wattage override table is not replicated -- see
+  `documentation/06-light-schedule.md`.
+  - Also refactored `get_attribute()` into a thin wrapper around a new
+    `get_attribute_raw()`, which preserves the device-reported response
+    index -- required for `MaxPower`/`NormalPower`, where the index *is*
+    the `VisualID` byte value, not just a positional offset. Added a
+    regression test proving this distinction matters (a device that
+    starts its response at a non-zero index would have silently
+    mismatched values to the wrong channels under the old approach).
+  - 15 new tests across `tests/test_power.py` and
+    `tests/test_hyperdrive_device.py`.
+
+- **Added Insolation detection/flagging.** Insolation itself is not
+  implemented (it's more than a missing modifier -- when active, the app
+  substitutes an entirely different, dynamically-generated schedule
+  before interpolating, not something layered on top the way lunar/
+  acclimation are). `get_current_light_intensities()` now returns a
+  `LightIntensityResult` -- a fully backward-compatible dict subclass with
+  an added `.diagnostics["insolation_active"]` flag, via a new
+  `get_insolation_enabled()` (`InsolationEnabled`, attribute 912).
+
+- **Fixed a real accuracy bug**: `get_current_light_intensities()`
+  previously returned only the raw per-channel interpolated curve, missing
+  a schedule-level master intensity scalar (`Schedule1Intensity`, attribute
+  511) that the real app applies on top. Caught by direct comparison
+  against real app screenshots showing different numbers than this
+  library computed for the same light at the same time. Traced to
+  `WidgetViewCell.java`/`IntensityView.java` in the decompiled source.
+  Added `get_schedule_intensity()`; `get_current_light_intensities()` now
+  applies it automatically.
+- **Added lunar-phase and acclimation-ramp support**, the two remaining
+  modifiers flagged as gaps in the previous entry. New `mobius.modifiers`
+  module, ported from `LunarInfo.java`/`AcclimationInfo.java`:
+  - `lunar_percent_reduction(date)` -- verified against real,
+    independently-confirmed 2026 moon phase dates (full moon Jan 3, new
+    moon Jan 18); the ported algorithm matches exactly.
+  - `AcclimationInfo` -- linear intensity ramp from a starting percentage
+    up to full over a configured period.
+  - `is_night_segment()` -- ported from the boolean half of
+    `PointSchedule.getIntensitiesAtTime()`; confirmed this is specifically
+    "the dusk-to-night transition segment," not simply "is it night."
+  - `get_lunar_enabled()`, `get_acclimation_info()`,
+    `get_current_light_intensities()` now applies the full branching the
+    app itself uses (night+lunar / night-no-lunar / day+active-acclimation
+    / day-no-acclimation).
+  - "Insolation" (a real per-calendar-day natural daylight simulation,
+    likely a paid/premium feature -- see `mobius.modifiers` docstring for
+    details) is a separate, rarer modifier the app also layers in; still
+    not implemented -- see `documentation/06-light-schedule.md`.
+  - 19 new tests across `tests/test_modifiers.py` and
+    `tests/test_light_intensity_branching.py`.
+
+## 0.1.2
+
+- 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.
+- `get_pump_telemetry()` now includes a confirmed `"speed_percent"` field
+  alongside the existing raw `"speed"`. `MotorSpeed` is confirmed (via the
+  decompiled app's own display code) to be a percentage of max pump power
+  in tenths of a percent, NOT RPM -- `String.format("%.0f%%",
+  Math.abs(currentSpeed / 10.0f))` is literally what the app does to this
+  exact value. `speed_percent` is that same `abs(speed)/10` conversion;
+  `speed` is still returned raw since its sign encodes rotation direction
+  (reverse), which `speed_percent` discards.
+- Fixed a real connection leak in `MobiusDevice.connect()`: if
+  `start_notify()` failed after the BLE connection was already
+  established (a known common flaky point right after a fresh connection),
+  the exception propagated out of `connect()` (`__aenter__`) -- and per the
+  async context manager protocol, a raising `__aenter__` means `__aexit__`
+  (and therefore `disconnect()`) is never called by the caller's `async
+  with` block. The already-open connection was left orphaned on the
+  adapter. Since callers like Home Assistant coordinators retry
+  periodically, this leak compounded over repeated failures, plausibly
+  exhausting a real adapter's connection-slot pool over time even with no
+  other integration competing for it and without any range/signal issue.
+  `connect()` now cleans up (disconnects) before re-raising if anything
+  fails after the connection is established. Added regression tests
+  confirming both the cleanup-on-failure and no-spurious-disconnect-on-
+  success behavior.
+
+## 0.1.0 — initial release
+
+- Core FSCI/C2CI wire protocol: framing, CRC16, Get/Set-attribute codec.
+  Verified byte-for-byte against real captured packets.
+- Scene control (`start_scene`, `start_feed_mode`, `resume_schedule`).
+- Pump telemetry (speed, estimated GPH) — verified live against real
+  VorTech MP40QD pumps.
+- Pump schedule reading (mode + parameters per time block) — verified live.
+- Light schedule reading + client-side interpolation, matching the app's
+  own behavior — verified live against real Radion XR15 G6 Pro lights.
+- Device discovery, identity (`get_device_info`), and a unified
+  `get_device_summary()` with explicit support tiers
+  (light / pump / pump-experimental / unsupported).
+- Advertisement-only discovery: model, serial, and `pan_id` (tank/mesh
+  grouping) with no GATT connection required — verified against 4 real
+  devices sharing one `pan_id`.
+- `mobius-scan` CLI.
+
+### Known gaps
+
+- `DoseV1` and `HotSauceV1` primitive types have no parser (see
+  `documentation/10-known-gaps-and-open-questions.md`).
+- `CoffeeV1` (NYOS Quantum) pump-primitive support is structurally
+  plausible but unverified against real hardware.
+- Thread/CoAP device-to-device relay (used by the official app to reach
+  devices without a direct BLE connection) is not implemented — this
+  library always connects directly to each device instead.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-mobius
-Version: 0.1.1
+Version: 0.1.3
 Summary: Reverse-engineered Python client for the Mobius BLE protocol (EcoTech Marine VorTech/Radion, AquaIllumination, Neptune Systems, NYOS)
 Project-URL: Homepage, https://code.r3pek.org/r3pek/python-mobius
 Project-URL: Documentation, https://code.r3pek.org/r3pek/python-mobius/src/branch/main/documentation
@@ -24,6 +24,7 @@ Requires-Python: >=3.9
 Requires-Dist: bleak>=0.21
 Provides-Extra: dev
 Requires-Dist: bleak-retry-connector>=3.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Provides-Extra: retry
 Requires-Dist: bleak-retry-connector>=3.0; extra == 'retry'

{python_mobius-0.1.1 → python_mobius-0.1.3}/documentation/00-overview.md

@@ -51,6 +51,8 @@ Interface conventions, extended by EcoTech).
 | [08-manufacturer-data.md](./08-manufacturer-data.md) | BLE advertisement format (no-connection discovery) |
 | [09-thread-coap-relay.md](./09-thread-coap-relay.md) | How the official app relays to devices without direct BLE (not implemented here) |
 | [10-known-gaps-and-open-questions.md](./10-known-gaps-and-open-questions.md) | Everything not yet confirmed or implemented |
+| [11-device-status-attributes.md](./11-device-status-attributes.md) | Flow range, override mode, battery backup, group/sync, calibration (light-only), maintenance |
+| [12-device-identity-and-address-stability.md](./12-device-identity-and-address-stability.md) | Why device identity is serial-number-based, not address-based |
 
 ## On the use of AI assistance
 

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

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

python_mobius-0.1.3/documentation/06-light-schedule.md

@@ -0,0 +1,216 @@
+# Light schedule
+
+## There is no "current intensity" attribute
+
+This is the single most important, least obvious thing about lights in
+this protocol: **the app does not read live output from a light at all.**
+There's no attribute you can `Get` that tells you what a light is currently
+displaying. Instead, the app fetches the entire programmed point-schedule
+and computes the current intensity **client-side**, by linearly
+interpolating between the two points that bracket the current time, then
+applying a schedule-level master intensity scalar on top (see below), plus
+acclimation-ramp and lunar-cycle modifiers this library still doesn't
+implement.
+
+This library's `get_current_light_intensities()` replicates that
+client-side computation. **Correction to an earlier version of this doc**:
+this was previously described as "confirmed correct by validating against
+real fetched schedules" -- that validation only checked the per-channel
+interpolation curve, not the schedule-level scalar below, which was
+missing entirely at the time and silently returned values that didn't
+match the app's real displayed numbers. Caught by direct comparison
+against real app screenshots. Fixed; see below.
+
+## Schedule-level master intensity (`Schedule1Intensity`, attribute 511)
+
+Confirmed via `WidgetViewCell.java`/`IntensityView.java` in the decompiled
+app: on top of the per-channel interpolated curve, the app applies a
+**separate schedule-level master dimmer** -- `dCurrentIntensity =
+schedule.intensity / 1000.0`, multiplied onto every channel's interpolated
+value. This is genuinely separate from any individual channel's own value,
+including the "Brightness" `VisualID` channel (which is just another
+regular per-channel value some models expose, not this).
+
+`get_schedule_intensity()` fetches this (a plain `Get` on
+`Schedule1Intensity`/`Schedule2Intensity`, no special indexing -- a short,
+0-1000, default 500/50% per the app's own initialization code).
+`get_current_light_intensities()` now applies it automatically.
+
+**Update**: lunar-phase and acclimation-ramp reductions, which are layered
+on top of this same scalar under specific conditions (night + lunar phases
+enabled; an active, incomplete acclimation period), are now also
+implemented -- see "Lunar phase and acclimation ramp" below. "Insolation"
+(a separate, rarer modifier) is still not.
+
+## Wire format
+
+### `Schedule1` / `Schedule2` attribute (500 / 503)
+
+`Get`-ing this attribute with `index=0, count=0xFFFF` returns every
+programmed point as a separate element in the response (see
+[03-attributes-and-opcodes.md](./03-attributes-and-opcodes.md) for the
+general Get-response shape).
+
+### Point format
+
+```
+time (u16 LE, minutes since midnight, 0-1439)
+flags (u8)
+primitiveData (variable)
+```
+
+Flags (confirmed bitmasks from the decompile):
+
+| Bit value | Meaning |
+|---|---|
+| 1 | `ACTIVE` — points without this bit set are skipped by this library entirely |
+| 2 | `NIGHT` |
+| 6 | `SUNRISE` (combination flag) |
+| 10 | `SUNSET` (combination flag) |
+
+### `LightPrimitive` (the `primitiveData` for `VisualV1` points)
+
+Repeating triplets, one per channel the point defines:
+
+```
+VisualID (u8) + intensity (u16 LE, 0-1000 = 0.0-100.0%)
+```
+
+Confirmed via a full 9-point schedule fetched live from two real XR15
+lights (identical schedules on both — a deliberately symmetric setup, not a
+parsing artifact, confirmed by the two lights having different serial
+numbers).
+
+## Interpolation algorithm
+
+Ported from `PointSchedule.getIntensitiesAtTime()`:
+
+1. Sort points by time.
+2. Find the two points that bracket the target minute-of-day, wrapping
+   around midnight (the point after the last one is treated as being on
+   "the next day," i.e. its time + 1440).
+3. For each channel present in either bracketing point, linearly
+   interpolate: `value(t) = v1 + (v2 - v1) * (t - t1) / (t2 - t1)`.
+4. Channels absent from a point default to `0` (off).
+
+Verified against a synthetic two-point schedule (exact endpoint values,
+midpoint blending, and midnight-wraparound blending all behave correctly —
+see `tests/test_light_schedule.py`) and against a real 9-point schedule
+fetched live, which produced a coherent daily light-intensity curve
+(dim moonlight overnight → ramp to full blues/UV midday → wind back down).
+
+## `SupportedColorChannels` (attribute 901)
+
+A static list of `VisualID` values (channel identities) a given light has —
+this is capability metadata, not live state. Confirmed via `Get` with
+`index=0, count=0xFFFF` against real hardware; both test lights reported
+the same 13-channel set (`Violet, CoolWhite, WarmWhite, Blue, UV, RoyalBlue,
+Green, Red, MoonlightBlue, MoonlightWhite, Brightness, StormProbability,
+CloudProbability`).
+
+## Lunar phase and acclimation ramp
+
+Both now implemented, on top of the schedule-level master intensity above.
+Ported from `LunarInfo.java`/`AcclimationInfo.java` in the decompiled app.
+
+**Lunar phase** (`lunar_percent_reduction(date)`): a simplified moon-phase
+model -- a Julian-Day-based calculation (`julian_day_from_date()`, the
+standard Fliegel-Van Flandern conversion) feeding a 16-entry lookup table
+(`LUNAR_CYCLE_SCALERS`), returning `0.0` at new moon ramping to `1.0` at
+full moon. Verified against real, independently-confirmed 2026 moon phase
+dates (full moon Jan 3 2026, new moon Jan 18 2026) -- the ported algorithm
+matches exactly.
+
+This replaces the normal schedule-intensity scalar specifically during the
+**dusk-to-night segment** of the schedule (see `is_night_segment()` below),
+and only when `LunarPhasesEnabled` (attribute 907) is set on the device --
+otherwise that segment just uses a flat `1.0` (full/unreduced) scalar,
+matching the app's own fallback.
+
+**`is_night_segment()`**: ported from the boolean half of
+`PointSchedule.getIntensitiesAtTime()`'s return value. This is *not*
+simply "is it night" -- confirmed by reading the Java source directly, it's
+specifically true for the segment whose start point is NOT flagged `NIGHT`
+or `SUNRISE` and whose end point IS flagged `NIGHT` (the dusk-transition
+segment), or when the query time exactly matches a `NIGHT`-flagged point.
+
+**Acclimation ramp** (`AcclimationInfo`): a linear intensity ramp from
+`start_intensity` (0-1000 permille) up to full (1000) over `period_days`,
+starting at `start_time` (unix timestamp). Applied as an additional
+multiplier on the schedule-level intensity, only during normal (non-night)
+segments, only while `AcclimationEnabled` is set and the ramp period hasn't
+completed yet.
+
+`get_current_light_intensities()` fetches and applies all of this
+automatically -- no separate calls needed for the common case.
+
+## Insolation detection (flagged, not implemented)
+
+Insolation itself is not implemented (see below), but
+`get_current_light_intensities()` does cheaply detect whether it's active
+and flag it, via `LightIntensityResult` -- the return value is a real
+dict (fully backward compatible with code that indexes/iterates it like a
+plain dict), with an added `.diagnostics` attribute:
+
+```python
+result = await device.get_current_light_intensities()
+if result.diagnostics["insolation_active"]:
+    # values were computed from the wrong schedule entirely -- see below
+    ...
+```
+
+This is a best-effort warning, not a refusal: the values are still
+returned even when Insolation is detected as active, since a possibly-
+wrong-but-present value is often more useful than nothing, and the
+severity depends on how different the real Insolation-derived schedule is
+from the manually-programmed one on a given day.
+
+## Hyperdrive (boosted channels above 100%)
+
+Some light channels can be driven above their normally-rated power
+(`MaxPower` > `NormalPower` for that channel), allowing programmed
+intensity values above `1000` permille (100%) on the wire, up to `2000`
+(200% of normal). Naively dividing a boosted raw value by 10 to get a
+percentage is wrong once it's above 1000 -- the true percentage depends on
+how much headroom that specific channel actually has.
+
+`get_current_light_intensities()` (and `interpolate_light_schedule()`
+underneath it) already handled boosted raw values correctly all along --
+nothing was capped or clamped, so the interpolation itself was never
+wrong. What was missing was converting a boosted raw value to an accurate
+*percentage* for display.
+
+`get_current_light_percentages()` is the corrected alternative: it fetches
+`MaxPower`/`NormalPower` (`get_channel_power_info()`, attributes `1504`/
+`1513`) and applies `channel_percent_value()` (`mobius.power`, ported from
+`LightPowerInfo.getPercentValue()`) per channel. For the overwhelming
+common case -- non-hyperdrive channels/devices, i.e. any raw value at or
+below 1000 -- this gives byte-identical results to the old `raw/10`
+shortcut; the extra machinery only changes anything for genuinely boosted
+channels. It also flags which channels are currently boosted via
+`.diagnostics["hyperdrive_channels"]`.
+
+This costs extra BLE round trips beyond `get_current_light_intensities()`
+alone (two more `Get`s for `MaxPower`/`NormalPower`). Use
+`get_current_light_intensities()` directly if you don't need hyperdrive
+accuracy or want to minimize round trips.
+
+**Not replicated**: `LightPowerInfo`'s `gm8b4()` lookup table -- a
+hardcoded wattage override for a handful of specific AquaIllumination
+Prime/Hydra model + channel combinations. Only relevant to those specific
+models; the general case (including every EcoTech Radion model this
+library has been verified against) doesn't use it.
+
+## Not implemented here
+
+- "Insolation" -- a real per-calendar-day natural daylight simulation:
+  each light stores a 365-entry table (one per day of the year, packed
+  into 8 bytes via `InsolationTable1`/`InsolationTable2`), where every
+  entry holds sunrise time, sunset time, sun intensity (0-100%), moonrise
+  time, moonset time, and moon intensity (0-100%) for that specific
+  calendar day. Lets a light automatically track real seasonal daylight
+  variation instead of running one fixed schedule year-round. Gated
+  behind `AccountSettings.hasPermission()` in the app -- likely a
+  paid/premium feature, not merely an obscure one. Not implemented here;
+  treated as always-disabled.
+- Writing/programming a schedule (only reading is implemented).

python_mobius-0.1.3/documentation/11-device-status-attributes.md

@@ -0,0 +1,166 @@
+# Device status attributes (pump-specific and generic)
+
+Beyond live telemetry (`get_pump_telemetry()`, see
+[03-attributes-and-opcodes.md](./03-attributes-and-opcodes.md)) and the
+programmed schedule ([07-pump-schedule.md](./07-pump-schedule.md)), pumps
+expose several additional static-capability and configuration attributes.
+This document also covers a few attributes that aren't pump-specific
+(group/sync info, calibration, maintenance tracking), grouped here since
+they're all read via the same small set of `MobiusDevice` methods.
+
+## Pump-specific attributes
+
+## Flow range (`get_pump_flow_range()`)
+
+`MinimumGallonsPerHour`/`MaximumGallonsPerHour` (707/708) — the pump's
+rated flow spec range. This is static capability info (like
+`SupportedColorChannels` for lights), not a live reading. Confirmed via
+`FlowRange.java` in the decompile to **not** apply to `VectraV1` pumps
+specifically (explicitly excluded in the app's own support check).
+
+## Override mode (`get_pump_override_mode()`)
+
+`PumpOverrideMode` (705) — `None`/`AllOff`/`Manual`. **Confidence note**:
+confirmed in the decompile only as a *write* target (the app sets it to
+`None` to exit override mode after the pump-side calibration flow) --
+never actually read anywhere in the app itself. This library's read
+implementation is a reasonable inference (plain byte enum, matching every
+other attribute of this shape in the protocol), not something directly
+observed being read by the real app.
+
+## Battery backup (`get_battery_backup_info()`, `get_boosted_battery_info()`)
+
+- `BatteryBackupSpeed` (706, current setting) / `BatteryBackupMaxSpeed`
+  (701, ceiling) — confirmed via `BatterySpeed.java`. Same 0-1000-permille
+  speed-percentage convention as `MotorSpeed`.
+- `BoostedBatteryPower` (803) / `BoostedBatteryPowerOnTime` (804) /
+  `BoostedBatteryPowerOffTime` (805) — confirmed via `BoostedBattery.java`.
+  A pulsed battery-backup power mode. Units for the on/off time fields
+  aren't confirmed beyond being raw shorts (plausibly seconds, matching
+  the pattern of other duration fields elsewhere in the protocol, but not
+  independently verified).
+
+All four methods fail soft (return `None`) if the underlying attribute(s)
+aren't supported or fail to fetch, rather than raising -- these are all
+genuinely optional/model-dependent.
+
+## Generic (not pump-specific)
+
+## Group/sync info (`get_group_info()`)
+
+`GroupMaster` (900) / `IsGroupMaster` (911). **Confidence note**: neither
+attribute is referenced anywhere in the decompiled app beyond their own
+enum definitions -- genuinely dead/unused in this app version, the same
+situation as `MotorRPM`. `group_master` is returned as raw bytes rather
+than interpreted. **Confirmed against real hardware to be 28 bytes when
+populated** (a real Radion light returned a 28-byte all-zero value; real
+VorTech pumps tested returned nothing for either attribute, i.e.
+unsupported) -- this corrects an earlier guess here that it was probably
+8 bytes by loose analogy to the `Master` field in `Sync`/`EcoSmartBack`
+pump modes (see [07-pump-schedule.md](./07-pump-schedule.md)); that
+analogy was wrong. The all-zero value observed is consistent with "no
+group master set," but the field's actual semantics remain unconfirmed --
+still dead in the app itself. `is_group_master` uses the
+single-byte-boolean convention confirmed consistently across every other
+boolean attribute in this protocol.
+
+## Calibration (`get_calibration_info()`) -- a LIGHT feature, not a pump one
+
+`IsCalibrated` (1300) / `LastCalibrationTime` (1304) / `MinCalibratedSpeed`
+(1308) / `MaxCalibratedSpeed` (1309).
+
+Despite the "Speed"-sounding attribute names (a naming legacy from these
+attributes' shared use across device types in the protocol), **confirmed
+via the decompiled app's own UI gating** that this is surfaced only for
+lighting-category devices:
+
+```java
+// DeviceSettingsFragment.java
+if (Feature.checkSupport(Calibration.class, this.device)
+        && this.device.primitive.category() == M.DeviceCategory.Lighting) {
+    this.sects.add(4, Section.Calibration);
+}
+```
+
+Tapping it launches `LightCalibrationActivity`, a dedicated LED low-end/
+high-end calibration wizard (`c2development.mobius.lighting.calibration.*`
+in the decompile). There's a *separate*, unrelated pump-side calibration
+flow in the app (`c2development.mobius.flow.calibration.CalibrationActivity`
+-- zero-flow/max-flow calibration, relevant to Nero-class pumps with a
+genuine flow sensor, gated elsewhere by checking the pump isn't in Vectra
+closed-loop mode) -- **not implemented here**, and unrelated to this
+attribute set. It wouldn't apply to VorTech pumps anyway, which use
+magnetic drive with no physical flow sensor to calibrate.
+
+Confirmed via real device testing that VorTech pumps specifically do not
+expose Calibration in the app -- expect `get_calibration_info()` to
+return `None` (unsupported) against VorTech and similar pumps, and to
+work against Radion lights.
+
+## Maintenance tracking (`get_maintenance_info()`)
+
+`RecommendedMaintenanceInterval` (1400) / `MaintenanceTimer` (1401) /
+`LastMaintenanceTime` (1402) / `MaintenanceDue` (1403). **Confidence
+note**: none of these four attributes are referenced anywhere in the
+decompiled app beyond their own enum definitions -- genuinely dead/unused
+in this app version, the same situation as `MotorRPM` and
+`GroupMaster`/`IsGroupMaster`. Because there's zero evidence for the
+actual byte width/encoding of any of these fields, this deliberately
+returns **raw bytes** for each one rather than guessing a specific
+integer width and risking silently misinterpreting real device data. If
+you have hardware that actually populates these, please report back what
+you observe so the real format can be pinned down.
+
+## Firmware and hardware info (`get_firmware_versions()`, `get_hardware_info()`)
+
+`FirmwareVersion` (attribute 1) and `HardwareRevision` (attribute 2) are
+both sub-indexed -- a `Get` with `index=0, count=0xFFFF` returns one
+element per component the device has, the same "get all elements" pattern
+as `MaxPower`/`NormalPower`/`SupportedColorChannels`. The sub-index is
+`FirmwareType`/`HardwareInfo` respectively (see `mobius.constants`).
+
+**Firmware version display labels are fully confirmed against real
+hardware.** `FirmwareType.name(Model)` in the decompiled app maps each
+`FirmwareType` value to the exact label shown in the UI, gated by
+manufacturer. For EcoTech Marine devices specifically (the `isEtm()`
+branch), confirmed to match real output exactly:
+
+| `FirmwareType` | Value | Label |
+|---|---|---|
+| `OS` | 1 | Radio |
+| `Bootloader` | 2 | Radio Bootloader |
+| `MainMicroOS` | 3 | Product OS |
+| `MainMicroBootloader` | 4 | Product Bootloader |
+| `QCA4020Firmware` | 5 | Radio Firmware |
+| `QCA4020FileSystem` | 6 | Filesystem |
+| `QCA4020M4F` | 7 | Radio OS |
+| `QCA4020M0` | 8 | Radio |
+| `QCA4020WLAN` | 9 | WLAN |
+
+A real VorTech pump showed exactly Radio/Radio Bootloader/Product
+OS/Product Bootloader (values 1-4); a real Radion light showed exactly
+Product OS/Product Bootloader/Radio Firmware/Filesystem/Radio OS/Radio/
+WLAN (values 3-9, confirming lights use a QCA4020-based radio chip with
+WiFi+BLE, unlike the simpler radio in pumps). `get_firmware_versions()`
+takes an optional `model` parameter to apply these confirmed labels;
+without it (or for non-EcoTech models, whose label mapping in the
+decompile is a different, unverified branch), falls back to the raw
+`FirmwareType` enum name.
+
+Each version is a **dot-joined string built directly from the raw
+response bytes** (e.g. `[4, 0, 21]` -> `"4.0.21"`) -- confirmed via
+`FirmwareType.format()` in the decompile, which does exactly that and
+nothing more exotic.
+
+`get_hardware_info()` follows the same fetch pattern for
+`HardwareRevision`/`HardwareInfo`, but **no display-formatting convention
+is confirmed** for those fields (`Color`/`Revision`/`ProductType`/
+`RadioType`/`MotorType`/`Segments` read more like small integer/enum
+codes than version numbers) -- returns raw bytes per field rather than
+guessing a format.
+
+Both are included automatically in `get_device_summary()`'s
+`"firmware_versions"` field (using the confirmed EcoTech labels, since
+`get_device_summary()` already has the device's `Model` on hand).
+`get_hardware_info()` is not currently wired into the summary -- call it
+directly if you want it.