python-mobius 0.4.4__tar.gz → 0.6.0__tar.gz

{python_mobius-0.4.4 → python_mobius-0.6.0}/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## 0.6.0
+
+- get_metadata_batch() now falls back to individual reads if the
+  batched request itself fails (e.g. no batch support at all) --
+  never returns less than those would have. New `used_batch` field,
+  `force_individual_reads` param.
+- Added get_metadata_batch() -- one round-trip for AdvancedFeatures/
+  CalibrationInfo/hardware/firmware/channels/error state/time,
+  confirmed 6-14x faster than individual reads over relay.
+- Wired set_advanced_features() into cli.py -- one flag per field
+  (--set-local-control-enabled/--set-auto-dim-timeout/
+  --set-max-fan-speed/--set-fan-shutdown-enabled).
+- Added set_advanced_features() -- writes LocalControlEnabled/
+  AutoDimTimeout/MaxFanSpeed/FanShutdownEnabled, whichever are given.
+- get_current_light_intensities() now uses get_app_lunar_date(),
+  deliberately replicating a confirmed app bug in its lunar
+  calculation instead of the physically correct date.
+- Fixed RelayedMobiusDevice missing overrides for
+  get_supported_attributes()/get_attributes_batch() -- both bypassed
+  the relay path entirely.
+- Fixed --dump-attributes/--set-time-to-now in cli.py ignoring
+  --relay-target.
+- Added get_attributes_batch() -- reads multiple attributes in one
+  round-trip.
+- Added get_supported_attributes()/dump_attributes()/
+  enrich_attribute_dump(), replicating the app's own attribute-dump
+  feature. New CLI flags: --dump-attributes/--parse-dump.
+
+## 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,
@@ -244,9 +308,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
@@ -298,8 +361,8 @@ branch has been merged into main as part of this release.
   is a bare, meaningless ack the app itself discards, confirmed
   byte-for-byte via real hardware testing showing exactly 1 byte in every
   relayed read's outer response), matched purely by CoAP token
-  (confirmed via reverse engineering: `coapRequest.getToken() ==
-  coapResponse.getToken()`), never by the outer FSCI message ID. Added
+  (confirmed via reverse engineering: the request's own token must
+  match the response's own token), never by the outer FSCI message ID. Added
   `MobiusDevice._register_coap_token()`/`wait_for_coap_response()` -- a
   token-keyed pending-response registry, entirely separate from the
   existing message-ID-based `self._pending` mechanism -- wired into
@@ -417,7 +480,8 @@ branch has been merged into main as part of this release.
   (`get_device_summary()`, `get_current_light_intensities()`, etc.) works
   transparently through relay, confirmed with a test that specifically
   exercises an inherited high-level method rather than just the
-  overridden primitives. Confirmed `request.getData(true)` builds a
+  overridden primitives. Confirmed via reverse engineering the app that its
+  own request wrapping builds a
   complete self-contained FSCI frame (byte-for-byte identical in
   structure to this library's own `build_frame()`), resolving an
   ambiguity flagged in an earlier commit -- relaying a request needed no
@@ -529,10 +593,11 @@ branch has been merged into main as part of this release.
 
 - **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
+  between runs. Investigating the app via reverse engineering
   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
+  its own equality and hash logic for a discovered device are based purely
+  on serial number, and
+  its own update logic 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()`
@@ -609,8 +674,8 @@ branch has been merged into main as part of this release.
   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
+  results for genuinely boosted channels. A confirmed Prime/Hydra-
+  specific 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
@@ -680,11 +745,11 @@ branch has been merged into main as part of this release.
   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;
+  alongside the existing raw `"speed"`. `MotorSpeed` is confirmed (via
+  reverse engineering the app's own display code) to be a percentage of max pump power
+  in tenths of a percent, NOT RPM -- the app's own display logic formats
+  this same value with the exact same abs-value, tenths-to-percent
+  conversion. `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

{python_mobius-0.4.4 → python_mobius-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-mobius
-Version: 0.4.4
+Version: 0.6.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,34 @@ 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.
+- **Dump every attribute a device supports** (`dump_attributes()`),
+  matching the app's own Settings → Troubleshoot diagnostic feature's
+  data collection — confirmed against real hardware. Output is enriched
+  JSON (resolved names, decoded values where known), not the app's own
+  plain-text format. See
+  [13-attribute-dump.md](./documentation/13-attribute-dump.md).
 - **Low-level protocol access** (`build_frame`, `get_attribute`,
   `set_attribute`, ...) if you want to go beyond what's wrapped in
   `MobiusDevice`.
@@ -113,13 +139,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.4 → python_mobius-0.6.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,34 @@ 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.
+- **Dump every attribute a device supports** (`dump_attributes()`),
+  matching the app's own Settings → Troubleshoot diagnostic feature's
+  data collection — confirmed against real hardware. Output is enriched
+  JSON (resolved names, decoded values where known), not the app's own
+  plain-text format. See
+  [13-attribute-dump.md](./documentation/13-attribute-dump.md).
 - **Low-level protocol access** (`build_frame`, `get_attribute`,
   `set_attribute`, ...) if you want to go beyond what's wrapped in
   `MobiusDevice`.
@@ -81,13 +107,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.4 → python_mobius-0.6.0}/documentation/00-overview.md

@@ -34,7 +34,7 @@ Interface conventions, extended by EcoTech).
    and two Radion XR15 G6 Pro lights, all sharing one tank. Every field
    marked "confirmed" in these docs was checked this way — either by
    successfully round-tripping known values, or by cross-validating two
-   independent derivations (e.g. a value read via decompiled Java source
+   independent derivations (e.g. a value read via a decompiled source
    matching a value read live over BLE).
 
 ## Document map
@@ -53,12 +53,14 @@ Interface conventions, extended by EcoTech).
 | [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 |
+| [13-attribute-dump.md](./13-attribute-dump.md) | Reading every attribute a device supports, enriched JSON output, the app-compatible text format |
+| [14-batched-attribute-reads.md](./14-batched-attribute-reads.md) | Reading multiple, different attributes in one round-trip |
 
 ## On the use of AI assistance
 
 The decompiled-source analysis, protocol derivation, and Python
 implementation in this project were done with substantial assistance from
-Claude (Anthropic) — reading the decompiled Java sources, cross-referencing
+Claude (Anthropic) — reading the decompiled app sources, cross-referencing
 them against the public community research above, resolving several
 decompilation artifacts specific to the reverse-engineering process (see
 [03-attributes-and-opcodes.md](./03-attributes-and-opcodes.md) for a

{python_mobius-0.4.4 → python_mobius-0.6.0}/documentation/02-framing-and-crc.md

@@ -26,7 +26,7 @@ using this library's own encoder, matching the captured bytes exactly (see
 
 ## opGroup values
 
-Java's original constants are signed bytes:
+The app's own original constants are signed bytes:
 
 | Name | Signed | Unsigned (hex) |
 |---|---|---|

{python_mobius-0.4.4 → python_mobius-0.6.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.4 → python_mobius-0.6.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.4 → python_mobius-0.6.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.4 → python_mobius-0.6.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,69 @@ 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. This is a THIRD,
+independent value from the two below -- see the real-hardware findings
+just below for why all three (this one, the app's own display, and
+what the LEDs physically do) can genuinely differ from each other.
+
+**A confirmed bug in the app itself -- and this library deliberately
+replicates it.** The app's own `date`-to-calendar-day conversion
+(confirmed via disassembling the actual raw bytecode with androguard,
+not just the decompile -- see `get_app_lunar_date()`'s own docstring
+in device.py for the full instruction-level trace) applies a timezone
+shift TWICE: once converting `Epoch` to `LocalTime` (the device's own
+job), and again via the phone's own equivalent calendar-day
+conversion, reading the PHONE's own
+timezone off a value that's already been shifted once. When phone and
+device agree on timezone (assumed here, since this library can't know
+the phone's own setting), the net effect is the SAME offset applied
+twice -- not once. For UTC+1, that means the app's own effective
+calendar day rolls over **two hours early**, not one -- confirmed by
+working the exact arithmetic (`2 * LocalTime - Epoch`) and
+independently verified against real captured device data spanning
+both a real summer evening and a forced-clock winter test:
+
+- **Summer (UTC+1)**: at 23:25 and again at 23:55 local -- both well
+  before that night's true midnight -- the app's own formula computed
+  the NEXT calendar day's scalar, while the device's own reported
+  `LunarPhasesCurrentDay`/`CurrentScalar` were both still on the
+  PREVIOUS day at those exact same moments. The two only agreed again
+  once true midnight had actually passed.
+- **Winter (UTC+0)**: the formula and the device's own reported values
+  agreed exactly at every point tested -- confirming the shift
+  magnitude really does scale with the timezone offset, and vanishes
+  entirely at zero.
+
+`get_current_light_intensities()` uses `get_app_lunar_date()`
+specifically (not `get_device_local_date()`, which is the physically
+correct one) for this calculation, because this method's own stated
+job is to replicate what the app itself shows -- bugs included, not to
+compute ground truth. A `ha-mobius` user comparing this library's
+output against the official app should see them agree, including
+during the window where the app is (confirmedly) wrong about the
+calendar day.
+
+**A separate, ALSO real-hardware-confirmed finding: the device's own
+physical LED output doesn't track EITHER of the above continuously.**
+Three real dumps of a real light, spanning an actual midnight
+rollover, cross-checked against the device's own live `Intensity`
+(1500) readback and direct visual/power observation, showed the
+device locks its own scalar in ONCE -- at the moment the evening's
+ramp into the night segment physically completes -- and holds that
+exact value fixed for the rest of the night, regardless of what
+`LunarPhasesCurrentDay`/`CurrentScalar` do afterward. Neither this
+library's own calculation nor the app's own display attempts to model
+this transition-locked behavior; both compute a value continuously,
+as if the physical output tracked the calendar day in real time. It
+doesn't. This is a third, genuinely different value from the two
+above, not a bug in either of them -- there's no confirmed way to
+predict the device's own physical value from `Epoch`/`LocalTime` alone
+without also knowing when the most recent schedule transition into
+the night segment actually completed.
+
 ## Insolation detection (flagged, not implemented)
 
 Insolation itself is not implemented (see below), but
@@ -214,22 +275,31 @@ from the manually-programmed one on a given day.
 
 `.diagnostics` also includes `"is_night_segment"`, `"lunar_enabled"`,
 `"scalar_source"` (one of `"lunar"`/`"night_no_lunar"`/
-`"schedule_intensity"`), and `"scalar"` (the actual final multiplier
-applied) -- useful for telling apart which branch/scalar produced a given
-value, e.g. when a computed value doesn't match the app's own displayed
-one and it isn't obvious whether `is_night_segment()` misjudged a
-schedule's point structure or `get_lunar_enabled()` read incorrectly:
+`"schedule_intensity"`), `"scalar"` (the actual final multiplier
+applied), and, specifically for the `"lunar"` case, `"lunar_date"` (the
+actual date `get_app_lunar_date()` computed -- see that section above
+for why this is deliberately the app's own, confirmed-buggy value, not
+the physically correct one) and `"lunar_date_source"` (one of
+`"app_lunar_date"`/`"local_fallback"`) -- useful for telling apart
+which branch/scalar produced a given value, e.g. when a computed value
+doesn't match the app's own displayed one and it isn't obvious whether
+`is_night_segment()` misjudged a schedule's point structure,
+`get_lunar_enabled()` read incorrectly, or the date computation itself
+went wrong:
 
 ```python
 result = await device.get_current_light_intensities()
 print(result.diagnostics)
 # {'insolation_active': False, 'is_night_segment': True,
-#  'lunar_enabled': True, 'scalar_source': 'lunar', 'scalar': 0.35}
+#  'lunar_enabled': True, 'scalar_source': 'lunar', 'scalar': 0.6,
+#  'lunar_date': datetime.date(2026, 8, 29), 'lunar_date_source': 'app_lunar_date'}
 ```
 
 `lunar_enabled` is `None` (not `False`) when `is_night_segment` is
 `False`, since it isn't checked/relevant outside the night segment --
-don't read a `None` here as "lunar phases are off."
+don't read a `None` here as "lunar phases are off." Similarly,
+`lunar_date`/`lunar_date_source` are both `None` whenever
+`scalar_source` isn't `"lunar"`.
 
 ## Hyperdrive (boosted channels above 100%)
 
@@ -243,7 +313,7 @@ how much headroom that specific channel actually has.
 `get_current_light_percentages()` accounts for this: 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 common case --
+the app's own confirmed equivalent logic) per channel. For the common case --
 non-hyperdrive channels/devices, i.e. any raw value at or below 1000 --
 this gives the same results as a simple `raw/10`; the extra machinery
 only changes anything for genuinely boosted channels. It also flags which
@@ -254,22 +324,39 @@ alone (two more `Get`s for `MaxPower`/`NormalPower`). Use
 `get_current_light_intensities()` directly if hyperdrive accuracy isn't
 needed, or to minimize round trips.
 
-**Not replicated**: `LightPowerInfo`'s `gm8b4()` lookup table -- a
+**Not replicated**: a lookup table confirmed present in the app -- 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
+## The insolation modifier itself -- not implemented here
+
+Raw reading of the underlying attributes IS implemented (see
+`get_insolation_tables()`/`InsolationTables` below) -- what's NOT
+implemented is the client-side modifier that would actually use this
+table to adjust intensity based on the calendar day, the way
+`mobius.modifiers`'s own lunar/acclimation modifiers already do for
+their own attributes.
 
 - "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
+  each light stores a 365-entry table (one per day of the year), 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. Confirmed via reverse engineering the app that
+  each entry is packed into 8 bytes -- but the actual raw bytes read
+  from `InsolationTable1`/`InsolationTable2` (see
+  `get_insolation_tables()`/`InsolationTables` in device_status.py) are
+  9 bytes per entry on a real light; this discrepancy is unresolved,
+  and since every entry captured so far was all-zero (unconfigured),
+  there's no way to independently confirm the field-level byte layout
+  either way. `get_insolation_tables()` returns raw per-entry bytes
+  rather than decoding this structure, for exactly that reason. 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.
+  behind an account-level permission check in the app -- likely a
+  paid/premium feature, not merely an obscure one. The lunar/
+  acclimation MODIFIERS in `mobius.modifiers` are implemented and
+  confirmed; this separate, rarer modifier is not, and is treated as
+  always-disabled by those modifiers.
 - Writing/programming a schedule (only reading is implemented).