python-mobius 0.2.0__tar.gz → 0.2.1__tar.gz

{python_mobius-0.2.0 → python_mobius-0.2.1}/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.2.1
+
+- **Fixed a real bug found via real hardware testing: some "get all
+  elements" responses were silently truncated to their first block.**
+  `get_attribute_raw()` returned only the first matching
+  `(attrId, index, count, values)` block in a response and discarded any
+  others -- a Radion light showing 8 firmware components in the official
+  app came back as only 5 via `get_firmware_versions()`, because that
+  light's `FirmwareVersion` response genuinely splits across two
+  separate blocks (one covering `MainMicroOS`/`MainMicroBootloader`,
+  another covering the `QCA4020`-prefixed types), not one block covering
+  every element. Added `get_attribute_raw_all()`/`get_attribute_all()`
+  (`MobiusDevice`, with a matching `RelayedMobiusDevice` override --
+  without one, callers built on these would have silently fallen through
+  to `MobiusDevice`'s own non-relay implementation when called on a
+  relayed device) -- return every matching block instead of just the
+  first. `get_firmware_versions()`, `get_hardware_info()`,
+  `get_channel_power_info()`, and `get_supported_channels()` are now
+  built on these rather than the single-block versions, merging every
+  block's values, each interpreted using its own block's starting index.
+  5 new tests, including ones that specifically reproduce the two-block
+  scenario found on real hardware, both directly and through relay.
+
 ## 0.2.0
 
 Thread/CoAP device relay -- see

{python_mobius-0.2.0 → python_mobius-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-mobius
-Version: 0.2.0
+Version: 0.2.1
 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

{python_mobius-0.2.0 → python_mobius-0.2.1}/documentation/00-overview.md

@@ -49,7 +49,7 @@ Interface conventions, extended by EcoTech).
 | [06-light-schedule.md](./06-light-schedule.md) | Light point-schedule format + client-side interpolation |
 | [07-pump-schedule.md](./07-pump-schedule.md) | Pump primitive format, mode/parameter tables, block lookup |
 | [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) |
+| [09-thread-coap-relay.md](./09-thread-coap-relay.md) | Relaying requests to devices without a direct BLE connection, through another connected device |
 | [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 |

{python_mobius-0.2.0 → python_mobius-0.2.1}/documentation/06-light-schedule.md

@@ -8,18 +8,12 @@ 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.
+applying a schedule-level master intensity scalar (see below), plus
+lunar-cycle and acclimation-ramp modifiers under specific conditions.
 
 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.
+client-side computation, including the master intensity scalar and the
+lunar/acclimation modifiers.
 
 ## Schedule-level master intensity (`Schedule1Intensity`, attribute 511)
 
@@ -34,13 +28,13 @@ 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.
+`get_current_light_intensities()` 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.
+Lunar-phase and acclimation-ramp reductions layer on top of this same
+scalar under specific conditions (night + lunar phases enabled; an
+active, incomplete acclimation period) -- see "Lunar phase and
+acclimation ramp" below. "Insolation" (a separate, rarer modifier) is
+not implemented.
 
 ## Wire format
 
@@ -76,10 +70,8 @@ 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).
+Confirmed against a full 9-point schedule fetched live from real XR15
+lights.
 
 ## Interpolation algorithm
 
@@ -94,32 +86,29 @@ Ported from `PointSchedule.getIntensitiesAtTime()`:
 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).
+midpoint blending, and midnight-wraparound blending -- see
+`tests/test_light_schedule.py`) and against a real 9-point schedule
+fetched live, which produces 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`).
+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.
 
 ## Lunar phase and acclimation ramp
 
-Both now implemented, on top of the schedule-level master intensity above.
+Both 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.
+full moon. Verified against independently-confirmed real 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),
@@ -129,10 +118,10 @@ 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.
+simply "is it night" -- 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`,
@@ -147,8 +136,8 @@ 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
+`get_current_light_intensities()` cheaply detects whether it's active
+and flags 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:
 
@@ -165,18 +154,15 @@ 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.
 
-## Debugging diagnostics: which branch/scalar was actually used
+## Diagnostics: which branch/scalar was actually used
 
 `.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). Added specifically because a mismatch between this library's
-computed value and the app's own displayed value could stem from either
-`is_night_segment()` misjudging a specific schedule's point structure, or
-`get_lunar_enabled()` reading incorrectly -- and those need to be told
-apart with real data rather than guessed at. If you ever see a value that
-doesn't match the app, check these fields first before assuming which
-piece is wrong:
+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:
 
 ```python
 result = await device.get_current_light_intensities()
@@ -198,26 +184,19 @@ intensity values above `1000` permille (100%) on the wire, up to `2000`
 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
+`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 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"]`.
+`LightPowerInfo.getPercentValue()`) 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
+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.
+`get_current_light_intensities()` directly if hyperdrive accuracy isn't
+needed, or to minimize round trips.
 
 **Not replicated**: `LightPowerInfo`'s `gm8b4()` lookup table -- a
 hardcoded wattage override for a handful of specific AquaIllumination

python_mobius-0.2.1/documentation/09-thread-coap-relay.md

@@ -0,0 +1,214 @@
+# Thread/CoAP device relay
+
+Every device this library talks to normally needs its own direct,
+persistent BLE connection. The official app doesn't work this way -- it
+connects to just one or a few devices and reaches the rest through them.
+If something else (this library, a downstream integration, or another
+instance of the app) is already holding direct BLE connections to every
+device, the app can end up with nothing to connect to at all. Relay lets
+this library behave the same way the app does: connect to one device,
+reach the others through it.
+
+`mobius.relay.RelayedMobiusDevice` implements this. Every method on
+`MobiusDevice` (`get_device_summary()`, `get_current_light_intensities()`,
+everything) works transparently through it, since all of them are built
+in terms of `get_attribute()`/`get_attribute_raw()`/`set_attribute()` --
+the three methods `RelayedMobiusDevice` overrides.
+
+## How it works
+
+Devices form a Thread mesh network (802.15.4 radio, separate hardware
+from BLE) identified by a `pan_id` (see
+[08-manufacturer-data.md](./08-manufacturer-data.md)). The Thread
+border-router function lives on the connected device itself, not on the
+phone -- a phone (or a laptop) never needs its own 802.15.4 radio, only
+BLE to reach one mesh member, which does the Thread-side forwarding
+using its own onboard hardware.
+
+Routing decision, from `Comm.java`'s `sendRequest()`:
+
+```java
+if (commDevice.equals(request.getTarget())) {
+    // direct: send over the existing BLE connection as-is
+} else if (iPv6 != null) {
+    // relay: wrap in CoAP, address it to the target's mesh IPv6,
+    // send through commDevice (the connected gateway)
+} else {
+    // no known address for the target -- fail
+}
+```
+
+## CoAP wire format
+
+Reuses the same C2CI envelope described in
+[02-framing-and-crc.md](./02-framing-and-crc.md), with two new opcodes
+alongside the existing Get(`0x17`)/Set(`0x18`) attribute opcodes:
+
+- **`25`** (`mobius.coap.COAP_OPCODE`) -- the request opcode. Its
+  confirm is a bare, meaningless 1-byte ack (`Coap.RequestType`/etc. are
+  set, but the payload carries no real data) -- the app itself
+  unconditionally discards it in `BaseConnection.java`'s `handleBytes()`
+  before ever checking whether it resolves a pending request. This
+  library sends on this opcode without waiting for its confirm
+  (`wait_response=False`).
+- **`26`** (`mobius.coap.COAP_INDICATION_OPCODE`) -- where the real
+  response actually arrives, as a separate, asynchronous message
+  ("indication"). Matched to its originating request purely by CoAP
+  token, from `BaseConnection.java`'s `lambda$getSentRequest$6`:
+  `coapRequest.getToken() == coapResponse.getToken()`. The outer FSCI
+  message ID is never used for this correlation -- it only has meaning
+  for the single BLE hop to the gateway, not across a full Thread mesh
+  round-trip.
+
+**Request** (`encode_coap_request()`) -- `CoapRequest`'s constructor:
+```
+IPv6(16 bytes, REVERSED) + token(4, LE) + method(2, LE)
++ payload_length(2, LE) + request_type(1) + payload
+```
+
+**Response** (`decode_coap_response()`) -- `CoapResponse`'s constructor:
+```
+IPv6(16 bytes, NOT reversed) + token(4, LE) + response_code(2, LE)
++ payload_length(2, LE) + request_type(1) + payload
+```
+
+The IPv6 reversal is asymmetric: requests reverse the address, responses
+don't. Easy to get backwards -- `mobius.coap`'s test suite specifically
+checks this with a deliberately non-palindromic test address, since a
+palindromic one would still pass even with the reversal backwards or
+missing.
+
+**The payload is a complete, self-contained FSCI frame** -- byte-for-byte
+identical in structure to what this library's own `build_frame()`
+produces for a direct request (`opGroup + opCode + messageId(2) +
+reserved(1) + dataLength(2) + data + CRC16(2)`, prefixed with the magic
+byte `0x02`). Relaying a request is exactly as simple as that sounds:
+build the request the normal way, wrap that complete frame wholesale as
+the CoAP payload, and send it to the gateway on the CoAP opcode instead
+of sending it directly. No separate encoding path for relayed vs. direct
+requests -- only the outer envelope differs.
+
+The CoAP method field is always `GET`, regardless of whether the
+relayed operation is itself a Get or Set attribute request -- the CoAP
+method is a generic transport-layer wrapper; the actual semantic
+operation is determined by the *inner* FSCI opcode.
+
+`Coap.ResponseCode` values are standard RFC 7252 codes (`2.01 Created`,
+`2.05 Content`, `4.00 Bad Request`, `5.00 Internal Server Error`, etc.,
+encoded as `class*100 + detail`) -- but `mobius.coap.CoapResponseCode`
+only defines the subset that could be independently confirmed as
+literal or reliably cross-referenced values (see that module's
+docstring for exactly which). An unrecognized response code decodes to
+a plain `int` rather than a guessed enum member, matching the real app's
+own graceful fallback behavior. In practice, the response code isn't
+load-bearing for this library -- the payload's own embedded FSCI frame
+carries its own CRC, which is what's actually checked.
+
+## Response correlation implementation
+
+`MobiusDevice` maintains a token-keyed pending-response registry
+(`_pending_coap_tokens`), separate from the existing message-ID-based
+`_pending` used for direct requests:
+
+- `_register_coap_token(token)` -- synchronous, registers and returns a
+  future immediately. Call this *before* sending the triggering request,
+  eliminating any race against the response arriving first.
+- `wait_for_coap_response(token, timeout)` -- convenience wrapper that
+  registers and awaits in one call; only race-free if nothing could
+  plausibly respond before it starts running.
+- `_on_rx_final()` resolves a pending token's future when a frame
+  matching `opGroup==0xDF && opCode==26` arrives and decodes to a
+  `CoapResponse` with a matching token -- entirely independent of the
+  normal message-ID-based resolution used for direct requests.
+
+`RelayedMobiusDevice._relay()` registers the token, sends the outer
+frame without waiting for its confirm, and awaits the token-matched
+indication with a timeout.
+
+## Address discovery
+
+A device's Thread mesh-local RLOC (Routing Locator) IPv6 address:
+
+```
+mesh_local_prefix(8 bytes) + 00:00(2 bytes) + 00:FF:FE:00(4 bytes)
++ short_address(2 bytes, LITTLE-ENDIAN)
+```
+
+The `00:FF:FE:00` marker is the standard Thread/6LoWPAN convention for a
+short-address-derived interface identifier (confirmed via
+`IPv6.isEui64Address()`'s exact byte check) -- a real, publicly
+documented Thread networking convention, not proprietary to EcoTech. The
+little-endian byte order for the short-address portion is the opposite
+of IPv6's own conventional big-endian (network byte order) -- confirmed
+via `ByteUtilities.getShort()`'s explicit `ByteOrder.LITTLE_ENDIAN`, not
+assumed.
+
+`mobius.mesh_address` implements construction (`build_rloc_address()`)
+and the reverse (`extract_short_address()`), plus
+`mesh_local_prefix_from_own_address()`/`is_valid_mesh_address()` for
+deriving a network's shared prefix from any one device's own address.
+
+### Two discovery mechanisms
+
+**`MobiusDevice.get_own_mesh_address()`** -- fetches `MeshLocalAddresses`
+(attribute `1005`) from the connected device itself. Returns that
+device's own complete 16-byte mesh-local address (not "the prefix" on
+its own -- extract the first 8 bytes yourself for the shared network
+prefix), sanity-checked as non-all-zero. Confirmed via
+`PeripheralConnection.java`'s `updateConnectionState()` ->
+`getDeviceInfo()` to be exactly what the official app does automatically
+on every connection to any non-legacy device -- universal, standard
+behavior, not tied to any specific hardware.
+
+**`mobius.discovery.discover_mesh_peers_via_direct_connect()`** -- the
+practical way to build a serial→IPv6 map across multiple devices:
+connects directly and briefly to each one in turn (sequentially, not
+concurrently), calling `get_own_mesh_address()` on each. Meant to be run
+once (or occasionally) to build the map, not on every poll cycle -- keep
+only one connection open afterward (the "gateway") and reach the rest via
+`RelayedMobiusDevice`.
+
+**`MobiusDevice.discover_mesh_peers()`** -- an alternative that asks a
+*connected* device to report on other devices it already knows about,
+via three parallel attributes:
+`ShortAddressArray`/`SerialNumberArray`/`DeviceModelArray` (`3700`/
+`3701`/`3702`, fetched via the same "get all elements" pattern used
+elsewhere in this library, index-matched). `SerialNumberArray`'s
+per-element format is the same 14-byte ASCII serial format used
+elsewhere in this library; a cleared/empty slot is the literal sentinel
+string `"00000000000000"` (fourteen ASCII zero characters, not null
+bytes), filtered out automatically. A fourth parallel array,
+`BladeBleAddressArray` (`3714`, each peer's real BLE MAC address), is
+recorded in `constants.py` but not used by this method.
+
+**This mechanism requires a dedicated Cowboy hub device.** These three
+arrays were originally found in `CowboyNetworkProcess.java` -- the class
+specifically for setting up a network via a Cowboy hub -- and on
+hardware without one, all three return `FsciStatus.UnsupportedAttribute`
+even though `MeshLocalAddresses` on that same device succeeds. Cheap and
+fails soft, so it's a reasonable first attempt, but
+`discover_mesh_peers_via_direct_connect()` is the mechanism to actually
+rely on unless a Cowboy hub is confirmed present.
+
+## CLI support
+
+`mobius-scan` flags for working with relay against real hardware:
+
+- `--dump-mesh-peers` -- runs `discover_mesh_peers()` (the Cowboy-hub
+  path) with verbose, step-by-step output at each stage (own address,
+  each of the three arrays), rather than collapsing every possible
+  failure into a single empty result.
+- `--build-peer-map` -- runs `discover_mesh_peers_via_direct_connect()`
+  across every device found in a scan.
+- `--relay-target SERIAL` (used with `--by-serial <gateway>`) -- looks
+  for the target among the gateway's Cowboy-tracked peers first; if not
+  found there, falls back to a brief direct connection to the target
+  itself to learn its address. Either way, relays a full
+  `get_device_summary()` read to it and prints the result.
+- `--debug-relay` (with `--relay-target`) -- prints raw bytes at every
+  layer of a relayed request/response: the inner request frame, the
+  outer request frame, every frame the gateway receives while waiting
+  (via `MobiusDevice.on_any_frame`, a hook called for every parsed
+  incoming frame regardless of whether it resolves anything), the
+  decoded CoAP envelope, the inner response frame, and the decoded
+  attribute status/values.

{python_mobius-0.2.0 → python_mobius-0.2.1}/documentation/10-known-gaps-and-open-questions.md

@@ -51,17 +51,6 @@ included as a starting point.
   The write path would need the same `Set`-attribute mechanism already
   implemented for scenes, applied to `Schedule1`/`Schedule2`, but hasn't
   been built or tested.
-- **Thread/CoAP device relay** — see
-  [09-thread-coap-relay.md](./09-thread-coap-relay.md) for the full
-  writeup of why and what it would take.
-- **Acclimation ramp / lunar cycle modifiers** for light interpolation —
-  the app layers these on top of the raw schedule interpolation; this
-  library returns the raw interpolated value only.
-- **`FirmwareVersion`/`HardwareRevision`** — these are sub-indexed per
-  `FirmwareType`/`HardwareInfo` (the same "attribute + index" pattern as
-  `PhysicalValues`), adding real complexity that wasn't worth it for the
-  currently-covered use cases. Straightforward to add following the same
-  pattern as `PhysicalValues`/`GallonsPerHour`.
 - **Group/master pump relationships** (`Sync`/`EcoSmartBack` modes'
   `Master` parameter) — the raw 8-byte BLE-address-suffix is returned, but
   matching it against known devices in a scan result is left to the

{python_mobius-0.2.0 → python_mobius-0.2.1}/documentation/11-device-status-attributes.md

@@ -55,14 +55,11 @@ 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.
+unsupported). 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
 
@@ -119,6 +116,25 @@ 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`).
 
+**A single such response can split across more than one block.**
+Confirmed via real hardware testing: a Radion light showing 8 firmware
+components in the official app initially came back with only 5 via this
+library, because the underlying transport method returned just the
+first `(attrId, index, count, values)` block in the response and
+silently discarded the rest -- this device's `FirmwareVersion` response
+genuinely arrives as two separate blocks (one covering
+`MainMicroOS`/`MainMicroBootloader`, another covering the
+`QCA4020`-prefixed types), not one block covering every element. Fixed
+via `get_attribute_raw_all()`/`get_attribute_all()` (`MobiusDevice`, and
+`RelayedMobiusDevice` with a matching override for the same reason),
+which return every matching block rather than just the first;
+`get_firmware_versions()`, `get_hardware_info()`,
+`get_channel_power_info()`, and `get_supported_channels()` are all built
+on these rather than the single-block `get_attribute_raw()`/
+`get_attribute()`, and merge every block's values together, each
+interpreted using its own block's starting index (never assuming one
+single starting index covers every returned value).
+
 **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
@@ -138,14 +154,15 @@ branch), confirmed to match real output exactly:
 | `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.
+OS/Product Bootloader (values 1-4, in one block). A real Radion light
+showed 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) -- split across
+two blocks as described above, not one. `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

python_mobius-0.2.1/documentation/12-device-identity-and-address-stability.md

@@ -0,0 +1,105 @@
+# Device identity and BLE address stability
+
+## Device identity is based on serial number, not BLE address
+
+A device's BLE MAC address is not a stable identifier -- it can change
+between connections (confirmed via `Peripheral.java` in the decompiled
+app, and independently via real-world testing showing a device's
+advertised address change between runs while its serial number stayed
+the same). The official app relies entirely on serial number for device
+identity, never on address stability:
+
+```java
+// Peripheral.java
+public int hashCode() {
+    return getDevice().serialNumber.hashCode();
+}
+
+public boolean equals(Object obj) {
+    return obj != null && (obj instanceof Peripheral)
+        && ((Peripheral) obj).getDevice().serialNumber.equals(getDevice().serialNumber);
+}
+
+public void update(Peripheral peripheral) {
+    setBluetoothDevice(peripheral.getBluetoothDevice());  // <-- replaces the address
+    setRssi(peripheral.getRssi());
+    setScanRecord(peripheral.getScanRecord());
+    setDevice(peripheral.getDevice());
+    this.lastSeen = new Date();
+}
+```
+
+`equals()`/`hashCode()` never reference the BLE address at all -- only
+`serialNumber`. `update()`, called whenever a new scan result matches an
+*existing* `Peripheral` by serial number, explicitly **overwrites** the
+stored `BluetoothDevice` (which encapsulates the address) with whatever
+came from the new scan result. This is the app's designed architecture
+for handling devices whose BLE address may change over time (plausibly
+BLE resolvable-private-address rotation, though this library doesn't
+need to know the mechanism, only that the address isn't a safe long-term
+identifier).
+
+## API
+
+- **`find_device_by_serial(serial, timeout=10.0, adapter=None)`**
+  (`mobius.discovery`): scans and returns whichever device is *currently*
+  advertising the given serial number, regardless of its current address.
+- **`dedupe_by_serial(devices)`** (`mobius.discovery`): if the same serial
+  appears twice in one scan result set (plausible if caught mid-rotation),
+  keeps only the first entry. Applied automatically in the CLI.
+- **`MobiusDevice(device=None, serial=None, ...)`**: `serial` is an
+  optional parameter; at least one of `device` or `serial` must be
+  provided.
+  - If a `BLEDevice` is given, it's used directly for the *first* connect
+    (no extra scan needed). If `serial` is also set, that `BLEDevice` is
+    discarded after first use: any *subsequent* `connect()` on the same
+    instance (e.g. a coordinator reusing one `MobiusDevice` object across
+    multiple poll cycles) re-resolves the current address via
+    `find_device_by_serial()` instead of assuming the original address is
+    still valid.
+  - If only `serial` is given (no `device`), every `connect()` resolves
+    the current address via serial from scratch.
+  - If only a bare address string is given (no `serial`), reconnection
+    re-scans by that *fixed* address. This path is only as reliable as
+    the assumption that the address doesn't change; prefer passing
+    `serial` if that isn't certain.
+
+Passing both `device` and `serial` into one `MobiusDevice` and expecting
+that to give serial-based robustness on every connect is a common
+mistake: a directly-provided `BLEDevice` is always used on the *first*
+connect regardless of whether `serial` is also set. If something only
+ever calls `connect()` once per `MobiusDevice` instance (e.g. a
+scan-then-connect-once loop over several devices), passing `serial=`
+*alone* (omitting `device`) forces a fresh resolution immediately before
+each connect, rather than trusting a scan-time `BLEDevice` reference that
+could be stale by the time it's actually used.
+
+## In practice
+
+**Prefer passing `serial` whenever it's available** (which is almost
+always -- it's right there in the BLE advertisement's manufacturer data,
+no connection needed to read it; see
+[08-manufacturer-data.md](./08-manufacturer-data.md)), especially for any
+`MobiusDevice` instance reused across multiple connect cycles (like a
+polling coordinator) or held onto for more than a single short-lived
+scan-then-connect sequence.
+
+The CLI's `--by-serial SERIAL` flag resolves the current address for a
+given serial from scratch and connects, independent of whatever address
+may have been seen previously.
+
+`ha-mobius` uses serial-based identity throughout: config entries store
+`CONF_SERIAL` alongside `CONF_ADDRESS`, `MobiusConnectionManager` resolves
+the current address via Home Assistant's own Bluetooth cache (matching
+by serial) rather than a fixed address, and setup fails cleanly (asking
+for re-configuration) for any entry that predates this and lacks a stored
+serial.
+
+## Still open
+
+Not confirmed whether the address changes seen are BLE address-privacy
+rotation specifically (vs. some other cause -- a firmware update, a
+factory reset, etc.). This library doesn't need to know the mechanism to
+handle it correctly, but it would be useful to know for certain --
+watching a device's address over time with a tool like
+`bluetoothctl scan on`, independent of this library, would settle it.

{python_mobius-0.2.0 → python_mobius-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-mobius"
-version = "0.2.0"
+version = "0.2.1"
 description = "Reverse-engineered Python client for the Mobius BLE protocol (EcoTech Marine VorTech/Radion, AquaIllumination, Neptune Systems, NYOS)"
 readme = "README.md"
 license = { text = "GPL-2.0-only" }