python-mobius 0.9.0__py3-none-any.whl → 0.10.1__py3-none-any.whl

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",

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

mobius/cli.py

@@ -11,11 +11,13 @@ from __future__ import annotations
 
 import argparse
 import asyncio
+import contextlib
 import json
 import struct
 from typing import Optional
 
-from .device import MobiusDevice, min_schedule_capacity
+from .checksums import configured_scenes_checksum, schedule_checksum, supported_attributes_crc
+from .device import ALL_ELEMENTS, MobiusDevice, min_schedule_capacity
 from .relay import RelayedMobiusDevice
 from .device_status import MeshPeer
 from .mesh_address import (
@@ -29,6 +31,7 @@ from .constants import (
 from .discovery import (
     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,
 )
 from .schedule import (
     SchedulePoint, light_schedule_to_dict, light_schedule_from_dict,
@@ -232,19 +235,24 @@ async def _load_schedule_from_mob_file(device: MobiusDevice, support: str, path:
 
 async def _resolve_group_targets(
     gateway: MobiusDevice, target_serial: str, target_device, target_group_mask,
-    support: str, debug_relay: bool,
+    support: str, debug_relay: bool, pan_id: Optional[int] = None,
+    stack: Optional[contextlib.AsyncExitStack] = None, args=None,
 ) -> list[tuple[str, object]]:
     """
     Every device a schedule write to `target_device` should reach: the
-    target itself and, for a light with a group_mask, every other light on
-    `gateway`'s mesh with exactly the same group_mask (reached through
-    RelayedMobiusDevice(gateway, peer)). See
+    target itself and, for a light with a group_mask, every other light of
+    the tank with exactly the same group_mask. See
     documentation/06-light-schedule.md, "Schedule groups". A light without
     a group_mask, or a pump, only returns the target.
 
+    Lights on `gateway`'s mesh are reached through
+    RelayedMobiusDevice(gateway, peer); Bluetooth-only lights advertising
+    `pan_id` (find_bluetooth_only_tank_members()) through their own
+    connection, kept open on `stack` (both needed for them to be included).
+
     `gateway` is the directly connected device, also when `target_device`
-    is itself relayed. Peers that can't be read through the relay are
-    skipped with a warning.
+    is itself relayed. Devices that can't be read are skipped with a
+    warning.
     """
     targets = [(target_serial, target_device)]
     if support != "light" or target_group_mask is None:
@@ -253,10 +261,10 @@ async def _resolve_group_targets(
     try:
         tank = await discover_tank(gateway)
     except Exception as e:
-        print(f"  Could not discover tank mesh peers ({e}) -- writing only to {target_serial!r}.")
-        return targets
+        print(f"  Could not discover tank mesh peers ({e}) -- only Bluetooth-only lights will be added.")
+        tank = None
 
-    for peer in tank.peers:
+    for peer in (tank.peers if tank is not None else []):
         if peer.serial == target_serial:
             continue
         relayed = RelayedMobiusDevice(gateway, peer, debug=debug_relay)
@@ -270,9 +278,51 @@ async def _resolve_group_targets(
         if peer_info.get("group_mask") == target_group_mask:
             targets.append((peer.serial, relayed))
 
+    if pan_id is not None and stack is not None:
+        targets += await _bluetooth_only_group_targets(
+            pan_id, target_group_mask, {serial for serial, _device in targets}, stack, args,
+        )
+    return targets
+
+
+async def _bluetooth_only_group_targets(
+    pan_id: int, group_mask: int, exclude: set[str], stack: contextlib.AsyncExitStack, args,
+) -> list[tuple[str, MobiusDevice]]:
+    """Bluetooth-only lights of the tank with `group_mask`, each connected
+    directly and kept open on `stack`."""
+    targets = []
+    adapter = getattr(args, "adapter", None)
+    for ble_device, info in await find_bluetooth_only_tank_members(
+        pan_id, timeout=getattr(args, "timeout", 10.0), adapter=adapter,
+    ):
+        if info.serial in exclude:
+            continue
+        member = MobiusDevice(
+            ble_device, serial=info.serial, adapter=adapter,
+            connect_timeout=getattr(args, "connect_timeout", 30.0),
+        )
+        try:
+            await member.connect()
+            member_info = await member.get_device_info()
+        except Exception as e:
+            print(f"  {info.serial!r} (Bluetooth-only): could not connect directly ({e}) -- skipped.")
+            await _disconnect_quietly(member)
+            continue
+        if member_info.get("primitive_type") == "VisualV1" and member_info.get("group_mask") == group_mask:
+            stack.push_async_callback(_disconnect_quietly, member)
+            targets.append((info.serial, member))
+        else:
+            await _disconnect_quietly(member)
     return targets
 
 
+async def _disconnect_quietly(device: MobiusDevice) -> None:
+    try:
+        await device.disconnect()
+    except Exception:
+        pass
+
+
 async def _min_group_capacity(group_targets: list[tuple[str, MobiusDevice]], which: int) -> Optional[int]:
     """min_schedule_capacity() of the devices in `group_targets`."""
     return await min_schedule_capacity([device for _serial, device in group_targets], which)
@@ -300,6 +350,46 @@ async def _dump_scenes(device: MobiusDevice, primitive: PrimitiveType | None) ->
               f"timeout={scene.timeout}s: {payload}")
 
 
+def _print_checksum(label: str, reported: Optional[int], computed: int, covering: str) -> None:
+    reported_text = f"0x{reported:04X}" if reported is not None else "not readable"
+    verdict = "match" if reported == computed else "MISMATCH"
+    print(f"  {label}: reported {reported_text}, computed 0x{computed:04X} from {covering} -- {verdict}")
+
+
+async def _check_checksums(target) -> None:
+    """
+    Reads the configuration checksums (see checksums.py) and the data each
+    covers, and prints whether the device's value matches the computation.
+    """
+    supported = await target.get_supported_attributes()
+    supported_ids = {a.attr_id for a in supported}
+    checksums = await target.get_configuration_checksums()
+
+    _print_checksum(
+        "SupportedAttributesCRC (14)", checksums.supported_attributes,
+        supported_attributes_crc(supported), f"the {len(supported)} supported attributes",
+    )
+    sections = (
+        ("ConfiguredScenesChecksum (408)", checksums.configured_scenes, C2Attribute.ConfiguredScenes),
+        ("Schedule1Checksum (501)", checksums.schedule1, C2Attribute.Schedule1),
+        ("Schedule2Checksum (504)", checksums.schedule2, C2Attribute.Schedule2),
+    )
+    for label, reported, data_attr in sections:
+        if data_attr not in supported_ids:
+            print(f"  {label}: not supported by this device")
+            continue
+        values = await target.get_attribute_all(data_attr, 0, ALL_ELEMENTS)
+        if data_attr == C2Attribute.ConfiguredScenes:
+            computed = configured_scenes_checksum(values)
+            used = sum(1 for v in values if len(v) >= 2 and struct.unpack_from("<H", v)[0] != 0)
+            covering = f"the {used} used of {len(values)} slots"
+        else:
+            computed = schedule_checksum(values)
+            active = sum(1 for v in values if len(v) >= 3 and v[2] & 0x01)
+            covering = f"the {active} active of {len(values)} points"
+        _print_checksum(label, reported, computed, covering)
+
+
 async def _debug_mesh_discovery(device) -> list:
     """
     Step-by-step version of discover_mesh_peers_auto() that prints every
@@ -433,12 +523,9 @@ async def _print_summary(mdevice: MobiusDevice, args) -> dict:
     return summary
 
 
-async def _learn_peer_directly(args) -> Optional[MeshPeer]:
-    """Connects briefly to --relay-target to read its own mesh address."""
-    found_target = await find_device_by_serial(args.relay_target, timeout=args.timeout, adapter=args.adapter)
-    if found_target is None:
-        print(f"  No device currently advertising serial {args.relay_target!r} found.")
-        return None
+async def _learn_peer_directly(args, found_target) -> Optional[MeshPeer]:
+    """Connects briefly to --relay-target (`found_target`, from
+    find_device_by_serial()) to read its own mesh address."""
     target_device, target_info = found_target
     target_address = None
     try:
@@ -460,7 +547,8 @@ async def _learn_peer_directly(args) -> Optional[MeshPeer]:
 
 
 async def _write_to_group(mdevice, args, target, label: str, serial: str, summary: dict,
-                          point_counts: dict, title: str, write) -> None:
+                          point_counts: dict, title: str, write, pan_id: Optional[int] = None,
+                          stack: Optional[contextlib.AsyncExitStack] = None) -> None:
     """
     Writes to `target` and every light sharing its schedule group
     (_resolve_group_targets()). `point_counts` maps a schedule slot to the
@@ -482,6 +570,7 @@ async def _write_to_group(mdevice, args, target, label: str, serial: str, summar
     print(f"\n=== resolving schedule-group targets for {label} ===")
     group_targets = await _resolve_group_targets(
         mdevice, serial, target, target_group_mask, target_support, args.debug_relay,
+        pan_id=pan_id, stack=stack, args=args,
     )
     if len(group_targets) > 1:
         print(f"  Writing to {len(group_targets)} device(s) sharing this light's "
@@ -523,7 +612,8 @@ async def _run_by_serial(args) -> None:
     try:
         # Passing the BLEDevice just found avoids a second scan in connect().
         async with MobiusDevice(device=device, serial=args.by_serial, adapter=args.adapter,
-                                connect_timeout=args.connect_timeout) as mdevice:
+                                connect_timeout=args.connect_timeout) as mdevice, \
+                contextlib.AsyncExitStack() as stack:
             summary = await _print_summary(mdevice, args)
 
             peers = []
@@ -533,13 +623,35 @@ async def _run_by_serial(args) -> None:
                 peers = await _debug_mesh_discovery(mdevice)
                 _print_mesh_peers_or_hint(peers)
 
+            relay_is_direct = False
             if args.relay_target:
                 print(f"\n=== Relaying to {args.relay_target!r} through {args.by_serial!r} ===")
                 target_peer = next((p for p in peers if p.serial == args.relay_target), None)
+                found_target = None
                 if target_peer is None:
+                    found_target = await find_device_by_serial(
+                        args.relay_target, timeout=args.timeout, adapter=args.adapter,
+                    )
+                    if found_target is None:
+                        print(f"  No device currently advertising serial {args.relay_target!r} found.")
+                if found_target is not None and found_target[1] is not None and found_target[1].bluetooth_only:
+                    print(f"  {args.relay_target!r} is a Bluetooth-only device (not on the Thread "
+                          f"mesh) -- connecting to it directly instead.")
+                    try:
+                        relayed = await stack.enter_async_context(MobiusDevice(
+                            found_target[0], serial=args.relay_target, adapter=args.adapter,
+                            connect_timeout=args.connect_timeout,
+                        ))
+                        relay_is_direct = True
+                        for k, v in (await relayed.get_device_summary()).items():
+                            print(f"  {k}: {v}")
+                    except Exception as e:
+                        relayed = None
+                        print(f"  direct connection failed: {e}")
+                elif target_peer is None and found_target is not None:
                     print(f"  Not reported by {args.by_serial!r}'s mesh peer list -- trying a "
                           f"brief direct connection to {args.relay_target!r} to learn its address...")
-                    target_peer = await _learn_peer_directly(args)
+                    target_peer = await _learn_peer_directly(args, found_target)
                 if target_peer is not None:
                     relayed = RelayedMobiusDevice(mdevice, target_peer, debug=args.debug_relay)
                     try:
@@ -561,6 +673,8 @@ async def _run_by_serial(args) -> None:
                     print(f"\n=== {action} on {args.relay_target!r} (via relay) -- "
                           f"SKIPPED: relay target could not be resolved above ===")
                     return None
+                if relay_is_direct:
+                    return f"{args.relay_target!r} (direct, Bluetooth-only)", relayed, args.relay_target
                 return f"{args.relay_target!r} (via relay through {args.by_serial!r})", relayed, args.relay_target
 
             async def target_support(target, serial: str) -> str:
@@ -590,6 +704,14 @@ async def _run_by_serial(args) -> None:
                 except Exception as e:
                     print(f"  set_time_to_now() FAILED: {e}")
 
+            if args.check_checksums and (picked := pick_target("checksum check")):
+                label, target, _serial = picked
+                print(f"\n=== Configuration checksums on {label} ===")
+                try:
+                    await _check_checksums(target)
+                except Exception as e:
+                    print(f"  checksum check FAILED: {e}")
+
             if args.dump_attributes and (picked := pick_target("dump_attributes()")):
                 label, target, _serial = picked
                 print(f"\n=== dump_attributes() on {label} -- writing to {args.dump_attributes!r} ===")
@@ -624,6 +746,7 @@ async def _run_by_serial(args) -> None:
                     lambda dev, support, member_serial: _load_schedule_from_file(
                         dev, support, member_serial, args.load_schedule_file,
                     ),
+                    pan_id=info.pan_id if info else None, stack=stack,
                 )
 
             if args.dump_mob_file and (picked := pick_target("mob dump")):
@@ -657,6 +780,7 @@ async def _run_by_serial(args) -> None:
                     lambda dev, support, _member_serial: _load_schedule_from_mob_file(
                         dev, support, args.load_mob_file, which=args.mob_which,
                     ),
+                    pan_id=info.pan_id if info else None, stack=stack,
                 )
 
             requested_features = {}
@@ -885,6 +1009,11 @@ def main() -> None:
                               "(serial/model/short address/IPv6). Useful when neither "
                               "--dump-mesh-peers mechanism is supported. See "
                               "documentation/09-thread-coap-relay.md.")
+    parser.add_argument("--check-checksums", action="store_true",
+                        help="With --by-serial: read SupportedAttributesCRC, "
+                             "ConfiguredScenesChecksum and Schedule1/2Checksum and the data "
+                             "each covers, and print whether each matches its computation "
+                             "(on --relay-target if given). Read-only.")
     parser.add_argument("--dump-attributes", default=None, metavar="FILE",
                          help="Only usable with --by-serial. Discovers every attribute the "
                               "target device reports supporting -- the relay target if "

mobius/constants.py

@@ -304,6 +304,25 @@ def manufacturer_for_model(model: Optional[Model]) -> Optional[str]:
     return MODEL_MANUFACTURER.get(model)
 
 
+# Models that are not on the tank's Thread mesh: they share the tank's
+# pan_id in their advertisement but have no mesh address, so they can't be
+# reached through a gateway (see documentation/09-thread-coap-relay.md,
+# "Bluetooth-only devices"). The app keeps the same list.
+BLUETOOTH_ONLY_MODELS = frozenset({
+    Model.Blade, Model.BladeD, Model.BladeCoralGlow, Model.BladeCoralGrow, Model.BladeFreshwater,
+    Model.BladeRefugium, Model.BladeGrowPlus, Model.BladeGloFish, Model.MXM,
+})
+
+
+def is_bluetooth_only(model: "Model | int | None") -> bool:
+    """Whether `model` (a Model or its raw value) is reached only over its
+    own Bluetooth connection, never through a gateway. False for None or
+    an unknown value."""
+    if model is None:
+        return False
+    return enum_or_none(Model, int(model)) in BLUETOOTH_ONLY_MODELS
+
+
 class ErrorState(IntEnum):
     """Device error states (pump and light fault codes; dosing-pump-specific
     codes are not included).