python-mobius 0.8.4__py3-none-any.whl → 0.10.0__py3-none-any.whl

mobius/__init__.py

@@ -1,16 +1,18 @@
 """
 python-mobius: a reverse-engineered Python client for the BLE protocol used
 by EcoTech Marine (VorTech, Radion), AquaIllumination (Prime, Hydra),
-Neptune Systems, and NYOS "Mobius"-branded aquarium devices.
+Neptune Systems and NYOS "Mobius" aquarium devices.
 
 Not affiliated with or endorsed by any of those companies. This is an
-independent reimplementation of the wire protocol for interoperability,
-derived from public community reverse-engineering work and analysis of the
-publicly-distributed Mobius Android app. See documentation/ for the full
-protocol writeup and confirmation evidence for every field.
+independent implementation of the wire protocol for interoperability. See
+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,9 +24,10 @@ from .frame import (
 )
 from .constants import (
     PrimitiveType, PRIMITIVE_SIZE, LIGHT_PRIMITIVES,
-    PUMP_PRIMITIVES_VERIFIED, PUMP_PRIMITIVES_EXPERIMENTAL,
-    Model, MODEL_MANUFACTURER, manufacturer_for_model,
-    ErrorState, C2Attribute, PhysicalValueID, VisualID,
+    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, BLUETOOTH_ONLY_MODELS, is_bluetooth_only,
+    ErrorState, C2Attribute, OperationMode, PhysicalValueID, VisualID,
     SceneID, OperationState, FsciStatus,
     PumpMode, PumpOverrideMode, RampType, PumpParam, PUMP_PARAM_SIZE, PUMP_MODE_PARAMS,
     supported_pump_modes,
@@ -37,11 +40,11 @@ from .schedule import (
     LightPrimitive, SchedulePoint, interpolate_light_schedule,
     PumpPrimitiveValue, PumpSchedulePoint, get_active_pump_block,
     light_schedule_to_dict, light_schedule_from_dict,
-    pump_schedule_to_dict, pump_schedule_from_dict,
+    pump_schedule_to_dict, pump_schedule_from_dict, pump_params_to_dict,
     MAX_PUMP_SCHEDULE_POINT_SIZE,
 )
 from .scenes import Scene, ActiveScene, decode_configured_scenes, decode_active_scene
-from .manufacturer import MOBIUS_COMPANY_ID_ECOTECH, MOBIUS_COMPANY_ID_AQUAILLUMINATION, MOBIUS_COMPANY_IDS, MobiusAdvertisement, parse_manufacturer_data
+from .manufacturer import MOBIUS_COMPANY_ID_ECOTECH, MOBIUS_COMPANY_ID_AQUAILLUMINATION, MOBIUS_COMPANY_IDS, MobiusAdvertisement, parse_manufacturer_data, parse_advertisement
 from .modifiers import (
     AcclimationInfo, is_night_segment,
     julian_day_from_date, lunar_days_into_phase, lunar_percent_reduction,
@@ -58,19 +61,21 @@ from .coap import (
 from .mesh_address import (
     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,
+    is_short_address_derived, format_mesh_address,
 )
 from .relay import RelayedMobiusDevice
 from .device import (
     MobiusDevice, MobiusPump, LightIntensityResult, LightPollResult, FullPollResult,
+    schedule_capacity, min_schedule_capacity, tank_group,
     SERVICE_GENERAL, CHAR_RX_DATA, CHAR_RX_FINAL, CHAR_TX_DATA, CHAR_TX_FINAL,
 )
 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.8.4"
+__version__ = "0.10.0"
 
 __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",
@@ -98,9 +104,10 @@ __all__ = [
     "OPCODE_GET_ATTR_ELEMENTS", "OPCODE_GET_ATTR_ELEMENTS_EXT", "OPCODE_GET_OPCODES",
     # constants
     "PrimitiveType", "PRIMITIVE_SIZE", "LIGHT_PRIMITIVES",
-    "PUMP_PRIMITIVES_VERIFIED", "PUMP_PRIMITIVES_EXPERIMENTAL",
-    "Model", "MODEL_MANUFACTURER", "manufacturer_for_model",
-    "ErrorState", "C2Attribute", "PhysicalValueID", "VisualID",
+    "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", "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",
     "supported_pump_modes",
@@ -112,12 +119,12 @@ __all__ = [
     "LightPrimitive", "SchedulePoint", "interpolate_light_schedule",
     "PumpPrimitiveValue", "PumpSchedulePoint", "get_active_pump_block",
     "light_schedule_to_dict", "light_schedule_from_dict",
-    "pump_schedule_to_dict", "pump_schedule_from_dict",
+    "pump_schedule_to_dict", "pump_schedule_from_dict", "pump_params_to_dict",
     "MAX_PUMP_SCHEDULE_POINT_SIZE",
     # scenes
     "Scene", "ActiveScene", "decode_configured_scenes", "decode_active_scene",
     # manufacturer
-    "MOBIUS_COMPANY_ID_ECOTECH", "MOBIUS_COMPANY_ID_AQUAILLUMINATION", "MOBIUS_COMPANY_IDS", "MobiusAdvertisement", "parse_manufacturer_data",
+    "MOBIUS_COMPANY_ID_ECOTECH", "MOBIUS_COMPANY_ID_AQUAILLUMINATION", "MOBIUS_COMPANY_IDS", "MobiusAdvertisement", "parse_manufacturer_data", "parse_advertisement",
     # modifiers
     "AcclimationInfo", "is_night_segment",
     "julian_day_from_date", "lunar_days_into_phase", "lunar_percent_reduction",
@@ -133,14 +140,16 @@ __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", "posix_tz_string", "TIME_ZONE_FIELD_SIZE",
     "RelayedMobiusDevice",
     # device
     "MobiusDevice", "MobiusPump", "LightIntensityResult", "LightPollResult", "FullPollResult",
+    "schedule_capacity", "min_schedule_capacity", "tank_group",
     "SERVICE_GENERAL", "CHAR_RX_DATA", "CHAR_RX_FINAL", "CHAR_TX_DATA", "CHAR_TX_FINAL",
     # 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",

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()