python-mobius 0.1.0__py3-none-any.whl

mobius/device.py

@@ -0,0 +1,429 @@
+"""
+High-level async client for a single Mobius BLE device (pump, light, or
+anything else sharing the protocol).
+
+Uses `bleak` for BLE, and `bleak-retry-connector` if installed (recommended
+-- same connection-retry approach Home Assistant's own Bluetooth integration
+uses; falls back to a manual retry loop otherwise).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import struct
+from typing import Optional
+
+from bleak import BleakClient, BleakScanner
+from bleak.backends.device import BLEDevice
+
+try:
+    from bleak_retry_connector import establish_connection
+    _HAVE_RETRY_CONNECTOR = True
+except ImportError:
+    _HAVE_RETRY_CONNECTOR = False
+
+from .frame import (
+    build_frame, parse_frame, ParsedFrame,
+    encode_get_attribute, encode_set_attribute, decode_attribute_response,
+    OPGROUP_C2CI_REQUEST, OPCODE_GET_ATTR, OPCODE_SET_ATTR, next_message_id,
+)
+from .constants import (
+    C2Attribute, PrimitiveType, Model, ErrorState, SceneID, OperationState,
+    FsciStatus, PhysicalValueID, VisualID,
+    PRIMITIVE_SIZE, LIGHT_PRIMITIVES, PUMP_PRIMITIVES_VERIFIED, PUMP_PRIMITIVES_EXPERIMENTAL,
+)
+from .schedule import (
+    SchedulePoint, interpolate_light_schedule,
+    PumpSchedulePoint, get_active_pump_block,
+)
+
+# --------------------------------------------------------------------------
+# GATT UUIDs (service 01ff0100-...; four characteristics under it)
+# --------------------------------------------------------------------------
+
+SERVICE_GENERAL = "01ff0100-ba5e-f4ee-5ca1-eb1e5e4b1ce0"
+CHAR_RX_DATA = "01ff0101-ba5e-f4ee-5ca1-eb1e5e4b1ce0"   # notify: device -> app, fragment
+CHAR_RX_FINAL = "01ff0102-ba5e-f4ee-5ca1-eb1e5e4b1ce0"  # notify: device -> app, last fragment
+CHAR_TX_DATA = "01ff0103-ba5e-f4ee-5ca1-eb1e5e4b1ce0"   # write: app -> device, fragment
+CHAR_TX_FINAL = "01ff0104-ba5e-f4ee-5ca1-eb1e5e4b1ce0"  # write: app -> device, last fragment
+
+
+class MobiusDevice:
+    """
+    High-level async client for a single Mobius-protocol BLE device.
+
+    Usage:
+        found = await scan_for_mobius_devices()
+        async with MobiusDevice(found[0]) as device:
+            summary = await device.get_device_summary()
+    """
+
+    def __init__(self, device: "str | BLEDevice", mtu: int = 20, connect_timeout: float = 30.0,
+                 adapter: Optional[str] = None):
+        # Accepting a BLEDevice (from an existing scan) avoids a second,
+        # independent discovery pass in connect() -- re-scanning per device
+        # can cause BlueZ to drop the device between "found" and "connect"
+        # ("device disappeared" errors), especially when connecting to
+        # several devices back-to-back.
+        #
+        # adapter: only relevant for the fallback path in connect() (bare
+        # address, no pre-scanned BLEDevice). If you already have a
+        # BLEDevice from scan_for_mobius_devices(adapter=...), that device
+        # remembers which adapter it was seen on and this argument is ignored.
+        self._device_or_address = device
+        self.address = device.address if isinstance(device, BLEDevice) else device
+        self.mtu = mtu  # conservative default; bleak/OS negotiates the real MTU
+        self.connect_timeout = connect_timeout
+        self.adapter = adapter
+        self._client: Optional[BleakClient] = None
+        self._rx_buffer = bytearray()
+        self._pending: dict[int, asyncio.Future] = {}
+
+    async def __aenter__(self) -> "MobiusDevice":
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *exc):
+        await self.disconnect()
+
+    async def connect(self):
+        if _HAVE_RETRY_CONNECTOR:
+            if isinstance(self._device_or_address, BLEDevice):
+                device = self._device_or_address
+            else:
+                # Fallback: only re-scan if we were only ever given a bare
+                # address (e.g. a hardcoded MAC from a previous identify pass).
+                find_kwargs = {"timeout": 10.0}
+                if self.adapter is not None:
+                    find_kwargs["bluez"] = {"adapter": self.adapter}
+                device = await BleakScanner.find_device_by_address(self.address, **find_kwargs)
+                if device is None:
+                    raise IOError(f"could not find BLE device {self.address} while scanning")
+            self._client = await establish_connection(
+                BleakClient, device, "mobius-device", timeout=self.connect_timeout
+            )
+        else:
+            self._client = BleakClient(self.address, timeout=self.connect_timeout)
+            for attempt in range(3):
+                try:
+                    await self._client.connect()
+                    break
+                except Exception:
+                    if attempt == 2:
+                        raise
+                    await asyncio.sleep(2.0)
+        await self._client.start_notify(CHAR_RX_DATA, self._on_rx_data)
+        await self._client.start_notify(CHAR_RX_FINAL, self._on_rx_final)
+
+    async def disconnect(self):
+        if self._client and self._client.is_connected:
+            await self._client.disconnect()
+
+    def _on_rx_data(self, _handle, data: bytearray):
+        self._rx_buffer.extend(data)
+
+    def _on_rx_final(self, _handle, data: bytearray):
+        self._rx_buffer.extend(data)
+        raw = bytes(self._rx_buffer)
+        self._rx_buffer.clear()
+        frame = parse_frame(raw)
+        if frame is None:
+            return
+        fut = self._pending.pop(frame.message_id, None)
+        if fut and not fut.done():
+            fut.set_result(frame)
+
+    async def _send_frame(self, frame: bytes, message_id: int,
+                           wait_response: bool = True, timeout: float = 5.0) -> Optional[ParsedFrame]:
+        assert self._client is not None
+        fut: asyncio.Future = asyncio.get_event_loop().create_future()
+        if wait_response:
+            self._pending[message_id] = fut
+
+        # Fragment to MTU; last chunk goes to *_FINAL and triggers processing device-side.
+        chunks = [frame[i:i + self.mtu] for i in range(0, len(frame), self.mtu)] or [b""]
+        for chunk in chunks[:-1]:
+            await self._client.write_gatt_char(CHAR_TX_DATA, chunk, response=False)
+        await self._client.write_gatt_char(CHAR_TX_FINAL, chunks[-1], response=False)
+
+        if not wait_response:
+            return None
+        try:
+            return await asyncio.wait_for(fut, timeout=timeout)
+        finally:
+            self._pending.pop(message_id, None)
+
+    async def get_attribute(self, attr_id: int, index: int = 0, count: int = 1) -> list[bytes]:
+        message_id = next_message_id()
+        payload = encode_get_attribute(attr_id, index, count, extended=False)
+        frame = build_frame(OPGROUP_C2CI_REQUEST, OPCODE_GET_ATTR, payload, message_id)
+        resp = await self._send_frame(frame, message_id)
+        if resp is None or not resp.crc_ok:
+            raise IOError("no/invalid response from device")
+        status = resp.data[0] if resp.data else FsciStatus.Failed
+        if status != FsciStatus.Success:
+            raise IOError(f"device returned FSCI status {status!r} for attribute {attr_id}")
+        attrs = decode_attribute_response(resp.data, extended=False)
+        for a in attrs:
+            if a.attr_id == attr_id:
+                return a.values
+        return []
+
+    async def set_attribute(self, attr_id: int, value: bytes, index: int = 0) -> None:
+        message_id = next_message_id()
+        payload = encode_set_attribute(attr_id, [value], index, extended=False)
+        frame = build_frame(OPGROUP_C2CI_REQUEST, OPCODE_SET_ATTR, payload, message_id)
+        resp = await self._send_frame(frame, message_id)
+        if resp is None or not resp.crc_ok:
+            raise IOError("no/invalid response from device")
+        status = resp.data[0] if resp.data else FsciStatus.Failed
+        if status != FsciStatus.Success:
+            raise IOError(f"device returned FSCI status {status!r} setting attribute {attr_id}")
+
+    # ---- scenes -----------------------------------------------------------
+
+    async def start_scene(self, scene_id: SceneID, duration_minutes: int = 0) -> None:
+        """duration_minutes=0 lets the device use the scene's own configured duration."""
+        value = struct.pack("<HH", int(scene_id), duration_minutes)
+        await self.set_attribute(C2Attribute.CurrentScene, value)
+
+    async def start_feed_mode(self, duration_minutes: int = 0) -> None:
+        await self.start_scene(SceneID.FeedMode, duration_minutes)
+
+    async def resume_schedule(self) -> None:
+        """Cancel whatever scene is running and go back to the normal schedule."""
+        await self.set_attribute(C2Attribute.OperationState, bytes([OperationState.Schedule]))
+
+    async def get_current_scene(self) -> tuple[SceneID, int]:
+        raw = await self.get_attribute(C2Attribute.CurrentScene)
+        scene_id, duration = struct.unpack("<HH", raw[0])
+        return SceneID(scene_id), duration
+
+    async def get_operation_state(self) -> OperationState:
+        raw = await self.get_attribute(C2Attribute.OperationState)
+        return OperationState(raw[0][0])
+
+    async def identify_device_type(self) -> PrimitiveType:
+        """
+        All Mobius-protocol devices (pumps, lights, dosers...) share the
+        exact same BLE/FSCI wire protocol and advertise the same name, so
+        this is the reliable way to tell them apart over BLE without
+        hardcoding MAC addresses.
+        """
+        raw = await self.get_attribute(C2Attribute.PrimitiveType)
+        return PrimitiveType(raw[0][0])
+
+    # ---- generic identity (mirrors BasicInfoProcess.setupRequest) --------
+
+    async def get_device_info(self) -> dict:
+        """
+        Fields the app itself reads for ANY device before doing anything
+        type-specific: Model, Name, SerialNumber, PrimitiveType, ErrorState.
+        Also grabs MACAddress since it's cheap. FirmwareVersion/HardwareRevision
+        are skipped -- the app indexes them per-FirmwareType/HardwareInfo
+        sub-field, adding real complexity for modest payoff.
+        """
+        async def _get(attr, default=None):
+            try:
+                raw = await self.get_attribute(attr)
+                return raw[0] if raw else default
+            except Exception:
+                return default
+
+        model_raw = await _get(C2Attribute.Model)
+        name_raw = await _get(C2Attribute.Name)
+        serial_raw = await _get(C2Attribute.SerialNumber)
+        primitive_raw = await _get(C2Attribute.PrimitiveType)
+        error_raw = await _get(C2Attribute.ErrorState)
+        mac_raw = await _get(C2Attribute.MACAddress)
+
+        model_val = struct.unpack("<h", model_raw)[0] if model_raw and len(model_raw) >= 2 else None
+        try:
+            model = Model(model_val) if model_val is not None else None
+        except ValueError:
+            model = None
+
+        error_val = struct.unpack("<h", error_raw)[0] if error_raw and len(error_raw) >= 2 else None
+        try:
+            error = ErrorState(error_val) if error_val is not None else None
+        except ValueError:
+            error = None
+
+        return {
+            "model_raw": model_val,
+            "model": model.name if model is not None else (f"unknown({model_val})" if model_val is not None else None),
+            "name": name_raw.decode("utf-8", errors="replace").rstrip("\x00") if name_raw else None,
+            "serial": serial_raw.hex() if serial_raw else None,
+            "primitive_type": PrimitiveType(primitive_raw[0]).name if primitive_raw else None,
+            "error_state": error.name if error is not None else (f"unknown({error_val})" if error_val is not None else None),
+            "mac_address": ":".join(f"{b:02X}" for b in mac_raw) if mac_raw else None,
+        }
+
+    async def get_device_summary(self) -> dict:
+        """
+        The "read everything" entrypoint: generic identity info for any
+        device, plus type-specific telemetry dispatched by PrimitiveType.
+
+        Every result includes info["support"], one of:
+          "light"                -- VisualV1, fully implemented and verified live
+          "pump"                  -- pump-class primitives, fully implemented and verified live
+          "pump (experimental)"   -- CoffeeV1 (NYOS Quantum etc.): same primitive
+                                      size/structure as pump devices, so the pump
+                                      parser is applied, but this has never been
+                                      checked against real Coffee/Quantum hardware
+          "unsupported"            -- known primitive type, no parser implemented;
+                                      identity info only, plus the primitive's
+                                      byte size as a starting point
+        """
+        info = await self.get_device_info()
+        primitive_name = info.get("primitive_type")
+        try:
+            primitive = PrimitiveType[primitive_name] if primitive_name else None
+        except KeyError:
+            primitive = None
+
+        if primitive in LIGHT_PRIMITIVES:
+            info["support"] = "light"
+            info["channels"] = [c.name for c in await self.get_supported_channels()]
+            points = await self.get_light_schedule(which=1)
+            info["schedule_point_count"] = len(points)
+            current = await self.get_current_light_intensities(which=1)
+            info["current_intensities"] = {ch.name: v for ch, v in current.items()}
+
+        elif primitive in PUMP_PRIMITIVES_VERIFIED or primitive in PUMP_PRIMITIVES_EXPERIMENTAL:
+            info["support"] = "pump" if primitive in PUMP_PRIMITIVES_VERIFIED else "pump (experimental)"
+            info["telemetry"] = await self.get_pump_telemetry()
+            info["operation_state"] = (await self.get_operation_state()).name
+            try:
+                points = await self.get_pump_schedule(which=1)
+                info["schedule_point_count"] = len(points)
+                import datetime
+                now = datetime.datetime.now()
+                block = get_active_pump_block(points, now.hour * 60 + now.minute)
+                if block:
+                    info["current_pump_mode"] = block.pump.mode.name
+                    info["current_pump_params"] = {
+                        p.name: (v.hex() if isinstance(v, bytes) else (v.name if hasattr(v, "name") else v))
+                        for p, v in block.pump.params.items()
+                    }
+            except Exception as e:
+                info["schedule_error"] = str(e)
+
+        else:
+            info["support"] = "unsupported"
+            size = PRIMITIVE_SIZE.get(primitive) if primitive else None
+            info["support_note"] = (
+                f"PrimitiveType {primitive_name!r} has no parser implemented here. "
+                f"Identity info only (model/name/serial/error_state above). "
+                + (f"Its schedule-point primitive is {size} bytes, per the protocol, "
+                   f"if you want to add support." if size is not None else "")
+            )
+
+        return info
+
+    # ---- pump telemetry (mirrors FlowRange.setupRequest) ------------------
+
+    async def get_pump_telemetry(self) -> dict:
+        """
+        Returns {"speed": int, "gph": int}. Both are genuinely read live from
+        the device -- confirmed via FlowRange.java, which is what the app's
+        dashboard actually queries for the pump gauge widget.
+
+        "gph" comes from PhysicalValues/GallonsPerHour (int32 LE).
+        "speed" comes from MotorSpeed directly (int16).
+        MotorRPM is defined in the protocol but never queried anywhere in the
+        app -- not included here since it's unconfirmed whether firmware
+        actually populates it.
+        """
+        speed_raw = await self.get_attribute(C2Attribute.MotorSpeed)
+        gph_raw = await self.get_attribute(
+            C2Attribute.PhysicalValues, index=int(PhysicalValueID.GallonsPerHour), count=1
+        )
+        speed = struct.unpack("<h", speed_raw[0])[0] if speed_raw else None
+        gph = struct.unpack("<i", gph_raw[0])[0] if gph_raw else None
+        return {"speed": speed, "gph": gph}
+
+    # ---- light schedule (Radion/XR15 etc.) --------------------------------
+
+    async def get_supported_channels(self) -> list[VisualID]:
+        """Confirmed via Visuals.java: the static list of channels this light has."""
+        raw = await self.get_attribute(C2Attribute.SupportedColorChannels, index=0, count=0xFFFF)
+        out = []
+        for v in raw:
+            if v:
+                try:
+                    out.append(VisualID(v[0]))
+                except ValueError:
+                    pass
+        return out
+
+    async def get_light_schedule(self, which: int = 1) -> list[SchedulePoint]:
+        """
+        Fetches the raw programmed point-schedule (which=1 or 2, for
+        Schedule1/Schedule2). Mirrors Schedule.setupRequest()'s
+        addAttribute(Schedule1, index=0, count=0xFFFF) call.
+
+        NOTE: the response parser assumes every returned point element is the
+        same byte length (see FsciConfirmResponse's fixed count*length
+        layout). This holds if every point on the device always encodes the
+        full supported-channel set; unconfirmed for schedules with points
+        that were only ever edited to include a subset of channels.
+        """
+        attr = C2Attribute.Schedule1 if which == 1 else C2Attribute.Schedule2
+        raw = await self.get_attribute(attr, index=0, count=0xFFFF)
+        points = []
+        for element in raw:
+            pt = SchedulePoint.parse(element)
+            if pt is not None:
+                points.append(pt)
+        return points
+
+    async def get_current_light_intensities(self, which: int = 1,
+                                              minute_of_day: Optional[int] = None) -> dict:
+        """
+        Replicates what the app actually shows as "current intensity": fetch
+        the schedule, then linearly interpolate it for the given time
+        (defaults to local system time -- NOT read from the device; the app
+        itself uses the tank's configured timezone against phone-local time,
+        not a device clock read, so this mirrors that behavior).
+
+        Returns {VisualID: intensity_float_permille}. Divide by 10 for percent.
+        """
+        if minute_of_day is None:
+            import datetime
+            now = datetime.datetime.now()
+            minute_of_day = now.hour * 60 + now.minute
+        points = await self.get_light_schedule(which)
+        return interpolate_light_schedule(points, minute_of_day)
+
+    # ---- pump schedule (VorTech/Nero/Vectra/Alpaca/Turtle) -----------------
+
+    async def get_pump_schedule(self, which: int = 1) -> list[PumpSchedulePoint]:
+        """Same Schedule1/Schedule2 attribute as lights, decoded as PumpPrimitive."""
+        attr = C2Attribute.Schedule1 if which == 1 else C2Attribute.Schedule2
+        raw = await self.get_attribute(attr, index=0, count=0xFFFF)
+        points = []
+        for element in raw:
+            pt = PumpSchedulePoint.parse(element)
+            if pt is not None:
+                points.append(pt)
+        return points
+
+    async def get_current_pump_block(self, which: int = 1,
+                                      minute_of_day: Optional[int] = None) -> Optional[PumpSchedulePoint]:
+        """
+        Returns the PumpSchedulePoint currently active (block lookup, not
+        interpolation -- see get_active_pump_block()). Defaults to local
+        system time, same rationale as get_current_light_intensities().
+        """
+        if minute_of_day is None:
+            import datetime
+            now = datetime.datetime.now()
+            minute_of_day = now.hour * 60 + now.minute
+        points = await self.get_pump_schedule(which)
+        return get_active_pump_block(points, minute_of_day)
+
+
+# Backwards-compatible alias (this class was originally MobiusPump before the
+# library grew to cover lights, dosers, etc. too).
+MobiusPump = MobiusDevice

mobius/discovery.py

@@ -0,0 +1,64 @@
+"""
+BLE discovery helpers: finding Mobius devices, and reading model/serial/
+pan_id straight from their advertisements with no GATT connection required.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Optional
+
+from bleak import BleakScanner
+from bleak.backends.device import BLEDevice
+
+from .manufacturer import MOBIUS_COMPANY_ID, MobiusAdvertisement, parse_manufacturer_data
+
+
+async def scan_for_mobius_devices(timeout: float = 15.0, adapter: Optional[str] = None) -> list[BLEDevice]:
+    """
+    adapter: Linux/BlueZ only, e.g. "hci0" or "hci1". Devices returned carry
+    the adapter they were seen on, and MobiusDevice reuses that same adapter
+    for connecting -- so set it here, not on MobiusDevice.
+    """
+    kwargs = {"timeout": timeout}
+    if adapter is not None:
+        kwargs["bluez"] = {"adapter": adapter}
+    devices = await BleakScanner.discover(**kwargs)
+    return [d for d in devices if d.name and "mobius" in d.name.lower()]
+
+
+async def scan_for_mobius_devices_with_info(
+    timeout: float = 15.0, adapter: Optional[str] = None
+) -> list[tuple[BLEDevice, Optional[MobiusAdvertisement]]]:
+    """
+    Like scan_for_mobius_devices(), but also parses manufacturer data --
+    giving you model, serial, and pan_id (tank/mesh grouping) for every
+    device found, with NO GATT connection required at all.
+    """
+    found: dict = {}
+
+    def _cb(device, adv):
+        if device.name and "mobius" in device.name.lower():
+            payload = adv.manufacturer_data.get(MOBIUS_COMPANY_ID)
+            info = parse_manufacturer_data(payload) if payload else None
+            found[device.address] = (device, info)
+
+    kwargs = {"detection_callback": _cb}
+    if adapter is not None:
+        kwargs["bluez"] = {"adapter": adapter}
+    scanner = BleakScanner(**kwargs)
+    await scanner.start()
+    await asyncio.sleep(timeout)
+    await scanner.stop()
+    return list(found.values())
+
+
+def group_by_pan_id(
+    devices: list[tuple[BLEDevice, Optional[MobiusAdvertisement]]]
+) -> dict:
+    """Groups scan_for_mobius_devices_with_info() results by pan_id (tank/mesh)."""
+    groups: dict = {}
+    for device, info in devices:
+        key = info.pan_id if info else None
+        groups.setdefault(key, []).append((device, info))
+    return groups

mobius/frame.py

@@ -0,0 +1,170 @@
+"""
+Wire framing for the FSCI/C2CI protocol: the byte layout every message
+shares, and the Get/Set-attribute payload structure layered on top of it.
+
+See documentation/02-framing-and-crc.md and documentation/03-attributes-and-opcodes.md
+for the full derivation and confirmation evidence.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+from typing import Optional
+
+from .crc import crc16
+
+# --------------------------------------------------------------------------
+# opGroup / opCode constants
+# --------------------------------------------------------------------------
+
+OPGROUP_C2CI_REQUEST = 0xDE
+OPGROUP_C2CI_CONFIRM = 0xDF
+OPGROUP_FSCI_REQUEST = 0xCE
+OPGROUP_FSCI_CONFIRM = 0xCF
+OPGROUP_QOTAP_REQUEST = 0xBE
+OPGROUP_QOTAP_CONFIRM = 0xBF
+# Java's constants are signed bytes:
+#   C2CI_Request = -34 = 0xDE, C2CI_Confirm = -33 = 0xDF
+#   FSCI_Request = -50 = 0xCE, FSCI_Confirm = -49 = 0xCF
+#   QOTAP_Request = -66 = 0xBE, QOTAP_Confirm = -65 = 0xBF
+
+OPCODE_GET_ATTR = 0x17            # 23 - old/short variant (1-byte index/count/length)
+OPCODE_GET_ATTR_EXT = 0x1C        # 28 - new/long variant (2-byte fields)
+OPCODE_SET_ATTR = 0x18            # 24 - old/short variant
+OPCODE_SET_ATTR_EXT = 0x1D        # 29 - new/long variant
+OPCODE_GET_ATTR_ELEMENTS = 0x20   # 32
+OPCODE_GET_ATTR_ELEMENTS_EXT = 0x25  # 37
+OPCODE_GET_OPCODES = 0x29         # 41
+
+
+def make_reserved(fsci_instance: int = 0, group: int = 0,
+                   do_not_respond: bool = False, superuser: bool = False) -> bytes:
+    """Builds the 2-byte 'reserved' frame field. Bit layout confirmed from Request.java:
+    byte0 bits0-1=fsci_instance, bits2-7=group<<2; byte1 bit0=doNotRespond, bit1=superuser."""
+    b0 = (fsci_instance & 0x03) | ((group & 0x3F) << 2)
+    b1 = (1 if do_not_respond else 0) | (2 if superuser else 0)
+    return bytes([b0, b1])
+
+
+_next_message_id = 0
+
+
+def next_message_id() -> int:
+    """Simple monotonically-increasing message ID generator (module-global)."""
+    global _next_message_id
+    _next_message_id = (_next_message_id + 1) % 20000
+    return _next_message_id
+
+
+def build_frame(op_group: int, op_code: int, data: bytes,
+                 message_id: Optional[int] = None,
+                 reserved: bytes = b"\x00\x00") -> bytes:
+    """
+    Builds a full wire frame:
+        0x02 | opGroup | opCode | msgId(u16 LE) | reserved(2) | len(u16 LE) | data | crc16(u16 LE)
+    CRC is computed over everything from opGroup through data (i.e. bytes[1:] before the CRC).
+    """
+    if message_id is None:
+        message_id = next_message_id()
+    body = struct.pack("<BBH2sH", op_group, op_code, message_id, reserved, len(data)) + data
+    crc = crc16(body)
+    return b"\x02" + body + struct.pack("<H", crc)
+
+
+@dataclass
+class ParsedFrame:
+    op_group: int
+    op_code: int
+    message_id: int
+    reserved: bytes
+    data: bytes
+    crc_ok: bool
+
+
+def parse_frame(raw: bytes) -> Optional[ParsedFrame]:
+    """Parses and CRC-validates a full wire frame. Mirrors FsciHelper.isValidMessage + Response.create."""
+    if len(raw) <= 8 or raw[0] != 0x02:
+        return None
+    data_len = struct.unpack_from("<H", raw, 7)[0]
+    total_len = data_len + 11
+    if len(raw) < total_len:
+        return None
+    body_end = data_len + 9
+    computed = crc16(raw[1:body_end])
+    received = struct.unpack_from("<H", raw, body_end)[0]
+    crc_ok = computed == received
+    op_group = raw[1]
+    op_code = raw[2]
+    message_id = struct.unpack_from("<H", raw, 3)[0]
+    reserved = raw[5:7]
+    data = raw[9:body_end]
+    return ParsedFrame(op_group, op_code, message_id, reserved, data, crc_ok)
+
+
+# --------------------------------------------------------------------------
+# Get / Set attribute payload (en/de)coding
+# --------------------------------------------------------------------------
+
+def encode_get_attribute(attr_id: int, index: int = 0, count: int = 1,
+                          extended: bool = False) -> bytes:
+    """Payload for a Get-attribute request: attrId(u16) + index + count (1 or 2 bytes each)."""
+    if extended:
+        return struct.pack("<HHH", attr_id, index, count)
+    return struct.pack("<H", attr_id) + bytes([index & 0xFF, count & 0xFF])
+
+
+def encode_set_attribute(attr_id: int, values: list[bytes], index: int = 0,
+                          extended: bool = False) -> bytes:
+    """Payload for a Set-attribute request. `values` is a list of same-shaped
+    byte strings (usually length 1): attrId + index + count + length + data."""
+    length = max(len(v) for v in values)
+    padded = [v + bytes(length - len(v)) for v in values]
+    if extended:
+        header = struct.pack("<HHHH", attr_id, index, len(values), length)
+    else:
+        header = struct.pack("<H", attr_id) + bytes([index & 0xFF, len(values) & 0xFF, length & 0xFF])
+    return header + b"".join(padded)
+
+
+@dataclass
+class AttributeValue:
+    attr_id: int
+    index: int
+    values: list[bytes]
+
+
+def decode_attribute_response(data: bytes, extended: bool = False) -> list[AttributeValue]:
+    """
+    Parses the repeated
+      attrId(u16) + index(u8/u16) + count(u8/u16) + length(u8/u16) + count*length bytes
+    structure used by Get-attribute confirm responses. `data` is the FSCI
+    confirm payload *after* the leading status byte (data[0]).
+    """
+    out: list[AttributeValue] = []
+    pos = 1  # skip status byte
+    field = 2 if extended else 1
+    while pos < len(data):
+        attr_id = struct.unpack_from("<H", data, pos)[0]
+        pos += 2
+        if extended:
+            index = struct.unpack_from("<H", data, pos)[0]
+        else:
+            index = data[pos]
+        pos += field
+        if extended:
+            count = struct.unpack_from("<H", data, pos)[0]
+        else:
+            count = data[pos]
+        pos += field
+        if extended:
+            length = struct.unpack_from("<H", data, pos)[0]
+        else:
+            length = data[pos]
+        pos += field
+        values = []
+        for _ in range(count):
+            values.append(data[pos:pos + length])
+            pos += length
+        out.append(AttributeValue(attr_id, index, values))
+    return out