python-mobius 0.3.0__tar.gz → 0.4.0__tar.gz

{python_mobius-0.3.0 → python_mobius-0.4.0}/.forgejo/workflows/release.yml

@@ -88,14 +88,23 @@ jobs:
         if: github.event_name == 'push'
         run: python3 .forgejo/scripts/extract_changelog_section.py "${{ github.ref_name }}"
 
-      # direction: upload with no release-dir set -- no wheel/sdist attached
-      # to the Forgejo release itself (PyPI is the source of truth for the
-      # built artifacts); this step only creates the release entry with the
-      # extracted changelog section as its notes. Worth confirming on the
-      # first real run that omitting release-dir doesn't pick up dist/ by
-      # some other default -- the action's own docs only show examples with
-      # release-dir explicitly set, so this specific "notes only" case
-      # isn't directly demonstrated there.
+      # Both of the action's own README examples always set release-dir
+      # explicitly, even though it's documented as optional with a
+      # default -- confirmed via a real failure on this exact step
+      # ("tag v0.3.1 exists" / "curl: (26) Failed to open/read local
+      # data from file/application") that omitting it entirely doesn't
+      # work, the same bug already found and fixed the same way for
+      # ha-mobius's own release workflow. dist/ has the actual built
+      # wheel/sdist in it (from the Build package step above), but
+      # those are deliberately NOT what goes here -- PyPI stays the
+      # source of truth for the built artifacts, this step only creates
+      # the release entry with the extracted changelog section as its
+      # notes -- hence a separate, empty dist/release/ rather than
+      # pointing release-dir at dist/ itself.
+      - name: Ensure release-dir exists (empty -- no files attached)
+        if: github.event_name == 'push'
+        run: mkdir -p dist/release
+
       # Same event-gating reason as the two steps above -- nothing to
       # release against on a manual, non-tag run.
       - name: Create Forgejo release
@@ -107,4 +116,5 @@ jobs:
           repo: r3pek/python-mobius
           token: ${{ secrets.GITHUB_TOKEN }}
           tag: ${{ github.ref_name }}
+          release-dir: dist/release
           release-notes-file: release_notes.md

{python_mobius-0.3.0 → python_mobius-0.4.0}/CHANGELOG.md

@@ -1,12 +1,171 @@
 # Changelog
 
+## 0.4.0
+
+- **`mobius-scan`'s default now also connects to ONE device and dumps
+  real mesh addresses for its whole network**, not just the pan_id
+  listing. Reuses the exact same verbose discovery `--dump-mesh-peers`
+  already used (`_debug_mesh_discovery()` -- `MLPrefix`/
+  `NetworkedThreadDevices` first, falling back to the older Cowboy-hub
+  mechanism), so the output is identical in shape whether it happens via
+  the default run or that flag explicitly. `--scan-only` now has real
+  meaning again (it had briefly become a no-op after the previous
+  change made the pan_id listing itself the whole default): it skips
+  this connection step, for a genuinely connection-free run.
+  `--dump-tanks` still exists separately for connecting to EVERY pan_id
+  group rather than just one, useful when multiple genuinely separate
+  tanks/networks are in range at once. Verified end-to-end with the
+  scan/connect layer mocked out: confirmed exactly one `MobiusDevice`
+  connection gets created by the plain default (to the correct,
+  first-found serial), and confirmed `--scan-only` still makes zero.
+
+- **Added `Tank` and `discover_tank()`: the connection-based building
+  block for full tank discovery** (device + address + age + shared
+  prefix, all in one call) -- the "basic block" a downstream integration
+  (e.g. ha-mobius) can call to trigger an on-demand scan and show
+  address/age/prefix for its devices. `discover_tank(mdevice)` takes an
+  already-connected `MobiusDevice`, calls `discover_mesh_peers_auto()`
+  plus `get_own_mesh_address()`/`get_device_info()` to include the
+  connected device itself in the result (the peer-discovery calls only
+  ever report OTHER devices, never themselves) -- so a single-device
+  tank correctly comes back with that one device as its sole peer, not
+  an empty list that would be indistinguishable from "discovery failed
+  entirely." `tank.prefix` is `None` (and `peers` always empty) if the
+  connected device didn't report a valid mesh address at all. 3 new
+  tests. Also exported `mesh_local_prefix_from_mlprefix()` from the
+  top-level `mobius` package -- a real gap from when it was first added,
+  caught while adding these new exports alongside it.
+
+- **`mobius-scan`'s default behavior changed: now genuinely just scans
+  and lists devices grouped by tank, no connections at all** -- it used
+  to print that same pan_id-grouped listing (already existed, already
+  connection-free) and then STILL go on to connect to every single
+  scanned device for a full summary regardless. That's now opt-in via a
+  new `--full-summaries` flag instead of being the implicit default.
+  Added `--dump-tanks`: connects to just ONE device per pan_id group
+  (not every device) and calls the new `discover_tank()` on it, printing
+  the full mesh-address/age for every device sharing that tank --
+  richer than the default listing, which only has whatever's in the BLE
+  advertisement (model/serial), not address or age. `--scan-only` kept
+  accepted as a no-op (it's redundant now that its old behavior IS the
+  default) rather than removed, so no existing script using it
+  explicitly breaks. Renamed the printed header from "Pan ID groups" to
+  "Tanks" to match. Verified end-to-end with the scan/connect layer
+  mocked out, for both the new default (confirmed zero MobiusDevice
+  connections created) and `--dump-tanks` (confirmed it correctly
+  prints prefix/address/age for a 2-device tank), not just via
+  `--help`'s rendered text.
+
+- **`discover_networked_thread_devices()` confirmed against real
+  hardware** (a live 4-device tank: 2 VorTech pumps, 2 Radion lights) --
+  the byte layout, little-endian field order, and all 4 real peers'
+  model/serial/age/derived-address all matched exactly. One real
+  correction from this: empty slots on real hardware are encoded as 28
+  bytes of raw zero (an all-null-byte serial), **not** the ASCII
+  `"00000000000000"` sentinel string `discover_mesh_peers()`'s older
+  mechanism uses -- the existing `if not serial` filter already handled
+  this correctly (an all-null-byte serial decodes to an empty string
+  after stripping), but the docstring incorrectly claimed this newer
+  mechanism used the same ASCII convention as the older one. Docstring
+  corrected; added a dedicated test for the actual null-byte case, plus
+  a new test replaying the exact real capture end-to-end (all 4 peers,
+  interleaved with the 26 real empty slots).
+
+- **Added `NetworkedThreadDevices` (1001) + `MLPrefix` (2128) support: a
+  second, better Thread mesh peer-discovery mechanism.** Confirmed via
+  reverse engineering the app's own tank-setup logic to be checked via a
+  generic support check on the connected device, **not gated to a
+  Cowboy hub** the way the existing three-parallel-arrays mechanism
+  (`discover_mesh_peers()`) is -- found while investigating whether the
+  app caches device mesh addresses at all (it does, persisting them to
+  a local file and syncing them to a cloud backend as part of each
+  device's saved state; this attribute is what actually populates that
+  cache in the first place). `MobiusDevice.discover_networked_thread_devices()`
+  fetches both attributes and returns every peer the connected device
+  knows about in a single round-trip, including a per-peer "age" value
+  (present in the confirmed wire format, but its exact meaning isn't
+  independently confirmed against real hardware -- see `MeshPeer`'s own
+  docstring). `MeshPeer` gained an `age: Optional[int] = None` field
+  (only ever set by this new method; `None` from every other source, a
+  non-breaking addition verified against all 4 existing `MeshPeer(...)`
+  construction sites, all of which use keyword arguments). Added
+  `mesh_local_prefix_from_mlprefix()` to `mobius.mesh_address`
+  (MLPrefix's own response is 24 bytes; only the first 8 are the real
+  prefix, confirmed via reverse engineering).
+
+- **Added `MobiusDevice.discover_mesh_peers_auto()`: the new
+  recommended default entry point for mesh peer discovery**, replacing
+  the previous recommendation to call `discover_mesh_peers()` or
+  `discover_mesh_peers_via_direct_connect()` directly depending on
+  hardware. Tries `discover_networked_thread_devices()` first, falling
+  back to `discover_mesh_peers()` only if that finds nothing --
+  `discover_mesh_peers_via_direct_connect()` isn't included in this
+  chain, since it needs a list of scanned devices as input rather than
+  an already-connected `MobiusDevice`; it remains the right fallback to
+  reach for explicitly if both of the above come back empty.
+
+- **On "discovering Tanks"**: investigated and confirmed not locally
+  possible -- the app's own "Tank" grouping is account-level and
+  cloud-synced, with user-edited metadata (name, photo) that has no
+  local/BLE equivalent to read. The closest local approximation this
+  library can offer: every peer `discover_networked_thread_devices()`
+  returns shares the connected device's own `MLPrefix`, which in
+  practice is "every device on the same Thread mesh" -- for a typical
+  setup, the same thing as "every device in the same aquarium."
+  Documented as an approximation, not presented as equivalent to the
+  app's own Tank object.
+
+- **`mobius-scan` CLI updated to match**: `--dump-mesh-peers` and
+  `--relay-target` now run the new `discover_mesh_peers_auto()`
+  priority order (step 0: `MLPrefix`/`NetworkedThreadDevices`, falling
+  through to the existing Cowboy-hub-specific steps only if that finds
+  nothing) instead of only ever exercising the older mechanism;
+  `--dump-mesh-peers`' output now also prints each peer's `age` when
+  set. `--build-peer-map` unchanged in behavior, now documented as the
+  last-resort fallback when both attribute-based mechanisms come back
+  empty. 10 new tests covering the new discovery method, the prefix
+  helper, and both branches of `discover_mesh_peers_auto()`'s fallback
+  logic -- plus two direct end-to-end simulations of the updated CLI
+  debug path (both the new-mechanism-succeeds case and the
+  falls-through-to-the-old-mechanism case) run manually before
+  delivery, not just unit-level mocks.
+
+## 0.3.1
+
+- **Fixed a real, high-impact bug: `Brightness` (the master dimmer
+  channel) was never being applied to any other channel at all.**
+  Confirmed via reverse engineering the app's own "flatten" logic, called
+  on both bracketing schedule points before
+  interpolating between them -- an earlier decompilation attempt for this logic
+  was unreliable here, the same underlying issue that led to
+  finding the `is_night_segment()` bug, so this was re-verified against
+  the raw bytecode rather than trusted from the decompile a second time). Every
+  channel -- moonlight included -- was being interpolated and returned
+  without ever being scaled by `Brightness`, found via real hardware
+  testing: a light showing ~1% in the app's own display came back as
+  ~25% from this library at the same moment, with `Brightness` itself
+  reading ~3.3% at that point in its own ramp -- fully consistent with
+  the missing multiplication, not a lunar or scheduling bug.
+  `interpolate_light_schedule()` now flattens each bracketing point
+  SEPARATELY (by that point's own `Brightness` value) BEFORE
+  interpolating between the two already-flattened points -- confirmed
+  via a dedicated test that this is NOT mathematically equivalent to
+  interpolating raw values first and multiplying by a single
+  interpolated `Brightness` at the end, whenever `Brightness` itself
+  changes across the segment (which it usually does, e.g. ramping
+  during dusk/dawn). `Brightness` itself is still returned as the plain
+  raw interpolated value, not flattened to a constant 100% the way the
+  real `flatten()` does to the primitive it's applied to -- callers
+  (e.g. a dedicated `Brightness` sensor) want the actual current
+  master-dimmer level. 4 new tests.
+
 ## 0.3.0
 
 - **Fixed a real, high-impact bug in `is_night_segment()`: the condition
   deciding whether to apply lunar-phase reduction had its first check
-  inverted**, confirmed directly from raw smali bytecode after JADX's
-  own decompiled Java carried a "Code duplicated" warning on this exact
-  method that turned out to be a real signal -- the decompiler had
+  inverted**, confirmed directly against the raw bytecode after an
+  earlier decompilation attempt on this exact
+  method turned out to be unreliable -- a real signal, not noise: the decompiler had
   produced `!point.has(NIGHT)` where the actual bytecode requires
   `point.has(NIGHT)`. In practice this meant lunar reduction was applied
   only during the single dusk-transition segment (and only if the query
@@ -87,16 +246,16 @@ 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
+  after the user provided the raw disassembly for
+  the app's own connection logic -- the decompiler had given up specifically on
+  the indication-handling logic, the one thing 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() ==
+  (confirmed via reverse engineering: `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
@@ -120,7 +279,8 @@ branch has been merged into main as part of this release.
   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
+  confirmed via reverse engineering the app's own connection-setup logic
+  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
@@ -150,15 +310,15 @@ branch has been merged into main as part of this release.
 
 - **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
+  discarded by the app itself, on purpose.** The app's own byte-dispatch
+  logic 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
+  the app's own indication-handling logic -- a method the decompiler couldn't resolve to readable code, 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
@@ -169,8 +329,8 @@ branch has been merged into main as part of this release.
 - **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`) --
+  hardware dependency. Confirmed wire format traced directly from
+  reverse engineering the app's own CoAP model --
   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
@@ -184,8 +344,8 @@ branch has been merged into main as part of this release.
   `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
+  short-address portion is little-endian (confirmed via reverse
+  engineering the app's own byte-extraction logic), 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.
@@ -199,8 +359,8 @@ branch has been merged into main as part of this release.
   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
+  `"00000000000000"`, confirmed via reverse engineering the app's own
+  network-setup 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
@@ -249,8 +409,8 @@ branch has been merged into main as part of this release.
 
 - **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
+  confirmed via the app's own "Time Difference" troubleshooting feature,
+  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,
@@ -371,8 +531,7 @@ branch has been merged into main as part of this release.
   (`IsCalibrated`/`LastCalibrationTime`/`MinCalibratedSpeed`/
   `MaxCalibratedSpeed`, 1300/1304/1308/1309) -- **important correction**:
   despite "Speed"-sounding names, confirmed via the app's own UI gating
-  (`DeviceSettingsFragment.java`: `device.primitive.category() ==
-  M.DeviceCategory.Lighting`) that this is a light feature, not a pump
+  (its own device category check) that this is a light feature, not a pump
   one. A separate, unrelated pump-side calibration flow exists in the app
   (Nero-specific zero-flow/max-flow calibration) but isn't implemented and
   doesn't apply to VorTech anyway (no physical flow sensor to calibrate).
@@ -401,7 +560,7 @@ branch has been merged into main as part of this release.
 - **Added full hyperdrive support** (correct percentage conversion for
   light channels boosted above their normal 100% rating). New
   `mobius.power` module (`ChannelPowerInfo`, `channel_percent_value()`,
-  ported from `LightPowerInfo.java`) and `get_channel_power_info()`
+  confirmed via reverse engineering the app's own power model) and `get_channel_power_info()`
   (`MaxPower`/`NormalPower`, attributes 1504/1513). New
   `get_current_light_percentages()` convenience method returns corrected
   0-100+ percentages instead of raw permille, flagging boosted channels via
@@ -434,20 +593,21 @@ branch has been merged into main as part of this release.
   a schedule-level master intensity scalar (`Schedule1Intensity`, attribute
   511) that the real app applies on top. Caught by direct comparison
   against real app screenshots showing different numbers than this
-  library computed for the same light at the same time. Traced to
-  `WidgetViewCell.java`/`IntensityView.java` in the decompiled source.
+  library computed for the same light at the same time. Traced through
+  reverse engineering the app's own dashboard-rendering logic.
   Added `get_schedule_intensity()`; `get_current_light_intensities()` now
   applies it automatically.
 - **Added lunar-phase and acclimation-ramp support**, the two remaining
   modifiers flagged as gaps in the previous entry. New `mobius.modifiers`
-  module, ported from `LunarInfo.java`/`AcclimationInfo.java`:
+  module, confirmed via reverse engineering the app's own lunar and
+  acclimation models:
   - `lunar_percent_reduction(date)` -- verified against real,
     independently-confirmed 2026 moon phase dates (full moon Jan 3, new
     moon Jan 18); the ported algorithm matches exactly.
   - `AcclimationInfo` -- linear intensity ramp from a starting percentage
     up to full over a configured period.
-  - `is_night_segment()` -- ported from the boolean half of
-    `PointSchedule.getIntensitiesAtTime()`; confirmed this is specifically
+  - `is_night_segment()` -- confirmed via reverse engineering the boolean half of
+    the app's own schedule-interpolation logic; confirmed this is specifically
     "the dusk-to-night transition segment," not simply "is it night."
   - `get_lunar_enabled()`, `get_acclimation_info()`,
     `get_current_light_intensities()` now applies the full branching the
@@ -462,8 +622,8 @@ branch has been merged into main as part of this release.
 
 ## 0.1.2
 
-- Added `manufacturer_for_model()` / `MODEL_MANUFACTURER` (ported from
-  `M.Model.getManufacturer()`) — surfaces "EcoTech Marine" /
+- Added `manufacturer_for_model()` / `MODEL_MANUFACTURER` (confirmed via
+  reverse engineering the app's own manufacturer-lookup logic) — surfaces "EcoTech Marine" /
   "AquaIllumination" / "Neptune Systems" / "NYOS" per device model. Now
   included automatically in `get_device_info()`'s `"manufacturer"` field.
   Added while building a Home Assistant integration on top of this library,

{python_mobius-0.3.0 → python_mobius-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-mobius
-Version: 0.3.0
+Version: 0.4.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
@@ -140,7 +140,7 @@ GPLv2 — see [`LICENSE`](./LICENSE).
 
 The protocol reverse-engineering and implementation in this library were
 carried out with substantial assistance from Claude (Anthropic), used to
-analyze a decompiled copy of the official Mobius Android app (JADX) and
+analyze a decompiled copy of the official Mobius Android app and
 cross-reference it against prior public community research (notably the
 Reef2Reef "Controlling Mobius enabled VorTech pump using 0-10V and BLE"
 thread and the `danmrossi/MobiusControl` project), then to design, write,

{python_mobius-0.3.0 → python_mobius-0.4.0}/README.md

@@ -108,7 +108,7 @@ GPLv2 — see [`LICENSE`](./LICENSE).
 
 The protocol reverse-engineering and implementation in this library were
 carried out with substantial assistance from Claude (Anthropic), used to
-analyze a decompiled copy of the official Mobius Android app (JADX) and
+analyze a decompiled copy of the official Mobius Android app and
 cross-reference it against prior public community research (notably the
 Reef2Reef "Controlling Mobius enabled VorTech pump using 0-10V and BLE"
 thread and the `danmrossi/MobiusControl` project), then to design, write,

{python_mobius-0.3.0 → python_mobius-0.4.0}/documentation/00-overview.md

@@ -15,7 +15,7 @@ Interface conventions, extended by EcoTech).
    sniffing and partial decompilation. The `danmrossi/MobiusControl` GitHub
    repo has a working Arduino/ESP32 implementation built on that research.
 
-2. **Direct decompilation of the Mobius Android app** (JADX), which
+2. **Direct reverse engineering of the Mobius Android app**, which
    confirmed everything from (1) and filled in every gap it left:
    - The exact reserved-byte bit layout.
    - Both the "old" (1-byte field) and "new" (2-byte field) opcode variants
@@ -60,7 +60,7 @@ The decompiled-source analysis, protocol derivation, and Python
 implementation in this project were done with substantial assistance from
 Claude (Anthropic) — reading the decompiled Java sources, cross-referencing
 them against the public community research above, resolving several
-JADX cosmetic-decompilation artifacts (see
+decompilation artifacts specific to the reverse-engineering process (see
 [03-attributes-and-opcodes.md](./03-attributes-and-opcodes.md) for a
 specific example), and writing/testing the resulting Python code. Every
 claim in these docs is still tagged by how it was actually confirmed (see

{python_mobius-0.3.0 → python_mobius-0.4.0}/documentation/01-ble-transport.md

@@ -16,7 +16,7 @@ This UUID pattern is a generic Nordic-style "wireless UART" shape; the
 `01ff01xx` prefix is what actually identifies it as Mobius-specific, not the
 UUID base itself.
 
-**Confirmed** via the decompiled `PeripheralConnection.java`: the app writes
+**Confirmed** via reverse engineering the app's own connection logic: the app writes
 to `TX_DATA` for every chunk except the last, and to `TX_FINAL` for the
 last (or only) chunk — writing to `TX_FINAL` is what triggers the device to
 actually process the accumulated message. Symmetrically, on receive, it

{python_mobius-0.3.0 → python_mobius-0.4.0}/documentation/02-framing-and-crc.md

@@ -44,7 +44,7 @@ explored.
 
 ## `reserved` field bit layout
 
-Confirmed from `Request.java`:
+Confirmed via reverse engineering:
 
 ```
 byte0: bits 0-1 = FSCI instance
@@ -66,10 +66,10 @@ def crc16(data: bytes, seed: int = 0xFFFF) -> int:
     return crc
 ```
 
-The 256-entry table is ported directly from the decompiled
-`com.c2.comm.utilities.Crc` class (Java's signed-short constants, converted
+The 256-entry table is confirmed via reverse engineering the app's own
+CRC implementation (the original signed-short constants, converted
 to unsigned 16-bit for Python — see `src/mobius/crc.py`). There's also an
-unused CRC8 table in the same Java class, not used by anything observed and
+unused CRC8 table alongside it, not used by anything observed and
 not ported here.
 
 ## Message ID / request-response correlation

{python_mobius-0.3.0 → python_mobius-0.4.0}/documentation/03-attributes-and-opcodes.md

@@ -46,7 +46,7 @@ from a multi-element Get, this assumption is the first thing to suspect.
 
 ## The `C2Attribute` table
 
-The decompiled `M.C2Attribute` enum has on the order of 250 entries,
+The app's own attribute-identifier enum has on the order of 250 entries,
 covering the entire equipment line (lighting, pumps, dosing, Thread
 networking, OTA firmware, engineering/debug attributes, etc.). This library
 implements a curated subset — see `src/mobius/constants.py::C2Attribute` —
@@ -54,23 +54,22 @@ covering device identity, scenes, schedules, pump telemetry, and light
 channels.
 
 Every value is either a literal read directly from the decompile, or
-resolved through a JADX cosmetic-substitution artifact (explained below)
+resolved through a symbolic-substitution artifact (explained below)
 back to a real integer — confirmed, not guessed, in both cases.
 
-### The JADX substitution artifact
+### The symbolic-substitution artifact
 
-R8/ProGuard inlines small integer constants at compile time. JADX, when
-decompiling, sometimes picks a symbolic name for one of these literals from
+R8/ProGuard inlines small integer constants at compile time. The
+decompiler, in turn, sometimes picks a symbolic name for one of these literals from
 an *unrelated* imported class whose constant happens to share the same
 numeric value — purely cosmetic, but it means the decompiled source shows
-e.g. `TypedValues.CycleType.TYPE_CURVE_FIT` instead of the literal `401`.
+a symbolic name from an unrelated library instead of the literal `401`.
 
 Most of these were resolved by obtaining the real source of the referenced
-library class (e.g. `androidx.constraintlayout.core.motion.utils.TypedValues`)
-and reading its actual constant values. One, `Schedule1`, required an extra
-hop: it resolved to `com.google.firebase.messaging.ServiceStarter.ERROR_UNKNOWN`,
-a Firebase Cloud Messaging internal class — obtaining *that* class's source
-confirmed `ERROR_UNKNOWN = 500`, and therefore `Schedule1 = 500`. This was
+library class and reading its actual constant values. One, `Schedule1`, required an extra
+hop: it resolved to an unrelated library's internal
+constant — obtaining *that* class's source
+confirmed the real value was `500`, and therefore `Schedule1 = 500`. This was
 subsequently confirmed live: fetching schedules with attribute ID 500
 against real pumps and lights returned correctly-structured, sane data.
 

{python_mobius-0.3.0 → python_mobius-0.4.0}/documentation/04-device-identity.md

@@ -58,7 +58,7 @@ a fourth "Hera" product line (codenamed after Taco Bell menu items in the
 source — `CrunchyTaco`, `SoftTaco`, `BajaBlast`, etc.). This library
 implements a curated subset relevant to lights/pumps/skimmers — see
 `src/mobius/constants.py::Model`; add entries as needed by copying values
-from the decompiled `M.Model` enum.
+from the app's own model-identifier enum.
 
 Some newer model names in the decompile are Base64-encoded string literals
 rather than plain strings (likely an unrelated obfuscation pass) — e.g.
@@ -66,7 +66,7 @@ model `179` decodes to `"Radion XR15w G6 Pro"` from
 `base64.b64decode("UmFkaW9uIFhSMTV3IEc2IFBybw==")`. `RadionXR15wG6Blue = 180`
 is a sequential-numbering *inference*, not a directly-read literal (it sits
 in a gap between two confirmed values, but the exact literal wasn't
-resolvable through the JADX-substitution technique the way others were).
+resolvable through the symbolic-substitution technique the way others were).
 
 ## `ErrorState`
 

{python_mobius-0.3.0 → python_mobius-0.4.0}/documentation/06-light-schedule.md

@@ -17,8 +17,7 @@ lunar/acclimation modifiers.
 
 ## Schedule-level master intensity (`Schedule1Intensity`, attribute 511)
 
-Confirmed via `WidgetViewCell.java`/`IntensityView.java` in the decompiled
-app: on top of the per-channel interpolated curve, the app applies a
+Confirmed via reverse engineering the app's own dashboard-rendering logic: on top of the per-channel interpolated curve, the app applies a
 **separate schedule-level master dimmer** -- `dCurrentIntensity =
 schedule.intensity / 1000.0`, multiplied onto every channel's interpolated
 value. This is genuinely separate from any individual channel's own value,
@@ -75,18 +74,57 @@ lights.
 
 ## Interpolation algorithm
 
-Ported from `PointSchedule.getIntensitiesAtTime()`:
+Confirmed via reverse engineering the app's own schedule-interpolation logic:
 
 1. Sort points by time.
 2. Find the two points that bracket the target minute-of-day, wrapping
    around midnight (the point after the last one is treated as being on
    "the next day," i.e. its time + 1440).
-3. For each channel present in either bracketing point, linearly
-   interpolate: `value(t) = v1 + (v2 - v1) * (t - t1) / (t2 - t1)`.
-4. Channels absent from a point default to `0` (off).
+3. **`Brightness` (`VisualID.Brightness`) is a master dimmer, applied to
+   EACH bracketing point separately, before interpolating between them**
+   -- confirmed via reverse engineering the app's own "flatten" logic, called on
+   both point copies before the
+   interpolation loop -- an earlier decompilation attempt for this logic
+   was unreliable here, the same underlying issue that led to
+   finding the `is_night_segment()` bug, so this was verified against
+   the raw bytecode directly rather than trusted from the decompile). For each
+   point independently: every channel except `Brightness` itself is
+   multiplied by that same point's own `Brightness` value / 1000. This
+   was a real, confirmed-missing step for a while -- every channel
+   (moonlight included) was being interpolated and returned without
+   ever being scaled by `Brightness` at all, found via real hardware
+   testing (a light showing ~1% in the app's own display came back as
+   ~25% from this library at the same moment, with `Brightness` itself
+   reading ~3.3% at that point in its own ramp).
+4. For each channel present in either bracketing point, linearly
+   interpolate between the (already `Brightness`-scaled, for
+   non-`Brightness` channels) endpoint values:
+   `value(t) = v1 + (v2 - v1) * (t - t1) / (t2 - t1)`.
+   **Flattening happens per-endpoint before this step, not
+   interpolate-raw-then-multiply-by-a-single-`Brightness`-value after
+   it** -- these are NOT mathematically equivalent whenever `Brightness`
+   itself changes across the segment (which it usually does, e.g.
+   ramping during a dusk/dawn transition).
+5. Channels absent from a point default to `0` (off), except
+   `Brightness` itself: a point missing that channel entirely is treated
+   as a no-op 1000 (100%) multiplier for that point, matching
+   `flatten()`'s own `visuals().contains(Brightness)` guard (skips
+   scaling entirely rather than treating an absent value as 0, which
+   would zero out every other channel).
+6. `Brightness` itself is returned as the plain raw interpolated value
+   between the two points' own `Brightness` levels -- NOT flattened to
+   1000 the way the real `flatten()` call does internally to the
+   primitive it's applied to. Unlike the app's own dashboard (which
+   doesn't display `Brightness` as its own value at all, only as the
+   multiplier baked into every other channel), this library's callers
+   (e.g. a dedicated `Brightness` sensor) want the actual current
+   master-dimmer level itself.
 
 Verified against a synthetic two-point schedule (exact endpoint values,
-midpoint blending, and midnight-wraparound blending -- see
+midpoint blending, midnight-wraparound blending, and the `Brightness`
+master-dimmer behavior above, specifically including a case designed to
+mathematically distinguish flatten-then-interpolate from the wrong
+interpolate-then-multiply alternative -- 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).
@@ -100,7 +138,7 @@ A static list of `VisualID` values (channel identities) a given light has
 ## Lunar phase and acclimation ramp
 
 Both implemented, on top of the schedule-level master intensity above.
-Ported from `LunarInfo.java`/`AcclimationInfo.java` in the decompiled app.
+Confirmed via reverse engineering the app's own lunar and acclimation models.
 
 **Lunar phase** (`lunar_percent_reduction(date)`): a simplified moon-phase
 model -- a Julian-Day-based calculation (`julian_day_from_date()`, the
@@ -116,8 +154,8 @@ where `is_night_segment()` is true (see below), and only when
 that segment just uses a flat `1.0` (full/unreduced) scalar, matching
 the app's own fallback.
 
-**`is_night_segment()`**: ported from the boolean half of
-`PointSchedule.getIntensitiesAtTime()`'s return value. This is *not*
+**`is_night_segment()`**: confirmed via reverse engineering the boolean half of
+the app's own schedule-interpolation return value. This is *not*
 simply "is it night" as a general concept -- it's specifically true for
 the segment whose **start** point IS flagged `NIGHT` (but not also
 `SUNRISE`) and whose end point is ALSO flagged `NIGHT` -- i.e. once
@@ -127,9 +165,9 @@ point. In practice this covers essentially the whole night, *except*
 the two transition segments themselves: dusk (start point not yet
 night-flagged) and the sunrise segment (start point flagged `SUNRISE`).
 
-**Confirmed directly from raw smali bytecode, not the decompiled Java.**
-JADX's decompiler carried its own "Code duplicated" warning on this
-exact method -- a real signal, not noise: its decompiled Java had this
+**Confirmed directly against the raw bytecode, not the decompiled Java.**
+An earlier decompilation attempt for this
+exact method was unreliable -- a real signal, not noise: the decompiled Java had this
 condition's first check inverted (`!point.has(NIGHT)` instead of the
 actual `point.has(NIGHT)`), which an earlier version of this port
 carried forward uncorrected. Found via real hardware testing: a light

{python_mobius-0.3.0 → python_mobius-0.4.0}/documentation/07-pump-schedule.md

@@ -81,11 +81,10 @@ byte):
 `Time`, `StartTime`, and `EndTime` (**only these three** — not `OnTime`/
 `OffTime`/`BigTime`, which are stored raw) are stored as
 `actual_value - 250` on the wire, and the app adds `250` back when reading.
-`250` is a real Android constant:
-`androidx.recyclerview.widget.ItemTouchHelper.Callback.DEFAULT_SWIPE_ANIMATION_DURATION`
-— another instance of the JADX cosmetic-substitution artifact described in
+`250` is a real Android library constant
+— another instance of the symbolic-substitution artifact described in
 [03-attributes-and-opcodes.md](./03-attributes-and-opcodes.md), resolved by
-looking up that Android library constant's real value. Verified against
+looking up that library constant's real value. Verified against
 synthetic round-trip data (`tests/test_pump_schedule.py`).
 
 ### `MaxSpeed`/`MinSpeed` sign