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

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

@@ -1,5 +1,232 @@
 # 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
+[documentation/09-thread-coap-relay.md](documentation/09-thread-coap-relay.md)
+for the full protocol trace and implementation history. The `coap-relay`
+branch has been merged into main as part of this release.
+
+- **Root cause of relayed reads returning empty data found and fixed,**
+  after the user provided the raw smali disassembly for
+  `BaseConnection.java` -- JADX's decompiler had given up specifically on
+  `handleIndication()`, the one method that held the answer, but the
+  underlying bytecode was still traceable. Confirmed precisely: the real
+  CoAP relay response arrives on a completely separate opcode (`0xDF`/
+  `26`, `COAP_INDICATION_OPCODE` -- not the request's `25`, whose confirm
+  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
+  (`lambda$getSentRequest$6`: `coapRequest.getToken() ==
+  coapResponse.getToken()`), 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
+  `_on_rx_final()`. `RelayedMobiusDevice._relay()` was rewritten around
+  this: registers the token before sending (eliminating any race against
+  the response arriving first), sends without waiting for the
+  meaningless confirm, and awaits the token-matched indication instead.
+  `test_relay.py` rewritten entirely for the new architecture (14 tests);
+  new dedicated `test_coap_indication_handling.py` for the token-registry
+  mechanism itself (9 tests). Verified end-to-end with a full mocked
+  round-trip (both the discarded ack and the real indication arriving,
+  in that order) before asking for another real hardware run -- **this is
+  the next real test.**
+
+- **Real hardware testing confirmed Thread IS active on regular
+  VorTech/Radion devices** (a genuine, positive result -- `MeshLocalAddresses`
+  reads back a valid, non-zero address), **but the three-array peer
+  discovery mechanism (`discover_mesh_peers()`) is Cowboy-hub-specific**
+  (`FsciStatus.UnsupportedAttribute` on hardware with no Cowboy hub,
+  even though that same device's own address reads back fine). Added
+  `MobiusDevice.get_own_mesh_address()` and `mobius.discovery.
+  discover_mesh_peers_via_direct_connect()` as the alternative --
+  confirmed via `PeripheralConnection.java` to be exactly how the app
+  itself always learns a device's address (automatic on every
+  connection, not Cowboy-specific). Added `mobius-scan --build-peer-map`
+  to exercise this from the CLI. `discover_mesh_peers()` remains in
+  place as a cheap, fail-soft first attempt in case a Cowboy hub IS
+  present, but is no longer the primary/recommended discovery path. 10
+  new tests.
+
+- **Fixed a real bug found via real hardware testing: `--relay-target`
+  was never actually wired to the new Cowboy-hub-free discovery
+  mechanism.** After adding `discover_mesh_peers_via_direct_connect()`,
+  a real `--relay-target` attempt still failed with "not found among
+  discovered peers" -- not because relay itself failed, but because the
+  CLI's target lookup only ever checked the Cowboy-hub-specific peer
+  list. `--relay-target` now falls back to a brief direct connection to
+  the target itself (`find_device_by_serial()` +
+  `get_own_mesh_address()`) if the Cowboy-hub lookup doesn't find it.
+
+- **Added `--debug-relay`** after the fixed `--relay-target` reached the
+  target but `get_device_summary()` came back entirely empty with no
+  visible error. Turned out every attribute fetch WAS raising an
+  exception internally (a malformed CoAP response) -- silently, since
+  `get_device_summary()`'s own per-field fail-soft handling was catching
+  and discarding them without trace. Prints raw bytes at every layer of
+  a relayed request/response so this stops being invisible. Verified
+  with a mocked round-trip that debug output itself is correct before
+  asking for another real hardware run.
+
+- **Confirmed directly from source why the response comes back
+  malformed: the immediate confirm to a relay request is explicitly
+  discarded by the app itself, on purpose.** `BaseConnection.java`'s
+  `handleBytes()` matches `opGroup==0xDF && opCode==25` unconditionally
+  and logs it only -- before the dispatcher ever checks whether it
+  resolves a pending request. Real hardware testing independently
+  confirmed this byte-for-byte: every relayed read's outer response is
+  exactly 1 byte (`0x00`), not a truncated response but the genuine
+  complete confirm, thrown away by the app too. The real response, if it
+  arrives at all, comes through a separate "indication" handled by
+  `handleIndication()` -- a method JADX couldn't decompile, a genuine
+  limit of what source tracing alone can determine here. Added
+  `MobiusDevice.on_any_frame` (fires for every parsed incoming frame,
+  not just ones resolving a pending request) and extended
+  `--debug-relay` to watch for 2 seconds after the initial confirm, to
+  find out empirically whether a second frame actually arrives. 4 new
+  tests.
+
+- **Added `mobius.coap`**: CoAP (RFC 7252) protocol primitives --
+  `CoapRequestType`/`CoapMethod`/`CoapResponseCode` enums,
+  `encode_coap_request()`/`decode_coap_response()`. Pure functions, no
+  hardware dependency. Confirmed wire format traced directly from the
+  decompiled app (`Coap.java`/`CoapRequest.java`/`CoapResponse.java`) --
+  see the module's docstring for exactly which enum values are
+  confirmed-literal, cross-referenced from elsewhere in this project, or
+  inferred-only (deliberately not guessing at unconfirmed ones -- an
+  unrecognized response code decodes to a plain int, matching the real
+  app's own graceful fallback behavior). 15 new tests, including
+  specific coverage of the asymmetric IPv6 byte-reversal between
+  requests and responses, which is easy to get backwards.
+
+- **Added `mobius.mesh_address`**: Thread mesh-local RLOC IPv6 address
+  construction (`build_rloc_address()`/`extract_short_address()`/
+  `mesh_local_prefix_from_own_address()`/`is_valid_mesh_address()`/
+  `is_short_address_derived()`). Pure functions, no hardware dependency.
+  Includes a genuinely surprising, verified-not-assumed finding: the
+  short-address portion is little-endian (confirmed via
+  `ByteUtilities.getShort()`'s explicit `ByteOrder.LITTLE_ENDIAN`), the
+  opposite of IPv6's own conventional big-endian byte order -- easy to
+  get backwards by assuming the IPv6 standard's own convention applies
+  here too. 15 new tests.
+
+- **Added `MobiusDevice.discover_mesh_peers()`**: fetches
+  `MeshLocalAddresses` (1005) + the three parallel `ShortAddressArray`/
+  `SerialNumberArray`/`DeviceModelArray` attributes (3700/3701/3702)
+  from a connected device, returning every other device it knows about
+  over the Thread mesh as a list of new `MeshPeer` dataclasses (serial,
+  model, short address, ready-to-use IPv6). Confirms `SerialNumberArray`'s
+  per-element format matches the existing 14-byte ASCII serial format
+  already used elsewhere in this library -- no new parsing logic needed.
+  Filters out cleared/empty slots (the literal sentinel string
+  `"00000000000000"`, confirmed via `CowboyNetworkProcess.java`'s own
+  cleanup logic). Fails soft to an empty list for unsupported devices or
+  ones not currently part of an active Thread network, matching this
+  library's usual convention. Also recorded (but not yet used) a fourth
+  parallel array, `BladeBleAddressArray` (3714, each peer's real BLE MAC
+  address) -- found alongside the other three but not needed for CoAP
+  relay itself. 7 new tests.
+
+- **Added `RelayedMobiusDevice`** (`mobius.relay`): a `MobiusDevice`
+  subclass that overrides `get_attribute()`/`get_attribute_raw()`/
+  `set_attribute()` to route through a gateway device via CoAP instead of
+  owning its own BLE connection. Every other inherited method
+  (`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
+  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
+  new encoding path, just wrapping the same frame a direct request would
+  use. Also confirmed, directly from the one real call site in the
+  decompile, a subtle and easy-to-get-wrong detail: the outer CoAP method
+  is always `GET`, even for a relayed Set -- the actual operation is
+  determined by the inner FSCI opcode, not the CoAP transport layer. 13
+  new tests.
+
+- **Added `mobius-scan --dump-mesh-peers` / `--relay-target SERIAL`**
+  (both usable alongside `--by-serial`): prints every peer a connected
+  device knows about over the Thread mesh, and/or relays a full
+  `get_device_summary()` read to a specified target through it. This is
+  the last of the 5 planned pieces for this feature -- **implementation
+  is now complete, but not yet validated against real hardware.** Run a
+  separate direct `--by-serial <target>` command to confirm a relayed
+  read actually matches a direct one; this is also how the biggest open
+  question (whether these devices run Thread at all) finally gets
+  answered.
+
+- **Added a verbose, step-by-step mesh discovery diagnostic
+  (`_debug_mesh_discovery()`)** after real hardware testing showed every
+  device returning "No peers found" with no further detail.
+  `discover_mesh_peers()`'s fail-soft-to-empty-list behavior is correct
+  for production/library use, but collapses several genuinely different
+  failure modes into the same result -- device doesn't support Thread at
+  all, vs. supports it but isn't on an active network right now, vs.
+  the peer arrays came back empty for some other reason. `--dump-mesh-peers`
+  now surfaces each step's raw result or exception individually instead
+  of just the final empty-or-not outcome.
+
+- **Added `get_device_time_info()`** (`Epoch`/`RTCTime`, attributes
+  201/219) -- device clock drift vs. local system time. Not speculative:
+  confirmed via the app's own "Time Difference" troubleshooting feature
+  (`TimeDifferenceFragment.java`), which checks these exact two attributes
+  the same way. Included automatically in `get_device_summary()`'s
+  `"device_time"` field. Important caveat documented: the app's own
+  schedule interpolation uses the phone/tank clock, not either of these,
+  so this doesn't directly explain a schedule-interpolation mismatch by
+  itself -- still worth checking as a general health signal. 5 new tests.
+
+- **Added `mobius-scan --dump-schedule`**: prints each connected device's
+  full raw programmed schedule (every point's time, flags -- ACTIVE/NIGHT/
+  SUNRISE/SUNSET -- and per-channel/mode values), not just the
+  interpolated "current" value `get_device_summary()` already shows. For
+  lights, also prints `lunar_enabled`/`insolation_active`/
+  `schedule_intensity`/`acclimation` state. Combines with either the
+  normal scan or `--by-serial`. Added so a schedule's actual point
+  structure can be inspected directly -- needed to verify
+  `is_night_segment()`'s bracket-finding logic against real data, rather
+  than guessed at or transcribed by hand.
+
+- **Added debugging diagnostics to `get_current_light_intensities()`**:
+  `.diagnostics` now also includes `is_night_segment`, `lunar_enabled`,
+  `scalar_source` (`"lunar"`/`"night_no_lunar"`/`"schedule_intensity"`),
+  and `scalar` (the actual final multiplier applied). Added after a real
+  discrepancy was reported between this library's computed value and the
+  app's own displayed value for a light at night (app showing lunar-
+  reduced moonlight intensities, this library showing the unreduced
+  schedule-intensity value instead) -- these fields exist specifically so
+  that class of mismatch can be diagnosed with real data (which branch was
+  taken, and why) rather than guessed at blindly. Also threaded into
+  `get_device_summary()` as `"light_diagnostics"`, so `mobius-scan`
+  surfaces this directly -- debugging this kind of mismatch belongs in the
+  library/CLI, not in a specific downstream integration. Existing tests
+  updated to assert on these fields directly.
+
 ## 0.1.4
 
 - Added `MobiusDevice.is_connected` property -- lets callers check

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-mobius
-Version: 0.1.4
+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.1.4 → 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.1.4 → 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,6 +154,27 @@ 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.
 
+## 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) -- 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()
+print(result.diagnostics)
+# {'insolation_active': False, 'is_night_segment': True,
+#  'lunar_enabled': True, 'scalar_source': 'lunar', 'scalar': 0.35}
+```
+
+`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."
+
 ## Hyperdrive (boosted channels above 100%)
 
 Some light channels can be driven above their normally-rated power
@@ -174,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.