octo-bed-protocol 0.2.0__tar.gz

octo_bed_protocol-0.2.0/.gitignore

@@ -0,0 +1,16 @@
+.env
+.env.local
+
+__pycache__/
+*.pyc
+.venv/
+
+# Vendor app binaries and verbatim extracted third-party code. The protocol
+# description in docs/protocol.md is our own write-up and stays versioned;
+# the material it was derived from does not belong in this repository.
+reference/
+*.apk
+
+# Testartefakte - alles, was ein Lauf erzeugt, landet hier
+.artefakte/
+.ruff_cache/

octo_bed_protocol-0.2.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.5
+Name: octo-bed-protocol
+Version: 0.2.0
+Summary: Wire protocol of Octo adjustable bed controllers over Bluetooth Low Energy
+Project-URL: Homepage, https://github.com/skjall/home-assistant-octo-bed
+Project-URL: Source, https://github.com/skjall/home-assistant-octo-bed/tree/main/lib/octo_bed_protocol
+Project-URL: Issues, https://github.com/skjall/home-assistant-octo-bed/issues
+Author: Jan Großheim
+License-Expression: MIT
+Keywords: adjustable-bed,ble,bluetooth,home-assistant,octo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# octo-bed-protocol
+
+The wire protocol of Octo adjustable bed controllers (the RC2 receiver and its
+relatives) over Bluetooth Low Energy, as used by the
+[Octo Bed](https://github.com/skjall/home-assistant-octo-bed) Home Assistant
+integration.
+
+It builds frames and reads replies. It opens no connections and depends on no
+Bluetooth stack, so it can be used and tested without hardware.
+
+```python
+import octo_bed_protocol as octo
+
+octo.move(octo.MOTOR_HEAD, up=True).hex(" ")  # '40 02 70 00 01 0b 02 40'
+octo.stop().hex(" ")  # '40 02 73 00 00 0b 40'
+
+reader = octo.FrameReader()
+features = octo.Features()
+for packet in reader.feed(notification):
+    features.add(packet)
+```
+
+Every frame goes to characteristic `ffe1` of service `ffe0`. How each byte was
+established is recorded in
+[docs/protocol.md](https://github.com/skjall/home-assistant-octo-bed/blob/main/docs/protocol.md).
+
+Not affiliated with, endorsed by, or supported by Octo. All trademarks belong
+to their owners.

octo_bed_protocol-0.2.0/README.md

@@ -0,0 +1,28 @@
+# octo-bed-protocol
+
+The wire protocol of Octo adjustable bed controllers (the RC2 receiver and its
+relatives) over Bluetooth Low Energy, as used by the
+[Octo Bed](https://github.com/skjall/home-assistant-octo-bed) Home Assistant
+integration.
+
+It builds frames and reads replies. It opens no connections and depends on no
+Bluetooth stack, so it can be used and tested without hardware.
+
+```python
+import octo_bed_protocol as octo
+
+octo.move(octo.MOTOR_HEAD, up=True).hex(" ")  # '40 02 70 00 01 0b 02 40'
+octo.stop().hex(" ")  # '40 02 73 00 00 0b 40'
+
+reader = octo.FrameReader()
+features = octo.Features()
+for packet in reader.feed(notification):
+    features.add(packet)
+```
+
+Every frame goes to characteristic `ffe1` of service `ffe0`. How each byte was
+established is recorded in
+[docs/protocol.md](https://github.com/skjall/home-assistant-octo-bed/blob/main/docs/protocol.md).
+
+Not affiliated with, endorsed by, or supported by Octo. All trademarks belong
+to their owners.

octo_bed_protocol-0.2.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "octo-bed-protocol"
+version = "0.2.0" # x-release-please-version
+description = "Wire protocol of Octo adjustable bed controllers over Bluetooth Low Energy"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [{ name = "Jan Großheim" }]
+keywords = ["octo", "adjustable-bed", "bluetooth", "ble", "home-assistant"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Home Automation",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/skjall/home-assistant-octo-bed"
+Source = "https://github.com/skjall/home-assistant-octo-bed/tree/main/lib/octo_bed_protocol"
+Issues = "https://github.com/skjall/home-assistant-octo-bed/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/octo_bed_protocol"]
+
+[tool.pytest.ini_options]
+# Without this the repository's own pytest.ini applies here too and asks for
+# coverage of the integration, which this package knows nothing about.
+testpaths = ["tests"]
+addopts = ""

octo_bed_protocol-0.2.0/src/octo_bed_protocol/__init__.py

@@ -0,0 +1,61 @@
+"""Wire protocol of Octo adjustable bed controllers.
+
+This package knows how to build and read the bytes; it opens no connections
+and depends on no Bluetooth stack, so it can be tested without hardware.
+"""
+
+from .const import (
+    ADVERTISED_SERVICE_UUID,
+    CHAR_UUID,
+    MANUFACTURER,
+    MOTOR_3,
+    MOTOR_4,
+    MOTOR_BITS,
+    MOTOR_FEET,
+    MOTOR_HEAD,
+    NAME_PREFIXES,
+    REPLY_PIN_LOCK,
+    SERVICE_UUID,
+)
+from .protocol import (
+    Features,
+    FrameReader,
+    Packet,
+    build_frame,
+    checksum,
+    move,
+    pin,
+    pin_accepted,
+    read_listing,
+    recall_memory,
+    request_features,
+    set_light,
+    stop,
+)
+
+__all__ = [
+    "ADVERTISED_SERVICE_UUID",
+    "CHAR_UUID",
+    "MANUFACTURER",
+    "MOTOR_3",
+    "MOTOR_4",
+    "MOTOR_BITS",
+    "MOTOR_FEET",
+    "MOTOR_HEAD",
+    "NAME_PREFIXES",
+    "REPLY_PIN_LOCK",
+    "SERVICE_UUID",
+    "Features",
+    "FrameReader",
+    "Packet",
+    "build_frame",
+    "checksum",
+    "move",
+    "pin",
+    "pin_accepted",
+    "read_listing",
+    "recall_memory",
+    "request_features",
+    "set_light",
+    "stop",
+]

octo_bed_protocol-0.2.0/src/octo_bed_protocol/const.py

@@ -0,0 +1,63 @@
+"""Identifiers and command words of Octo bed controllers."""
+
+from typing import Final
+
+MANUFACTURER: Final = "Octo"
+
+# Every frame travels over this one characteristic, in both directions: writes
+# carry commands, notifications carry the answers.
+SERVICE_UUID: Final = "0000ffe0-0000-1000-8000-00805f9b34fb"
+CHAR_UUID: Final = "0000ffe1-0000-1000-8000-00805f9b34fb"
+
+# Advertised next to FFE0 by the RC2 receivers this was verified against.
+# FFE0 alone is shared with several other bed families, and the local name is
+# not reliable either: one of the two receivers advertised garbage instead of
+# "RC2". This UUID is what both had in common.
+ADVERTISED_SERVICE_UUID: Final = "58debc00-4083-4735-8926-6721a778ae5e"
+
+# Names the vendor app lists for Octo receivers, matched as prefixes.
+NAME_PREFIXES: Final = (
+    "RC2",
+    "RC3",
+    "MC1",
+    "MC2",
+    "RTV",
+    "L2M",
+    "CLI",
+    "BMB",
+    "BMS",
+    "BM3",
+    "OCTOBRICK",
+    "OCTOIQ",
+)
+
+FRAME_DELIMITER: Final = 0x40
+
+# Commands to the receiver. A reply sets bit 0 of the first byte.
+CMD_MOVE_UP: Final = b"\x02\x70"
+CMD_MOVE_DOWN: Final = b"\x02\x71"
+CMD_MEMORY_RECALL: Final = b"\x02\x72"
+CMD_STOP: Final = b"\x02\x73"
+CMD_PIN: Final = b"\x20\x43"
+CMD_FEATURES: Final = b"\x20\x71"
+CMD_SET_FEATURE: Final = b"\x20\x72"
+
+# Notifications from the receiver.
+REPLY_PIN_STATE: Final = b"\x21\x43"
+REPLY_PIN_LOCK: Final = b"\x21\x44"
+REPLY_FEATURE: Final = b"\x21\x71"
+
+# Motor bits of the move command. M1 lifts the back, M2 the legs.
+MOTOR_HEAD: Final = 0x02
+MOTOR_FEET: Final = 0x04
+MOTOR_3: Final = 0x08
+MOTOR_4: Final = 0x10
+MOTOR_BITS: Final = (MOTOR_HEAD, MOTOR_FEET, MOTOR_3, MOTOR_4)
+
+# Feature ids the receiver lists in answer to CMD_FEATURES.
+FEATURE_MOTOR_COUNT: Final = 0x000001
+FEATURE_MEMORY_COUNT: Final = 0x000002
+FEATURE_PIN: Final = 0x000003
+FEATURE_MEMORY_INFO: Final = 0x000004
+FEATURE_LIGHT: Final = 0x000102
+FEATURE_END: Final = 0xFFFFFF

octo_bed_protocol-0.2.0/src/octo_bed_protocol/protocol.py

@@ -0,0 +1,285 @@
+"""The wire format: building frames, and reading what the receiver sends back.
+
+A frame is ``40 | command (2) | data length (2, big-endian) | checksum | data |
+40``. The checksum makes the byte sum of the whole frame, both delimiters
+included, come out as zero.
+
+Between the delimiters the vendor app escapes the four bytes that would
+otherwise be taken for framing. None of the commands this package builds
+happens to contain one, which is why the escape never showed up in a capture.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .const import (
+    CMD_FEATURES,
+    CMD_MEMORY_RECALL,
+    CMD_MOVE_DOWN,
+    CMD_MOVE_UP,
+    CMD_PIN,
+    CMD_SET_FEATURE,
+    CMD_STOP,
+    FEATURE_END,
+    FEATURE_LIGHT,
+    FEATURE_MEMORY_COUNT,
+    FEATURE_MEMORY_INFO,
+    FEATURE_MOTOR_COUNT,
+    FEATURE_PIN,
+    FRAME_DELIMITER,
+    MOTOR_BITS,
+    REPLY_FEATURE,
+    REPLY_PIN_STATE,
+)
+
+_ESCAPE = 0x3C
+_ESCAPED = {0x40: 0x01, 0x3C: 0x02, 0x4F: 0x03, 0x41: 0x04}
+_UNESCAPED = {value: key for key, value in _ESCAPED.items()}
+
+# Longest frame that is still believable. A buffer that grows past this without
+# a closing delimiter is noise, not a frame that is still arriving.
+_MAX_FRAME = 256
+
+
+def checksum(frame: bytes) -> int:
+    """Return the byte that makes the frame sum to zero.
+
+    The checksum position itself is expected to hold zero while summing.
+    """
+    return (-sum(frame)) & 0xFF
+
+
+def _escape(payload: bytes) -> bytes:
+    out = bytearray()
+    for byte in payload:
+        if byte in _ESCAPED:
+            out += bytes((_ESCAPE, _ESCAPED[byte]))
+        else:
+            out.append(byte)
+    return bytes(out)
+
+
+def _unescape(payload: bytes) -> bytes | None:
+    out = bytearray()
+    it = iter(payload)
+    for byte in it:
+        if byte != _ESCAPE:
+            out.append(byte)
+            continue
+        code = next(it, None)
+        if code not in _UNESCAPED:
+            return None
+        out.append(_UNESCAPED[code])
+    return bytes(out)
+
+
+def build_frame(command: bytes, data: bytes = b"") -> bytes:
+    """Wrap one command and its data into a frame."""
+    if len(command) != 2:
+        raise ValueError("a command is two bytes")
+    body = bytearray(command)
+    body += len(data).to_bytes(2, "big")
+    body.append(0)
+    body += data
+    body[4] = checksum(bytes((FRAME_DELIMITER, *body, FRAME_DELIMITER)))
+    return bytes((FRAME_DELIMITER, *_escape(bytes(body)), FRAME_DELIMITER))
+
+
+def move(motors: int, up: bool) -> bytes:
+    """Run the given motors one step; the receiver stops unless it is repeated."""
+    if not motors or motors & ~sum(MOTOR_BITS):
+        raise ValueError(f"not a motor mask: {motors:#x}")
+    return build_frame(CMD_MOVE_UP if up else CMD_MOVE_DOWN, bytes((motors,)))
+
+
+def stop() -> bytes:
+    """Stop every motor."""
+    return build_frame(CMD_STOP)
+
+
+def recall_memory(slot: int) -> bytes:
+    """Drive one step towards a stored position (slot counted from zero)."""
+    if not 0 <= slot <= 0xFF:
+        raise ValueError(f"not a memory slot: {slot}")
+    return build_frame(CMD_MEMORY_RECALL, bytes((slot,)))
+
+
+def pin(digits: str) -> bytes:
+    """Unlock the receiver: four digits, one raw byte each."""
+    if len(digits) != 4 or not digits.isdigit():
+        raise ValueError("the PIN is four digits")
+    return build_frame(CMD_PIN, bytes(int(c) for c in digits))
+
+
+def request_features() -> bytes:
+    """Ask the receiver which motors, memories and light it has."""
+    return build_frame(CMD_FEATURES)
+
+
+def set_light(on: bool) -> bytes:
+    """Switch the under-bed light.
+
+    A feature record: id 0x000102, flag, one characteristic byte, value type,
+    then the value. Byte for byte what the vendor app sends.
+    """
+    record = FEATURE_LIGHT.to_bytes(3, "big") + bytes((1, 1, 1, 1, int(on)))
+    return build_frame(CMD_SET_FEATURE, record)
+
+
+@dataclass(frozen=True)
+class Packet:
+    """One frame received from the bed, already checked."""
+
+    command: bytes
+    data: bytes
+
+
+class FrameReader:
+    """Reassemble frames from notifications.
+
+    A frame may be split across notifications, and one notification may carry
+    several frames. Frames are cut by their length field first, which is how
+    smartbed-mqtt reads replies from real receivers: unescaped, so a 0x40
+    inside the data or the checksum is not a delimiter. Only a frame that does
+    not add up that way is tried again as the escaped form the app notes
+    describe. Anything that fits neither is
+    dropped rather than guessed at.
+    """
+
+    def __init__(self) -> None:
+        """Start with nothing buffered."""
+        self._buffer = bytearray()
+
+    def feed(self, chunk: bytes) -> list[Packet]:
+        """Take one notification, return every frame it completed."""
+        self._buffer += chunk
+        packets: list[Packet] = []
+        while True:
+            start = self._buffer.find(FRAME_DELIMITER)
+            if start < 0:
+                self._buffer.clear()
+                return packets
+            del self._buffer[:start]
+            taken = self._take()
+            if taken is _INCOMPLETE:
+                if len(self._buffer) > _MAX_FRAME:
+                    self._buffer.clear()
+                return packets
+            if taken is None:
+                # Not a frame that starts here; look for the next start.
+                del self._buffer[:1]
+                continue
+            assert isinstance(taken, Packet)
+            packets.append(taken)
+
+    def _take(self) -> Packet | _Incomplete | None:
+        """Cut one frame off the front of the buffer, if one is complete."""
+        buffer = self._buffer
+        if len(buffer) < 7:
+            return _INCOMPLETE
+        total = 7 + int.from_bytes(buffer[3:5], "big")
+        if total > _MAX_FRAME:
+            return None
+        if len(buffer) < total:
+            # An escaped frame is longer than its length field says, never
+            # shorter, so it cannot be complete either.
+            return _INCOMPLETE
+        if buffer[total - 1] == FRAME_DELIMITER and not sum(buffer[:total]) & 0xFF:
+            packet = Packet(
+                command=bytes(buffer[1:3]), data=bytes(buffer[6 : total - 1])
+            )
+            del buffer[:total]
+            return packet
+        end = buffer.find(FRAME_DELIMITER, 1)
+        if end < 0:
+            return _INCOMPLETE
+        if (packet := _decode_escaped(bytes(buffer[1:end]))) is not None:
+            del buffer[: end + 1]
+            return packet
+        return None
+
+
+class _Incomplete:
+    """The frame at the front of the buffer has not fully arrived yet."""
+
+
+_INCOMPLETE = _Incomplete()
+
+
+def _decode_escaped(raw: bytes) -> Packet | None:
+    body = _unescape(raw)
+    if body is None or len(body) < 5:
+        return None
+    length = int.from_bytes(body[2:4], "big")
+    if len(body) != 5 + length:
+        return None
+    if sum((FRAME_DELIMITER, *body, FRAME_DELIMITER)) & 0xFF:
+        return None
+    return Packet(command=body[:2], data=body[5:])
+
+
+def read_listing(chunks: list[bytes]) -> Features:
+    """Read the features out of a listing as it was received."""
+    reader = FrameReader()
+    features = Features()
+    for chunk in chunks:
+        for packet in reader.feed(chunk):
+            features.add(packet)
+    return features
+
+
+def pin_accepted(packet: Packet) -> bool | None:
+    """Return whether a PIN state reply says unlocked, or None for other frames."""
+    if packet.command != REPLY_PIN_STATE:
+        return None
+    return bool(packet.data) and packet.data[0] == 1
+
+
+@dataclass
+class Features:
+    """What the receiver says about itself, one record at a time."""
+
+    motor_count: int | None = None
+    memory_count: int = 0
+    memory_kinds: list[int] = field(default_factory=list)
+    has_light: bool = False
+    light_on: bool = False
+    pin_set: bool = False
+    pin_unlocked: bool = True
+    complete: bool = False
+
+    def add(self, packet: Packet) -> None:
+        """Take one feature record into account."""
+        if packet.command != REPLY_FEATURE or len(packet.data) < 5:
+            return
+        data = packet.data
+        feature = int.from_bytes(data[0:3], "big")
+        # A flag, then a length-prefixed characteristic, then one byte of value
+        # type, then the value.
+        characteristic = data[5 : 5 + data[4]]
+        value = data[6 + data[4] :]
+        if feature == FEATURE_END:
+            self.complete = True
+        elif feature == FEATURE_MOTOR_COUNT:
+            # The RC2 carries the count in the characteristic and sends no
+            # value at all: 00 00 01 | 01 | 01 | 02 | 00. A value, where a
+            # receiver sends one, is what the app notes describe.
+            count = value or characteristic
+            if count:
+                self.motor_count = count[0]
+        elif feature == FEATURE_MEMORY_COUNT and value:
+            self.memory_count = value[0]
+        elif feature == FEATURE_MEMORY_INFO:
+            self.memory_kinds = list(value)
+        elif feature == FEATURE_PIN and value:
+            self.pin_set = value[0] == 1
+            self.pin_unlocked = len(value) < 2 or value[1] == 1
+        elif feature == FEATURE_LIGHT:
+            self.has_light = True
+            self.light_on = bool(value) and value[0] == 1
+
+    def motor_mask(self) -> int:
+        """Return the bits of every motor the receiver drives."""
+        count = min(self.motor_count or 0, len(MOTOR_BITS))
+        return sum(MOTOR_BITS[:count])

octo_bed_protocol-0.2.0/tests/test_protocol.py

@@ -0,0 +1,263 @@
+"""The wire format, checked against frames the vendor app was seen to send."""
+
+import pytest
+from octo_bed_protocol import (
+    MOTOR_3,
+    MOTOR_4,
+    MOTOR_FEET,
+    MOTOR_HEAD,
+    Features,
+    FrameReader,
+    Packet,
+    build_frame,
+    move,
+    pin,
+    pin_accepted,
+    read_listing,
+    recall_memory,
+    request_features,
+    set_light,
+    stop,
+)
+
+BOTH = MOTOR_HEAD | MOTOR_FEET
+
+
+def frame(text: str) -> bytes:
+    return bytes.fromhex(text)
+
+
+# Captured from the vendor app, and sent by the ESPHome setup this package
+# replaces for months without complaint.
+@pytest.mark.parametrize(
+    ("motors", "up", "captured"),
+    [
+        (MOTOR_HEAD, True, "40 02 70 00 01 0b 02 40"),
+        (MOTOR_HEAD, False, "40 02 71 00 01 0a 02 40"),
+        (MOTOR_FEET, True, "40 02 70 00 01 09 04 40"),
+        (MOTOR_FEET, False, "40 02 71 00 01 08 04 40"),
+        (BOTH, True, "40 02 70 00 01 07 06 40"),
+        (BOTH, False, "40 02 71 00 01 06 06 40"),
+    ],
+)
+def test_move_matches_the_capture(motors: int, up: bool, captured: str) -> None:
+    assert move(motors, up) == frame(captured)
+
+
+def test_stop_matches_the_capture() -> None:
+    assert stop() == frame("40 02 73 00 00 0b 40")
+
+
+def test_light_matches_the_capture() -> None:
+    assert set_light(True) == frame("40 20 72 00 08 de 00 01 02 01 01 01 01 01 40")
+    assert set_light(False) == frame("40 20 72 00 08 df 00 01 02 01 01 01 01 00 40")
+
+
+def test_pin_is_four_raw_digits() -> None:
+    assert pin("2345") == frame("40 20 43 00 04 0b 02 03 04 05 40")
+
+
+@pytest.mark.parametrize("digits", ["123", "12345", "12a4", ""])
+def test_pin_rejects_anything_but_four_digits(digits: str) -> None:
+    with pytest.raises(ValueError):
+        pin(digits)
+
+
+def test_every_frame_sums_to_zero() -> None:
+    for built in (
+        move(MOTOR_3 | MOTOR_4, True),
+        recall_memory(2),
+        request_features(),
+        pin("9999"),
+    ):
+        assert sum(built) & 0xFF == 0
+
+
+def test_feature_request() -> None:
+    assert request_features() == frame("40 20 71 00 00 ef 40")
+
+
+def test_memory_recall() -> None:
+    assert recall_memory(0) == frame("40 02 72 00 01 0b 00 40")
+    with pytest.raises(ValueError):
+        recall_memory(256)
+
+
+@pytest.mark.parametrize("mask", [0, 0x01, 0x20, 0x06 | 0x40])
+def test_move_rejects_what_is_not_a_motor(mask: int) -> None:
+    with pytest.raises(ValueError):
+        move(mask, True)
+
+
+def test_build_frame_wants_a_two_byte_command() -> None:
+    with pytest.raises(ValueError):
+        build_frame(b"\x02")
+
+
+def test_framing_bytes_in_the_payload_are_escaped() -> None:
+    built = build_frame(b"\x02\x70", bytes((0x40, 0x3C, 0x4F, 0x41)))
+    inner = built[1:-1]
+    assert 0x40 not in inner
+    assert bytes((0x3C, 0x01)) in inner
+    # And a reader takes it apart again.
+    [packet] = FrameReader().feed(built)
+    assert packet.data == bytes((0x40, 0x3C, 0x4F, 0x41))
+
+
+def _feature(feature: int, value: bytes, characteristic: bytes = b"\x01") -> bytes:
+    record = (
+        feature.to_bytes(3, "big")
+        + bytes((1, len(characteristic)))
+        + characteristic
+        + b"\x01"
+        + value
+    )
+    return build_frame(b"\x21\x71", record)
+
+
+def test_reader_reassembles_split_and_joined_frames() -> None:
+    reader = FrameReader()
+    first = _feature(0x000001, b"\x02")
+    second = _feature(0x000102, b"\x01")
+    assert reader.feed(first[:4]) == []
+    packets = reader.feed(first[4:] + second)
+    assert [p.command for p in packets] == [b"\x21\x71", b"\x21\x71"]
+
+
+def test_reader_drops_what_does_not_add_up() -> None:
+    reader = FrameReader()
+    good = _feature(0x000001, b"\x02")
+    bad_checksum = bytearray(good)
+    bad_checksum[5] ^= 0xFF
+    bad_length = bytearray(good)
+    bad_length[4] += 1
+    bad_escape = bytes((0x40, 0x21, 0x71, 0x3C, 0x09, 0x40))
+    packets = reader.feed(
+        b"noise" + bytes(bad_checksum) + bytes(bad_length) + bad_escape + good
+    )
+    assert len(packets) == 1
+
+
+def test_reader_forgets_a_frame_that_never_ends() -> None:
+    reader = FrameReader()
+    assert reader.feed(bytes((0x40,)) + bytes(300)) == []
+    assert reader.feed(stop()) == [Packet(command=b"\x02\x73", data=b"")]
+
+
+def test_reader_without_any_delimiter() -> None:
+    assert FrameReader().feed(b"\x01\x02") == []
+
+
+def test_features_from_a_full_listing() -> None:
+    reader = FrameReader()
+    features = Features()
+    listing = (
+        _feature(0x000001, b"\x02")
+        + _feature(0x000002, b"\x04")
+        + _feature(0x000004, b"\x01\x02\x03\x04", characteristic=b"\x04\x00\x00")
+        + _feature(0x000003, b"\x01\x01")
+        + _feature(0x000101, b"")
+        + _feature(0x000102, b"\x01")
+        + _feature(0xFFFFFF, b"")
+    )
+    for packet in reader.feed(listing):
+        features.add(packet)
+    assert features.complete
+    assert features.motor_count == 2
+    assert features.motor_mask() == BOTH
+    assert features.memory_count == 4
+    assert features.memory_kinds == [1, 2, 3, 4]
+    assert features.pin_set
+    assert features.pin_unlocked
+    assert features.has_light
+    assert features.light_on
+
+
+def test_features_ignore_other_frames() -> None:
+    features = Features()
+    features.add(Packet(command=b"\x21\x43", data=b"\x01"))
+    features.add(Packet(command=b"\x21\x71", data=b"\x00"))
+    assert features == Features()
+
+
+def test_locked_pin_and_no_light() -> None:
+    features = Features()
+    [packet] = FrameReader().feed(_feature(0x000003, b"\x01\x00"))
+    features.add(packet)
+    assert features.pin_set
+    assert not features.pin_unlocked
+    assert not features.has_light
+    assert features.motor_mask() == 0
+
+
+def test_pin_state_reply() -> None:
+    assert pin_accepted(Packet(command=b"\x21\x43", data=b"\x01")) is True
+    assert pin_accepted(Packet(command=b"\x21\x43", data=b"\x00")) is False
+    assert pin_accepted(Packet(command=b"\x21\x43", data=b"")) is False
+    assert pin_accepted(Packet(command=b"\x21\x71", data=b"\x01")) is None
+
+
+def _unescaped(command: bytes, data: bytes) -> bytes:
+    """A frame the way the RC2 sends its replies: no escaping at all."""
+    body = bytearray(command) + len(data).to_bytes(2, "big") + b"\x00" + data
+    body[4] = (-(0x80 + sum(body))) & 0xFF
+    return bytes((0x40, *body, 0x40))
+
+
+def test_an_unescaped_delimiter_in_the_data_is_data() -> None:
+    record = bytes.fromhex("00 00 01 01 01 40 01 02")
+    frame = _unescaped(b"\x21\x71", record)
+    [packet] = FrameReader().feed(frame)
+    assert packet.data == record
+
+
+def test_an_unescaped_delimiter_as_checksum() -> None:
+    reader = FrameReader()
+    # Search a record whose checksum comes out as 0x40.
+    for value in range(256):
+        frame = _unescaped(b"\x21\x71", bytes((0, 0, 1, 1, 1, 1, 1, value)))
+        if frame[5] == 0x40:
+            break
+    else:  # pragma: no cover
+        raise AssertionError("no such record")
+    features = Features()
+    for packet in reader.feed(
+        frame + _unescaped(b"\x21\x71", bytes.fromhex("ff ff ff 00 00 00"))
+    ):
+        features.add(packet)
+    assert features.motor_count == value
+    assert features.complete
+
+
+def test_a_frame_split_before_its_length_is_known() -> None:
+    reader = FrameReader()
+    frame = _unescaped(b"\x21\x71", bytes.fromhex("00 00 01 01 01 01 01 02"))
+    assert reader.feed(frame[:3]) == []
+    assert reader.feed(frame[3:9]) == []
+    assert len(reader.feed(frame[9:])) == 1
+
+
+# The listing both RC2 receivers here sent, notification by notification.
+RC2_LISTING = [
+    bytes.fromhex("40 21 71 00 07 e2 00 00 01 01 01 02 00 40"),
+    bytes.fromhex("40 21 71 00 08 df 00 01 02 01 01 01 01 00 40"),
+    bytes.fromhex("40 21 71 00 08 d2 00 00 10 01 01 01 01 00 40"),
+    bytes.fromhex("40 21 71 00 06 ea ff ff ff 01 00 00 40"),
+]
+
+
+def test_the_rc2_listing() -> None:
+    """Two motors in the characteristic, a light that is off, no PIN."""
+    features = read_listing(RC2_LISTING)
+    assert features.complete
+    assert features.motor_count == 2
+    assert features.motor_mask() == MOTOR_HEAD | MOTOR_FEET
+    assert features.has_light
+    assert not features.light_on
+    assert not features.pin_set
+    assert features.memory_count == 0
+
+
+def test_a_motor_count_without_any_bytes() -> None:
+    frame = build_frame(b"\x21\x71", bytes.fromhex("00 00 01 01 00 00"))
+    assert read_listing([frame]).motor_count is None