sofapython 0.0.1rc1__py3-none-any.whl

sofapython/opcode_handlers.py

@@ -0,0 +1,1655 @@
+from __future__ import annotations
+
+"""Opcode-specific frame handlers used by :class:`~.x1_proxy.X1Proxy`."""
+
+import re
+import time
+import unicodedata
+from typing import TYPE_CHECKING
+
+from .hub_versions import HUB_VERSION_X1
+from .commands import decode_burst_frame, parse_ir_command_dump_frame
+from .frame_handlers import BaseFrameHandler, FrameContext, register_handler
+from .macros import (
+    MacroAssembler,
+    parse_macro_burst_frame,
+    parse_macro_records_from_burst,
+)
+from .protocol_const import (
+    BUTTONNAME_BY_CODE,
+    ButtonName,
+    FAMILY_DEVBTNS,
+    FAMILY_FAV_ORDER_RESP,
+    FAMILY_HUB_NAME_REPLY,
+    FAMILY_MACROS,
+    FAMILY_KEYMAP,
+    OP_ACK_READY,
+    OP_CATALOG_ROW_ACTIVITY,
+    OP_CATALOG_ROW_DEVICE,
+    OP_DEVBTN_HEADER,
+    OP_DEVBTN_MORE,
+    OP_DEVBTN_PAGE,
+    OP_DEVBTN_PAGE_ALT1,
+    OP_DEVBTN_PAGE_ALT2,
+    OP_DEVBTN_PAGE_ALT3,
+    OP_DEVBTN_PAGE_ALT4,
+    OP_DEVBTN_PAGE_ALT5,
+    OP_DEVBTN_PAGE_ALT6,
+    OP_DEVBTN_SINGLE,
+    OP_DEVBTN_TAIL,
+    OP_IDLE_BEHAVIOR,
+    OP_MACROS_A1,
+    OP_MACROS_A2,
+    OP_MACROS_B1,
+    OP_MACROS_B2,
+    OP_KEYMAP_CONT,
+    OP_KEYMAP_FINAL_X1S,
+    OP_KEYMAP_OVERLAY_X1,
+    OP_KEYMAP_PAGE_X1_663D,
+    OP_KEYMAP_PAGE_X1_AE3D,
+    OP_KEYMAP_PAGE_X1_E43D,
+    OP_KEYMAP_PAGE_X2_C03D,
+    OP_KEYMAP_TBL_A,
+    OP_KEYMAP_TBL_B,
+    OP_KEYMAP_TBL_C,
+    OP_KEYMAP_TBL_D,
+    OP_KEYMAP_TBL_F,
+    OP_KEYMAP_TBL_E,
+    OP_KEYMAP_TBL_G,
+    OP_CREATE_DEVICE_HEAD,
+    OP_DEFINE_IP_CMD,
+    OP_DEFINE_IP_CMD_EXISTING,
+    OP_PREPARE_SAVE,
+    OP_FINALIZE_DEVICE,
+    OP_DEVICE_SAVE_HEAD,
+    OP_SAVE_COMMIT,
+    OP_REQ_IPCMD_SYNC,
+    OP_IPCMD_ROW_A,
+    OP_IPCMD_ROW_B,
+    OP_IPCMD_ROW_C,
+    OP_IPCMD_ROW_D,
+    ACK_SUCCESS,
+    OP_MARKER,
+    OP_REQ_ACTIVATE,
+    OP_REQ_ACTIVITY_MAP,
+    OP_REQ_BUTTONS,
+    OP_REQ_COMMANDS,
+    OP_REQ_IDLE_BEHAVIOR,
+    OP_REQ_ACTIVITIES,
+    OP_SET_IDLE_BEHAVIOR,
+    OP_X2_REMOTE_LIST_ROW,
+    OP_ACTIVITY_MAP_PAGE,
+    OP_ACTIVITY_MAP_PAGE_X1S,
+    OP_ACTIVITY_CREATE_ACK,
+    OP_X1_ACTIVITY,
+    OP_X1_DEVICE,
+    OP_KEYMAP_EXTRA,
+    classify_device_class_code,
+    opcode_family,
+)
+if TYPE_CHECKING:
+    from .x1_proxy import X1Proxy
+
+
+OP_CREATE_DEVICE_ACK = 0x0107
+
+
+def _consume_length_prefixed_string(buf: bytes, offset: int) -> tuple[str, int]:
+    """Decode a length-prefixed UTF-8 string from ``buf`` starting at ``offset``."""
+
+    if offset >= len(buf):
+        return "", offset
+
+    length = buf[offset]
+    start = offset + 1
+    end = min(len(buf), start + length)
+    try:
+        return buf[start:end].decode("utf-8", errors="ignore").strip("\x00"), end
+    except Exception:
+        return "", end
+
+
+def _extract_text_fields(payload: bytes, start: int, count: int = 2) -> list[str]:
+    """Return up to ``count`` decoded fields from a length-prefixed payload segment."""
+
+    cursor = start
+    fields: list[str] = []
+    for _ in range(count):
+        text, cursor = _consume_length_prefixed_string(payload, cursor)
+        fields.append(text)
+
+    remaining = payload[cursor:]
+    if remaining:
+        parts = [p.decode("utf-8", errors="ignore").strip("\x00") for p in remaining.split(b"\x00") if p]
+        for idx, part in enumerate(parts):
+            if idx >= len(fields):
+                break
+            if not fields[idx]:
+                fields[idx] = part
+
+    return fields
+
+
+def _decode_utf16le_segment(payload: bytes, *, start: int = 0, length: int | None = None) -> str:
+    """Decode a UTF-16LE string from ``payload`` with optional bounds."""
+
+    end = None if length is None else start + length
+    segment = payload[start:end]
+    if not segment:
+        return ""
+    try:
+        text = segment.decode("utf-16le", errors="ignore").replace("\x00", "")
+        text = re.sub(r"[^\x20-\x7E]", "", text)
+        return text.strip()
+    except Exception:
+        return ""
+
+
+def _decode_ascii_blocks(payload: bytes) -> list[str]:
+    """Split an ASCII-ish payload into human-readable blocks."""
+
+    decoded = payload.decode("utf-8", errors="ignore")
+    parts = [p.strip("\x00") for p in decoded.replace("\r", "\n").split("\n") if p.strip("\x00")]
+    return parts
+
+
+
+@register_handler(opcode_families_low=(0x02,), directions=("H→A",))
+class BannerInfoHandler(BaseFrameHandler):
+    """Capture family-0x02 banner replies with model/build/firmware metadata."""
+
+    def handle(self, frame: FrameContext) -> None:
+        frame.proxy.record_banner_payload(frame.opcode, frame.payload)
+
+
+@register_handler(opcode_families_low=(FAMILY_MACROS,), directions=("H→A",))
+class MacroHandler(BaseFrameHandler):
+    """Decode macro pages and populate the activity cache."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+
+        now = time.monotonic()
+        parsed = parse_macro_burst_frame(frame.opcode, frame.raw)
+        if parsed is not None:
+            frag = (
+                f"{parsed.fragment_index}/{parsed.total_fragments}"
+                if parsed.fragment_index is not None and parsed.total_fragments is not None
+                else (f"{parsed.fragment_index}" if parsed.fragment_index is not None else "?")
+            )
+            activity = f" act=0x{parsed.activity_id:02X}" if parsed.activity_id is not None else ""
+            start_cmd = (
+                f" start_cmd=0x{parsed.start_command_id:02X}"
+                if parsed.start_command_id is not None
+                else ""
+            )
+            len_ok = " len_ok=yes" if parsed.payload_length_matches_hi else " len_ok=no"
+            proxy._log.debug(
+                "[REQ_MACROS] role=%s frag=%s%s%s%s",
+                parsed.role,
+                frag,
+                activity,
+                start_cmd,
+                len_ok,
+            )
+
+        completed = proxy._macro_assembler.feed(frame.opcode, frame.payload, frame.raw)
+        activity_hint = proxy._macro_assembler._last_activity_id
+        burst_key = "macros" if activity_hint is None else f"macros:{activity_hint & 0xFF}"
+
+        if proxy._burst.active and proxy._burst.kind and proxy._burst.kind.startswith("macros"):
+            proxy._burst.last_ts = now + proxy._burst.response_grace
+            if proxy._burst.kind == "macros":
+                proxy._burst.kind = burst_key
+        else:
+            proxy._burst.start(burst_key, now=now)
+
+        if not completed:
+            return
+
+        for activity_id, assembled, boundaries in completed:
+            act_lo = activity_id & 0xFF
+            macros: list[dict[str, int | str]] = []
+            # Production REQ_MACROS uses the assembled fixed-width parser via
+            # `parse_macro_records_from_burst`. The legacy
+            # `decode_macro_records` remains importable for tests and
+            # external callers.
+            for record in parse_macro_records_from_burst(
+                assembled,
+                activity_id=activity_id,
+                record_boundaries=boundaries,
+                hub_version=proxy.hub_version,
+            ):
+                # Surface every assembled record (including POWER_*) for
+                # read-modify-write callers like add_device_to_activity.
+                proxy.cache_macro_record(record)
+
+                # Suppress auto-generated POWER_* macros from the activity
+                # UI list.
+                if not record.label or record.label.upper().startswith("POWER_"):
+                    continue
+                macros.append({"command_id": record.key_id, "label": record.label})
+
+            proxy.state.replace_activity_macros(act_lo, macros)
+            proxy._macros_complete.add(act_lo)
+            proxy._pending_macro_requests.discard(act_lo)
+            if macros:
+                proxy._log.info(
+                    "[MACRO] act=0x%02X macros{%d}: %s",
+                    act_lo,
+                    len(macros),
+                    ", ".join(f"{m['command_id']}: {m['label']}" for m in macros),
+                )
+
+        if completed:
+            proxy._burst.finish(
+                burst_key,
+                can_issue=proxy.can_issue_commands,
+                sender=proxy._send_cmd_frame,
+                now=now,
+            )
+
+
+
+
+@register_handler(opcode_families_low=(0x47,), directions=("H→A",))
+class ActivityInputsHandler(BaseFrameHandler):
+    """Capture activity-inputs list frames used by the macro assignment wizard."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        proxy.notify_activity_inputs_frame(frame.payload)
+
+def _parse_header_lines(lines: list[str]) -> dict[str, str]:
+    headers: dict[str, str] = {}
+    for line in lines:
+        if ":" not in line:
+            continue
+        key, val = line.split(":", 1)
+        headers[key.strip()] = val.strip()
+    return headers
+
+
+def _parse_ip_command_fields(payload: bytes) -> tuple[str, str, dict[str, str]]:
+    """Extract HTTP method, URL, and headers from an IP command payload."""
+
+    method = ""
+    url = ""
+    headers: dict[str, str] = {}
+
+    if payload:
+        try:
+            cursor = 0
+            if cursor < len(payload):
+                m_len = payload[cursor]
+                cursor += 1
+                method = payload[cursor : cursor + m_len].decode("utf-8", errors="ignore")
+                cursor += m_len
+            if cursor < len(payload):
+                u_len = payload[cursor]
+                cursor += 1
+                url = payload[cursor : cursor + u_len].decode("utf-8", errors="ignore")
+                cursor += u_len
+            if cursor < len(payload):
+                h_len = payload[cursor]
+                cursor += 1
+                header_blob = payload[cursor : cursor + h_len].decode("utf-8", errors="ignore")
+                headers = _parse_header_lines(header_blob.split("\n"))
+        except Exception:
+            # fall through to heuristics
+            pass
+
+    ascii_parts = _decode_ascii_blocks(payload)
+    for part in ascii_parts:
+        clean = re.sub(r"[^\x20-\x7E]", "", part)
+        upper_clean = clean.upper()
+
+        if not method:
+            for verb in ("GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"):
+                if verb in upper_clean:
+                    method = verb
+                    break
+            if not method and clean.isalpha():
+                method = upper_clean
+        if not url:
+            lower_clean = clean.lower()
+            if lower_clean.startswith("http"):
+                url = clean
+            elif method and "http" in lower_clean:
+                for tok in clean.split():
+                    if tok.lower().startswith("http/"):
+                        continue
+                    if tok.lower().startswith("http"):
+                        url = tok
+                        break
+        if method and not url and "http/" not in clean.lower():
+            tokens = clean.split()
+            if method in tokens and len(tokens) > tokens.index(method) + 1:
+                candidate = tokens[tokens.index(method) + 1]
+                if not candidate.lower().startswith("http/" ):
+                    url = candidate
+        if ":" in clean:
+            headers |= _parse_header_lines([clean])
+
+    if method and not method.isalpha():
+        match = re.search(r"\b(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\b", method, re.IGNORECASE)
+        if match:
+            method = match.group(1).upper()
+
+    if url.upper().startswith("HTTP/"):
+        url = ""
+
+    if not url or url.startswith("-") or url.lower().startswith("content-"):
+        for part in ascii_parts:
+            if method:
+                tokens = part.split()
+                for idx, tok in enumerate(tokens):
+                    if method in tok.upper() and idx + 1 < len(tokens):
+                        candidate = tokens[idx + 1]
+                        if not candidate.lower().startswith("http/"):
+                            url = candidate if candidate.startswith("/") else url
+                            if candidate.startswith("/"):
+                                break
+                    if tok.lower().startswith("http/"):
+                        continue
+                    if tok.startswith("/") or tok.lower().startswith("http"):
+                        url = tok
+                        break
+            if url:
+                break
+
+
+    return method, url, headers
+
+def _extract_dev_id(
+    raw: bytes,
+    payload: bytes,
+    opcode: int,
+    *,
+    hub_version: str,
+) -> int:
+    """Determine device ID for a command burst frame."""
+
+    parsed = decode_burst_frame(opcode, raw, hub_version=hub_version)
+    if parsed is not None and hasattr(parsed, "device_id"):
+        return parsed.device_id
+
+    if len(payload) >= 4:
+        return payload[3]
+
+    return 0
+
+
+@register_handler(opcodes=(OP_CREATE_DEVICE_HEAD,), directions=("A→H",))
+class CreateVirtualDeviceHandler(BaseFrameHandler):
+    """Capture app-initiated virtual device creation requests."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        payload = frame.payload
+        device_name = _decode_utf16le_segment(payload, start=0, length=64) or _decode_utf16le_segment(payload)
+        proxy.start_virtual_device(device_name=device_name)
+        proxy._log.info("[CREATE] device name='%s' (%dB payload)", device_name, len(payload))
+
+
+@register_handler(opcodes=(OP_DEFINE_IP_CMD,), directions=("A→H",))
+class DefineIpCommandHandler(BaseFrameHandler):
+    """Decode IP command metadata sent from the app."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        payload = frame.payload
+        button_name = _decode_utf16le_segment(payload, start=0, length=64) or _decode_utf16le_segment(payload)
+        method, url, headers = _parse_ip_command_fields(payload[64:])
+        proxy.update_virtual_device(button_name=button_name, method=method, url=url, headers=headers)
+        proxy._log.info(
+            "[CREATE] button='%s' method=%s url='%s' headers=%s",
+            button_name,
+            method or "?",
+            url,
+            ", ".join(f"{k}: {v}" for k, v in headers.items()) if headers else "{}",
+        )
+
+
+@register_handler(opcodes=(OP_DEFINE_IP_CMD_EXISTING,), directions=("A→H",))
+class DefineExistingIpCommandHandler(BaseFrameHandler):
+    """Capture metadata when the app adds an IP command to an existing device."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        payload = frame.payload
+        button_name = _decode_utf16le_segment(payload, start=16, length=64) or _decode_utf16le_segment(payload, start=16)
+        method, url, headers = _parse_ip_command_fields(payload[64:])
+        proxy.update_virtual_device(button_name=button_name, method=method, url=url, headers=headers)
+        proxy._log.info(
+            "[CREATE] existing dev button='%s' method=%s url='%s' headers=%s",
+            button_name,
+            method or "?",
+            url,
+            ", ".join(f"{k}: {v}" for k, v in headers.items()) if headers else "{}",
+        )
+
+
+@register_handler(
+    opcodes=(OP_IPCMD_ROW_A, OP_IPCMD_ROW_B, OP_IPCMD_ROW_C, OP_IPCMD_ROW_D),
+    directions=("H→A",),
+)
+class IpCommandSyncRowHandler(BaseFrameHandler):
+    """Decode IP command rows returned when syncing commands for an existing device."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        payload = frame.payload
+        proxy._burst.start("commands", now=time.monotonic())
+        if len(payload) > 6:
+            proxy._burst.start(f"commands:{payload[6]}", now=time.monotonic())
+
+        device_id = payload[6] if len(payload) > 6 else None
+        button_id = payload[7] if len(payload) > 7 else None
+        button_name = _decode_utf16le_segment(payload, start=16, length=64) or _decode_utf16le_segment(payload, start=16)
+        method, url, headers = _parse_ip_command_fields(payload[64:])
+
+        if device_id is None:
+            return
+
+        device_meta = proxy.state.entities("device").get(device_id & 0xFF, {})
+        proxy.state.record_virtual_device(
+            device_id,
+            name=device_meta.get("name") or f"Device {device_id}",
+            button_id=button_id,
+            method=method,
+            url=url,
+            headers=headers,
+            button_name=button_name,
+        )
+
+        proxy._log.info(
+            "[CREATE] sync dev=0x%04X btn=0x%02X name='%s' method=%s url='%s'",
+            device_id,
+            button_id or 0,
+            button_name,
+            method or "?",
+            url,
+        )
+
+
+@register_handler(opcodes=(OP_PREPARE_SAVE,), directions=("A→H", "H→A"))
+class PrepareSaveHandler(BaseFrameHandler):
+    """Track the start of a save transaction for IP buttons."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        proxy._log.info("[CREATE] prepare/save transaction len=%d", len(frame.payload))
+
+
+@register_handler(opcodes=(OP_DEVICE_SAVE_HEAD,), directions=("H→A",))
+class DeviceSaveHeadHandler(BaseFrameHandler):
+    """Record hub-assigned device identifiers for virtual devices."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        payload = frame.payload
+        device_id = int.from_bytes(payload[:2], "big") if len(payload) >= 2 else None
+        button_id = payload[2] if len(payload) > 2 else None
+        proxy.update_virtual_device(device_id=device_id, button_id=button_id)
+        proxy._log.info(
+            "[CREATE] hub assigned dev=0x%04X btn=0x%02X", device_id or 0, button_id or 0
+        )
+
+
+@register_handler(opcodes=(OP_FINALIZE_DEVICE,), directions=("H→A",))
+class FinalizeDeviceHandler(BaseFrameHandler):
+    """Note finalize frames emitted during virtual device creation."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        payload = frame.payload
+        if len(payload) >= 3:
+            device_id = int.from_bytes(payload[:2], "big")
+            button_id = payload[2]
+            proxy.update_virtual_device(device_id=device_id, button_id=button_id)
+            proxy._log.info("[CREATE] finalize dev=0x%04X btn=0x%02X", device_id, button_id)
+        else:
+            proxy._log.info("[CREATE] finalize len=%d", len(payload))
+
+
+@register_handler(opcodes=(OP_SAVE_COMMIT, ACK_SUCCESS), directions=("H→A",))
+class SaveCommitHandler(BaseFrameHandler):
+    """Acknowledge successful save of a virtual device/button."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        if getattr(proxy, "_pending_virtual", None) is None:
+            return
+        proxy.update_virtual_device(status="success")
+        proxy._log.info("[CREATE] save commit/ack success")
+
+
+@register_handler(
+    opcodes=(OP_CREATE_DEVICE_ACK, OP_ACTIVITY_CREATE_ACK),
+    directions=("H→A",),
+)
+class CreateDeviceAckHandler(BaseFrameHandler):
+    """Capture assigned ids from create-device/activity-create acks."""
+
+    def handle(self, frame: FrameContext) -> None:
+        payload = frame.payload
+        if len(payload) < 1:
+            return
+        proxy: X1Proxy = frame.proxy
+        proxy.set_assigned_device_id(payload[0])
+        proxy.notify_ack(frame.opcode, payload)
+        entity = "activity" if frame.opcode == OP_ACTIVITY_CREATE_ACK else "device"
+        proxy._log.info("[WIFI] create ack %s_id=0x%02X", entity, payload[0])
+
+
+@register_handler(opcodes=(0x0103, 0x013E, 0x0112), directions=("H→A",))
+class GenericCreateAckHandler(BaseFrameHandler):
+    """Capture Create-sequence ACK frames so replay can gate each next step."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        proxy.notify_ack(frame.opcode, frame.payload)
+
+
+@register_handler(opcode_families_low=(FAMILY_HUB_NAME_REPLY,), directions=("H→A",))
+class HubNameReplyHandler(BaseFrameHandler):
+    """Queue variable-length hub-name replies for synchronous waiters."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        proxy.notify_ack(frame.opcode, frame.payload)
+
+
+
+
+@register_handler(opcodes=(OP_X2_REMOTE_LIST_ROW,), directions=("H→A",))
+class X2RemoteListRowHandler(BaseFrameHandler):
+    """Capture the first remote id from X2 remote-list response rows."""
+
+    def handle(self, frame: FrameContext) -> None:
+        payload = frame.payload
+        if len(payload) < 4:
+            return
+
+        # Observed layout starts with a count byte then a 3-byte remote id.
+        remote_id = payload[1:4]
+        proxy: X1Proxy = frame.proxy
+        proxy.update_x2_remote_sync_id(remote_id)
+        proxy._log.info("[REMOTE_SYNC] X2 remote id=%s", remote_id.hex(" "))
+
+@register_handler(opcodes=(OP_REQ_ACTIVATE,), directions=("A→H",))
+class ActivateRequestHandler(BaseFrameHandler):
+    """Log activation requests and track activity hints."""
+
+    def handle(self, frame: FrameContext) -> None:
+        payload = frame.payload
+        if len(payload) != 2:
+            return
+
+        proxy: X1Proxy = frame.proxy
+        ent_id, code = payload
+
+        activities_view = proxy.state.entities("activity")
+        devices_view = proxy.state.entities("device")
+        if ent_id in activities_view:
+            kind = "act"
+            record_kind = "activity"
+            name = activities_view[ent_id].get("name", "")
+            if code == ButtonName.POWER_ON:
+                proxy.state.set_hint(ent_id)
+        elif ent_id in devices_view:
+            kind = "dev"
+            record_kind = "device"
+            name = devices_view[ent_id].get("name", "")
+        else:
+            kind = "id"
+            record_kind = "unknown"
+            name = ""
+
+        cmd = proxy.state.commands.get(ent_id, {}).get(code)
+        btn = BUTTONNAME_BY_CODE.get(code) if cmd is None else None
+        extra = f" cmd='{cmd}'" if cmd else (f" btn='{btn}'" if btn else "")
+
+        proxy._log.info(
+            "[KEY] %s %s=0x%02X (%d) name='%s' key=0x%02X%s",
+            frame.direction,
+            kind,
+            ent_id,
+            ent_id,
+            name,
+            code,
+            extra,
+        )
+
+        proxy.record_app_activation(
+            ent_id=ent_id,
+            ent_kind=record_kind,
+            ent_name=name,
+            command_id=code,
+            command_label=cmd,
+            button_label=btn,
+            direction=frame.direction,
+        )
+
+
+@register_handler(opcode_families_low=(0x67,), directions=("H→A",))
+class OtaUpdatePushHandler(BaseFrameHandler):
+    """Handle the hub's OTA-in-progress push (opcode-lo 0x67).
+
+    The hub emits this frame when it begins a firmware update and then
+    goes silent for several minutes. We notify listeners so the
+    integration can tear down the session, back off reconnects, and
+    surface a notification to the user.
+    """
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        proxy._log.warning(
+            "[OTA] H→A OTA-update push (opcode=0x%04X len=%d)",
+            frame.opcode,
+            len(frame.payload),
+        )
+        proxy.notify_ota_in_progress()
+
+
+@register_handler(opcodes=(OP_ACK_READY,), directions=("H→A",))
+class AckReadyHandler(BaseFrameHandler):
+    """Handle ACK_READY frames and optionally trigger data refreshes."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        proxy._log.info("[HINT] ACK_READY from hub")
+        if proxy.can_issue_commands():
+            proxy._log.info("[HINT] no proxy client; auto-REQ_ACTIVITIES")
+            proxy.enqueue_cmd(OP_REQ_ACTIVITIES, expects_burst=True, burst_kind="activities")
+            if proxy.state.current_activity_hint is not None:
+                ent_lo = proxy.state.current_activity_hint & 0xFF
+
+                _, buttons_ready = proxy.get_buttons_for_entity(
+                    ent_lo,
+                    fetch_if_missing=False,
+                )
+                if not buttons_ready:
+                    proxy.request_buttons_for_entity(ent_lo)
+        else:
+            proxy._log.info("[HINT] proxy client connected; skipping auto-requests")
+            new_id, old_id = proxy.state.update_activity_state()
+            if new_id != old_id:
+                proxy._log.info("[HINT] current activity differs from hint; notifying listeners")
+                proxy._notify_activity_change(
+                    new_id & 0xFF if new_id is not None else None,
+                    old_id & 0xFF if old_id is not None else None,
+                )
+
+
+@register_handler(opcodes=(OP_CATALOG_ROW_DEVICE,), directions=("H→A",))
+class CatalogDeviceHandler(BaseFrameHandler):
+    """Handle catalog device rows emitted by the hub."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        now = time.monotonic()
+
+        payload = frame.payload
+        raw = frame.raw
+        row_idx = payload[0] if len(payload) >= 1 else None
+        expected_rows = payload[3] if len(payload) >= 4 and payload[3] > 0 else None
+        dev_id = int.from_bytes(payload[6:8], "big") if len(payload) >= 8 else None
+        device_class_code = payload[10] if len(payload) > 10 else None
+        device_class = classify_device_class_code(device_class_code)
+        name_bytes_raw = raw[36 : 36 + 60]
+        device_label = name_bytes_raw.decode("utf-16be").strip("\x00")
+        brand_bytes_raw = raw[96 : 96 + 60]
+        brand_label = brand_bytes_raw.decode("utf-16be", errors="ignore").strip("\x00")
+
+        # Keep the raw record body so the schema parser (parse_device_record)
+        # can rebuild a faithful DeviceConfig on demand (e.g. for backup), with
+        # no live parsed-dict cached in RAM.
+        record_body = bytes(payload[3:]) if len(payload) > 3 else b""
+
+        if dev_id is not None:
+            accepted = proxy.ingest_device_row(
+                row_idx=row_idx,
+                expected_rows=expected_rows,
+                dev_id=dev_id,
+                device={
+                    "brand": brand_label,
+                    "name": device_label,
+                    "device_class": device_class,
+                    "device_class_code": device_class_code,
+                    "raw_body": record_body,
+                },
+            )
+            if not accepted:
+                return
+            proxy._burst.start("devices", now=now)
+            proxy._log.info(
+                "[DEV] #%s/%s id=0x%04X (%d) class=%s/0x%02X brand='%s' name='%s'",
+                row_idx,
+                expected_rows if expected_rows is not None else "?",
+                dev_id,
+                dev_id,
+                device_class or "?",
+                device_class_code or 0,
+                brand_label,
+                device_label,
+            )
+        elif device_label:
+            proxy._log.info("[DEV] name='%s'", device_label)
+
+        proxy.try_finish_devices_burst()
+
+
+@register_handler(opcodes=(OP_X1_DEVICE,), directions=("H→A",))
+class X1CatalogDeviceHandler(BaseFrameHandler):
+    """Handle X1 firmware device rows."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        now = time.monotonic()
+
+        payload = frame.payload
+        row_idx = payload[0] if payload else None
+        expected_rows = payload[3] if len(payload) >= 4 and payload[3] > 0 else None
+        dev_id = int.from_bytes(payload[6:8], "big") if len(payload) >= 8 else None
+        device_class_code = payload[10] if len(payload) > 10 else None
+        device_class = classify_device_class_code(device_class_code)
+
+        name_bytes = payload[32:62]
+        device_label = name_bytes.split(b"\x00", 1)[0].decode("utf-8", errors="ignore")
+
+        brand_bytes = payload[62:]
+        brand_label = brand_bytes.split(b"\x00", 1)[0].decode("utf-8", errors="ignore")
+
+        record_body = bytes(payload[3:]) if len(payload) > 3 else b""
+
+        if dev_id is not None:
+            accepted = proxy.ingest_device_row(
+                row_idx=row_idx,
+                expected_rows=expected_rows,
+                dev_id=dev_id,
+                device={
+                    "brand": brand_label,
+                    "name": device_label,
+                    "device_class": device_class,
+                    "device_class_code": device_class_code,
+                    "raw_body": record_body,
+                },
+            )
+            if not accepted:
+                return
+            proxy._burst.start("devices", now=now)
+            proxy._log.info(
+                "[DEV] #%s/%s id=0x%04X (%d) class=%s/0x%02X brand='%s' name='%s'",
+                row_idx,
+                expected_rows if expected_rows is not None else "?",
+                dev_id,
+                dev_id,
+                device_class or "?",
+                device_class_code or 0,
+                brand_label,
+                device_label,
+            )
+        elif device_label:
+            proxy._log.info("[DEV] name='%s'", device_label)
+
+        proxy.try_finish_devices_burst()
+
+
+
+# --- X1S/X2 activity-row schema (CATALOG_ROW_ACTIVITY, 0xD53B) -------------
+#
+# The row body sits immediately after the 7-byte per-frame transport header.
+# All offsets below are absolute positions into the full frame (``raw``).
+#
+#   raw[35]       active-state byte (0x01 = active)
+#   raw[36..96)   primary name slot, 60 bytes UTF-16BE, null-padded
+#   raw[96..156)  secondary label slot (unused for activities; zero-filled)
+#   raw[156..216) tail token block: fc-prefixed sub-tokens encoding
+#                 wifi/ip, idle timeout, input/power modes, and the
+#                 needs-confirm flag, followed by zero padding.
+#
+# The previous label decoder scanned a 92-byte region with two byte-shift
+# candidates; the schema makes the slot exactly 60 bytes wide with a fixed
+# UTF-16BE encoding, so no shift heuristic is needed.
+ACTIVITY_ROW_LABEL_OFFSET = 36
+ACTIVITY_ROW_LABEL_LEN = 60
+ACTIVITY_ROW_TAIL_OFFSET_IN_PAYLOAD = 152
+ACTIVITY_ROW_TAIL_LEN = 60
+
+
+def _decode_x1s_needs_confirm_flag(payload: bytes) -> bool:
+    """Return ``True`` when an X1S/X2 activity row carries the confirm-needed flag.
+
+    Activity rows end in a 60-byte tail token block (see schema comment above)
+    composed of ``fc``-prefixed sub-tokens with trailing zero padding. The
+    confirm flag is encoded as the value byte of the final ``fc XX fc YY``
+    sub-token pair within that block; ``YY == 0x01`` means the activity was
+    impacted by a recent device delete and must be re-saved by the app.
+
+    No structured parse for this flag is exposed by the official app's row
+    parser, so we locate it by scanning the tail block for the trailing
+    ``fc XX fc YY`` pair. The scan is intentionally scoped to the schema's
+    tail region rather than an arbitrary window at the end of the payload.
+    """
+
+    tail_start = ACTIVITY_ROW_TAIL_OFFSET_IN_PAYLOAD
+    tail_end = min(len(payload), tail_start + ACTIVITY_ROW_TAIL_LEN)
+    if tail_end - tail_start < 4:
+        return False
+
+    marker_indexes = [
+        idx
+        for idx in range(tail_start, tail_end - 3)
+        if payload[idx] == 0xFC and payload[idx + 2] == 0xFC
+    ]
+    if not marker_indexes:
+        return False
+
+    flag_index = marker_indexes[-1] + 3
+    return flag_index < tail_end and payload[flag_index] == 0x01
+
+
+def _decode_x1s_activity_label(label_bytes: bytes) -> str:
+    """Decode the activity name from the X1S/X2 row's fixed UTF-16BE slot.
+
+    ``label_bytes`` is the 60-byte slot from the row body (see schema comment
+    above). It is always UTF-16BE, null-padded to fill the slot; the first
+    null code unit terminates the visible label.
+    """
+
+    even_bytes = label_bytes[: len(label_bytes) & ~1]
+    text = even_bytes.decode("utf-16be", errors="ignore")
+    text = text.split("\x00", 1)[0]
+    text = text.strip()
+    while text and unicodedata.category(text[0]).startswith("C"):
+        text = text[1:].lstrip()
+    return text
+
+@register_handler(opcodes=(OP_CATALOG_ROW_ACTIVITY,), directions=("H→A",))
+class CatalogActivityHandler(BaseFrameHandler):
+    """Handle activity catalog rows."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        now = time.monotonic()
+
+        payload = frame.payload
+        raw = frame.raw
+        row_idx = payload[0] if len(payload) >= 1 else None
+        # Start of a fresh activities list → reset 'active'
+        act_id = int.from_bytes(payload[6:8], "big") if len(payload) >= 8 else None
+        label_slot = raw[
+            ACTIVITY_ROW_LABEL_OFFSET : ACTIVITY_ROW_LABEL_OFFSET + ACTIVITY_ROW_LABEL_LEN
+        ]
+        activity_label = _decode_x1s_activity_label(label_slot)
+        active_state_byte = raw[35] if len(raw) > 35 else 0
+        is_active = active_state_byte == 0x01
+        needs_confirm = _decode_x1s_needs_confirm_flag(payload)
+
+        if act_id is not None:
+            accepted = proxy.ingest_activity_row(
+                row_idx=row_idx,
+                expected_rows=payload[3] if len(payload) >= 4 and payload[3] > 0 else None,
+                act_id=act_id,
+                activity={
+                    "id": act_id,
+                    "name": activity_label,
+                    "active": is_active,
+                    "needs_confirm": needs_confirm,
+                },
+                payload=payload,
+            )
+            if not accepted:
+                return
+            proxy._burst.start("activities", now=now)
+            if row_idx == 1:
+                proxy._log.info("[ACT] reset active (start of new activities list)")
+        elif activity_label:
+            proxy._log.info("[ACT] name='%s'", activity_label)
+
+        state = "ACTIVE" if is_active else "idle"
+        if row_idx is not None and act_id is not None:
+            proxy._log.info(
+                "[ACT] #%d/%s name='%s' act_id=0x%04X (%d) state=%s",
+                row_idx,
+                payload[3] if len(payload) >= 4 and payload[3] > 0 else "?",
+                activity_label,
+                act_id,
+                act_id,
+                state,
+            )
+        elif act_id is not None:
+            proxy._log.info(
+                "[ACT] name='%s' act_id=0x%04X (%d) state=%s",
+                activity_label,
+                act_id,
+                act_id,
+                state,
+            )
+        else:
+            proxy._log.info("[ACT] name='%s' state=%s", activity_label, state)
+
+        proxy.try_finish_activities_burst()
+
+
+@register_handler(opcodes=(OP_X1_ACTIVITY,), directions=("H→A",))
+class X1CatalogActivityHandler(BaseFrameHandler):
+    """Handle activity catalog rows emitted by X1 firmware."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        now = time.monotonic()
+
+        payload = frame.payload
+        row_idx = payload[0] if payload else None
+
+        act_id = int.from_bytes(payload[6:8], "big") if len(payload) >= 8 else None
+        active_flag = frame.raw[35] if len(frame.raw) > 35 else 0
+        needs_confirm_flag = payload[95] if len(payload) > 95 else 0
+        activity_label = payload[32:].split(b"\x00", 1)[0].decode("utf-8", errors="ignore")
+        is_active = active_flag == 1
+        needs_confirm = needs_confirm_flag == 1
+
+        if act_id is not None:
+            accepted = proxy.ingest_activity_row(
+                row_idx=row_idx,
+                expected_rows=payload[3] if len(payload) >= 4 and payload[3] > 0 else None,
+                act_id=act_id,
+                activity={
+                    "id": act_id,
+                    "name": activity_label,
+                    "active": is_active,
+                    "needs_confirm": needs_confirm,
+                },
+                payload=payload,
+            )
+            if not accepted:
+                return
+            proxy._burst.start("activities", now=now)
+            if row_idx == 1:
+                proxy._log.info("[ACT] reset active (start of new activities list)")
+        elif activity_label:
+            proxy._log.info("[ACT] name='%s'", activity_label)
+
+        state = "ACTIVE" if is_active else "idle"
+        if row_idx is not None and act_id is not None:
+            proxy._log.info(
+                "[ACT] #%d/%s name='%s' act_id=0x%04X (%d) state=%s",
+                row_idx,
+                payload[3] if len(payload) >= 4 and payload[3] > 0 else "?",
+                activity_label,
+                act_id,
+                act_id,
+                state,
+            )
+        elif act_id is not None:
+            proxy._log.info(
+                "[ACT] name='%s' act_id=0x%04X (%d) state=%s",
+                activity_label,
+                act_id,
+                act_id,
+                state,
+            )
+        else:
+            proxy._log.info("[ACT] name='%s' state=%s", activity_label, state)
+
+        proxy.try_finish_activities_burst()
+
+
+@register_handler(opcodes=(OP_REQ_ACTIVITY_MAP,), directions=("A→H",))
+class RequestActivityMapHandler(BaseFrameHandler):
+    """Log activity mapping requests from the app."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        payload = frame.payload
+        act_id = payload[0] if payload else 0
+        proxy._log.info("[ACTMAP] A→H requesting mapping act=0x%02X (%d)", act_id, act_id)
+
+
+@register_handler(opcodes=(OP_ACTIVITY_MAP_PAGE, OP_ACTIVITY_MAP_PAGE_X1S), directions=("H→A",))
+class ActivityMapHandler(BaseFrameHandler):
+    """Accumulate activity-member rows for an activity roster (X1/X1S/X2)."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        payload = frame.payload
+
+        if len(payload) < 8:
+            return
+        act_lo = self._burst_activity(proxy)
+        if act_lo is None:
+            act_lo = self._pending_activity(proxy)
+        if act_lo is None:
+            return
+
+        # REQ_ACTIVITY_MAP response frames use the same wire format as
+        # REQ_DEVICES. Each frame here is a complete 1-page device row burst
+        # whose body starts at raw[7] (= payload[3]). Layout:
+        #
+        #   body[3]      sign      (= payload[6])
+        #   body[4]      deviceID  (= payload[7])  ← we use this
+        #   body[5]      icon
+        #   body[6]      sort
+        #   body[7]      codeType
+        #   body[8]      type
+        #   body[9..24]  codeId (16 bytes)
+        #   body[25..28] hide / input / tongdao / powerState
+        #   body[29..88] name (60B UTF-16BE on X1S/X2, 30B ASCII on X1)
+        #   body[89..148] brand
+        #   body[149..208] ip/extras
+        #
+        # We only need the device id to record activity membership.
+        # If a future feature wants the richer full device-record data, the
+        # full schema is right here for the picking.
+        row_idx = payload[0]
+        total_rows = payload[3]
+        dev_lo = payload[7]
+        if dev_lo == 0:
+            return
+
+        proxy.state.record_activity_member(act_lo, dev_lo)
+
+        now = time.monotonic()
+        burst_key = f"activity_map:{act_lo}"
+        if proxy._burst.active and proxy._burst.kind == burst_key:
+            proxy._burst.last_ts = now + proxy._burst.response_grace
+        else:
+            proxy._burst.start(burst_key, now=now)
+
+        proxy._log.info(
+            "[ACTMAP] act=0x%02X member row=%d/%d dev=0x%02X",
+            act_lo,
+            row_idx,
+            total_rows,
+            dev_lo,
+        )
+
+        if self._is_last_page(payload):
+            proxy._pending_activity_map_requests.discard(act_lo)
+            proxy._activity_map_complete.add(act_lo)
+            proxy.try_finish_activity_map_burst(act_lo)
+
+    def _burst_activity(self, proxy: "X1Proxy") -> int | None:
+        burst_kind = getattr(proxy._burst, "kind", None)
+        if proxy._burst.active and burst_kind and burst_kind.startswith("activity_map:"):
+            try:
+                return int(burst_kind.split(":", 1)[1])
+            except ValueError:
+                return None
+        return None
+
+    def _pending_activity(self, proxy: "X1Proxy") -> int | None:
+        if proxy._pending_activity_map_requests:
+            return next(iter(proxy._pending_activity_map_requests))
+        return None
+
+    def _is_last_page(self, payload: bytes) -> bool:
+        if len(payload) < 4:
+            return False
+        page_no = payload[0]
+        total_pages = payload[3]
+        return total_pages > 0 and page_no >= total_pages
+
+
+@register_handler(
+    opcode_families_low=(FAMILY_KEYMAP,),
+    directions=("H→A",),
+)
+class KeymapHandler(BaseFrameHandler):
+    """Accumulate keymap table pages for activities."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        raw = frame.raw
+        payload = frame.payload
+        now = time.monotonic()
+        burst_act_lo = self._burst_activity(proxy)
+        parsed = decode_burst_frame(frame.opcode, raw, hub_version=proxy.hub_version)
+        if parsed is not None:
+            # Header frames carry the burst's activity id at payload[7].
+            # Continuation pages do not; the activity id is held by the active
+            # burst (keyed by header). Prefer burst_act_lo for non-header
+            # frames so a stray byte pattern in a row cannot redirect the
+            # burst to a different activity.
+            if parsed.is_header:
+                activity_id_decimal = parsed.activity_id if parsed.activity_id is not None else burst_act_lo
+            else:
+                activity_id_decimal = burst_act_lo if burst_act_lo is not None else parsed.activity_id
+            if activity_id_decimal is None:
+                return
+
+            burst_key = f"buttons:{activity_id_decimal}"
+            if proxy._burst.active and proxy._burst.kind == burst_key:
+                proxy._burst.last_ts = now + proxy._burst.response_grace
+            else:
+                proxy._burst.start(burst_key, now=now)
+
+            total_frames = parsed.total_frames
+            if total_frames is not None:
+                proxy.note_buttons_frame(
+                    activity_id_decimal,
+                    frame_no=parsed.frame_no,
+                    total_frames=total_frames,
+                )
+
+            total_rows = (
+                f" total_rows={parsed.total_rows}"
+                if parsed.total_rows is not None
+                else ""
+            )
+            activity_note = f" act=0x{activity_id_decimal:02X}"
+            row_data_note = " row_data=yes" if parsed.has_row_data else " row_data=no"
+            totals = (
+                f"{parsed.frame_no}/{parsed.total_frames}"
+                if parsed.total_frames is not None
+                else f"{parsed.frame_no}"
+            )
+            proxy._log.debug(
+                "[REQ_BUTTONS] role=%s variant=%s page=%s%s%s%s",
+                parsed.role,
+                parsed.layout_kind,
+                totals,
+                activity_note,
+                total_rows,
+                row_data_note,
+            )
+
+            completed = proxy._button_assembler.feed(
+                frame.opcode,
+                raw,
+                activity_id_override=activity_id_decimal,
+                hub_version=proxy.hub_version,
+            )
+            for act_lo, row_stream, row_count in completed:
+                proxy.state.replace_keymap_rows(act_lo, row_stream)
+                keys = [
+                    f"{BUTTONNAME_BY_CODE.get(c, f'0x{c:02X}')}(0x{c:02X})"
+                    for c in sorted(proxy.state.buttons.get(act_lo, set()))
+                ]
+                row_summary = f" rows={row_count}" if row_count is not None else ""
+                proxy._log.info(
+                    "[KEYMAP] act=0x%02X mapped{%d}%s: %s",
+                    act_lo,
+                    len(keys),
+                    row_summary,
+                    ", ".join(keys),
+                )
+                proxy._burst.finish(
+                    f"buttons:{act_lo}",
+                    can_issue=proxy.can_issue_commands,
+                    sender=proxy._send_cmd_frame,
+                )
+            return
+
+    def _burst_activity(self, proxy: "X1Proxy") -> int | None:
+        burst_kind = getattr(proxy._burst, "kind", None)
+        if proxy._burst.active and burst_kind and burst_kind.startswith("buttons:"):
+            try:
+                return int(burst_kind.split(":", 1)[1])
+            except ValueError:
+                return None
+        return None
+
+
+@register_handler(opcodes=(OP_REQ_COMMANDS,), directions=("A→H",))
+class RequestCommandsHandler(BaseFrameHandler):
+    """Log command list requests from the app."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        payload = frame.payload
+        dev_id = payload[0] if payload else 0
+        proxy._log.info("[DEVCTL] A→H requesting commands dev=0x%02X (%d)", dev_id, dev_id)
+
+
+@register_handler(opcodes=(OP_REQ_IDLE_BEHAVIOR,), directions=("A→H",))
+class RequestIdleBehaviorHandler(BaseFrameHandler):
+    """Log app requests for a device's idle/power behavior."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        payload = frame.payload
+        dev_id = payload[0] if payload else 0
+        proxy._log.info(
+            "[IDLE] A→H requesting idle behavior dev=0x%02X (%d)",
+            dev_id,
+            dev_id,
+        )
+
+
+@register_handler(opcodes=(OP_SET_IDLE_BEHAVIOR,), directions=("A→H",))
+class SetIdleBehaviorHandler(BaseFrameHandler):
+    """Track app-initiated idle/power behavior changes."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        payload = frame.payload
+        if len(payload) < 2:
+            proxy._log.info("[IDLE] A→H set idle behavior payload too short (%dB)", len(payload))
+            return
+
+        dev_id = payload[0]
+        mode = payload[1]
+        proxy.record_idle_behavior_value(dev_id, mode, source="app_set")
+
+
+@register_handler(opcodes=(OP_IDLE_BEHAVIOR,), directions=("H→A",))
+class IdleBehaviorHandler(BaseFrameHandler):
+    """Capture current device idle/power behavior replies from the hub."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        payload = frame.payload
+        if len(payload) < 2:
+            proxy._log.info("[IDLE] H→A idle behavior payload too short (%dB)", len(payload))
+            return
+
+        dev_id = payload[0]
+        mode = payload[1]
+        proxy.record_idle_behavior_value(dev_id, mode, source="hub_reply")
+
+
+class DeviceButtonSingleHandler(BaseFrameHandler):
+    """Handle single-command payloads and WiFi input-refresh labels."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        payload = frame.payload
+        raw = frame.raw
+        family = opcode_family(frame.opcode)
+
+        effective_opcode = (
+            OP_DEVBTN_SINGLE
+            if family in (FAMILY_DEVBTNS, 0x0D)
+            else frame.opcode
+        )
+
+        if len(payload) < 4:
+            return
+
+        if (
+            family == 0x0D
+            and len(payload) >= 16
+            and payload[:6] == b"\x01\x00\x01\x01\x00\x01"
+        ):
+            # 0x020C WiFi/input-config refresh replies return a single label
+            # using a distinct field layout from normal REQ_COMMANDS singles:
+            #   <dev_id> <slot_id> <fmt> ...
+            dev_id = payload[6]
+            command_id = payload[7]
+            if len(payload) >= 76 and payload[8] == 0x1C:
+                label = payload[16:76].decode("utf-16le", errors="ignore").split("\x00", 1)[0].strip()
+            else:
+                label_bytes = payload[15:45]
+                label = label_bytes.split(b"\x00", 1)[0].decode("ascii", errors="ignore").strip()
+            if label:
+                proxy.state.commands.setdefault(dev_id & 0xFF, {})[command_id & 0xFF] = label
+            return
+
+        dev_id = _extract_dev_id(
+            raw,
+            payload,
+            effective_opcode,
+            hub_version=proxy.hub_version,
+        )
+
+        now = time.monotonic()
+        burst_kind = proxy._burst.kind or ""
+        targeted_burst_key: str | None = None
+        if proxy._burst.active and burst_kind.startswith("commands:"):
+            # For targeted command fetches (commands:<dev>:<cmd>) we already
+            # have the response frame, so we can finish the burst as soon as
+            # this handler finishes processing the label and immediately drain
+            # the next queued request.
+            if burst_kind.count(":") >= 2:
+                targeted_burst_key = burst_kind
+                proxy._burst.last_ts = now
+            else:
+                proxy._burst.last_ts = now + proxy._burst.response_grace
+        else:
+            proxy._burst.start(f"commands:{dev_id}", now=now)
+
+        completed = proxy._command_assembler.feed(
+            effective_opcode,
+            raw,
+            dev_id_override=dev_id,
+            hub_version=proxy.hub_version,
+        )
+        for complete_dev_id, assembled_payload in completed:
+            commands = proxy.parse_device_commands(assembled_payload, complete_dev_id)
+            if (
+                effective_opcode == OP_DEVBTN_SINGLE
+                and len(assembled_payload) >= 2
+                and len(commands) == 1
+            ):
+                expected_cmd_id = assembled_payload[1]
+                parsed_cmd_id = next(iter(commands))
+                # Some X1S single-command responses encode the command tuple as:
+                #   <dev> <cmd> 0x1C ...
+                # The generic parser can lock onto 0x1C as the command id when
+                # scanning candidates, which causes the requested favorite label
+                # to be associated with cmd 28 instead of the real command.
+                if (
+                    parsed_cmd_id == 0x1C
+                    and expected_cmd_id not in (0x00, 0xFC)
+                    and expected_cmd_id != parsed_cmd_id
+                ):
+                    commands = {expected_cmd_id: next(iter(commands.values()))}
+            if commands:
+                dev_key = complete_dev_id & 0xFF
+                for cmd_id, label in commands.items():
+                    pair = (complete_dev_id, cmd_id)
+                    awaiting = proxy._favorite_label_requests.get(pair)
+                    awaiting_keybindings = proxy._keybinding_label_requests.get(pair)
+                    if awaiting or awaiting_keybindings:
+                        for act_id in awaiting or set():
+                            proxy.state.record_favorite_label(act_id, complete_dev_id, cmd_id, label)
+                        for act_id in awaiting_keybindings or set():
+                            proxy.state.record_keybinding_label(act_id, complete_dev_id, cmd_id, label)
+                        proxy._favorite_label_requests.pop(pair, None)
+                        proxy._keybinding_label_requests.pop(pair, None)
+                        continue
+
+                    pending_for_device = [
+                        candidate
+                        for candidate in set(proxy._favorite_label_requests) | set(proxy._keybinding_label_requests)
+                        if candidate[0] == complete_dev_id
+                    ]
+
+                    if len(pending_for_device) == 1:
+                        pending_pair = pending_for_device[0]
+                        pending_cmd_id = pending_pair[1]
+                        for act_id in proxy._favorite_label_requests.get(pending_pair, set()):
+                            proxy.state.record_favorite_label(
+                                act_id, complete_dev_id, pending_cmd_id, label
+                            )
+                        for act_id in proxy._keybinding_label_requests.get(pending_pair, set()):
+                            proxy.state.record_keybinding_label(
+                                act_id, complete_dev_id, pending_cmd_id, label
+                            )
+                        proxy._favorite_label_requests.pop(pending_pair, None)
+                        proxy._keybinding_label_requests.pop(pending_pair, None)
+
+                        cmds = proxy.state.commands.setdefault(dev_key, {})
+                        cmds[cmd_id] = label
+                        cmds[pending_cmd_id] = label
+                        continue
+
+                    proxy.state.commands.setdefault(dev_key, {})[cmd_id] = label
+
+                if dev_key in proxy.state.commands:
+                    proxy._log.info(
+                        " ".join(
+                            f"{cmd_id:2d} : {label}" for cmd_id, label in proxy.state.commands[dev_key].items()
+                        )
+                    )
+
+        if targeted_burst_key is not None:
+            proxy._burst.finish(
+                targeted_burst_key,
+                can_issue=proxy.can_issue_commands,
+                sender=proxy._send_cmd_frame,
+                now=now,
+            )
+
+
+class DeviceButtonHeaderHandler(BaseFrameHandler):
+    """Start device-command burst parsing."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        payload = frame.payload
+        raw = frame.raw
+
+        if len(payload) < 4:
+            return
+
+        dev_id = _extract_dev_id(
+            raw,
+            payload,
+            frame.opcode,
+            hub_version=proxy.hub_version,
+        )
+
+        now = time.monotonic()
+        burst_key = f"commands:{dev_id}"
+        proxy._burst.start(burst_key, now=now)
+
+        completed = proxy._command_assembler.feed(
+            frame.opcode,
+            raw,
+            dev_id_override=dev_id,
+            hub_version=proxy.hub_version,
+        )
+        for complete_dev_id, assembled_payload in completed:
+            commands = proxy.parse_device_commands(assembled_payload, complete_dev_id)
+            if commands:
+                dev_key = complete_dev_id & 0xFF
+                existing = proxy.state.commands.setdefault(dev_key, {})
+                existing.update(commands)
+                proxy._log.info(
+                    " ".join(f"{cmd_id:2d} : {label}" for cmd_id, label in existing.items())
+                )
+
+        if completed:
+            proxy._burst.finish(
+                burst_key,
+                can_issue=proxy.can_issue_commands,
+                sender=proxy._send_cmd_frame,
+                now=now,
+            )
+
+
+class DeviceButtonPayloadHandler(BaseFrameHandler):
+    """Accumulate device command pages."""
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy: X1Proxy = frame.proxy
+        payload = frame.payload
+        raw = frame.raw
+
+        if len(payload) < 4:
+            return
+
+        dev_id = _extract_dev_id(
+            raw,
+            payload,
+            frame.opcode,
+            hub_version=proxy.hub_version,
+        )
+
+        now = time.monotonic()
+        burst_key = f"commands:{dev_id}"
+        if not proxy._burst.active:
+            proxy._burst.start(burst_key, now=now)
+        else:
+            proxy._burst.last_ts = now + proxy._burst.response_grace
+
+        completed = proxy._command_assembler.feed(
+            frame.opcode,
+            raw,
+            dev_id_override=dev_id,
+            hub_version=proxy.hub_version,
+        )
+        for complete_dev_id, assembled_payload in completed:
+            commands = proxy.parse_device_commands(assembled_payload, complete_dev_id)
+            if commands:
+                dev_key = complete_dev_id & 0xFF
+                existing = proxy.state.commands.setdefault(dev_key, {})
+                existing.update(commands)
+                proxy._log.info(
+                    " ".join(f"{cmd_id:2d} : {label}" for cmd_id, label in existing.items())
+                )
+
+        if completed:
+            proxy._burst.finish(
+                burst_key,
+                can_issue=proxy.can_issue_commands,
+                sender=proxy._send_cmd_frame,
+                now=now,
+            )
+
+
+@register_handler(opcode_families_low=(FAMILY_DEVBTNS, 0x0D), directions=("H→A",))
+class DeviceButtonFamilyHandler(BaseFrameHandler):
+    """Route device-command family responses using parsed frame metadata."""
+
+    def __init__(self) -> None:
+        self._single = DeviceButtonSingleHandler()
+        self._header = DeviceButtonHeaderHandler()
+        self._payload = DeviceButtonPayloadHandler()
+
+    def handle(self, frame: FrameContext) -> None:
+        opcode = frame.opcode
+        burst_kind = str(frame.proxy._burst.kind or "")
+
+        if frame.proxy._burst.active and burst_kind.startswith("ir_dump:"):
+            parsed_ir_dump = parse_ir_command_dump_frame(opcode, frame.raw)
+            if parsed_ir_dump is not None:
+                frame.proxy._record_ir_dump_frame(parsed_ir_dump, frame.raw)
+                frame.proxy._burst.last_ts = time.monotonic() + frame.proxy._burst.response_grace
+                parts = burst_kind.split(":")
+                if len(parts) >= 3:
+                    try:
+                        request_key = (int(parts[1]) & 0xFF, int(parts[2]) & 0xFF)
+                    except ValueError:
+                        request_key = None
+                    if request_key is not None:
+                        frame.proxy.try_finish_ir_dump_burst(request_key)
+                return
+
+        parsed = decode_burst_frame(
+            opcode,
+            frame.raw,
+            hub_version=frame.proxy.hub_version,
+        )
+
+        if parsed is not None:
+            totals = (
+                f"{parsed.frame_no}/{parsed.total_frames}"
+                if parsed.total_frames is not None
+                else f"{parsed.frame_no}"
+            )
+            fmt = (
+                f" fmt=0x{parsed.format_marker:02X}"
+                if parsed.format_marker is not None
+                else ""
+            )
+            if parsed.layout_kind == "input_config_refresh":
+                slot = (
+                    f" slot=0x{parsed.first_command_id:02X}"
+                    if parsed.first_command_id is not None
+                    else ""
+                )
+                frame.proxy._log.debug(
+                    "[INPUT_REFRESH] role=%s variant=%s page=%s dev=0x%02X%s%s",
+                    parsed.role,
+                    parsed.layout_kind,
+                    totals,
+                    parsed.device_id,
+                    slot,
+                    fmt,
+                )
+            else:
+                first_cmd = (
+                    f" first_cmd=0x{parsed.first_command_id:02X}"
+                    if parsed.first_command_id is not None
+                    else ""
+                )
+                total_commands = (
+                    f" total_cmds={parsed.total_commands}"
+                    if parsed.total_commands is not None
+                    else ""
+                )
+                frame.proxy._log.debug(
+                    "[REQ_COMMANDS] role=%s variant=%s page=%s dev=0x%02X%s%s%s",
+                    parsed.role,
+                    parsed.layout_kind,
+                    totals,
+                    parsed.device_id,
+                    total_commands,
+                    first_cmd,
+                    fmt,
+                )
+
+        if parsed is None:
+            frame.proxy._log.debug(
+                "[REQ_COMMANDS] ignoring unparsed family frame opcode=0x%04X len=%d",
+                opcode,
+                len(frame.payload),
+            )
+            return
+
+        if parsed.is_single:
+            self._single.handle(frame)
+            return
+
+        if parsed.is_header:
+            self._header.handle(frame)
+            return
+
+        self._payload.handle(frame)
+
+
+@register_handler(opcode_families_low=(FAMILY_FAV_ORDER_RESP,), directions=("H→A",))
+class FavoritesOrderHandler(BaseFrameHandler):
+    """Parse hub response containing current favorites ordering for an activity.
+
+    Triggered by the app sending OP_FAV_ORDER_REQ (family 0x62 / opcode 0x0162).
+    The hub replies with a family-0x63 frame whose payload is:
+
+        [01 00 01 01 00 01] [act_lo] [fav_id slot] × N
+
+    Each (fav_id, slot) pair describes which hub-internal favorite identifier
+    occupies which display position (slot 1 = first shown).
+
+    After parsing the pairs are stored in ``proxy.state.activity_favorites_order``
+    and a synthetic ACK ``0xFF63`` is fired so that
+    ``wait_for_ack_any([(0xFF63, act_lo)])`` can unblock.
+    """
+
+    # Synthetic opcode used to signal completion via notify_ack
+    SYNTHETIC_ACK = 0xFF63
+
+    def handle(self, frame: FrameContext) -> None:
+        proxy = frame.proxy
+        payload = frame.payload
+
+        if proxy._try_handle_device_key_sort_payload(payload):
+            return
+
+        # Minimum: 6-byte fixed header + 1 act_lo byte
+        if len(payload) < 7:
+            proxy._log.debug("[FAV_ORDER] payload too short (%dB), skipping", len(payload))
+            return
+
+        act_lo = payload[6] & 0xFF
+        pairs_data = payload[7:]
+
+        if len(pairs_data) % 2 != 0:
+            proxy._log.warning(
+                "[FAV_ORDER] act=0x%02X odd pairs length %d, truncating",
+                act_lo,
+                len(pairs_data),
+            )
+            pairs_data = pairs_data[: len(pairs_data) - 1]
+
+        pairs: list[tuple[int, int]] = [
+            (pairs_data[i], pairs_data[i + 1])
+            for i in range(0, len(pairs_data), 2)
+        ]
+
+        proxy.state.activity_favorites_order[act_lo] = pairs
+        proxy._log.info(
+            "[FAV_ORDER] act=0x%02X received %d favorite(s): %s",
+            act_lo,
+            len(pairs),
+            " ".join(f"fav{fav}→slot{slot}" for fav, slot in pairs),
+        )
+
+        # Signal any waiting request_favorites_order() call
+        proxy.notify_ack(self.SYNTHETIC_ACK, bytes([act_lo]))
+