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

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

@@ -1,5 +1,209 @@
 # Changelog
 
+## 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.0}/PKG-INFO

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

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

@@ -165,6 +165,30 @@ 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` 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:
+
+```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

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

@@ -0,0 +1,337 @@
+# Thread/CoAP device relay
+
+**Status: root cause found and fixed, confirmed directly from smali
+bytecode (not just source) -- ready for a real hardware retest.** The
+user provided the raw smali disassembly for `BaseConnection.java`
+(specifically `handleIndication()`, the method JADX couldn't decompile).
+This resolved the mystery completely: the real CoAP relay response
+arrives as a genuinely separate message, on a different opcode (`0xDF`/
+`26`, not the request's `25`), matched purely by CoAP token -- never by
+the outer FSCI message ID, and never via the (confirmed meaningless,
+app-discarded) confirm to opcode 25. Implemented: `MobiusDevice` now
+tracks pending CoAP responses by token (`_register_coap_token()`/
+`wait_for_coap_response()`), and `_on_rx_final()` resolves them when a
+matching opcode-26 indication arrives, entirely independent of the
+existing message-ID-based mechanism used for direct requests.
+`RelayedMobiusDevice._relay()` was rewritten around this. See
+"What's confirmed vs. not yet" below for the full, current picture.
+
+## Why this matters in practice
+
+Every device this library talks to gets its own persistent, direct BLE
+connection. The official app doesn't -- it connects to just **one or a
+few** devices and reaches the rest through them. Concretely, this means:
+if something else (this library, `ha-mobius`, or another instance of the
+app) is already holding direct BLE connections to every device in a tank,
+the official app can end up with nothing to connect to at all, and stops
+working. Implementing relay properly is the fix -- it lets this library
+behave the way the app does, freeing up connections rather than holding
+one per device indefinitely.
+
+## How the app's relay actually 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)). `Comm.java`'s
+`sendRequest()` routing logic (confirmed directly from source, not
+inferred):
+
+```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
+}
+```
+
+The key insight: **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 -- it only needs BLE to reach *one* mesh
+member, and that device does the Thread-side forwarding using its own
+onboard hardware.
+
+## CoAP wire format (confirmed)
+
+Traced directly from `Coap.java` / `CoapRequest.java` / `CoapResponse.java`
+/ `CoapFsciRequest.java`. Reuses the same C2CI envelope described in
+[02-framing-and-crc.md](./02-framing-and-crc.md), just a new opcode
+(confirmed literal: **25**) alongside the existing Get(`0x17`)/Set(`0x18`)
+attribute opcodes.
+
+**Request** -- `CoapRequest`'s first constructor:
+```
+IPv6(16 bytes, REVERSED) + token(4, LE) + method(2, LE)
++ payload_length(2, LE) + request_type(1) + payload
+```
+
+**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 asymmetric reversal (request reverses the address, response doesn't)
+is confirmed directly from source and easy to get backwards -- see
+`mobius.coap`'s test suite, which specifically checks this doesn't happen
+by accident (a palindromic test address would pass even with the reversal
+backwards or missing; the tests deliberately avoid that).
+
+**The payload is a complete, self-contained FSCI frame.** `CoapFsciRequest`
+wraps `request.getData(true)` -- and `Request.getData(true)`'s exact
+implementation is now confirmed directly from source: it builds
+`opGroup + opCode + messageId(2) + reserved(1) + dataLength(2) + data +
+CRC16(2)`, then prepends the magic byte (`0x02`) to that -- i.e. the
+**complete outer FSCI frame**, byte-for-byte identical in structure to
+what this library's own `build_frame()` produces for a direct (non-
+relayed) request. This means relaying a request is exactly as simple as
+it 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 needed
+for relayed vs. direct requests -- only the outer envelope differs.
+
+`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`). Several are JADX symbolic substitutions
+rather than plain literals in the decompile; not all could be
+independently confirmed (see `mobius.coap`'s module docstring for exactly
+which values are literal, which are cross-referenced from elsewhere in
+this project, and which are inferred-only). One confirmed value
+(`ProxyingNotSupported = 512`) doesn't fit the otherwise-clean pattern --
+a reminder that guessing at the unconfirmed ones isn't safe.
+
+## Address discovery (confirmed -- this is what the earlier version of
+## this document got wrong)
+
+The earlier version of this document treated the target's Thread IPv6
+address as unverified/only-readable-from-the-target-itself. A more
+thorough trace found the actual mechanism, confirmed directly in
+`CowboyNetworkProcess.java` and `Comm.java`:
+
+1. **`MeshLocalAddresses`** (attribute `1005`) -- read from the connected
+   gateway device. Confirmed via `PeripheralConnection.java`: returns the
+   gateway's OWN complete 16-byte mesh-local address (not "the prefix" as
+   its own standalone value), sanity-checked there as non-all-zero before
+   use. Since every device on the same Thread network shares the same
+   8-byte prefix, extracting the first 8 bytes of the gateway's own
+   address gives the network's shared prefix.
+2. **`ShortAddressArray`/`SerialNumberArray`/`DeviceModelArray`**
+   (attributes `3700`/`3701`/`3702`) -- three parallel arrays, fetched via
+   the same "get all elements" pattern (`index=0, count=0xFFFF`) already
+   used elsewhere in this library, index-matched to give every mesh peer's
+   serial, model, and Thread short address (RLOC16) the gateway knows
+   about. **All readable from a single connected gateway device** --
+   nothing from the target itself is required. `SerialNumberArray`'s
+   per-element format is confirmed identical to the existing 14-byte
+   ASCII serial format already used elsewhere in this library (confirmed
+   via `CowboyNetworkProcess.java`'s own cleanup logic, which sets a
+   cleared slot to the literal string `"00000000000000"` -- fourteen
+   ASCII zero characters, the same length/format as a real serial, not
+   null bytes) -- no new serial-parsing logic needed.
+3. **Target IPv6 = `prefix(8) + 00:00 + 00:FF:FE:00 + short_address(2,
+   little-endian)`** -- the standard Thread RLOC IID format. Confirmed
+   via `IPv6.isEui64Address()`'s exact byte check (`bytes[10:14] ==
+   00:FF:FE:00`), which matches the real Thread specification's own
+   convention for short-address-derived interface identifiers -- not
+   something EcoTech invented, a well-known, publicly documented mesh
+   networking format. The little-endian byte order for the short-address
+   portion is a genuinely surprising, verified-not-assumed detail --
+   confirmed via `ByteUtilities.getShort()`'s explicit
+   `ByteOrder.LITTLE_ENDIAN`, which is the opposite of IPv6's own
+   conventional big-endian (network byte order); easy to get backwards by
+   just assuming the IPv6 standard's convention applies here too.
+
+## What's confirmed vs. not yet
+
+**Confirmed from source** (traced directly, not guessed): the CoAP
+envelope wire format (both directions), the routing decision logic, the
+RLOC-based address construction formula, that `request.getData(true)`
+produces a complete self-contained FSCI frame (byte-for-byte identical in
+structure to this library's own `build_frame()` output), and that the
+outer CoAP method is always `GET` regardless of whether the relayed
+operation is itself a Get or Set -- confirmed via the one real call site
+(`Comm.java`), which hardcodes `Request.Method.GET` unconditionally.
+
+**Confirmed from real hardware testing**:
+- **Thread IS active on regular VorTech/Radion devices** -- a real,
+  positive result. `MeshLocalAddresses` reads back a genuine, valid,
+  non-zero mesh-local address on hardware with no Cowboy hub present.
+  This resolves what had been the single biggest open question.
+- **The three-array peer discovery mechanism
+  (`ShortAddressArray`/`SerialNumberArray`/`DeviceModelArray`,
+  `MobiusDevice.discover_mesh_peers()`) is Cowboy-hub-specific.** On real
+  VorTech/Radion hardware with no Cowboy hub, all three return
+  `FsciStatus.UnsupportedAttribute` (an explicit "I don't support this,"
+  not a timeout or generic failure) -- even though `MeshLocalAddresses`
+  on that same device succeeds. This lines up with where these arrays
+  were originally found in the decompile: inside
+  `CowboyNetworkProcess.java`, the class specifically for setting up a
+  network via a dedicated Cowboy hub.
+- **The alternative -- connecting directly to each device to read its
+  own `MeshLocalAddresses` -- doesn't depend on a Cowboy hub, and is
+  confirmed to be exactly how the app itself always learns a device's
+  address.** `PeripheralConnection.java`'s `updateConnectionState()` (the
+  standard GATT-setup-completion handler, checking the same
+  RxData/RxFinal/TxData/TxFinal characteristics this library's own
+  transport already uses) calls `getDeviceInfo()` -- which reads
+  `MeshLocalAddresses` -- automatically on every connection to any
+  non-legacy device. Not Cowboy-specific, not conditional: universal,
+  standard behavior. `MobiusDevice.get_own_mesh_address()` and
+  `mobius.discovery.discover_mesh_peers_via_direct_connect()` implement
+  this directly.
+- **The real CoAP relay response arrives on a completely different
+  opcode than the request, matched purely by CoAP token.** Confirmed
+  directly from `BaseConnection.smali` (the user provided the raw
+  disassembly for the one method JADX couldn't decompile,
+  `handleIndication()`) -- traced from actual bytecode, not source-level
+  guessing:
+  - The confirm to a CoAP request (opGroup `0xDF`/opCode `25`,
+    `COAP_OPCODE`) is a **bare, meaningless ack**. `BaseConnection.java`'s
+    `handleBytes()` matches `opGroup==0xDF && opCode==25` unconditionally
+    and does nothing but log it, 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, the genuine, complete confirm, thrown away by the app too.
+  - **The real response arrives as a separate message on opGroup
+    `0xDF`/opCode `26`** (`COAP_INDICATION_OPCODE`) -- confirmed via the
+    packed-switch inside `handleIndication()`.
+  - **Matched purely by CoAP token, never by the outer FSCI message ID.**
+    Confirmed via `lambda$getSentRequest$6`'s exact comparison:
+    `coapRequest.getToken() == coapResponse.getToken()`.
+  - Implemented in `MobiusDevice._register_coap_token()`/
+    `wait_for_coap_response()` and wired into `_on_rx_final()`, entirely
+    independent of the existing message-ID-based `self._pending`
+    mechanism used for direct (non-relayed) requests.
+    `RelayedMobiusDevice._relay()` was rewritten around this: registers
+    the token before sending (eliminating any race), sends without
+    waiting for the meaningless confirm, and awaits the token-matched
+    indication instead.
+
+**Not yet confirmed**: whether this actually works end-to-end against
+real hardware. Everything above is confirmed from source/bytecode and
+covered by unit tests with mocked notifications, but hasn't been
+exercised against a real device yet -- that's the next test.
+hardware instead, which `--debug-relay`'s frame-sniffing window is for.
+
+## Implementation plan (this branch)
+
+Split by functionality, each independently testable before the next
+depends on it:
+
+1. **CoAP protocol primitives** (`mobius.coap`) -- envelope encode/decode,
+   pure functions, no hardware needed. *(done)*
+2. **Thread mesh IPv6 addressing** (`mobius.mesh_address`) -- RLOC
+   address construction from a mesh-local prefix + short address.
+   *(done -- includes a verified, non-obvious finding: the short-address
+   portion is little-endian, confirmed via `ByteUtilities.getShort()`'s
+   explicit `ByteOrder.LITTLE_ENDIAN`, not the IPv6 standard's own
+   big-endian convention one might otherwise assume)*
+3. **Peer discovery** (`MobiusDevice.discover_mesh_peers()`) -- fetching
+   and parsing the three parallel arrays into a serial→IPv6 map. *(done
+   -- also found and recorded a fourth parallel array,
+   `BladeBleAddressArray` (3714, each peer's real BLE MAC address), not
+   used by relay itself but included in constants.py for completeness.
+   **Confirmed via real hardware testing to be Cowboy-hub-specific** --
+   see item 6 below for the alternative this made necessary.)*
+4. **`RelayedMobiusDevice`** (`mobius.relay`) -- a `MobiusDevice` subclass
+   that overrides `get_attribute()`/`get_attribute_raw()`/`set_attribute()`
+   to route via CoAP through a gateway device instead of owning its own
+   connection. Every other inherited method (`get_device_summary()`,
+   `get_current_light_intensities()`, everything) works transparently
+   through relay, since they're all built in terms of those three
+   methods. *(done -- confirmed via a test that exercises an inherited
+   high-level method, not just the overridden primitives directly)*.
+   Also confirmed a subtle, easy-to-get-wrong detail directly from the
+   one real call site in the decompile: 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.
+5. **CLI support** (`mobius-scan --dump-mesh-peers` /
+   `--relay-target SERIAL`) -- a way to actually validate this against
+   real hardware: connect to one device (the gateway), discover its mesh
+   peers, and relay a full `get_device_summary()` read to a specified
+   target through it. Run a separate direct `--by-serial <target>`
+   command to confirm the two match. *(done -- this is the step that
+   actually answers the biggest open question: whether these devices run
+   Thread at all. Everything above this point is implemented and unit-
+   tested, but genuinely unverified against real hardware until this is
+   run.)* Added a verbose, step-by-step diagnostic path
+   (`_debug_mesh_discovery()`) after real hardware testing showed every
+   device returning "No peers found" with no further detail --
+   `discover_mesh_peers()`'s production fail-soft behavior (the right
+   choice for library use) collapses several genuinely different failure
+   modes into the same empty result, which made the CLI output useless
+   for telling apart "this device doesn't support Thread at all" from
+   "it supports Thread but isn't on an active network right now" from
+   "the arrays came back empty." The CLI now surfaces each step's raw
+   result or exception individually instead.
+6. **Cowboy-hub-free peer discovery** (`MobiusDevice.
+   get_own_mesh_address()` / `mobius.discovery.
+   discover_mesh_peers_via_direct_connect()` / `mobius-scan
+   --build-peer-map`) -- added after real hardware testing confirmed
+   item 3's three-array approach requires a Cowboy hub, which this
+   project's test hardware doesn't have. Connects directly and briefly to
+   each device in turn to read its own `MeshLocalAddresses`, confirmed
+   via `PeripheralConnection.java` to be exactly how the app itself
+   always learns a device's mesh address (`getDeviceInfo()`, called
+   automatically on every connection as standard setup, not something
+   Cowboy-specific). *(done -- 10 new tests. This is the discovery
+   mechanism to actually use going forward; `discover_mesh_peers()`
+   remains in place as a cheap, fail-soft first attempt in case a Cowboy
+   hub IS present, but isn't the primary path anymore.)*
+
+   **Follow-up fix**: `--relay-target` was still only looking through the
+   Cowboy-specific peer list after this item landed -- it was never wired
+   to fall back to a direct connection, so real hardware testing hit
+   "not found among discovered peers" even with this new discovery
+   mechanism in place. Fixed: `--relay-target` now falls back to briefly
+   connecting directly to the target itself (via `find_device_by_serial()`
+   + `get_own_mesh_address()`) if the Cowboy-hub lookup doesn't find it.
+7. **`--debug-relay`** -- added after `--relay-target` reached the
+   target but `get_device_summary()` came back entirely empty
+   (model/serial/everything `None`), with no visible error. Turned out
+   every individual attribute fetch WAS raising an exception internally
+   (a too-short, malformed CoAP response) -- just silently, since
+   `get_device_summary()`'s own per-field fail-soft handling (correct
+   behavior for genuinely optional attributes) was catching and
+   discarding them without any visible trace. Prints raw bytes at every
+   layer of a relayed request/response (outer frame, CoAP envelope
+   fields, inner frame, decoded status/values) so this stops being
+   invisible. Verified with a mocked round-trip that the debug output
+   itself is correct and doesn't interfere with normal operation before
+   asking for another real hardware run.
+8. **Discovered the immediate confirm to a relay request is explicitly
+   discarded by the app itself** -- confirmed directly from
+   `BaseConnection.java`'s `handleBytes()` (see "What's confirmed" above)
+   after `--debug-relay`'s raw bytes showed every relayed read's outer
+   response was exactly 1 byte, too short to be a valid CoAP envelope at
+   all. The real response-correlation mechanism lives in
+   `handleIndication()`, a method JADX couldn't decompile -- a genuine
+   limit of what source tracing alone could determine at this point.
+   Added `MobiusDevice.on_any_frame` (a hook called 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. 4 new tests for the hook itself.
+9. **Root cause found and fixed**, after the user provided the raw smali
+   disassembly for `BaseConnection.java` -- JADX's decompiler had given
+   up on `handleIndication()` specifically, but the underlying bytecode
+   was still traceable. This resolved everything precisely: the real
+   response arrives on a completely separate opcode (`0xDF`/`26`,
+   `COAP_INDICATION_OPCODE` -- not the request's `25`), matched purely by
+   CoAP token (`lambda$getSentRequest$6`:
+   `coapRequest.getToken() == coapResponse.getToken()`), never by the
+   outer FSCI message ID. Implemented:
+   `MobiusDevice._register_coap_token()`/`wait_for_coap_response()` (a
+   token-keyed pending-response registry, separate from the existing
+   message-ID-based `self._pending`), 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; new dedicated
+   `test_coap_indication_handling.py` for the token-registry mechanism
+   itself. 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.**

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

@@ -164,3 +164,27 @@ Both are included automatically in `get_device_summary()`'s
 `get_device_summary()` already has the device's `Model` on hand).
 `get_hardware_info()` is not currently wired into the summary -- call it
 directly if you want it.
+
+## Device clock drift (`get_device_time_info()`)
+
+`Epoch` (201) / `RTCTime` (219) -- two separate device-reported UNIX
+timestamps, with drift computed against local system time. **This is not
+a speculative diagnostic** -- it's confirmed via the app's own
+`TimeDifferenceFragment.java` ("Time Difference" under Troubleshoot in
+the app): it checks both of these attributes for drift against the
+phone's clock, using this exact same computation
+(`local_time_seconds - device_reported_seconds`), treating a large
+discrepancy as a real, known failure mode.
+
+**Important caveat**: the app's own schedule interpolation
+(`WidgetViewCell.java`) uses the phone/tank's own clock
+(`selectedTank.getDateTime()`), NOT either of these device-reported
+values -- so this does not directly explain a mismatch between this
+library's computed schedule value and the app's displayed one. It's
+still worth checking as a general device-health signal, exactly as the
+app's own troubleshooting tool treats it, but a clean result here doesn't
+rule out a schedule-interpolation bug, and a drifted result here doesn't
+necessarily explain one either.
+
+Included automatically in `get_device_summary()`'s `"device_time"` field.
+

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-mobius"
-version = "0.1.4"
+version = "0.2.0"
 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" }