python-mobius 0.9.0__tar.gz → 0.10.1__tar.gz

{python_mobius-0.9.0 → python_mobius-0.10.1}/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.10.1
+
+- Fixed lights not being read through a gateway: the poll's reply was too
+  large to be relayed. The schedule and scenes are now read in requests
+  of their own, as the app does.
+
+## 0.10.0
+
+- Added `set_time_zone()`; the batched polls now include the device's time
+  zone strings.
+- Relayed requests now accept a late response to the first attempt, as
+  the app does.
+- Fixed an unreachable light returning an empty poll as a success.
+- Added configuration checksums (`get_configuration_checksums()`, CLI
+  `--check-checksums`).
+- `get_full_poll_batch(cache=...)` reads scenes and schedules only when
+  their checksum changed.
+- `start_scene()` now runs a scene for its configured length by default
+  (a duration of 0 makes the device reuse its last scene length).
+- Fixed a scene briefly reporting about 18 hours remaining as it ends.
+- Added Bluetooth-only device support (Blades, MXM): `is_bluetooth_only()`
+  and `find_bluetooth_only_tank_members()`. The CLI connects to them
+  directly and includes them in schedule group writes.
+- Writes use the negotiated MTU instead of 20-byte fragments, as the app
+  does (fewer writes per request).
+- The pump's operation state is now part of the batched poll.
+- `ConfigurationCache(static_refresh_interval=...)` reads rarely-changing
+  attributes (identity, firmware, settings) only at that interval.
+
 ## 0.9.0
 
 - **Breaking:** `RelayedMobiusDevice` writes now raise an error when the

{python_mobius-0.9.0 → python_mobius-0.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-mobius
-Version: 0.9.0
+Version: 0.10.1
 Summary: Reverse-engineered Python client for the Mobius BLE protocol (EcoTech Marine VorTech/Radion, AquaIllumination, Neptune Systems, NYOS)
 Project-URL: Homepage, https://code.r3pek.org/r3pek/python-mobius
 Project-URL: Documentation, https://code.r3pek.org/r3pek/python-mobius/src/branch/main/documentation

{python_mobius-0.9.0 → python_mobius-0.10.1}/documentation/00-overview.md

@@ -27,6 +27,7 @@ and the `danmrossi/MobiusControl` project) and testing on real devices.
 | Reach many devices through one BLE connection | [09](./09-thread-coap-relay.md) |
 | Read settings, diagnostics or send commands (reboot, set time) | [11](./11-device-status-attributes.md) |
 | Dump every attribute of a device | [13](./13-attribute-dump.md) |
+| Avoid re-reading scenes, schedules or the attribute table | [17](./17-configuration-checksums.md) |
 | Know what is not covered or not tested | [10](./10-known-gaps-and-open-questions.md) |
 
 ## Document map
@@ -49,6 +50,7 @@ and the `danmrossi/MobiusControl` project) and testing on real devices.
 | [14-attribute-reference.md](./14-attribute-reference.md) | Every known attribute ID and enum value |
 | [15-mob-template-format.md](./15-mob-template-format.md) | The app's `.mob` schedule template file |
 | [16-python-library.md](./16-python-library.md) | How this Python library maps onto the protocol; CLI |
+| [17-configuration-checksums.md](./17-configuration-checksums.md) | Checksums of the attribute table, scenes and schedules |
 
 ## Conventions
 

{python_mobius-0.9.0 → python_mobius-0.10.1}/documentation/01-ble-transport.md

@@ -31,7 +31,11 @@ an `RX_FINAL` notification appends its bytes and completes the frame. Parse
 the buffer and clear it.
 
 20 bytes (the BLE 4.0 default ATT payload) always works; a larger
-negotiated MTU only reduces the number of writes.
+negotiated MTU only reduces the number of writes. The app asks for an MTU
+of 500 and writes chunks of the negotiated MTU minus 5; `MobiusDevice`
+does the same with the MTU the Bluetooth stack negotiated (20 bytes when
+it's unknown or 23), unless given a fixed `mtu`. Over a Bluetooth proxy
+every write is a network round trip, so this matters most there.
 
 ## Several requests in flight
 

{python_mobius-0.9.0 → python_mobius-0.10.1}/documentation/03-attributes-and-opcodes.md

@@ -126,6 +126,7 @@ that device. The app uses:
 
 | Write | Attribute | Group |
 |---|---|---|
+| Set the time zone | `PosixTimeZoneString` (205), `OlsonTimeZoneLocation` (206) | 1 |
 | Set the clock | `Epoch` (201) = current Unix time, u32 | 1. Rejected with group 0 |
 | Start a scene | `CurrentScene` (401) | The tank's group ([05](./05-scenes.md)) |
 | Cancel a scene | `OperationState` (104) = 3 | The tank's group ([05](./05-scenes.md#cancelling-a-scene)) |

{python_mobius-0.9.0 → python_mobius-0.10.1}/documentation/05-scenes.md

@@ -58,7 +58,9 @@ SceneTimer   (403): remaining seconds (u16)
 SceneTimeout (402): total seconds of the running scene (u16)
 ```
 
-A scene is running when the id is not 0 and `SceneTimer` is above 0. The
+A scene is running when the id is not 0 and `SceneTimer` is above 0 (and
+not above `SceneTimeout`; see below). Right after a scene is started,
+`SceneTimer` can still read 0 for a moment. The
 second half of `CurrentScene` doesn't change while the scene runs; the
 countdown is `SceneTimer`. The app reads these three attributes once and
 counts the remaining time down itself (end time = now + `SceneTimer`).
@@ -70,16 +72,32 @@ Example (idle VorTech pump): `CurrentScene` `00 00 00 00`, `SceneTimer`
 Write `CurrentScene`:
 
 ```
-id (u16) + duration (u16, seconds; 0 = use the scene's own timeout)
+id (u16) + duration (u16, seconds)
 ```
 
+A duration of 0 makes the device reuse the length of its last scene run
+(`SceneTimeout`), not the scene's configured timeout: on a VorTech whose
+Feed Mode is configured for 300 s, starting Feed Mode with 20 and later
+with 0 ran it for 20 s both times. `start_scene()` therefore writes the
+scene's configured timeout from `ConfiguredScenes` unless a duration is
+given.
+
 The app writes 0 as the duration and sends the write to one device with
 the reserved field set to the **tank's group**
 ([02](./02-framing-and-crc.md#reserved-field)), so every device of the tank
 starts the scene. With group 0 only the addressed device changes.
+Bluetooth-only devices (Blades) are not on the mesh, so the group write
+doesn't reach them; the app sends them the same write directly
+([09](./09-thread-coap-relay.md#bluetooth-only-devices)).
 
 To add time to the running scene, the app writes the same id with
 `remaining + extra` seconds (at most 65535), also to the tank's group.
+Written with group 0, the same write doesn't change the running scene
+(the countdown continues); with the tank's group it's untested.
+
+As a scene ends, `SceneTimer` can briefly read just below 65536 (the
+timer passing zero); a `SceneTimer` above `SceneTimeout` means the scene
+has ended.
 
 ## Cancelling a scene
 

{python_mobius-0.9.0 → python_mobius-0.10.1}/documentation/09-thread-coap-relay.md

@@ -143,9 +143,12 @@ Request types: 0 Con, 1 Non, 2 Ack, 3 Rst. Methods: 1 GET, 2 POST, 3 PUT,
 
 ### Timeouts and retries
 
-Use a timeout of a few seconds (5 s works) per attempt and retry once with
-a new token: a single lost relay round trip is common. When both attempts
-time out, the route to that target is probably down for a while; failing
+Wait 5 s for the response. On a timeout, send the same request again
+with the **same token** and wait another 5 s; a response to either send
+completes the request. This is what the app does, and it matters: a
+relayed response can arrive after the first 5 s, and with a new token for
+the resend that late response would be discarded. When both waits time
+out, the route to that target is probably down for a while; failing
 further requests to it immediately until the next poll cycle avoids
 waiting on every one.
 
@@ -153,8 +156,47 @@ A gateway can lose its route to a single target while everything else
 keeps working. The protocol has no command to rebuild the mesh; switching
 to another device as gateway is the practical recovery.
 
+## Reply size
+
+A relayed reply that is too large never arrives: the request times out
+as if the target were unreachable, while smaller requests to the same
+target keep working. Seen with a Radion XR15 G6 relayed through a VorTech
+MP40: a poll batch whose reply was about 2 KB (schedule, scenes and
+metadata together) always timed out, the same data read in three requests
+arrived. The limit is somewhere above 1.1 KB (a 25-point light schedule
+alone, about 1.05 KB of data, arrives).
+
+The app reads the schedule (and the Insolation schedule and driver
+information) in a request of its own, and everything else together; the
+Insolation table even takes 8 requests. `get_full_poll_batch()` does the
+same with the schedule and `ConfiguredScenes`.
+
 ## Writes and the mesh
 
 A relayed Set reaches only its target. A Set sent with the reserved
 field's group = 1 is forwarded by the receiving device to the whole mesh
 instead; see [03](./03-attributes-and-opcodes.md#group-writes).
+
+## Bluetooth-only devices
+
+Some devices share a tank's pan_id in their advertisement but are not on
+its Thread mesh: they have no mesh address, don't appear in any device's
+`NetworkedThreadDevices`, and can't be relayed to. They are the Blade
+models and MXM (`BLUETOOTH_ONLY_MODELS`, `is_bluetooth_only()`; the app
+keeps the same list). A Blade reports `RadioType` ESP32C3.
+
+The app handles them as follows:
+
+- A request to a Bluetooth-only device always goes over that device's own
+  connection, never through the gateway.
+- A Bluetooth-only device is never chosen as the device to connect to for
+  the rest of the tank, unless the tank has no other device.
+- A tank-wide write (scenes, cancelling a scene, time sync, restart all)
+  is sent once through a mesh device with the tank's group, which reaches
+  the mesh, and once more directly to each Bluetooth-only device. A group
+  write sent over a Bluetooth-only device's connection reaches only that
+  device.
+
+`find_bluetooth_only_tank_members(pan_id)` lists the Bluetooth-only
+devices advertising a tank's pan_id. `RelayedMobiusDevice` refuses a peer
+whose model is Bluetooth-only.

{python_mobius-0.9.0 → python_mobius-0.10.1}/documentation/11-device-status-attributes.md

@@ -131,7 +131,18 @@ encoding unknown. Read them as raw bytes.
 | `RTCTime` | 219 | u32 Unix seconds from the real-time clock |
 | `IsClockSet` | 200 | bool |
 
-The device's local date is the UTC date of `LocalTime`. For lunar
+The device's local date is the UTC date of `LocalTime`. The device
+derives `LocalTime` from `Epoch` and its POSIX TZ string (205), so a wrong
+time zone shifts schedules and the lunar date.
+
+**How the app keeps the clock right:** it doesn't sync on a timer. When it
+loads a tank it compares the tank's `Epoch` with the phone's clock, and if
+they differ by more than 15 minutes it shows "Your device's clock is
+incorrect", which the user taps to fix (unless the time was deliberately
+set by hand). The fix writes the time zone (205 and 206, from the phone's
+time zone), then `Epoch`, all with group 1. The POSIX string of an Olson
+zone name is the last line of its TZif file (for example `Europe/Lisbon`
+→ `WET0WEST,M3.5.0/1,M10.5.0`). For lunar
 calculations see [06](./06-light-schedule.md#the-lunar-date).
 
 The app's "Time Difference" troubleshooting check compares `Epoch` and
@@ -142,6 +153,7 @@ the schedule computation, which uses the client's clock.
 
 | Command | Write | Reserved group |
 |---|---|---|
+| Set the time zone | `PosixTimeZoneString` (205) and `OlsonTimeZoneLocation` (206), each a 40-byte zero-padded string | 1 |
 | Set the time | `Epoch` (201) = current Unix time (u32) | **1** (required; forwarded to the whole tank) |
 | Reboot one device | `Reset` (6) = 0 (Soft) | 0 |
 | Battery backup speed | `BatteryBackupSpeed` (706) = i16 permille | 0 |

{python_mobius-0.9.0 → python_mobius-0.10.1}/documentation/14-attribute-reference.md

@@ -23,9 +23,9 @@ Integers are little-endian; see the conventions in
 | 9 | `NumberOfFsciInstances` | u8 |  |
 | 10 | `MaxFSCIPacketSize` | u16 |  |
 | 11 | `BootCounter` | u32 | Boot counter |
-| 12 | `CRCAttributes` | — | Reads as 32 × 0xFFFF on every device seen |
+| 12 | `CRCAttributes` | — | Reads as 32 × 0xFFFF on every device seen. [17](./17-configuration-checksums.md#crcattributes-12-and-crcfunction-13) |
 | 13 | `CRCFunction` | u16 |  |
-| 14 | `SupportedAttributesCRC` | u16 |  |
+| 14 | `SupportedAttributesCRC` | u16 | Checksum of the supported attribute table. [17](./17-configuration-checksums.md#supportedattributescrc-14) |
 | 15 | `NumberOfPrimitives` | u8 |  |
 | 101 | `PhysicalValues` | indexed by PhysicalValueID; element = i32 (4 bytes) or raw | Supported indexes differ per device. [11](./11-device-status-attributes.md#pump-telemetry) |
 | 102 | `PowerState` | u8 |  |
@@ -76,12 +76,12 @@ Integers are little-endian; see the conventions in
 | 405 | `LiveDemoTimeout` | u16 |  |
 | 406 | `LiveDemoTimer` | u16 |  |
 | 407 | `LiveDemoScene` | raw | Length differs between lights and pumps |
-| 408 | `ConfiguredScenesChecksum` | u16 |  |
+| 408 | `ConfiguredScenesChecksum` | u16 | CRC16 of the used scene slots. [17](./17-configuration-checksums.md#configuredsceneschecksum-408) |
 | 500 | `Schedule1` | list of schedule points | [06](./06-light-schedule.md), [07](./07-pump-schedule.md). Index count = capacity |
-| 501 | `Schedule1Checksum` | — |  |
+| 501 | `Schedule1Checksum` | u16 | CRC16 of the active points. [17](./17-configuration-checksums.md#schedule1checksum-501-schedule2checksum-504) |
 | 502 | `Schedule1StartTime` | — |  |
 | 503 | `Schedule2` | list of schedule points | Insolation moon schedule (lights only); same format as 500 ([06](./06-light-schedule.md#moon-schedule-schedule2)) |
-| 504 | `Schedule2Checksum` | — |  |
+| 504 | `Schedule2Checksum` | u16 | CRC16 of the active points. [17](./17-configuration-checksums.md#schedule1checksum-501-schedule2checksum-504) |
 | 505 | `Schedule2StartTime` | — |  |
 | 506 | `Schedule2ActiveDays` | — |  |
 | 507 | `CurrentSchedule` | — |  |

{python_mobius-0.9.0 → python_mobius-0.10.1}/documentation/16-python-library.md

@@ -18,6 +18,7 @@ documents. The README has installation and a quick start.
 | `mobius.device_status`, `mobius.pump_status` | Result dataclasses ([11](./11-device-status-attributes.md)) |
 | `mobius.mob` | `.mob` templates ([15](./15-mob-template-format.md)) |
 | `mobius.dump` | Attribute dumps ([13](./13-attribute-dump.md)) |
+| `mobius.checksums` | Configuration checksums ([17](./17-configuration-checksums.md)) |
 | `mobius.cli` | The `mobius-scan` command |
 
 ## Connecting
@@ -57,8 +58,9 @@ Higher level, by area:
 | Pumps | `get_pump_telemetry()`, `get_pump_flow_range()`, `get_pump_schedule()`, `set_pump_schedule()`, `get_current_pump_block()`, `get_pump_override_mode()`, `get_operation_mode()`, `get_battery_backup_info()`, `set_battery_backup_speed()`, `get_boosted_battery_info()`, `set_boosted_battery()`, `get_vectra_info()`, `get_coffee_info()` |
 | Scenes | `get_configured_scenes()`, `get_current_scene()`, `start_scene()`, `start_feed_mode()`, `resume_schedule()`, `get_operation_state()`, `get_tank_group()` |
 | Settings | `get_advanced_features()`, `set_advanced_features()`, `get_calibration_info()`, `get_maintenance_info()`, `get_group_info()`, `get_fan_thresholds()` |
-| Commands | `set_time_to_now()`, `reboot()`, `reboot_all()` |
+| Commands | `set_time_to_now()`, `set_time_zone()`, `reboot()`, `reboot_all()` |
 | Clock | `get_device_time_info()`, `get_clock_sync_info()` |
+| Checksums | `get_configuration_checksums()` |
 | Mesh | `get_own_mesh_address()`, `discover_networked_thread_devices()`, `discover_mesh_peers()`, `discover_mesh_peers_auto()` |
 | Diagnostics | `get_fsci_diagnostic_info()`, `get_thread_provisioning_info()`, `get_thread_network_state_info()`, `get_scene_diagnostic_info()`, `get_legacy_device_info()`, `get_calibration_extra_info()`, `get_ble_connection_info()`, `get_wifi_remnant_info()`, `get_engineering_diagnostic_info()`, `get_channel_intensities()`, `get_extra_physical_values()` |
 
@@ -88,6 +90,21 @@ Pass `supported_attribute_ids` (read once with
 `get_full_poll_batch()` needs the `PrimitiveType` and `Model` from a first
 `get_device_info()`; after that one request per poll is enough.
 
+Pass a `ConfigurationCache` (one per device, kept between polls) as
+`get_full_poll_batch(cache=...)` to read the scenes and the schedule only
+when their checksum changed
+([17](./17-configuration-checksums.md#polling-with-the-checksums)).
+`configuration_read` on the result lists what was read, and
+`attribute_table_changed` reports a changed `SupportedAttributesCRC`, after
+which the supported attributes should be read again.
+
+Setting the cache's `static_refresh_interval` (seconds) also limits how
+often the attributes that rarely change are read (`STATIC_POLL_ATTRIBUTES`:
+identity, firmware and hardware, color channels, calibration, advanced
+settings, pump flow range and battery settings); in between they come from
+the cache. After writing one of them, call `cache.invalidate_static()`;
+`cache.clear()` makes the next poll read everything.
+
 ## Relaying
 
 ```python
@@ -117,6 +134,9 @@ tank including the gateway itself.
 | `light_schedule_to_mob()`, `mob_to_light_schedule()`, `pump_schedule_to_mob()`, `mob_to_pump_schedule()` | `.mob` templates |
 | `dump_attributes()`, `format_attribute_dump_json()`, `parse_attribute_dump()` | Attribute dumps |
 | `format_mesh_address()` | IPv6 text of a mesh address |
+| `is_bluetooth_only()`, `BLUETOOTH_ONLY_MODELS`, `find_bluetooth_only_tank_members()` | Devices of a tank that aren't on its mesh ([09](./09-thread-coap-relay.md#bluetooth-only-devices)) |
+| `supported_attributes_crc()`, `configured_scenes_checksum()`, `schedule_checksum()` | Configuration checksums computed from the data |
+| `posix_tz_string()` | POSIX TZ string of an Olson time zone name |
 
 ## Command line: `mobius-scan`
 
@@ -138,12 +158,13 @@ With `--by-serial SERIAL` (connects to one device):
 |---|---|
 | `--dump-schedule`, `--dump-scenes` | Print the schedule and the scene slots |
 | `--dump-mesh-peers` | Mesh discovery, step by step |
-| `--relay-target SERIAL` | Reach another device through this one; the options below then act on it |
+| `--relay-target SERIAL` | Reach another device through this one; the options below then act on it. A Bluetooth-only device is connected directly instead ([09](./09-thread-coap-relay.md#bluetooth-only-devices)) |
 | `--debug-relay` | Print every layer of each relayed request |
 | `--set-time-to-now`, `--reboot` | Commands |
 | `--set-local-control-enabled`, `--set-auto-dim-timeout`, `--set-max-fan-speed`, `--set-fan-shutdown-enabled` | Advanced features |
 | `--set-battery-backup-speed`, `--set-boosted-battery-power`, `--set-boosted-battery-on-time`, `--set-boosted-battery-off-time` | Pump battery settings |
 | `--dump-attributes FILE` | Attribute dump (JSON) |
+| `--check-checksums` | Compare the device's configuration checksums with their computation ([17](./17-configuration-checksums.md)) |
 | `--dump-schedule-file FILE` / `--load-schedule-file FILE` | Save / load both schedules as editable JSON |
 | `--dump-mob-file FILE` / `--load-mob-file FILE` (`--mob-template-name`, `--mob-which`) | Save / load a `.mob` template |
 

python_mobius-0.10.1/documentation/17-configuration-checksums.md

@@ -0,0 +1,88 @@
+# Configuration checksums
+
+A device reports 2-byte checksums of parts of its configuration. Reading a
+checksum instead of the data it covers lets a client re-read the data only
+when it changed.
+
+| Attribute | ID | Covers |
+|---|---|---|
+| `SupportedAttributesCRC` | 14 | The supported attribute table ([03](./03-attributes-and-opcodes.md#listing-supported-attributes)) |
+| `ConfiguredScenesChecksum` | 408 | `ConfiguredScenes` (400) |
+| `Schedule1Checksum` | 501 | `Schedule1` (500) |
+| `Schedule2Checksum` | 504 | `Schedule2` (503) |
+
+## SupportedAttributesCRC (14)
+
+The app keeps the supported attribute table of every device and computes
+this checksum over it:
+
+```
+crc16 over, for each attribute in the order the device lists them:
+  id (u16) + number of indexes (u8) + each index (u8)
+```
+
+([CRC16](./02-framing-and-crc.md#crc16), seed 0xFFFF; counts and indexes above
+255 keep only their low byte.) When the device's value differs, the app
+reads the table again, and then every cached feature. The app also reads
+it again after a firmware update. The table is a property of the
+firmware, so the checksum is expected to change only with a firmware
+update. The device's value is the same computation.
+
+## ConfiguredScenesChecksum (408)
+
+```
+crc16 (seed 0xFFFF) over the used slots of ConfiguredScenes (id != 0),
+each slot's bytes as read, in slot order
+```
+
+Changes when a scene is edited in the app.
+
+## Schedule1Checksum (501), Schedule2Checksum (504)
+
+```
+crc16 (seed 0xFFFF) over the active points of Schedule1 / Schedule2
+(flags bit 0 set), each point's bytes as read, in order
+```
+
+`Schedule1Intensity` / `Schedule2Intensity` are not included. A schedule
+with no active points (an unused moon schedule, for example) reports
+0xFFFF, the CRC16 of no data.
+
+All four computations are confirmed on a VorTech MP40 and a Radion XR15
+G6. `mobius --by-serial SERIAL --check-checksums` compares a device's
+values with them.
+
+## Polling with the checksums
+
+To read scenes and a schedule only when they changed:
+
+1. Read the data together with its checksum in one request, and keep
+   both.
+2. On each later poll, read only the checksum (2 bytes). If it equals the
+   kept one, the kept data is current.
+3. If it differs, or can't be read, read the data and its checksum again.
+
+Read each data attribute in a request of its own: a light's schedule or
+scenes are close to the largest reply a relay carries
+([09](./09-thread-coap-relay.md#reply-size)).
+
+The key is the device's own value, so this works without computing
+anything and also catches changes made by other clients (the app, or
+this client's own writes). Include `SupportedAttributesCRC` in the poll: a
+new value means a firmware update, after which the supported attributes
+should be read again.
+
+## What the app does with these
+
+The app reads none of 408, 501 and 504. It keeps scenes and schedules on
+the phone and reads them again only when it has no copy, has unsaved
+changes of its own, or after the attribute table changed; changes made by
+another client are not noticed.
+
+## CRCAttributes (12) and CRCFunction (13)
+
+`CRCAttributes` reads as 32 × 0xFFFF on every device seen. The app has
+code that writes a list of attribute IDs (padded to 32 with 0xFFFF) to
+`CRCAttributes` together with a u16 to `CRCFunction`, which looks like a
+device-side check of a checksum over those attributes, but never calls
+it.

{python_mobius-0.9.0 → python_mobius-0.10.1}/pyproject.toml

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

{python_mobius-0.9.0 → python_mobius-0.10.1}/src/mobius/__init__.py

@@ -9,6 +9,10 @@ documentation/ for the protocol description.
 """
 
 from .crc import crc16, CRC16_TABLE
+from .checksums import (
+    ConfigurationCache, ConfigurationChecksums, configured_scenes_checksum, schedule_checksum,
+    supported_attributes_crc,
+)
 from .frame import (
     build_frame, parse_frame, ParsedFrame,
     encode_get_attribute, encode_get_attributes_batch, encode_set_attribute, decode_attribute_response, AttributeValue,
@@ -22,7 +26,7 @@ from .constants import (
     PrimitiveType, PRIMITIVE_SIZE, LIGHT_PRIMITIVES,
     PUMP_PRIMITIVES_VERIFIED, PUMP_PRIMITIVES_EXPERIMENTAL, PUMP_PRIMITIVES, enum_or_none,
     primitive_type_from_name, support_tier, PumpParamRange, pump_param_range, pump_param_errors,
-    Model, MODEL_MANUFACTURER, manufacturer_for_model,
+    Model, MODEL_MANUFACTURER, manufacturer_for_model, BLUETOOTH_ONLY_MODELS, is_bluetooth_only,
     ErrorState, C2Attribute, OperationMode, PhysicalValueID, VisualID,
     SceneID, OperationState, FsciStatus,
     PumpMode, PumpOverrideMode, RampType, PumpParam, PUMP_PARAM_SIZE, PUMP_MODE_PARAMS,
@@ -68,9 +72,10 @@ from .device import (
 from .discovery import (
     scan_for_mobius_devices, scan_for_mobius_devices_with_info, group_by_pan_id,
     dedupe_by_serial, find_device_by_serial, discover_mesh_peers_via_direct_connect,
-    discover_tank,
+    discover_tank, find_bluetooth_only_tank_members,
 )
 from .frame import SupportedAttribute
+from .timezone import posix_tz_string, TIME_ZONE_FIELD_SIZE
 from .dump import (
     dump_attributes, format_attribute_dump_json, parse_attribute_dump_json,
     format_attribute_dump_text, parse_attribute_dump_text, parse_attribute_dump,
@@ -82,12 +87,13 @@ from .mob import (
     MAX_PUMP_PRIMITIVE_SIZE,
 )
 
-__version__ = "0.9.0"
+__version__ = "0.10.1"
 
 __all__ = [
     "__version__",
     # crc
-    "crc16", "CRC16_TABLE",
+    "crc16", "CRC16_TABLE", "supported_attributes_crc", "configured_scenes_checksum",
+    "schedule_checksum", "ConfigurationChecksums", "ConfigurationCache",
     # frame
     "build_frame", "parse_frame", "ParsedFrame",
     "encode_get_attribute", "encode_get_attributes_batch", "encode_set_attribute", "decode_attribute_response", "AttributeValue",
@@ -100,7 +106,7 @@ __all__ = [
     "PrimitiveType", "PRIMITIVE_SIZE", "LIGHT_PRIMITIVES",
     "PUMP_PRIMITIVES_VERIFIED", "PUMP_PRIMITIVES_EXPERIMENTAL", "PUMP_PRIMITIVES", "enum_or_none",
     "primitive_type_from_name", "support_tier", "PumpParamRange", "pump_param_range", "pump_param_errors",
-    "Model", "MODEL_MANUFACTURER", "manufacturer_for_model",
+    "Model", "MODEL_MANUFACTURER", "BLUETOOTH_ONLY_MODELS", "is_bluetooth_only", "manufacturer_for_model",
     "ErrorState", "C2Attribute", "OperationMode", "PhysicalValueID", "VisualID",
     "SceneID", "OperationState", "FsciStatus",
     "PumpMode", "PumpOverrideMode", "RampType", "PumpParam", "PUMP_PARAM_SIZE", "PUMP_MODE_PARAMS",
@@ -134,7 +140,7 @@ __all__ = [
     "next_coap_token",
     "mesh_local_prefix_from_own_address", "mesh_local_prefix_from_mlprefix", "is_valid_mesh_address",
     "build_rloc_address", "extract_short_address", "is_short_address_derived",
-    "format_mesh_address",
+    "format_mesh_address", "posix_tz_string", "TIME_ZONE_FIELD_SIZE",
     "RelayedMobiusDevice",
     # device
     "MobiusDevice", "MobiusPump", "LightIntensityResult", "LightPollResult", "FullPollResult",
@@ -143,7 +149,7 @@ __all__ = [
     # discovery
     "scan_for_mobius_devices", "scan_for_mobius_devices_with_info", "group_by_pan_id",
     "dedupe_by_serial", "find_device_by_serial", "discover_mesh_peers_via_direct_connect",
-    "discover_tank",
+    "find_bluetooth_only_tank_members", "discover_tank",
     "SupportedAttribute", "dump_attributes", "enrich_attribute_dump", "generic_interpretations",
     "format_attribute_dump_json", "parse_attribute_dump_json",
     "format_attribute_dump_text", "parse_attribute_dump_text", "parse_attribute_dump",

python_mobius-0.10.1/src/mobius/checksums.py

@@ -0,0 +1,119 @@
+"""Checksums a device reports about its own configuration, and how to
+compute them. Reading a 2-byte checksum instead of the data it covers lets
+a client skip re-reading data that hasn't changed.
+
+| Attribute | ID | Covers |
+|---|---|---|
+| `SupportedAttributesCRC` | 14 | The supported attribute table (see supported_attributes_crc()) |
+| `ConfiguredScenesChecksum` | 408 | ConfiguredScenes (400) |
+| `Schedule1Checksum` | 501 | Schedule1 (500) |
+| `Schedule2Checksum` | 504 | Schedule2 (503) |
+
+All four are CRC16 with seed 0xFFFF (see the functions below for what each
+covers), confirmed on a VorTech MP40 and a Radion XR15 G6. The app
+computes SupportedAttributesCRC itself and compares it with the device's
+value to decide whether to read the attribute table again; the other
+three it doesn't read.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass, field
+from typing import Iterable, Optional
+
+from .crc import crc16
+from .frame import AttributeValue, SupportedAttribute
+
+
+def supported_attributes_crc(supported: Iterable[SupportedAttribute]) -> int:
+    """
+    The app's checksum of a supported attribute table, for comparison with
+    SupportedAttributesCRC (14): crc16 over, for each attribute in the
+    order the device lists them, the id (u16 LE), the number of indexes
+    (u8) and each index (u8). Counts and indexes above 255 are truncated
+    to their low byte, as the app does.
+    """
+    data = bytearray()
+    for attribute in supported:
+        data += struct.pack("<H", attribute.attr_id)
+        data.append(len(attribute.indexes) & 0xFF)
+        data.extend(index & 0xFF for index in attribute.indexes)
+    return crc16(bytes(data))
+
+
+def configured_scenes_checksum(slots: Iterable[bytes]) -> int:
+    """ConfiguredScenesChecksum (408) of ConfiguredScenes (400) slots as
+    read: crc16 over the used slots (scene id != 0) in slot order."""
+    return crc16(b"".join(slot for slot in slots if len(slot) >= 2 and struct.unpack_from("<H", slot)[0] != 0))
+
+
+def schedule_checksum(points: Iterable[bytes]) -> int:
+    """Schedule1Checksum (501) / Schedule2Checksum (504) of Schedule1 (500) /
+    Schedule2 (503) points as read: crc16 over the active points (flags
+    bit 0 set) in order. Schedule1Intensity/Schedule2Intensity are not
+    included."""
+    return crc16(b"".join(point for point in points if len(point) >= 3 and point[2] & 0x01))
+
+
+@dataclass(frozen=True)
+class ConfigurationChecksums:
+    """The checksums a device reports; None when not supported or not
+    readable."""
+    supported_attributes: Optional[int] = None
+    configured_scenes: Optional[int] = None
+    schedule1: Optional[int] = None
+    schedule2: Optional[int] = None
+
+
+@dataclass
+class ConfigurationCache:
+    """
+    Data of one device kept between get_full_poll_batch(cache=...) calls
+    so a poll reads the 2-byte checksums instead of the data they cover.
+
+    entries: {data attribute id: (checksum, response blocks)} for
+      ConfiguredScenes and the polled schedule, each with the checksum the
+      device reported in the same request. A poll whose checksum differs
+      (or can't be read) reads the data again. The device's own value is
+      the key, so no local computation is involved, and a change by any
+      client, this one included, shows up as a changed checksum.
+    supported_attributes_crc: SupportedAttributesCRC from the last poll.
+      When it changes (a firmware update), the poll result says so
+      (FullPollResult.attribute_table_changed) and the static attributes
+      are read again on the next poll. `entries` stay valid: each is still
+      checked against its own checksum.
+    static / static_read_at / static_refresh_interval: attributes that
+      rarely change (identity, firmware and hardware, color channels,
+      calibration, advanced settings, pump flow range and battery settings;
+      STATIC_POLL_ATTRIBUTES in device.py), read at most every
+      `static_refresh_interval` seconds and kept here in between. None (the
+      default) reads them on every poll. A client that writes one of them
+      calls invalidate_static() so the next poll reads them again.
+
+    One per device.
+    """
+    entries: dict[int, tuple[int, list[AttributeValue]]] = field(default_factory=dict)
+    supported_attributes_crc: Optional[int] = None
+    static: dict[int, list[AttributeValue]] = field(default_factory=dict)
+    static_read_at: Optional[float] = None
+    static_refresh_interval: Optional[float] = None
+
+    def static_due(self, now: float) -> bool:
+        """Whether the static attributes are to be read by a poll at
+        `now` (time.monotonic())."""
+        return (
+            self.static_refresh_interval is None or self.static_read_at is None
+            or now - self.static_read_at >= self.static_refresh_interval
+        )
+
+    def invalidate_static(self) -> None:
+        """Makes the next poll read the static attributes."""
+        self.static.clear()
+        self.static_read_at = None
+
+    def clear(self) -> None:
+        """Forgets everything: the next poll reads all data."""
+        self.entries.clear()
+        self.supported_attributes_crc = None
+        self.invalidate_static()