python-mobius 0.7.1__tar.gz → 0.8.0__tar.gz

{python_mobius-0.7.1 → python_mobius-0.8.0}/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.8.0
+
+- Added `supported_pump_modes(primitive_type, closed_loop=None)`: the
+  `PumpMode` values a given pump actually supports. See
+  documentation/07-pump-schedule.md's own "Which modes a given pump
+  actually supports" section.
+- Added schedule write support: set_light_schedule()/set_pump_schedule(),
+  GroupBitmap (group_mask), and --dump-schedule-file/--load-schedule-file
+  CLI flags.
+- Added support for .mob (Template) files -- export/import for both
+  light and pump schedules, plus --dump-mob-file/--load-mob-file CLI
+  flags.
+- --load-schedule-file/--load-mob-file now write to every device in a
+  light's schedule group, not just the one named, and check the whole
+  group's smallest schedule capacity up front so a too-large schedule
+  aborts cleanly instead of partially applying.
+- get_pump_telemetry() now also includes every other sensor value a
+  pump reports supporting (motor RPM, temperatures, battery/input
+  voltage, etc.) under a new extra_physical_values key, alongside the
+  existing gph/motor_power_watts.
+- Added get_extra_physical_values() -- the same extra sensor values as
+  above, for callers with no get_pump_telemetry()-equivalent method of
+  their own. get_device_summary() uses this for lights specifically
+  (ClusterTemperature/DriverTemperature/etc.), which previously had no
+  way to surface this data at all.
+- Added get_fan_thresholds() -- FanOnTemperature/FanOffTemperature,
+  shown unconditionally in get_device_summary().
+
+## 0.7.2
+
+- get_full_poll_batch() now includes scene data (ConfiguredScenes/
+  CurrentScene) in the same combined request, falling back to
+  get_configured_scenes()/get_current_scene() if the batch itself
+  fails.
+- start_scene()/start_feed_mode() now broadcast to the whole mesh by
+  default (one write instead of one per device) -- pass
+  broadcast=False for the old, single-device-only behavior.
+
 ## 0.7.1
 
 - Added scene support: get_configured_scenes(), get_current_scene(),

{python_mobius-0.7.1 → python_mobius-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-mobius
-Version: 0.7.1
+Version: 0.8.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
@@ -102,20 +102,43 @@ mobius-scan --adapter hci0
 - **Discover devices** and group them by tank/mesh (`pan_id`), reading
   model/serial straight from BLE advertisements — no connection required.
 - **Read pump telemetry**: current speed, estimated flow (GPH), operation
-  state, error state, and (Vectra/NYOS Quantum pumps) motor power in watts.
+  state, error state, and (Vectra/NYOS Quantum pumps) motor power in watts —
+  plus every OTHER live sensor value (motor RPM, temperatures, battery/input
+  voltage, etc.) a specific pump reports supporting, merged into the same
+  result under `extra_physical_values` rather than a separate call. Lights
+  get the same extra sensor values too (`get_extra_physical_values()`) —
+  a light has no telemetry method of its own to merge them into, but
+  `get_device_summary()` still surfaces them the same way.
 - **Read pump schedules**: which mode (constant speed, tidal swell, pulse,
   etc.) is active at any given time, exactly as programmed.
 - **Read light schedules**: per-channel intensity at any given time,
   replicating the app's own client-side interpolation (there's no "current
   intensity" attribute — lights only expose the programmed curve).
+- **Read every configured scene** (`get_configured_scenes()`) — name,
+  timeout, and its own light/pump payload, at whatever slot it lives in,
+  plus the currently active one (`get_current_scene()`).
+- **Control scenes**: start feed mode, resume the normal schedule, or any
+  other configured scene — one write, broadcast to the whole mesh by
+  default (`broadcast=True`). Uses the same mesh-propagation mechanism
+  confirmed against real hardware for the clock-sync write below;
+  applying it to scene activation specifically hasn't been
+  independently verified the same way yet.
+- **Fetch everything one device poll needs in a single round-trip**
+  (`get_full_poll_batch()`) — identity, metadata, light/pump state, and
+  scene data together, confirmed 2-2.6x faster on real hardware than
+  reading each piece separately.
 - **Read device-specific settings**: VorTech's own "Local Control"/"Led
   Auto Dim" and Radion's own "Max Fan Speed"/"Fan Shutdown"
   (`get_advanced_features()`), plus Vectra and NYOS Quantum settings
   (`get_vectra_info()`/`get_coffee_info()` — no real hardware to verify
   either against, see
   [known gaps](./documentation/10-known-gaps-and-open-questions.md)).
-- **Control scenes**: start feed mode, resume the normal schedule, or any
-  other configured scene.
+- **Read a device's own fan protection thresholds** (`get_fan_thresholds()`)
+  — FanOnTemperature/FanOffTemperature, if supported at all; confirmed
+  against real hardware that neither a Radion light nor a VorTech pump
+  reports supporting either one, and — forcing a direct read anyway —
+  that the device actively rejects it (`FsciStatus.UnsupportedAttribute`),
+  not merely omitting it while still functioning underneath.
 - **Fix a desynced device clock** (`set_time_to_now()`) — a WRITE.
   Writing to one device appears to propagate to the rest of its Thread
   mesh too, confirmed against real hardware — see

{python_mobius-0.7.1 → python_mobius-0.8.0}/README.md

@@ -70,20 +70,43 @@ mobius-scan --adapter hci0
 - **Discover devices** and group them by tank/mesh (`pan_id`), reading
   model/serial straight from BLE advertisements — no connection required.
 - **Read pump telemetry**: current speed, estimated flow (GPH), operation
-  state, error state, and (Vectra/NYOS Quantum pumps) motor power in watts.
+  state, error state, and (Vectra/NYOS Quantum pumps) motor power in watts —
+  plus every OTHER live sensor value (motor RPM, temperatures, battery/input
+  voltage, etc.) a specific pump reports supporting, merged into the same
+  result under `extra_physical_values` rather than a separate call. Lights
+  get the same extra sensor values too (`get_extra_physical_values()`) —
+  a light has no telemetry method of its own to merge them into, but
+  `get_device_summary()` still surfaces them the same way.
 - **Read pump schedules**: which mode (constant speed, tidal swell, pulse,
   etc.) is active at any given time, exactly as programmed.
 - **Read light schedules**: per-channel intensity at any given time,
   replicating the app's own client-side interpolation (there's no "current
   intensity" attribute — lights only expose the programmed curve).
+- **Read every configured scene** (`get_configured_scenes()`) — name,
+  timeout, and its own light/pump payload, at whatever slot it lives in,
+  plus the currently active one (`get_current_scene()`).
+- **Control scenes**: start feed mode, resume the normal schedule, or any
+  other configured scene — one write, broadcast to the whole mesh by
+  default (`broadcast=True`). Uses the same mesh-propagation mechanism
+  confirmed against real hardware for the clock-sync write below;
+  applying it to scene activation specifically hasn't been
+  independently verified the same way yet.
+- **Fetch everything one device poll needs in a single round-trip**
+  (`get_full_poll_batch()`) — identity, metadata, light/pump state, and
+  scene data together, confirmed 2-2.6x faster on real hardware than
+  reading each piece separately.
 - **Read device-specific settings**: VorTech's own "Local Control"/"Led
   Auto Dim" and Radion's own "Max Fan Speed"/"Fan Shutdown"
   (`get_advanced_features()`), plus Vectra and NYOS Quantum settings
   (`get_vectra_info()`/`get_coffee_info()` — no real hardware to verify
   either against, see
   [known gaps](./documentation/10-known-gaps-and-open-questions.md)).
-- **Control scenes**: start feed mode, resume the normal schedule, or any
-  other configured scene.
+- **Read a device's own fan protection thresholds** (`get_fan_thresholds()`)
+  — FanOnTemperature/FanOffTemperature, if supported at all; confirmed
+  against real hardware that neither a Radion light nor a VorTech pump
+  reports supporting either one, and — forcing a direct read anyway —
+  that the device actively rejects it (`FsciStatus.UnsupportedAttribute`),
+  not merely omitting it while still functioning underneath.
 - **Fix a desynced device clock** (`set_time_to_now()`) — a WRITE.
   Writing to one device appears to propagate to the rest of its Thread
   mesh too, confirmed against real hardware — see

{python_mobius-0.7.1 → python_mobius-0.8.0}/documentation/00-overview.md

@@ -45,7 +45,7 @@ Interface conventions, extended by EcoTech).
 | [02-framing-and-crc.md](./02-framing-and-crc.md) | Wire frame layout, CRC16 algorithm |
 | [03-attributes-and-opcodes.md](./03-attributes-and-opcodes.md) | Get/Set-attribute opcodes, payload format, the `C2Attribute` table |
 | [04-device-identity.md](./04-device-identity.md) | `PrimitiveType`, `Model`, `ErrorState`, support tiers |
-| [05-scenes.md](./05-scenes.md) | Scene control (feed mode, resume schedule, etc.) |
+| [05-scenes.md](./05-scenes.md) | Scene control (reading configured scenes, activating one, mesh-wide broadcast, resuming the schedule) |
 | [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) |
@@ -54,7 +54,7 @@ Interface conventions, extended by EcoTech).
 | [11-device-status-attributes.md](./11-device-status-attributes.md) | Flow range, override mode, battery backup, group/sync, calibration (light-only), maintenance |
 | [12-device-identity-and-address-stability.md](./12-device-identity-and-address-stability.md) | Why device identity is serial-number-based, not address-based |
 | [13-attribute-dump.md](./13-attribute-dump.md) | Reading every attribute a device supports, enriched JSON output, the app-compatible text format |
-| [14-batched-attribute-reads.md](./14-batched-attribute-reads.md) | Reading multiple, different attributes in one round-trip |
+| [14-batched-attribute-reads.md](./14-batched-attribute-reads.md) | Reading multiple, different attributes in one round-trip, and the combined-poll methods built on top |
 
 ## On the use of AI assistance
 

{python_mobius-0.7.1 → python_mobius-0.8.0}/documentation/03-attributes-and-opcodes.md

@@ -85,7 +85,8 @@ against real pumps and lights returned correctly-structured, sane data.
 | `MACAddress` | 103 | Observed unpopulated (empty response) on all devices tested |
 | `OperationState` | 104 | `OOB`/`LiveDemo`/`Scene`/`Schedule` |
 | `ErrorState` | 107 | See [04-device-identity.md](./04-device-identity.md) |
-| `CurrentScene` | 401 | Set to `sceneId(u16 LE) + durationMinutes(u16 LE)` to start a scene |
+| `CurrentScene` | 401 | Set to `sceneId(u16 LE) + durationSeconds(u16 LE)` to start a scene -- see [05-scenes.md](./05-scenes.md) |
+| `ConfiguredScenes` | 400 | Every scene this device has programmed, one per slot -- see [05-scenes.md](./05-scenes.md) |
 | `Schedule1` / `Schedule2` | 500 / 503 | The programmed point-schedule — see 06/07 |
 | `MotorSpeed` | 700 | Live pump speed (int16). Confirmed NOT RPM -- percentage of max power in tenths of a percent (abs(value)/10 = %); sign encodes rotation direction. Confirmed via the app's own display formatting. |
 | `LocalControlEnabled` / `AutoDimTimeout` / `MaxFanSpeed` / `FanShutdownEnabled` | 300 / 301 / 910 / 1203 | VorTech/Radion advanced feature settings — see 11 |

python_mobius-0.8.0/documentation/05-scenes.md

@@ -0,0 +1,137 @@
+# Scenes
+
+Scenes are device-side presets (feed mode, all-off, disco, a user-created
+custom one, etc.) that can be activated on demand, separate from the
+normal time-based schedule. A scene is genuinely tank-wide, not a
+per-device concept — creating one (not implemented by this library; see
+below) writes a matching entry, with the same `id`/`name`/`timeout`, to
+every device in the tank that supports scenes and has a free slot.
+
+## `SceneID`
+
+Confirmed literal values — the ten built-in presets. A user-created
+custom scene's own `id` is a device-assigned value outside this range
+(see "Configured scenes" below), not one of these:
+
+| Value | Name |
+|---|---|
+| 0 | `EmptyScene` |
+| 1 | `FeedMode` |
+| 2 | `BatteryBackup` |
+| 3 | `AllOff` |
+| 4 | `ColorCycle` |
+| 5 | `Disco` |
+| 6 | `Thunderstorm` |
+| 7 | `CloudCover` |
+| 8 | `AllOn` |
+| 9 | `All50` |
+
+## Configured scenes
+
+`C2Attribute.ConfiguredScenes` (400) holds every scene this device has
+programmed, one per slot, read via the same "get all elements" pattern
+used for the point schedule (`index=0, count=0xFFFF`) — the number of
+slots a device actually has is device-reported, not a fixed constant,
+and can genuinely differ by device type. Each element is:
+
+```
+id (u16 LE) + timeout (u16 LE) + name (16 bytes, null-padded) + primitiveData
+```
+
+`primitiveData` is exactly the same payload a schedule point's own
+primitive would be — a light's own per-channel intensities, or a pump's
+own mode + parameters (see
+[06-light-schedule.md](./06-light-schedule.md)/
+[07-pump-schedule.md](./07-pump-schedule.md)) — just without the
+schedule-point header (time/flags) wrapping it, since a scene isn't
+tied to a time of day. A custom scene's own `id` is a randomly-chosen
+value confirmed unique across the whole tank (not just this one
+device); a genuinely empty/unused slot has `id=EmptyScene` and an empty
+`name`.
+
+`get_configured_scenes()` reads and decodes this into a `Scene` per
+slot (`index`/`id`/`scene_type`/`name`/`timeout`/`light`/`pump`) —
+`scene_type` is `None` whenever `id` doesn't match one of the ten
+built-in presets, i.e. exactly the custom-scene case.
+
+## The currently active scene
+
+`C2Attribute.CurrentScene` (401) reports whichever scene is currently
+active:
+
+```
+id (u16 LE) + durationSeconds (u16 LE)
+```
+
+`get_current_scene()` reads and decodes this into an `ActiveScene`
+(`id`/`scene_type`/`duration_seconds`) — `scene_type` is `None` for a
+custom scene's own id here too, the same as above.
+
+## Starting a scene
+
+`start_scene(scene_id, duration_seconds=0)` sets `CurrentScene` to:
+
+```
+sceneId (u16 LE) + durationSeconds (u16 LE)
+```
+
+`duration_seconds=0` lets the device use the scene's own configured
+timeout rather than overriding it. The unit is confirmed to be
+**seconds**, not minutes — traced directly through the app's own
+duration-remaining calculation, which multiplies this same value by
+1000 to build a millisecond timestamp offset.
+
+**Confirmed live and via byte-for-byte packet reconstruction**: building a
+"start feed mode" frame with this library's own encoder reproduces a real
+packet captured from the community reverse-engineering thread exactly —
+see `tests/test_frame.py::test_build_frame_reproduces_captured_bytes_exactly`.
+
+### Broadcasting to the whole mesh
+
+`start_scene()`/`start_feed_mode()` default to `broadcast=True`, which
+sets the frame's own reserved-byte `group` field to 1 (see
+[02-framing-and-crc.md](./02-framing-and-crc.md)) — a single write to
+one device then propagates to the rest of its Thread mesh, the exact
+same mechanism confirmed against real hardware for `set_time_to_now()`'s
+own `Epoch` write (see
+[09-thread-coap-relay.md](./09-thread-coap-relay.md)). Applying that
+same mechanism to `CurrentScene` specifically hasn't been independently
+verified against real hardware the same way — it's the app's own code
+path for scene activation, not yet its own separate confirmation.
+`group=1` only ever reaches devices on that same mesh; a Thread network
+is its own isolated network (its own `pan_id`), so this cannot cross
+into a different tank's own, separate mesh even within physical radio
+range. Pass `broadcast=False` to write to only the one device instead.
+
+## Returning to the normal schedule
+
+`resume_schedule()` sets `C2Attribute.OperationState` (104) to
+`OperationState.Schedule` (3). This is what "cancel the current scene"
+actually means at the protocol level — there's no separate "cancel"
+opcode, just setting operation state back to schedule-driven. Unlike
+scene activation, this write has no confirmed mesh-propagation evidence
+of its own — call it per-device if you need it to apply tank-wide.
+
+## `OperationState`
+
+Confirmed literal values:
+
+| Value | Name |
+|---|---|
+| 0 | `OOB` (out-of-box, unconfigured) |
+| 1 | `LiveDemo` |
+| 2 | `Scene` |
+| 3 | `Schedule` |
+
+## Not implemented: creating/editing a scene
+
+Writing a new or modified `Scene` entry (rather than just activating an
+existing one) is not implemented by this library. The wire format above
+is fully confirmed and sufficient to build one, but doing so correctly
+means writing it to every scene-capable device in the tank individually
+(no broadcast shortcut exists for this — `ConfiguredScenes` is written
+per-device, per-slot, not as a single group write), choosing a slot that
+isn't already in use on each one, and — for a genuinely custom scene —
+generating an `id` confirmed unique across the whole tank first. See
+[10-known-gaps-and-open-questions.md](./10-known-gaps-and-open-questions.md).
+

{python_mobius-0.7.1 → python_mobius-0.8.0}/documentation/06-light-schedule.md

@@ -29,6 +29,11 @@ regular per-channel value some models expose, not this).
 0-1000, default 500/50% per the app's own initialization code).
 `get_current_light_intensities()` applies it automatically.
 
+`set_schedule_intensity()` writes it back -- a plain `Set` mirroring the
+same encoding, taking a 0.0-1.0 fraction (matching the getter's own
+return range) and raising `ValueError` before writing anything if it's
+out of that range.
+
 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
@@ -72,6 +77,75 @@ VisualID (u8) + intensity (u16 LE, 0-1000 = 0.0-100.0%)
 Confirmed against a full 9-point schedule fetched live from real XR15
 lights.
 
+## Writing a schedule
+
+`Set`-ing `Schedule1`/`Schedule2` with every point's own encoded bytes
+concatenated as one multi-element payload (same "every point is a
+separate element" shape the `Get` response already uses) replaces the
+whole schedule in a single request. This is `set_light_schedule()` in
+`device.py`.
+
+Two requirements, both load-bearing — get either wrong and the device
+accepts the write (a normal FSCI success status) but silently leaves
+the schedule unchanged, with no error surfaced anywhere:
+
+- **Every point must define this light's full channel set**
+  (`get_supported_channels()`), not a subset. A partial channel set is
+  accepted but has no effect; the full set takes effect correctly.
+- **The write must be padded to the device's own full reported
+  capacity** for `Schedule1`/`Schedule2` (`get_supported_attributes()`'s
+  own index count for that attribute), not just `len(points)` —
+  otherwise indexes beyond `len(points)` keep whatever was stored there
+  before. Padding entries are all-zero bytes (`time=0, flags=0, no
+  channels`); `flags` lacking `ACTIVE` (see the flags table above) is
+  what makes a padding entry read back as an empty slot.
+
+`set_light_schedule()` raises `ValueError` before attempting any write
+if a point is missing a required channel, or if `len(points)` itself
+exceeds the reported capacity — both checkable ahead of time, so
+neither needs a round-trip to the device to catch.
+
+## Schedule groups (`GroupBitmap`, attribute 108)
+
+Multiple lights can share one schedule: editing one and saving pushes
+the same schedule to every OTHER light whose `GroupBitmap` matches,
+each as its own independent GATT write (see `Tank.java`'s own
+`createSave()` call site). Not to be confused with `GroupMaster`/
+`IsGroupMaster` (900/911, `GroupInfo`/`get_group_info()`) — an
+unrelated, dead attribute pair with nothing to do with schedule
+sharing.
+
+A 64-bit value (`Tank.createGroupBitmap()`/`parseGroupBitmap()`/
+`parseSubGroupBitmap()` in `Tank.java`): bit 0 always set, bits 1–30
+a main group number (2–31), bits 31–62 an optional per-fixture
+sub-group. **Matching is exact equality of the whole 64-bit value**,
+not overlapping bits.
+
+Observed values, two Radion lights on the same tank:
+
+| State | Light A | Light B |
+|---|---|---|
+| Same schedule group | `0x4000000000000003` (bits 0, 1, 62) | `0x4000000000000003` (bits 0, 1, 62) |
+| Split into separate groups | `0x2000000000000003` (bits 0, 1, 61) | `0x4000000000000003` (bits 0, 1, 62) |
+
+Bit 1 (main group) is the same in both rows; only the subgroup bit (61
+vs 62) differs once split — matching the bit layout above.
+
+Every light belongs to a group in the app's own UI, including a group
+of one — there is no ungrouped state exposed there. A light whose
+`group_mask` (`get_device_info()`'s own field) is `None` is treated as
+its own exclusive schedule group by this library, matched with no
+other light regardless of that other light's own value.
+
+`mobius.cli`'s own `--load-schedule-file`/`--load-mob-file` use this
+exact-equality rule to replicate the app's own group-propagation
+behavior: for a light with a real `group_mask`, both flags also write
+to every other light discovered on the same Thread mesh
+(`discovery.discover_tank()`) whose own `group_mask` matches exactly,
+each reached via `RelayedMobiusDevice` — see `cli._resolve_group_targets()`.
+A light with no `group_mask`, or a pump (which has no such grouping
+concept at all), only ever writes to the one device named.
+
 ## Interpolation algorithm
 
 Confirmed via reverse engineering the app's own schedule-interpolation logic:
@@ -82,6 +156,10 @@ Confirmed via reverse engineering the app's own schedule-interpolation logic:
    "the next day," i.e. its time + 1440).
 3. **`Brightness` (`VisualID.Brightness`) is a master dimmer, applied to
    EACH bracketing point separately, before interpolating between them**
+   (the app's own UI calls this channel "Point Intensity," not
+   "Brightness" -- not to be confused with the separate,
+   whole-schedule `Schedule1Intensity` master dimmer above, which
+   applies once to the whole schedule rather than per-point)
    -- 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
@@ -360,3 +438,17 @@ their own attributes.
   confirmed; this separate, rarer modifier is not, and is treated as
   always-disabled by those modifiers.
 - Writing/programming a schedule (only reading is implemented).
+
+## One combined round-trip: `get_light_poll_batch()`
+
+Everything on this page — the schedule fetch, and every
+lunar/acclimation/insolation-related attribute
+`process_light_intensities()` needs — is also available as ONE combined
+round-trip via `get_light_poll_batch()`, rather than the schedule fetch
+plus several further, conditional individual reads. See
+[14-batched-attribute-reads.md](./14-batched-attribute-reads.md) for the
+full confirmation and how it fits alongside `get_metadata_batch()`/
+`get_full_poll_batch()`. The decode logic itself is identical either
+way — both paths call the same pure functions this page's own formulas
+describe.
+

python_mobius-0.8.0/documentation/07-pump-schedule.md

@@ -0,0 +1,185 @@
+# Pump schedule
+
+## Same attribute, same `Point` framing, different primitive and different semantics
+
+Pumps use the exact same `Schedule1`/`Schedule2` attributes and the exact
+same `time + flags + primitiveData` point framing as lights (confirmed: the
+app's own support check only checks whether `Schedule1` is a supported
+attribute at all — it isn't gated by `PrimitiveType`). What differs:
+
+- `primitiveData` decodes as a **`PumpPrimitive`**, not a `LightPrimitive`.
+- Semantics are **discrete blocks, not a continuous curve**. `Point.getEnd()`
+  in the decompile literally returns "the next point's start time" — a
+  point's mode and parameters are the exact active setting from its own
+  start time until the next point begins. There is no blending between two
+  pump speeds the way there is between two light-channel intensities.
+
+This library's `get_active_pump_block()` reflects that: it's a lookup
+(which point's `[start, next_start)` range contains "now"), not an
+interpolation.
+
+## `PumpPrimitive` wire format
+
+```
+mode (u8)
+params (variable, depends on mode)
+```
+
+### `PumpMode` and its own parameters
+
+Confirmed literal values (note the gap: value `11` is genuinely unused
+in the source) and each mode's own full parameter set, type, and size
+(byte offset within `params` is cumulative, in the listed order,
+starting right after the mode byte) — everything needed to build a
+valid `PumpPrimitiveValue` for that mode in one place, rather than
+split across separate mode/parameter/size tables:
+
+| Value | Mode | Parameters (type, size) |
+|---|---|---|
+| 0 | `Undefined` | *(none)* — the padding placeholder `set_pump_schedule()` itself writes for an empty slot |
+| 1 | `ConstantSpeed` | `MaxSpeed` (int16, 2B) |
+| 2 | `Lagoon` | `MaxSpeed` (int16, 2B) |
+| 3 | `ReefCrest` | `MaxSpeed` (int16, 2B) |
+| 4 | `NutrientTransport` | `MaxSpeed` (int16, 2B) |
+| 5 | `TidalSwell` | `MaxSpeed` (int16, 2B) |
+| 6 | `ShortPulse` | `MaxSpeed` (int16, 2B), `Time` (int32, 4B, **+250 offset** — see below) |
+| 7 | `Gyre` | `MaxSpeed` (int16, 2B), `BigTime` (int32, 4B) |
+| 8 | `Transition` | `RampType` (byte enum, 1B — see `RampType` below) |
+| 9 | `ExpandingPulse` | `MaxSpeed` (int16, 2B), `StartTime` (int16, 2B, **+250 offset**), `EndTime` (int16, 2B, **+250 offset**) |
+| 10 | `Sync` | `MaxSpeed` (int16, 2B), `PhaseShift` (int16, 2B), `Master` (8 raw bytes — see below) |
+| 12 | `EcoSmartBack` | `MaxSpeed` (int16, 2B), `PhaseShift` (int16, 2B), `Master` (8 raw bytes) |
+| 13 | `Feed` | `MaxSpeed` (int16, 2B) |
+| 14 | `BatteryBackup` | `MaxSpeed` (int16, 2B) |
+| 15 | `Random` | `MinSpeed` (int16, 2B), `MaxSpeed` (int16, 2B), `Variance` (int16, 2B) |
+| 16 | `Pulse` | `MaxSpeed` (int16, 2B), `OnTime` (int32, 4B), `OffTime` (int32, 4B) |
+
+All multi-byte integers are little-endian. `Master`'s own 8 bytes are
+the last 8 bytes of the BLE address of the pump this one syncs to, not
+a numeric field. `RampType` is a separate byte-valued enum, not a
+plain integer — see its own table below.
+
+## Which modes a given pump actually supports
+
+The app does not offer all 16 `PumpMode` values on every pump.
+`M.PumpMode.supportedModes(PrimitiveType, Object)` (decompiled app,
+`com/c2/comm/M.java`) returns a different mode list per
+`PrimitiveType` (the pump's own product family, not a separate
+per-model table) — and this is a genuinely enforced rule, not just a
+UI display filter: `BlockSchedule.removeUnsupportedModes()` calls this
+same function and actively downgrades any point whose mode isn't in
+the returned list to `ConstantSpeed` before further use.
+
+This library exposes the same logic as `supported_pump_modes()`:
+
+| `PrimitiveType` | Supported modes |
+|---|---|
+| `PumpV1`, `AlpacaV1` | `ConstantSpeed`, `Random`, `Pulse`, `Sync`, `Feed` |
+| `VorTechV1` | `ConstantSpeed`, `ReefCrest`, `Lagoon`, `ShortPulse`, `Feed`, `TidalSwell`, `NutrientTransport`, `Sync`, `EcoSmartBack`, `ExpandingPulse`, `Gyre`, `Transition` |
+| `VectraV1`, closed-loop | `ConstantSpeed`, `ReefCrest`, `Lagoon`, `Gyre`, `Feed` |
+| `VectraV1`, open-loop (or unknown) | `ConstantSpeed`, `Feed` |
+| `TurtleV1`, `CoffeeV1` | `ConstantSpeed`, `Feed` |
+| `Undefined`, `VisualV1`, `DoseV1`, `HotSauceV1` | *(none — this mechanism was never wired up for these)* |
+
+`VectraV1` is the one primitive type where the result additionally
+depends on a live, per-device value: whether that specific Vectra is
+in "closed loop" mode (`VectraInfo.closed_loop`, from
+`get_vectra_info()` — `ClosedLoop`/attribute `801`, a real settings-
+screen toggle per that dataclass's own docstring, not something
+inferrable from `PrimitiveType` alone). The decompiled app's own two
+real call sites (`BlockInfoSliderView`, `BlockSchedule`) both use the
+single-argument `supportedModes(PrimitiveType)` overload, which passes
+a literal `null` through — so `supported_pump_modes()` defaults
+`closed_loop` to `None` and treats that identically to `False` (the
+smaller, open-loop list), matching the app's own real-world behavior
+rather than guessing permissively when this value hasn't been fetched.
+
+**`BatteryBackup`(14) is real** — a genuine `PumpMode` value with the
+real, documented parameter set above — but is never returned by this
+function for any `PrimitiveType`, confirmed directly from the
+decompiled app's own logic. Whatever real device or app flow assigns
+that mode, it isn't through this schedule-editor mode-picker path.
+
+### The `+250` offset quirk
+
+`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 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 library constant's real value. Verified against
+synthetic round-trip data (`tests/test_pump_schedule.py`).
+
+### `MaxSpeed`/`MinSpeed` sign
+
+Negative values encode reverse rotation direction (per `getReverse()` in
+the decompile, which separately inspects the sign). This library reports
+the raw signed value as-is rather than replicating the app's
+sign-stripping/`getReverse()` split — check the sign yourself if direction
+matters for your use case.
+
+### `RampType`
+
+Confirmed literal values:
+
+| Value | Name |
+|---|---|
+| 1 | `Sinusoidal` |
+| 2 | `Logarithmic` |
+| 3 | `Linear` |
+
+## Live verification
+
+Fetched an 11-point schedule from a real VorTech MP40QD pump; the point
+active at the time of the test decoded as `TidalSwell` mode with a single
+`MaxSpeed` parameter (`300`) — exactly matching the parameter table above
+for that mode (`TidalSwell` → `[MaxSpeed]` only), with a plausible value.
+
+## Avoiding a redundant re-fetch
+
+`get_current_pump_block()` accepts an optional `points` parameter — pass
+an already-fetched schedule (e.g. from a caller that already called
+`get_pump_schedule()` itself for its own purposes, such as counting
+points) to skip this method's own otherwise-redundant re-fetch of the
+exact same attribute. `None` (the default) still fetches it fresh, same
+as always.
+
+## Writing a pump schedule
+
+Same mechanism as lights (see
+[06-light-schedule.md](./06-light-schedule.md)'s own "Writing a
+schedule" section): `Set`-ing `Schedule1`/`Schedule2` with every
+point's own encoded bytes concatenated as one multi-element payload,
+always padded to the device's own full reported capacity for that
+attribute so a shorter write doesn't leave stale points at higher
+indexes. This is `set_pump_schedule()` in `device.py`.
+
+**Every point must also be padded to a FIXED size** —
+`MAX_PUMP_SCHEDULE_POINT_SIZE` (16 bytes: 2 time + 1 flags + 1 mode +
+the largest per-mode parameter total, currently `Sync`/`EcoSmartBack`'s
+own `MaxSpeed`+`PhaseShift`+`Master`) — not just the longest point
+within the current write. This differs from lights, which only need
+padding to the longest point in that same write (see the Set-attribute
+request format in
+[03-attributes-and-opcodes.md](./03-attributes-and-opcodes.md): one
+shared `length` field for the whole request, every element in a write
+must already be the same length). A device is consistent with
+expecting every schedule slot to be sized for the largest mode it can
+ever hold, regardless of which mode a given point actually uses — a
+short, unpadded write (e.g. a single `ConstantSpeed` point, naturally
+6 bytes) is accepted (normal FSCI success) but has no effect; the same
+point padded to 16 bytes takes effect correctly.
+
+Padding entries (for the capacity padding above) are
+`PumpSchedulePoint(0, 0, PumpPrimitiveValue(PumpMode.Undefined, {}))`,
+also padded out to the same fixed 16-byte size.
+
+Unlike lights, there's no "full channel set" requirement here — each
+mode's own required parameters are already strictly checked by
+`PumpPrimitiveValue.encode()` itself (raises if one is missing).
+
+## Not implemented here
+
+- The `Master` field's BLE-address matching against known devices in a
+  group (this library returns the raw 8 bytes; matching it against a scan
+  result's address suffix is left to the caller).

{python_mobius-0.7.1 → python_mobius-0.8.0}/documentation/09-thread-coap-relay.md

@@ -161,6 +161,21 @@ unreachable when propagation happens), or whether writing via
 same way -- see `set_time_to_now()`'s own docstring for the full
 breakdown.
 
+## Scene activation (`start_scene()`/`start_feed_mode()`) -- same mechanism, one level less confirmed
+
+`start_scene()` defaults to `broadcast=True`, using the exact same
+`group=1` reserved-byte mechanism confirmed above for `set_time_to_now()`
+-- the app's own scene-activation code path sets this same group value
+on every `CurrentScene` write it sends. Unlike the time-sync write,
+this specific application (`CurrentScene` propagating the same way
+`Epoch` does) hasn't been independently confirmed against real
+hardware the same way -- it's confirmed as the app's own real code
+path, not yet its own separate real-hardware propagation test. See
+[05-scenes.md](./05-scenes.md) for the full picture (the wire format,
+the fallback via `broadcast=False`) and the same "group=1 only reaches
+this one mesh, never a different tank's own" reasoning that applies
+here too.
+
 ## Device control (`reboot()`) -- targeted, no mesh-wide propagation
 
 `reboot()` writes `ResetType.Soft` (0) to `Reset` (6) -- confirmed via