From 2e502c8c63f0b452f8ce1b3ac7256d888f682fef Mon Sep 17 00:00:00 2001 From: gabriel Date: Wed, 18 Nov 2026 13:14:42 +0100 Subject: [PATCH 1/9] feat: classify a device and plan its setup steps (opendisplay.setup) device_state() says where a device stands from SEC_STATUS, the READ_IDENT tail bits or the advertisement: legacy, virgin, fresh, gesture, open, claimed, claimed in claim mode, locked, unknown. plan_setup() lists the steps for it. Both are pure, ported case by case from the website's wizard planner (Web od-wizard.js and its tests, v3/website b7df514). Added to the port, from our hardware work: - a display with no config, or one that needs migration, is configured and its panel checked before it is claimed, since it cannot show the claim code otherwise (unless claim mode has locked the config); - a 2.x device is backed up, given 3.0 and confirmed first, and planned again once it runs 3.0; - a device in claim mode whose owner wants no key leaves claim mode first (USE_WITHOUT_KEY). DeviceIdent gains the SECURITY_V2 tail bits (sec2, claimed, claim_mode, legacy_secrets_open). Claude-Session: https://claude.ai/code/session_01Ap1E7UWkx9cYSPdYvmgmu3 --- src/opendisplay/models/ident.py | 24 +++ src/opendisplay/setup/__init__.py | 10 ++ src/opendisplay/setup/planner.py | 151 ++++++++++++++++++ src/opendisplay/setup/state.py | 80 ++++++++++ tests/unit/setup/test_planner.py | 255 ++++++++++++++++++++++++++++++ tests/unit/test_read_ident.py | 15 ++ 6 files changed, 535 insertions(+) create mode 100644 src/opendisplay/setup/__init__.py create mode 100644 src/opendisplay/setup/planner.py create mode 100644 src/opendisplay/setup/state.py create mode 100644 tests/unit/setup/test_planner.py diff --git a/src/opendisplay/models/ident.py b/src/opendisplay/models/ident.py index 963c2f7..8afd519 100644 --- a/src/opendisplay/models/ident.py +++ b/src/opendisplay/models/ident.py @@ -17,6 +17,10 @@ IDENT_FLAG_CONFIG_DRIVEN = 0x01 IDENT_FLAG_NEEDS_MIGRATION = 0x02 IDENT_FLAG_BUILTIN_DRIVER = 0x04 +IDENT_FLAG_SEC_V2 = 0x08 +IDENT_FLAG_CLAIMED = 0x10 +IDENT_FLAG_CLAIM_MODE = 0x20 +IDENT_FLAG_LEGACY_SECRETS_OPEN = 0x40 IDENT_ESC_WINDOW = 0x01 IDENT_ESC_FILL = 0x02 @@ -90,6 +94,26 @@ def builtin_driver(self) -> bool | None: """A display is driven by a built-in controller driver (packet 0xB3).""" return self._flag(IDENT_FLAG_BUILTIN_DRIVER) + @property + def sec2(self) -> bool | None: + """The firmware speaks SECURITY_V2 (claim, sealed sessions).""" + return self._flag(IDENT_FLAG_SEC_V2) + + @property + def claimed(self) -> bool | None: + """The device is claimed (advisory: READ_IDENT is unauthenticated).""" + return self._flag(IDENT_FLAG_CLAIMED) + + @property + def claim_mode(self) -> bool | None: + """The device is in claim mode.""" + return self._flag(IDENT_FLAG_CLAIM_MODE) + + @property + def legacy_secrets_open(self) -> bool | None: + """Unclaimed, but the stored config still holds 2.x secrets.""" + return self._flag(IDENT_FLAG_LEGACY_SECRETS_OPEN) + @property def supports_window(self) -> bool | None: """The drive-sequence WINDOW escape (0x0C) is compiled in.""" diff --git a/src/opendisplay/setup/__init__.py b/src/opendisplay/setup/__init__.py new file mode 100644 index 0000000..b031e38 --- /dev/null +++ b/src/opendisplay/setup/__init__.py @@ -0,0 +1,10 @@ +"""The setup and upgrade flow: where a device stands, and the steps that take it to set up. + +``device_state()`` classifies a device from what it signals; ``plan_setup()`` lists the steps. Both +are pure; a runner performs them. Ported from the website's wizard planner (Web ``od-wizard.js``). +""" + +from .planner import SetupPlan, Step, plan_setup +from .state import DeviceState, device_state + +__all__ = ["DeviceState", "SetupPlan", "Step", "device_state", "plan_setup"] diff --git a/src/opendisplay/setup/planner.py b/src/opendisplay/setup/planner.py new file mode 100644 index 0000000..90d06e9 --- /dev/null +++ b/src/opendisplay/setup/planner.py @@ -0,0 +1,151 @@ +"""``plan_setup()``: the ordered steps for a device (Web ``planWizard`` and ``planMigrationAssistant``). + +The website's wizard, with the rules our hardware work added: + +- a display with no config, or one that needs migration, is configured (and its panel checked) + before it is claimed: it cannot show the claim code otherwise; +- a 2.x device is backed up, given 3.0 and confirmed first; the plan is made again once it runs 3.0; +- a device in claim mode whose owner wants no key leaves claim mode first. + +``notes`` carry the wizard's text keys unchanged (``awaiting_claim``, ``claim_choice``, ...), so a +caller can show its own texts. An empty ``steps`` means nothing to do, or a choice first +(``claim_choice``: claim, or use without a key). +""" + +from __future__ import annotations + +from dataclasses import dataclass +from enum import Enum +from typing import TYPE_CHECKING + +from .state import DeviceState + +if TYPE_CHECKING: + from ..models.profile import DeviceProfile + from ..sec2.wire import SecStatus + + +class Step(Enum): + """One step of the flow, in the order they run.""" + + BACK_UP = "back_up" + INSTALL_3_0 = "install_3_0" + CONFIRM_IMAGE = "confirm_image" + USE_WITHOUT_KEY = "use_without_key" # leave claim mode, unclaimed + CONFIGURE_DISPLAY = "configure_display" + VERIFY_PANEL = "verify_panel" + CLAIM = "claim" + ROTATE_KEY = "rotate_key" + SECRETS = "secrets" + DONE = "done" + + +@dataclass(frozen=True) +class SetupPlan: + """What to do: the state it was planned from, the steps, and the text keys to show.""" + + state: DeviceState + steps: tuple[Step, ...] + notes: tuple[str, ...] + + +_CLAIM_MODE_STATES = (DeviceState.VIRGIN, DeviceState.FRESH, DeviceState.GESTURE) +_CONFIGURE = (Step.CONFIGURE_DISPLAY, Step.VERIFY_PANEL) + + +def _configure_needed(profile: DeviceProfile | None) -> bool: + return profile is not None and (not profile.configured or profile.needs_migration) + + +def _claim_mode_steps( + state: DeviceState, profile: DeviceProfile | None, status: SecStatus | None, want_key: bool | None +) -> tuple[list[Step], list[str]]: + configure = _configure_needed(profile) + if want_key is False: + return [Step.USE_WITHOUT_KEY, *(_CONFIGURE if configure else ())], ["use_without_key"] + locked = status is not None and status.config_locked + steps: list[Step] = [] + if not locked and (configure or state is DeviceState.VIRGIN): + steps.append(Step.CONFIGURE_DISPLAY) + if not locked and (configure or state in (DeviceState.VIRGIN, DeviceState.FRESH)): + steps.append(Step.VERIFY_PANEL) + return [*steps, Step.CLAIM, Step.SECRETS], ["awaiting_claim"] + + +def _open_steps( + profile: DeviceProfile | None, status: SecStatus | None, want_key: bool | None +) -> tuple[list[Step], list[str]]: + configure = list(_CONFIGURE) if _configure_needed(profile) else [] + notes = ["needs_migration"] if profile is not None and profile.needs_migration else [] + secrets = status is not None and status.legacy_secrets_open + if secrets: + notes.append("legacy_secrets") + if want_key is None: + return [], [*notes, "claim_choice"] + if want_key is False: + return configure, [*notes, "use_without_key"] + return [*configure, Step.CLAIM, Step.SECRETS], [*notes, "gesture", *(["change_wifi"] if secrets else [])] + + +def _claimed_steps( + profile: DeviceProfile | None, status: SecStatus | None, rotate_legacy_key: bool +) -> tuple[list[Step], list[str]]: + steps = list(_CONFIGURE) if _configure_needed(profile) else [] + notes = ["needs_migration"] if profile is not None and profile.needs_migration else [] + if status is not None and (status.rotation_suggested or status.key_legacy): + if rotate_legacy_key: + steps.append(Step.ROTATE_KEY) + notes.append("rotation_one_way") + else: + notes.append("rotation_pending") + return steps, notes + + +def _legacy_steps(want_key: bool | None) -> tuple[list[Step], list[str]]: + install = [Step.BACK_UP, Step.INSTALL_3_0, Step.CONFIRM_IMAGE] + notes = ["replan_after_install"] + if want_key is False: # a wired install leaves it in claim mode + return [*install, Step.USE_WITHOUT_KEY, *_CONFIGURE], [*notes, "use_without_key"] + if want_key is None: + return [*install, *_CONFIGURE], [*notes, "claim_choice"] + return [*install, *_CONFIGURE, Step.CLAIM, Step.SECRETS], notes + + +def plan_setup( + *, + state: DeviceState, + profile: DeviceProfile | None, + sec_status: SecStatus | None, + want_key: bool | None = None, + rotate_legacy_key: bool = True, +) -> SetupPlan: + """The steps for a device in ``state``. + + Args: + state: From :func:`device_state`. + profile: The device's profile (whether it is configured, whether it needs migration); + ``None`` when it is not known yet, as before a 2.x device runs 3.0. + sec_status: SEC_STATUS, when read. + want_key: ``True`` to claim, ``False`` to use the device without a key, ``None`` not + decided yet (an open device then asks). + rotate_legacy_key: Replace a key carried over from 2.x on a claimed device. + """ + steps: list[Step] + notes: list[str] + if state in _CLAIM_MODE_STATES: + steps, notes = _claim_mode_steps(state, profile, sec_status, want_key) + elif state is DeviceState.OPEN: + steps, notes = _open_steps(profile, sec_status, want_key) + elif state is DeviceState.CLAIMED: + steps, notes = _claimed_steps(profile, sec_status, rotate_legacy_key) + elif state is DeviceState.CLAIMED_IN_CLAIM_MODE: + steps, notes = [Step.SECRETS], [] + elif state is DeviceState.LEGACY: + steps, notes = _legacy_steps(want_key) + elif state is DeviceState.LOCKED: + steps, notes = [], ["locked", "factory_reset"] + else: + steps, notes = [], ["identify"] + if steps: + steps.append(Step.DONE) + return SetupPlan(state=state, steps=tuple(steps), notes=tuple(notes)) diff --git a/src/opendisplay/setup/state.py b/src/opendisplay/setup/state.py new file mode 100644 index 0000000..9747b1f --- /dev/null +++ b/src/opendisplay/setup/state.py @@ -0,0 +1,80 @@ +"""``device_state()``: where a device stands (SECURITY_V2 § 5.3.1 / § 15.1; Web ``deviceState``). + +SEC_STATUS is preferred, then the READ_IDENT tail bits, then the advertisement's status byte. +Every input is unauthenticated and so advisory: the state picks the steps to offer, and the +handshake makes the security decisions. +""" + +from __future__ import annotations + +from enum import Enum +from typing import TYPE_CHECKING + +from ..sec2.wire import SecState + +if TYPE_CHECKING: + from ..models.advertisement import AdvertisementData + from ..models.firmware import FirmwareVersion + from ..models.ident import DeviceIdent + from ..sec2.wire import SecStatus + + +class DeviceState(Enum): + """Where a device stands before setup.""" + + LEGACY = "legacy" # firmware 2.x, or no SECURITY_V2 + VIRGIN = "virgin" # just flashed: fresh claim mode, no display configured + FRESH = "fresh" # fresh claim mode with a display configured + GESTURE = "gesture" # claim mode entered by the two-power-cycle gesture + OPEN = "open" # unclaimed, normal mode + CLAIMED = "claimed" + CLAIMED_IN_CLAIM_MODE = "claimed_in_claim_mode" + LOCKED = "locked" + UNKNOWN = "unknown" + + +def _unconfigured(ident: DeviceIdent | None, advertisement: AdvertisementData | None) -> bool: + if ident is not None and ident.has_tail and not ident.displays: + return True + return bool(advertisement is not None and advertisement.unconfigured) + + +def _from_status(status: SecStatus, unconfigured: bool) -> DeviceState: + if status.state == SecState.LOCKED: + return DeviceState.LOCKED + if status.state == SecState.CLAIMED: + return DeviceState.CLAIMED_IN_CLAIM_MODE if status.claim_mode else DeviceState.CLAIMED + if status.claim_mode: + if status.claim_mode_fresh: + return DeviceState.VIRGIN if unconfigured else DeviceState.FRESH + return DeviceState.GESTURE + return DeviceState.OPEN + + +def device_state( + *, + firmware: FirmwareVersion | None, + ident: DeviceIdent | None, + sec_status: SecStatus | None, + advertisement: AdvertisementData | None, +) -> DeviceState: + """Classify a device from what it signals; any input may be missing.""" + if firmware is not None and firmware["major"] < 3: + return DeviceState.LEGACY + if ident is not None and ident.has_tail and not ident.sec2: + return DeviceState.LEGACY + unconfigured = _unconfigured(ident, advertisement) + if sec_status is not None: + return _from_status(sec_status, unconfigured) + if ident is not None and ident.has_tail: + if ident.claimed: + return DeviceState.CLAIMED + if ident.claim_mode: + return DeviceState.VIRGIN if unconfigured else DeviceState.GESTURE + return DeviceState.OPEN + if advertisement is not None: + if advertisement.session_required: + return DeviceState.CLAIMED + if advertisement.claim_mode: + return DeviceState.VIRGIN if advertisement.unconfigured else DeviceState.GESTURE + return DeviceState.UNKNOWN diff --git a/tests/unit/setup/test_planner.py b/tests/unit/setup/test_planner.py new file mode 100644 index 0000000..3e6e286 --- /dev/null +++ b/tests/unit/setup/test_planner.py @@ -0,0 +1,255 @@ +"""The setup planner: device states (SECURITY_V2 § 5.3.1 / § 15.1) and the steps for each. + +Ported case by case from the website's ``tests/od-wizard.test.js`` (Web ``v3/website`` b7df514), +plus the rules our own hardware work added: a display with no config is configured before it is +claimed (it cannot show the code), a 2.x device is backed up and installed first, and a device in +claim mode whose owner wants no key leaves claim mode. +""" + +from __future__ import annotations + +from types import SimpleNamespace +from typing import Any + +import pytest + +from opendisplay.protocol.responses import parse_read_ident +from opendisplay.sec2.wire import SecState, SecStatus +from opendisplay.setup import DeviceState, Step, device_state, plan_setup + +S = Step + +_FLAGS = { + "claim_mode": 0x01, + "legacy_secrets_open": 0x08, + "rotation_suggested": 0x10, + "claim_mode_fresh": 0x20, + "config_locked": 0x40, +} + + +def _status(*, state: SecState = SecState.UNCLAIMED, key_legacy: bool = False, **flags: bool) -> SecStatus: + bits = sum(_FLAGS[name] for name, on in flags.items() if on) + return SecStatus( + sec_ver=2, + state=state, + flags=bits, + window_s=300 if flags.get("claim_mode") else 0, + uid=bytes(8), + timeout_s=3600, + dflags=0x04 if key_legacy else 0, + renders_left=3, + ) + + +def _fw(major: int) -> dict[str, Any]: + return {"major": major, "minor": 0, "patch": 2, "sha": ""} + + +def _ident(flags: int, displays: int) -> Any: + record = "37002003e00103" if displays else "" # one display: 0x0037, 800x480, scheme 3 + return parse_read_ident(bytes.fromhex(f"00460401{displays:02x}{record}{flags:02x}a00f800003")) + + +def _adv(*, claim_mode: bool, session_required: bool, unconfigured: bool) -> Any: + return SimpleNamespace(claim_mode=claim_mode, session_required=session_required, unconfigured=unconfigured) + + +def _profile(*, configured: bool = True, needs_migration: bool = False) -> Any: + return SimpleNamespace(configured=configured, needs_migration=needs_migration) + + +def _state(**kw: Any) -> DeviceState: + return device_state( + firmware=kw.get("firmware", _fw(3)), + ident=kw.get("ident"), + sec_status=kw.get("sec_status"), + advertisement=kw.get("advertisement"), + ) + + +# ── device_state ───────────────────────────────────────────────────────────── + + +@pytest.mark.parametrize( + ("status", "ident_displays", "want"), + [ + (_status(claim_mode=True, claim_mode_fresh=True), 0, DeviceState.VIRGIN), + (_status(claim_mode=True, claim_mode_fresh=True), 1, DeviceState.FRESH), + (_status(claim_mode=True), 1, DeviceState.GESTURE), + (_status(), 1, DeviceState.OPEN), + (_status(state=SecState.CLAIMED), 1, DeviceState.CLAIMED), + (_status(state=SecState.CLAIMED, claim_mode=True), 1, DeviceState.CLAIMED_IN_CLAIM_MODE), + (_status(state=SecState.LOCKED), 1, DeviceState.LOCKED), + ], +) +def test_sec_status_decides_the_state(status: SecStatus, ident_displays: int, want: DeviceState) -> None: + assert _state(sec_status=status, ident=_ident(0x09, ident_displays)) is want + + +def test_firmware_2x_and_a_tail_without_sec_v2_are_legacy() -> None: + assert _state(firmware=_fw(2)) is DeviceState.LEGACY + assert _state(ident=_ident(0x01, 0)) is DeviceState.LEGACY # a 3.0 tail without SEC_V2 + + +def test_without_sec_status_the_ident_bits_decide() -> None: + assert _state(ident=_ident(0x29, 0)) is DeviceState.VIRGIN # the E1002 just flashed + assert _state(ident=_ident(0x29, 1)) is DeviceState.GESTURE + assert _state(ident=_ident(0x19, 1)) is DeviceState.CLAIMED + assert _state(ident=_ident(0x09, 1)) is DeviceState.OPEN + + +def test_without_either_the_advertisement_decides() -> None: + adv = _adv(claim_mode=True, session_required=False, unconfigured=True) + assert _state(advertisement=adv) is DeviceState.VIRGIN + assert ( + _state(advertisement=_adv(claim_mode=True, session_required=False, unconfigured=False)) is DeviceState.GESTURE + ) + assert ( + _state(advertisement=_adv(claim_mode=False, session_required=True, unconfigured=False)) is DeviceState.CLAIMED + ) + assert _state() is DeviceState.UNKNOWN + + +def test_an_unconfigured_advertisement_makes_a_fresh_claim_mode_virgin() -> None: + adv = _adv(claim_mode=True, session_required=False, unconfigured=True) + assert _state(sec_status=_status(claim_mode=True, claim_mode_fresh=True), advertisement=adv) is DeviceState.VIRGIN + + +# ── plan_setup ─────────────────────────────────────────────────────────────── + + +def _plan(state: DeviceState, *, status: SecStatus | None = None, profile: Any = None, **kw: Any) -> Any: + return plan_setup(state=state, profile=profile or _profile(), sec_status=status, **kw) + + +def test_virgin_device_is_configured_verified_then_claimed() -> None: + p = _plan(DeviceState.VIRGIN, profile=_profile(configured=False), want_key=None) + + assert p.steps == (S.CONFIGURE_DISPLAY, S.VERIFY_PANEL, S.CLAIM, S.SECRETS, S.DONE) + assert "awaiting_claim" in p.notes + + +def test_fresh_after_config_verifies_then_claims_and_skips_verify_once_the_code_was_drawn() -> None: + a = _plan(DeviceState.FRESH, status=_status(claim_mode=True, claim_mode_fresh=True)) + assert a.steps == (S.VERIFY_PANEL, S.CLAIM, S.SECRETS, S.DONE) + + b = _plan(DeviceState.FRESH, status=_status(claim_mode=True, claim_mode_fresh=True, config_locked=True)) + assert b.steps == (S.CLAIM, S.SECRETS, S.DONE) + + +def test_a_locked_config_is_not_written_even_when_it_needs_migration() -> None: + # Claim mode refuses config writes once the code was drawn (§ 7.4, config_locked). + status = _status(claim_mode=True, claim_mode_fresh=True, config_locked=True) + p = _plan(DeviceState.FRESH, status=status, profile=_profile(needs_migration=True)) + + assert S.CONFIGURE_DISPLAY not in p.steps and S.VERIFY_PANEL not in p.steps + + +def test_gesture_claim_mode_goes_straight_to_claim() -> None: + p = _plan(DeviceState.GESTURE, status=_status(claim_mode=True)) + + assert p.steps == (S.CLAIM, S.SECRETS, S.DONE) + assert "awaiting_claim" in p.notes + + +def test_an_open_device_offers_the_choice_then_follows_it() -> None: + choice = _plan(DeviceState.OPEN, status=_status(), want_key=None) + assert choice.steps == () + assert "claim_choice" in choice.notes + + claim = _plan(DeviceState.OPEN, status=_status(), want_key=True) + assert claim.steps == (S.CLAIM, S.SECRETS, S.DONE) + assert "gesture" in claim.notes # two power cycles first + + no_key = _plan(DeviceState.OPEN, status=_status(), want_key=False) + assert no_key.steps == () # nothing to do + assert "use_without_key" in no_key.notes + + +def test_an_open_device_that_needs_migration_is_configured_first() -> None: + p = _plan(DeviceState.OPEN, status=_status(), profile=_profile(needs_migration=True), want_key=True) + + assert p.steps == (S.CONFIGURE_DISPLAY, S.VERIFY_PANEL, S.CLAIM, S.SECRETS, S.DONE) + assert "needs_migration" in p.notes + + +@pytest.mark.parametrize("profile", [_profile(configured=False), _profile(needs_migration=True)]) +def test_no_config_and_needs_migration_both_lead_to_configure_display(profile: Any) -> None: + # The EN05 after use_without_key(): open, unclaimed, no config at all. + p = _plan(DeviceState.OPEN, status=_status(), profile=profile, want_key=False) + + assert p.steps == (S.CONFIGURE_DISPLAY, S.VERIFY_PANEL, S.DONE) + + +def test_a_device_with_no_config_is_configured_before_it_is_claimed() -> None: + # It cannot show the claim code without a display. + p = _plan(DeviceState.GESTURE, status=_status(claim_mode=True), profile=_profile(configured=False)) + + assert p.steps.index(S.CONFIGURE_DISPLAY) < p.steps.index(S.CLAIM) + + +@pytest.mark.parametrize("state", [DeviceState.VIRGIN, DeviceState.FRESH, DeviceState.GESTURE]) +def test_claim_mode_without_a_key_leaves_claim_mode_first(state: DeviceState) -> None: + p = _plan(state, status=_status(claim_mode=True), profile=_profile(configured=False), want_key=False) + + assert p.steps == (S.USE_WITHOUT_KEY, S.CONFIGURE_DISPLAY, S.VERIFY_PANEL, S.DONE) + assert S.CLAIM not in p.steps and S.SECRETS not in p.steps + + +def test_claimed_in_claim_mode_only_has_secrets_left() -> None: + assert _plan(DeviceState.CLAIMED_IN_CLAIM_MODE, status=_status(state=SecState.CLAIMED, claim_mode=True)).steps == ( + S.SECRETS, + S.DONE, + ) + + +def test_claimed_locked_unknown() -> None: + assert _plan(DeviceState.CLAIMED, status=_status(state=SecState.CLAIMED)).steps == () + locked = _plan(DeviceState.LOCKED, status=_status(state=SecState.LOCKED)) + assert (locked.steps, locked.notes) == ((), ("locked", "factory_reset")) + assert _plan(DeviceState.UNKNOWN).steps == () + + +def test_a_claimed_device_with_a_2x_key_rotates_unless_asked_not_to() -> None: + status = _status(state=SecState.CLAIMED, rotation_suggested=True) + p = _plan(DeviceState.CLAIMED, status=status, profile=_profile(needs_migration=True)) + assert p.steps == (S.CONFIGURE_DISPLAY, S.VERIFY_PANEL, S.ROTATE_KEY, S.DONE) + assert "rotation_one_way" in p.notes + + kept = _plan(DeviceState.CLAIMED, status=_status(state=SecState.CLAIMED, key_legacy=True), rotate_legacy_key=False) + assert kept.steps == () + assert "rotation_pending" in kept.notes + + +def test_an_open_device_holding_2x_secrets_is_told_and_claiming_changes_them() -> None: + status = _status(legacy_secrets_open=True) + assert "legacy_secrets" in _plan(DeviceState.OPEN, status=status, want_key=None).notes + + p = _plan(DeviceState.OPEN, status=status, want_key=True) + assert p.steps == (S.CLAIM, S.SECRETS, S.DONE) + assert "change_wifi" in p.notes + + +def test_a_2x_device_is_backed_up_installed_and_confirmed_before_the_3_0_steps() -> None: + p = plan_setup(state=DeviceState.LEGACY, profile=None, sec_status=None, want_key=True) + + assert p.steps == ( + S.BACK_UP, + S.INSTALL_3_0, + S.CONFIRM_IMAGE, + S.CONFIGURE_DISPLAY, + S.VERIFY_PANEL, + S.CLAIM, + S.SECRETS, + S.DONE, + ) + assert "replan_after_install" in p.notes + + # A wired install leaves it in claim mode: without a key it leaves claim mode first. + no_key = plan_setup(state=DeviceState.LEGACY, profile=None, sec_status=None, want_key=False) + assert no_key.steps[3:] == (S.USE_WITHOUT_KEY, S.CONFIGURE_DISPLAY, S.VERIFY_PANEL, S.DONE) + + choice = plan_setup(state=DeviceState.LEGACY, profile=None, sec_status=None, want_key=None) + assert choice.steps == (S.BACK_UP, S.INSTALL_3_0, S.CONFIRM_IMAGE, S.CONFIGURE_DISPLAY, S.VERIFY_PANEL, S.DONE) + assert "claim_choice" in choice.notes diff --git a/tests/unit/test_read_ident.py b/tests/unit/test_read_ident.py index 30d179b..bf20aeb 100644 --- a/tests/unit/test_read_ident.py +++ b/tests/unit/test_read_ident.py @@ -40,6 +40,21 @@ def test_parses_a_reply_without_a_tail_as_2x() -> None: assert (ident.flags, ident.config_driven, ident.needs_migration, ident.max_config) == (None, None, None, None) +def test_the_security_bits_of_the_tail() -> None: + # Web od-v3.js parseReadIdent: bit3 SEC_V2, bit4 CLAIMED, bit5 CLAIM_MODE, bit6 LEGACY_SECRETS_OPEN. + virgin = parse_read_ident(V3_NO_DISPLAY) # flags 0x29: the E1002 just flashed, in claim mode + assert (virgin.sec2, virgin.claimed, virgin.claim_mode, virgin.legacy_secrets_open) == (True, False, True, False) + + claimed = parse_read_ident(bytes.fromhex("004604010019a00f800003")) # 0x19 + assert (claimed.sec2, claimed.claimed, claimed.claim_mode) == (True, True, False) + + secrets = parse_read_ident(bytes.fromhex("004604010049a00f800003")) # 0x49 + assert secrets.legacy_secrets_open is True + + old = parse_read_ident(V2_ONE_DISPLAY) + assert (old.sec2, old.claimed, old.claim_mode, old.legacy_secrets_open) == (None, None, None, None) + + def test_needs_migration_flag() -> None: assert parse_read_ident(bytes.fromhex("00460401000ba00f800003")).needs_migration is True From 5d4ca4f0b67907eef7be53ce95d5f2e62331542f Mon Sep 17 00:00:00 2001 From: gabriel Date: Wed, 18 Nov 2026 13:17:36 +0100 Subject: [PATCH 2/9] feat: parse the first move from 2.x over Bluetooth in the release manifest BoardRelease gains from_2x_files, from_2x_protocol and from_2x_erases_config (the ble-ota-from-2x flow: the BG22 AppLoader and nRF54 SMP), and usb_install_protocol (adafruit-serial-dfu, swd, or none for the website flasher). The setup flow picks the install path from these. Claude-Session: https://claude.ai/code/session_01Ap1E7UWkx9cYSPdYvmgmu3 --- src/opendisplay/firmware/releases.py | 14 ++++++++++++-- tests/unit/firmware/test_releases.py | 11 +++++++++++ 2 files changed, 23 insertions(+), 2 deletions(-) diff --git a/src/opendisplay/firmware/releases.py b/src/opendisplay/firmware/releases.py index 78e7662..adc4b34 100644 --- a/src/opendisplay/firmware/releases.py +++ b/src/opendisplay/firmware/releases.py @@ -39,7 +39,8 @@ class Artefact: @dataclass(frozen=True) class BoardRelease: # pylint: disable=too-many-instance-attributes - """What one board's release offers: its Bluetooth update and its USB install.""" + """What one board's release offers: its Bluetooth update, its USB install, and the first move + from 2.x over Bluetooth where the board has one (``ble-ota-from-2x``: BG22, nRF54).""" board: str target: str @@ -50,6 +51,10 @@ class BoardRelease: # pylint: disable=too-many-instance-attributes usb_install_files: tuple[str, ...] usb_install_erases_config: bool | None legacy_names: tuple[str, ...] = () + usb_install_protocol: str | None = None # "adafruit-serial-dfu", "swd"; None: the website flasher + from_2x_files: tuple[str, ...] = () + from_2x_protocol: str | None = None + from_2x_erases_config: bool | None = None def _flow(flows: Mapping[str, Any], name: str) -> tuple[tuple[str, ...], str | None, bool | None]: @@ -80,7 +85,8 @@ def parse(cls, data: bytes) -> ReleaseManifest: boards = [] for entry in doc["boards"]: ota_files, ota_protocol, ota_erases = _flow(entry["flows"], "ble-ota") - usb_files, _, usb_erases = _flow(entry["flows"], "usb-install") + usb_files, usb_protocol, usb_erases = _flow(entry["flows"], "usb-install") + from_2x_files, from_2x_protocol, from_2x_erases = _flow(entry["flows"], "ble-ota-from-2x") boards.append( BoardRelease( board=entry["board"], @@ -92,6 +98,10 @@ def parse(cls, data: bytes) -> ReleaseManifest: usb_install_files=usb_files, usb_install_erases_config=usb_erases, legacy_names=tuple(entry.get("legacy_names") or ()), + usb_install_protocol=usb_protocol, + from_2x_files=from_2x_files, + from_2x_protocol=from_2x_protocol, + from_2x_erases_config=from_2x_erases, ) ) artefacts = tuple( diff --git a/tests/unit/firmware/test_releases.py b/tests/unit/firmware/test_releases.py index 0f2ae5f..06df3b6 100644 --- a/tests/unit/firmware/test_releases.py +++ b/tests/unit/firmware/test_releases.py @@ -43,6 +43,17 @@ def test_the_bg22_updates_through_its_apploader_and_keeps_the_config(manifest: R assert board.ble_ota_erases_config is False +def test_the_first_move_from_2x_over_bluetooth_where_a_board_has_one(manifest: ReleaseManifest) -> None: + bg22, nrf54, esp32 = manifest.board("bg22"), manifest.board("xiao_nrf54l15"), manifest.board("s3-n32r8") + + assert bg22 is not None and nrf54 is not None and esp32 is not None + assert (bg22.from_2x_files, bg22.from_2x_protocol) == (("opendisplay-bg22-ota.gbl",), "silabs-apploader") + assert bg22.from_2x_erases_config is False + assert (nrf54.from_2x_files, nrf54.from_2x_protocol) == (("opendisplay-xiao_nrf54l15-ota.bin",), "mcumgr-smp") + assert (esp32.from_2x_files, esp32.from_2x_protocol) == ((), None) # USB only + assert esp32.usb_install_protocol is None and nrf54.usb_install_protocol == "swd" + + def test_an_unknown_board_is_none(manifest: ReleaseManifest) -> None: assert manifest.board("nope") is None From 78ff5363662afa75ae5269a96f743b492e605823 Mon Sep 17 00:00:00 2001 From: gabriel Date: Wed, 18 Nov 2026 13:18:42 +0100 Subject: [PATCH 3/9] refactor: move the config secrets helpers and the checked write into opendisplay.setup.configure find_secrets, unclaimed_form, strip_secrets and the write-then-read-back check move out of the CLI module so the setup runner can use them. cli_migrate imports them back; its output is unchanged (its 35 tests pass as before). write_and_verify raises ConfigMismatchError instead of exiting, and returns whether the device rewrote the 0x27. Claude-Session: https://claude.ai/code/session_01Ap1E7UWkx9cYSPdYvmgmu3 --- src/opendisplay/cli_migrate.py | 109 ++++--------------------- src/opendisplay/setup/configure.py | 127 +++++++++++++++++++++++++++++ 2 files changed, 143 insertions(+), 93 deletions(-) create mode 100644 src/opendisplay/setup/configure.py diff --git a/src/opendisplay/cli_migrate.py b/src/opendisplay/cli_migrate.py index 9543a4d..6257108 100644 --- a/src/opendisplay/cli_migrate.py +++ b/src/opendisplay/cli_migrate.py @@ -12,20 +12,22 @@ from .cli_common import _add_device_options, _console, _device_kwargs, _error, _handle_ble_error, _parse_hex_key, _run from .device import connect from .exceptions import OpenDisplayError -from .models.config import GlobalConfig, SecurityConfig, WifiConfig +from .models.config import GlobalConfig from .models.config_json import config_from_json, config_to_json from .models.panel_drive import LengthPrefixedPacket from .panels import MigrationPlan, PanelDatabase, PanelEntry, apply_migration, plan_migration from .protocol import config_parser as packet_ids from .protocol.config_serializer import serialize_config from .sec2.keystore import JsonFileKeyStore +from .setup.configure import ( + ConfigMismatchError, + find_secrets, + strip_secrets, + unclaimed_form, + without_security, + write_and_verify, +) -_SHOW_KEY_ON_SCREEN = 0x02 # SecurityConfig.flags bit 1 -# 0x2D FindMyConfig key fields (od_cfg_policy.c S2D_*): eik[32] at 8, net_a_adv_key[28] at 40, -# advertisement_key[20] at 76; the check applies to bodies of at least 96 bytes. -_FINDMY_KEY_FIELDS = ((8, 32), (40, 28), (76, 20)) -_FINDMY_MIN_BODY = 96 -_FINDMY_PACKET = 2 + packet_ids.FINDMY_CONFIG_SIZE # [number][0x2D][body] _SECRETS_REFUSAL = ( "The backup carries secrets: {found}. An unclaimed firmware 3.0 device does not store secrets; " "claim it first, then enter WiFi / FindMy settings again (run `opendisplay claim`, then migrate again " @@ -53,78 +55,6 @@ def _ask(prompt: str) -> bool: return False -# ── secrets (SECURITY_V2.md § 10.4, the closed list) ───────────────────────── - - -def _findmy_packets(raw: bytes) -> list[bytes]: - """Split ``findmy_config_raw`` (every 0x2D packet, header included, in order) into packets.""" - return [raw[i : i + _FINDMY_PACKET] for i in range(0, len(raw), _FINDMY_PACKET)] - - -def _findmy_has_keys(packet: bytes) -> bool: - body = packet[2:] - return len(body) >= _FINDMY_MIN_BODY and any(any(body[o : o + n]) for o, n in _FINDMY_KEY_FIELDS) - - -def _findmy_without_keys(packet: bytes) -> bytes: - if len(packet) - 2 < _FINDMY_MIN_BODY: - return packet - out = bytearray(packet) - for offset, size in _FINDMY_KEY_FIELDS: - out[2 + offset : 2 + offset + size] = bytes(size) - return bytes(out) - - -def find_secrets(config: GlobalConfig) -> list[str]: - """The secrets a config carries, by name; never their values.""" - found = [] - security = config.security_config - if security is not None and (security.encryption_enabled or any(security.encryption_key)): - found.append("encryption key") - if config.wifi_config is not None and any(config.wifi_config.password): - found.append("WiFi password") - if config.findmy_config_raw and any(_findmy_has_keys(p) for p in _findmy_packets(config.findmy_config_raw)): - found.append("FindMy keys") - return found - - -def unclaimed_form(config: GlobalConfig) -> GlobalConfig: - """The config with its 0x27 as an unclaimed 3.0 device stores every 0x27 it is written. - - The firmware's ``unclaimed_form`` (od_cfg_policy.c) clears ``encryption_enabled``, the key, - the show-key flag and the first reserved byte on every write to an unclaimed device. - """ - security: SecurityConfig | None = config.security_config - if security is None: - return config - return dataclasses.replace( - config, - security_config=dataclasses.replace( - security, - encryption_enabled=0, - encryption_key=bytes(16), - flags=security.flags & ~_SHOW_KEY_ON_SCREEN, - reserved=bytes(1) + security.reserved[1:], - ), - ) - - -def strip_secrets(config: GlobalConfig) -> GlobalConfig: - """The config without secrets, in the form an unclaimed 3.0 device stores. - - The 0x27 in its unclaimed form (``unclaimed_form``), the 0x26 password zeroed, and the key - fields of every 0x2D zeroed in place; the other FindMy settings stay. - """ - config = unclaimed_form(config) - wifi: WifiConfig | None = config.wifi_config - if wifi is not None: - wifi = dataclasses.replace(wifi, password=bytes(len(wifi.password))) - findmy = config.findmy_config_raw - if findmy: - findmy = b"".join(_findmy_without_keys(p) for p in _findmy_packets(findmy)) - return dataclasses.replace(config, wifi_config=wifi, findmy_config_raw=findmy) - - # ── describing packets ─────────────────────────────────────────────────────── @@ -334,20 +264,13 @@ async def _restore(dev: Any, backup: GlobalConfig, *, dry_run: bool) -> None: async def _write_and_verify(dev: Any, config: GlobalConfig) -> None: """Write ``config``, read it back and compare the bytes; exit 1 on a mismatch.""" _console.print("Writing...") - await dev.config.write(config) - stored = await dev.config.read() - expected, actual = serialize_config(config), serialize_config(stored) - if _without_security(stored) != _without_security(config): - _error( - f"The config read back ({len(actual)} bytes) does not match what was written ({len(expected)} bytes). " - "Keep your backup; the write may have been interrupted." - ) - if actual != expected: - # The firmware rewrites 0x27 on store: unclaimed_form on an unclaimed device, the key at - # rest on a claimed one (od_cfg_policy.c), so the security packet is compared apart. + try: + rewrote_security = await write_and_verify(dev, config) + except ConfigMismatchError as exc: + _error(str(exc)) + if rewrote_security: _console.print("The device stored the security packet (0x27) in its own form; everything else matches.") - _console.print(f"Config written and verified ({len(expected)} bytes).") + _console.print(f"Config written and verified ({len(serialize_config(config))} bytes).") -def _without_security(config: GlobalConfig) -> bytes: - return serialize_config(dataclasses.replace(config, security_config=None)) +__all__ = ["find_secrets", "strip_secrets", "unclaimed_form", "without_security"] diff --git a/src/opendisplay/setup/configure.py b/src/opendisplay/setup/configure.py new file mode 100644 index 0000000..c52c2a6 --- /dev/null +++ b/src/opendisplay/setup/configure.py @@ -0,0 +1,127 @@ +"""Writing a config in the setup flow: the secrets a config carries, and a checked write. + +Moved from the CLI's ``migrate`` so the setup runner and the CLI share it. An unclaimed firmware 3.0 +device does not store secrets (SECURITY_V2.md § 10.4, § 10.5): a config for one is written without +them, and its 0x27 in the form the device stores. +""" + +from __future__ import annotations + +import dataclasses +from typing import TYPE_CHECKING + +from ..exceptions import OpenDisplayError +from ..models.config import GlobalConfig, SecurityConfig, WifiConfig +from ..protocol import config_parser as packet_ids +from ..protocol.config_serializer import serialize_config + +if TYPE_CHECKING: + from ..device.api import Device + +_SHOW_KEY_ON_SCREEN = 0x02 # SecurityConfig.flags bit 1 +# 0x2D FindMyConfig key fields (od_cfg_policy.c S2D_*): eik[32] at 8, net_a_adv_key[28] at 40, +# advertisement_key[20] at 76; the check applies to bodies of at least 96 bytes. +_FINDMY_KEY_FIELDS = ((8, 32), (40, 28), (76, 20)) +_FINDMY_MIN_BODY = 96 +_FINDMY_PACKET = 2 + packet_ids.FINDMY_CONFIG_SIZE # [number][0x2D][body] + + +class ConfigMismatchError(OpenDisplayError): + """The config read back after a write differs from what was written.""" + + +def _findmy_packets(raw: bytes) -> list[bytes]: + """Split ``findmy_config_raw`` (every 0x2D packet, header included, in order) into packets.""" + return [raw[i : i + _FINDMY_PACKET] for i in range(0, len(raw), _FINDMY_PACKET)] + + +def _findmy_has_keys(packet: bytes) -> bool: + body = packet[2:] + return len(body) >= _FINDMY_MIN_BODY and any(any(body[o : o + n]) for o, n in _FINDMY_KEY_FIELDS) + + +def _findmy_without_keys(packet: bytes) -> bytes: + if len(packet) - 2 < _FINDMY_MIN_BODY: + return packet + out = bytearray(packet) + for offset, size in _FINDMY_KEY_FIELDS: + out[2 + offset : 2 + offset + size] = bytes(size) + return bytes(out) + + +def find_secrets(config: GlobalConfig) -> list[str]: + """The secrets a config carries, by name; never their values.""" + found = [] + security = config.security_config + if security is not None and (security.encryption_enabled or any(security.encryption_key)): + found.append("encryption key") + if config.wifi_config is not None and any(config.wifi_config.password): + found.append("WiFi password") + if config.findmy_config_raw and any(_findmy_has_keys(p) for p in _findmy_packets(config.findmy_config_raw)): + found.append("FindMy keys") + return found + + +def unclaimed_form(config: GlobalConfig) -> GlobalConfig: + """The config with its 0x27 as an unclaimed 3.0 device stores every 0x27 it is written. + + The firmware's ``unclaimed_form`` (od_cfg_policy.c) clears ``encryption_enabled``, the key, + the show-key flag and the first reserved byte on every write to an unclaimed device. + """ + security: SecurityConfig | None = config.security_config + if security is None: + return config + return dataclasses.replace( + config, + security_config=dataclasses.replace( + security, + encryption_enabled=0, + encryption_key=bytes(16), + flags=security.flags & ~_SHOW_KEY_ON_SCREEN, + reserved=bytes(1) + security.reserved[1:], + ), + ) + + +def strip_secrets(config: GlobalConfig) -> GlobalConfig: + """The config without secrets, in the form an unclaimed 3.0 device stores. + + The 0x27 in its unclaimed form (``unclaimed_form``), the 0x26 password zeroed, and the key + fields of every 0x2D zeroed in place; the other FindMy settings stay. + """ + config = unclaimed_form(config) + wifi: WifiConfig | None = config.wifi_config + if wifi is not None: + wifi = dataclasses.replace(wifi, password=bytes(len(wifi.password))) + findmy = config.findmy_config_raw + if findmy: + findmy = b"".join(_findmy_without_keys(p) for p in _findmy_packets(findmy)) + return dataclasses.replace(config, wifi_config=wifi, findmy_config_raw=findmy) + + +# ── a checked write ────────────────────────────────────────────────────────── + + +def without_security(config: GlobalConfig) -> bytes: + """The serialised config without its 0x27, which the firmware rewrites on store.""" + return serialize_config(dataclasses.replace(config, security_config=None)) + + +async def write_and_verify(dev: Device, config: GlobalConfig) -> bool: + """Write ``config``, read it back and compare. + + Returns: + Whether the device stored the security packet (0x27) in its own form, which the firmware + does on every store (``unclaimed_form`` unclaimed, the key at rest claimed; od_cfg_policy.c). + + Raises: + ConfigMismatchError: Anything but the 0x27 differs; the write may have been interrupted. + """ + await dev.config.write(config) + stored = await dev.config.read() + if without_security(stored) != without_security(config): + raise ConfigMismatchError( + f"The config read back ({len(serialize_config(stored))} bytes) does not match what was written " + f"({len(serialize_config(config))} bytes). Keep your backup; the write may have been interrupted." + ) + return serialize_config(stored) != serialize_config(config) From db230954a04c5c6e5ef601b59d2ec6b9fa00b6c4 Mon Sep 17 00:00:00 2001 From: gabriel Date: Wed, 18 Nov 2026 13:25:43 +0100 Subject: [PATCH 4/9] feat: run the setup flow step by step, pausing on requests (SetupRun) SetupRun performs plan_setup()'s steps on a device and pauses on a typed request when it needs the user: the key choice, the claim-mode gesture, the claim code, a panel, a confirmation (untested drive data, a BG22 install with no rollback, the panel check), a board, a wired install, or a config to start from. It saves and restores as JSON for a Home Assistant restart. Every run_until_input opens the device again and plans from what it reads, so a saved run never repeats a step the device shows as done; only the backup, the panel check and the image confirm are remembered. A claim code is confirmed on the link that asked for it. The 2.x backup goes to the caller's sink with its secrets; the run keeps a copy without them. From 2.x it installs over Bluetooth where the release has a ble-ota-from-2x flow (BG22 AppLoader, nRF54 SMP), checking the image against the manifest SHA-256, and otherwise names the USB install files and the website flasher. Claude-Session: https://claude.ai/code/session_01Ap1E7UWkx9cYSPdYvmgmu3 --- src/opendisplay/setup/requests.py | 144 ++++++++ src/opendisplay/setup/runner.py | 491 +++++++++++++++++++++++++++ tests/unit/test_setup_runner.py | 532 ++++++++++++++++++++++++++++++ 3 files changed, 1167 insertions(+) create mode 100644 src/opendisplay/setup/requests.py create mode 100644 src/opendisplay/setup/runner.py create mode 100644 tests/unit/test_setup_runner.py diff --git a/src/opendisplay/setup/requests.py b/src/opendisplay/setup/requests.py new file mode 100644 index 0000000..31cefea --- /dev/null +++ b/src/opendisplay/setup/requests.py @@ -0,0 +1,144 @@ +"""What a setup run can pause on: one request at a time, answered with ``SetupRun.answer()``. + +Each request is a frozen dataclass and saves as plain JSON (``to_dict`` / ``from_dict``), so a run +paused on one survives a Home Assistant restart. The answer each takes is in its docstring. +""" + +from __future__ import annotations + +import dataclasses +from dataclasses import dataclass +from typing import Any, ClassVar + + +@dataclass(frozen=True) +class NeedKeyChoice: + """Claim the display (answer ``True``) or use it without a key (``False``).""" + + kind: ClassVar[str] = "key_choice" + + +@dataclass(frozen=True) +class NeedGesture: + """The user must act on the device; answer ``None`` once done. + + ``gesture`` is ``"claim_mode"``: power-cycle it twice quickly to enter claim mode. + """ + + gesture: str = "claim_mode" + kind: ClassVar[str] = "gesture" + + +@dataclass(frozen=True) +class NeedClaimCode: + """The six-digit code the display shows; answer it as typed. ``retry``: the last one was wrong.""" + + has_panel: bool = True + retry: bool = False + kind: ClassVar[str] = "claim_code" + + +@dataclass(frozen=True) +class NeedPanelChoice: + """Which panel the display has; answer its ``panel_ic_type``. ``reason`` says why it is asked.""" + + reason: str = "" + candidates: tuple[int, ...] = () + kind: ClassVar[str] = "panel_choice" + + +@dataclass(frozen=True) +class NeedConfirmation: + """A yes/no before going on; ``False`` stops the run (it asks again when run next). + + ``reason`` is one of ``untested_panel`` (drive data nobody has seen draw), ``no_rollback`` (a + BG22 install: no old image to return to), ``panel_ok`` (does the test pattern look right). + """ + + reason: str + detail: str = "" + subject: str = "" + kind: ClassVar[str] = "confirmation" + + +@dataclass(frozen=True) +class NeedBoardChoice: + """Which board the display is; answer the board name. Several boards share one chip.""" + + candidates: tuple[str, ...] = () + kind: ClassVar[str] = "board_choice" + + +@dataclass(frozen=True) +class NeedWiredInstall: + """Install 3.0 over USB with these files, then answer ``None``. + + The library does not flash over USB: ``url`` is the website flasher, ``protocol`` the method + (``None``: the flasher; ``adafruit-serial-dfu``; ``swd``). After the install the display may + advertise under another name. + """ + + board: str + files: tuple[str, ...] + protocol: str | None + erases_config: bool | None + url: str + release_url: str = "" + kind: ClassVar[str] = "wired_install" + + +@dataclass(frozen=True) +class NeedConfig: + """A config to start from: the display has none and no backup was taken. Answer a + ``GlobalConfig`` (for example ``config_from_json()`` of a Config Builder export).""" + + reason: str = "no_config" + kind: ClassVar[str] = "config" + + +Request = ( + NeedKeyChoice + | NeedGesture + | NeedClaimCode + | NeedPanelChoice + | NeedConfirmation + | NeedBoardChoice + | NeedWiredInstall + | NeedConfig +) + +_KINDS: dict[str, type[Any]] = { + cls.kind: cls + for cls in ( + NeedKeyChoice, + NeedGesture, + NeedClaimCode, + NeedPanelChoice, + NeedConfirmation, + NeedBoardChoice, + NeedWiredInstall, + NeedConfig, + ) +} + + +def to_dict(request: Request) -> dict[str, Any]: + """The request as plain JSON values.""" + return {"kind": request.kind, **dataclasses.asdict(request)} + + +def from_dict(data: dict[str, Any]) -> Request: + """The request ``to_dict`` saved. + + Raises: + ValueError: An unknown kind. + """ + fields = dict(data) + cls = _KINDS.get(fields.pop("kind", "")) + if cls is None: + raise ValueError(f"Unknown setup request {data!r}") + for name, value in fields.items(): + if isinstance(value, list): + fields[name] = tuple(value) + request: Request = cls(**fields) + return request diff --git a/src/opendisplay/setup/runner.py b/src/opendisplay/setup/runner.py new file mode 100644 index 0000000..f993cca --- /dev/null +++ b/src/opendisplay/setup/runner.py @@ -0,0 +1,491 @@ +"""``SetupRun``: perform a setup plan, pausing on requests, saved and resumed as JSON. + +Every ``run_until_input`` opens the device afresh, reads where it stands and plans again +(``plan_setup``), so a saved run never repeats a step the device shows as done: a run saved while +asking for a wired install, resumed after the device was updated some other way, goes on from the +3.0 steps (Review Focus 4). Only steps the device cannot show (the backup, the panel check, the +image confirm) are remembered as done. + +A claim code is confirmed on the link that asked for it: the run holds that link open across the +``NeedClaimCode`` request. A saved run does not keep it; resumed, it starts the claim again. + +Secrets never enter the saved run: the backup goes to the caller's ``backup_sink`` as it is, and +the run keeps a copy without secrets to configure the device from if its config is lost. +""" + +from __future__ import annotations + +import dataclasses +import hashlib +import json +import logging +from collections.abc import Awaitable, Callable +from contextlib import AbstractAsyncContextManager, AsyncExitStack +from typing import Any, Final + +from epaper_dithering import DitherMode +from PIL import Image, ImageDraw + +from .. import redraw +from ..exceptions import OpenDisplayError +from ..firmware import smp +from ..firmware.releases import BoardRelease, ReleaseManifest +from ..models.config import GlobalConfig +from ..models.config_json import config_from_json, config_to_json +from ..models.enums import ColorScheme, ICType +from ..ota import perform_silabs_ota +from ..panels import PanelDatabase, apply_migration, plan_migration +from ..protocol.config_serializer import serialize_config +from ..sec2.errors import Sec2CodeMismatchError +from . import requests as rq +from .configure import strip_secrets, write_and_verify +from .planner import Step, plan_setup +from .state import device_state + +_LOGGER = logging.getLogger(__name__) + +INSTALL_URL: Final = "https://opendisplay.org/firmware/install/" +RELEASES_URL: Final = "https://github.com/OpenDisplay/Firmware_Unified/releases/tag/" +_REBOOT_ALLOWANCE_S: Final = 180.0 +_MAX_STEPS: Final = 24 +_FORMAT: Final = 1 +_CHIPS: Final[dict[int, str]] = { + ICType.NRF52840: "nrf52840", + ICType.ESP32_S3: "esp32s3", + ICType.ESP32_C3: "esp32c3", + ICType.ESP32_C6: "esp32c6", + ICType.EFR32BG22: "efr32bg22", +} +_REMEMBERED: Final = frozenset({Step.BACK_UP, Step.CONFIRM_IMAGE, Step.VERIFY_PANEL, Step.SECRETS}) +_BLACK, _WHITE, _RED, _YELLOW = (0, 0, 0), (255, 255, 255), (255, 0, 0), (255, 255, 0) +_PATTERNS: Final[dict[int, tuple[tuple[str, tuple[int, int, int]], ...]]] = { + ColorScheme.MONO: (("black", _BLACK), ("white", _WHITE)), + ColorScheme.BWR: (("black", _BLACK), ("white", _WHITE), ("red", _RED)), + ColorScheme.BWY: (("black", _BLACK), ("white", _WHITE), ("yellow", _YELLOW)), + ColorScheme.BWRY: (("black", _BLACK), ("white", _WHITE), ("red", _RED), ("yellow", _YELLOW)), + ColorScheme.BWGBRY: ( + ("black", _BLACK), + ("white", _WHITE), + ("green", (0, 255, 0)), + ("blue", (0, 0, 255)), + ("red", _RED), + ("yellow", _YELLOW), + ), + ColorScheme.GRAYSCALE_4: ( + ("black", _BLACK), + ("dark gray", (85, 85, 85)), + ("light gray", (170, 170, 170)), + ("white", _WHITE), + ), +} + +DeviceFactory = Callable[[], AbstractAsyncContextManager[Any]] +FetchImage = Callable[[str], Awaitable[bytes]] +FindDevice = Callable[[str], Awaitable[Any]] + + +class SetupError(OpenDisplayError): + """The setup cannot go on; the message says why. A saved run can be resumed once fixed.""" + + +def panel_pattern(width: int, height: int, scheme: int | None) -> tuple[Image.Image, tuple[str, ...]]: + """Vertical bands of every colour the scheme has, and their names left to right.""" + bands = _PATTERNS.get(scheme if scheme is not None else -1, _PATTERNS[ColorScheme.MONO]) + image = Image.new("RGB", (width, height), _WHITE) + draw = ImageDraw.Draw(image) + step = width // len(bands) + for i, (_, colour) in enumerate(bands): + draw.rectangle((i * step, 0, width - 1 if i == len(bands) - 1 else (i + 1) * step - 1, height - 1), fill=colour) + return image, tuple(name for name, _ in bands) + + +class SetupRun: # pylint: disable=too-many-instance-attributes + """One setup or upgrade of one device. Make it with :meth:`start` or :meth:`from_json`.""" + + def __init__( # pylint: disable=too-many-arguments + self, + *, + want_key: bool | None, + rotate_legacy_key: bool, + backup_sink: Callable[[bytes], None], + manifest: ReleaseManifest | None, + fetch_image: FetchImage | None, + find_device: FindDevice | None, + ) -> None: + self.want_key = want_key + self.rotate_legacy_key = rotate_legacy_key + self._sink = backup_sink + self._manifest = manifest + self._fetch = fetch_image + self._find = find_device + self._done: set[Step] = set() + self._backup: dict[str, Any] | None = None # without secrets + self._board: str | None = None + self._panel: int | None = None + self._accepted: set[str] = set() + self._claim_code: str | None = None + self._claim_retry = False + self._live: tuple[AsyncExitStack, Any] | None = None # the claim link and its device + self._live_flow: Any = None + self._stop_pending = False + #: The request the run waits for, or ``None``. + self.pending: rq.Request | None = None + #: The confirmation the user declined, which stopped the run; cleared when it runs again. + self.stopped: str | None = None + #: Whether the device is set up. + self.finished = False + #: The planner's text keys for the device as last seen. + self.notes: tuple[str, ...] = () + + # ── making, saving, answering ──────────────────────────────────────────── + + @classmethod + def start( # pylint: disable=too-many-arguments + cls, + *, + want_key: bool | None, + backup_sink: Callable[[bytes], None], + manifest: ReleaseManifest | None = None, + fetch_image: FetchImage | None = None, + find_device: FindDevice | None = None, + rotate_legacy_key: bool = True, + ) -> SetupRun: + """A new run. + + Args: + want_key: Claim the device (``True``), use it without a key (``False``), or ask + (``None``: an open device then pauses on ``NeedKeyChoice``). + backup_sink: Receives the 2.x config backup, with its secrets, as JSON bytes. The + run never writes it anywhere else. + manifest: The release to install from a 2.x device (``ReleaseManifest.parse``). + fetch_image: Returns a release file's bytes by name, for an install over Bluetooth. + find_device: Finds the display's ``BLEDevice`` by address (Home Assistant passes its + own); needed for an install over Bluetooth. + rotate_legacy_key: Replace a 2.x key on a claimed device. + """ + return cls( + want_key=want_key, + rotate_legacy_key=rotate_legacy_key, + backup_sink=backup_sink, + manifest=manifest, + fetch_image=fetch_image, + find_device=find_device, + ) + + def to_json(self) -> str: + """The run as JSON, without the claim link and without secrets.""" + return json.dumps( + { + "format": _FORMAT, + "want_key": self.want_key, + "rotate_legacy_key": self.rotate_legacy_key, + "done": sorted(step.value for step in self._done), + "backup": self._backup, + "board": self._board, + "panel": self._panel, + "accepted": sorted(self._accepted), + "claim_retry": self._claim_retry, + "pending": rq.to_dict(self.pending) if self.pending is not None else None, + "stopped": self.stopped, + "stop_pending": self._stop_pending, + "finished": self.finished, + "notes": list(self.notes), + } + ) + + @classmethod + def from_json( # pylint: disable=too-many-arguments + cls, + data: str, + *, + backup_sink: Callable[[bytes], None], + manifest: ReleaseManifest | None = None, + fetch_image: FetchImage | None = None, + find_device: FindDevice | None = None, + ) -> SetupRun: + """A run ``to_json`` saved; the callables are the caller's again. + + Raises: + ValueError: Not a saved run, or another format. + """ + doc = json.loads(data) + if doc.get("format") != _FORMAT: + raise ValueError(f"Unsupported saved setup run format {doc.get('format')!r}") + run = cls.start( + want_key=doc["want_key"], + backup_sink=backup_sink, + manifest=manifest, + fetch_image=fetch_image, + find_device=find_device, + rotate_legacy_key=doc["rotate_legacy_key"], + ) + run._done = {Step(value) for value in doc["done"]} + run._backup = doc["backup"] + run._board = doc["board"] + run._panel = doc["panel"] + run._accepted = set(doc["accepted"]) + run._claim_retry = doc["claim_retry"] + run.pending = rq.from_dict(doc["pending"]) if doc["pending"] is not None else None + run.stopped = doc["stopped"] + run._stop_pending = doc["stop_pending"] + run.finished = doc["finished"] + run.notes = tuple(doc["notes"]) + return run + + def answer(self, request: rq.Request | None, value: Any) -> None: # pylint: disable=too-many-branches + """Answer the pending ``request``; the next ``run_until_input`` goes on from it. + + Raises: + ValueError: ``request`` is not the pending one. + """ + if request is None or request != self.pending: + raise ValueError(f"{request!r} is not the pending request ({self.pending!r})") + self.pending = None + if isinstance(request, rq.NeedKeyChoice): + self.want_key = bool(value) + elif isinstance(request, rq.NeedBoardChoice): + self._board = str(value) + elif isinstance(request, rq.NeedPanelChoice): + self._panel = int(value) + elif isinstance(request, rq.NeedClaimCode): + self._claim_code = str(value) + elif isinstance(request, rq.NeedConfig): + if not isinstance(value, GlobalConfig): + raise ValueError("NeedConfig takes a GlobalConfig") + self._backup = config_to_json(strip_secrets(value)) + elif isinstance(request, rq.NeedConfirmation): + if value: + self._accepted.add(f"{request.reason}:{request.subject}") + if request.reason == "panel_ok": + self._done.add(Step.VERIFY_PANEL) + else: + self.stopped, self._stop_pending = request.reason, True + # NeedGesture and NeedWiredInstall need no value: the device shows what was done. + + # ── running ────────────────────────────────────────────────────────────── + + async def run_until_input(self, device_factory: DeviceFactory) -> rq.Request | None: + """Go on until the run needs an answer (the request), finishes, or was stopped (``None``). + + Args: + device_factory: Opens the device, connected: ``opendisplay.connect(...)`` or the + caller's own; called again for every step. + + Raises: + SetupError: The setup cannot go on (see the message); the run can be saved and resumed. + """ + if self._stop_pending: + self._stop_pending = False + return None + self.stopped = None + await self._finish_claim() + last: Step | None = None + for _ in range(_MAX_STEPS): + async with AsyncExitStack() as stack: + dev = await stack.enter_async_context(device_factory()) + step, request = await self._next(dev, stack.aclose) + if isinstance(request, rq.NeedClaimCode): + self._live = (stack.pop_all(), dev) + if step is None or request is not None: + self.pending = request + return request + if step is last and step not in _REMEMBERED: + raise SetupError(f"The step '{step.value}' did not take; the device still needs it") + last = step + raise SetupError("The setup did not finish within its step limit") + + async def _next(self, dev: Any, close: Callable[[], Awaitable[None]]) -> tuple[Step | None, rq.Request | None]: + """Plan from the device and perform the first step not done: (step, request).""" + profile = dev.profile + legacy = profile.firmware["major"] < 3 + status = dev.security.status + state = device_state(firmware=profile.firmware, ident=profile.ident, sec_status=status, advertisement=None) + plan = plan_setup( + state=state, + profile=None if legacy else profile, + sec_status=status, + want_key=self.want_key, + rotate_legacy_key=self.rotate_legacy_key, + ) + self.notes = plan.notes + if not plan.steps: + if "claim_choice" in plan.notes: + return None, rq.NeedKeyChoice() + self.finished = True + return None, None + step = next((s for s in plan.steps if s not in self._done), Step.DONE) + if step is Step.DONE: + self.finished = True + return None, None + request = await self._perform(step, dev, close) + if request is None and step in _REMEMBERED: + self._done.add(step) + return step, request + + async def _perform( # pylint: disable=too-many-return-statements + self, step: Step, dev: Any, close: Callable[[], Awaitable[None]] + ) -> rq.Request | None: + if step is Step.BACK_UP: + self._back_up(dev) + return None + if step is Step.INSTALL_3_0: + return await self._install(dev, close) + if step is Step.CONFIRM_IMAGE: + await dev.legacy.read_ident() + return None + if step is Step.USE_WITHOUT_KEY: + await dev.security.use_without_key() + return None + if step is Step.CONFIGURE_DISPLAY: + return await self._configure(dev) + if step is Step.VERIFY_PANEL: + return await self._verify(dev) + if step is Step.CLAIM: + return await self._claim(dev) + if step is Step.ROTATE_KEY: + await dev.security.rotate_key() + return None + return None # SECRETS: entered by the caller once claimed; nothing for the run to write + + # ── the steps ──────────────────────────────────────────────────────────── + + def _back_up(self, dev: Any) -> None: + config = dev.config.cached + if config is not None: + self._sink(json.dumps(config_to_json(config), indent=2).encode()) + self._backup = config_to_json(strip_secrets(config)) + + def _choose_board(self, dev: Any) -> BoardRelease | rq.NeedBoardChoice: + if self._manifest is None: + raise SetupError("Installing 3.0 needs the release manifest (SetupRun.start(manifest=...))") + if self._board is not None: + chosen = self._manifest.board(self._board) + if chosen is None: + raise SetupError(f"The release has no board {self._board!r}") + return chosen + config = dev.config.cached + chip = _CHIPS.get(config.system.ic_type) if config is not None else None + boards = self._manifest.boards_for_chip(chip) if chip is not None else list(self._manifest.boards) + if len(boards) == 1: + return boards[0] + return rq.NeedBoardChoice(candidates=tuple(b.board for b in boards)) + + async def _install(self, dev: Any, close: Callable[[], Awaitable[None]]) -> rq.Request | None: + board = self._choose_board(dev) + if isinstance(board, rq.NeedBoardChoice): + return board + assert self._manifest is not None + if not board.from_2x_files: + return rq.NeedWiredInstall( + board=board.board, + files=board.usb_install_files, + protocol=board.usb_install_protocol, + erases_config=board.usb_install_erases_config, + url=INSTALL_URL, + release_url=RELEASES_URL + self._manifest.version, + ) + if board.from_2x_protocol == "silabs-apploader" and f"no_rollback:{board.board}" not in self._accepted: + return rq.NeedConfirmation( + reason="no_rollback", + subject=board.board, + detail="A BG22 has no old image to return to: if the new image does not start, it waits in " + "its AppLoader (advertising as 'OTA') for a .gbl, and without USB only a debugger recovers it.", + ) + image = await self._image(board.from_2x_files[0]) + address = dev.legacy.mac_address + keys = dev.legacy._redraw_keys() # pylint: disable=protected-access + if self._find is None: + raise SetupError("Installing over Bluetooth needs find_device (SetupRun.start(find_device=...))") + if board.from_2x_protocol == "silabs-apploader": + await dev.legacy.trigger_dfu_bootloader() # 2.x: reboots into the AppLoader + await close() + await perform_silabs_ota(image, await self._find(address), None) + else: # mcumgr-smp: Firmware_NRF54 1.1.x serves SMP in its app + await close() + async with smp.session(await self._find(address)) as client: + await smp.upload(client, image) + await smp.test_and_reset(client) + redraw.mark_redrawing(*keys, allowance=_REBOOT_ALLOWANCE_S) + return None + + async def _image(self, name: str) -> bytes: + if self._fetch is None: + raise SetupError("Installing over Bluetooth needs fetch_image (SetupRun.start(fetch_image=...))") + image = await self._fetch(name) + artefact = self._manifest.artefact(name) if self._manifest is not None else None + if artefact is not None and hashlib.sha256(image).hexdigest() != artefact.sha256: + raise SetupError(f"{name} does not match the release manifest's SHA-256; not sent") + return image + + @staticmethod + def _for_device(dev: Any, config: GlobalConfig) -> GlobalConfig: + """The saved backup (already without secrets) as this device stores it. + + A claimed device keeps its own key: the backup goes without its 0x27. An unclaimed one + stores the 0x27 in its unclaimed form (show-key flag cleared), which ``strip_secrets`` + gave it already. + """ + if dev.security.sec2_session_open: + return dataclasses.replace(config, security_config=None) + return config + + async def _configure(self, dev: Any) -> rq.Request | None: + profile = dev.profile + start: GlobalConfig | None = dev.config.cached if profile.configured else None + from_backup = start is None and self._backup is not None + if from_backup: + assert self._backup is not None + start = self._for_device(dev, config_from_json(self._backup)) + if start is None: + return rq.NeedConfig() + plan = plan_migration(start, profile, PanelDatabase.load(), panel_ic_type=self._panel) + if plan.blocked: + return rq.NeedPanelChoice(reason=plan.reason) + subject = f"{plan.panel_ic_type:#06x}" if plan.panel_ic_type is not None else "" + if plan.needs_confirmation and f"untested_panel:{subject}" not in self._accepted: + return rq.NeedConfirmation(reason="untested_panel", detail=plan.reason, subject=subject) + config = apply_migration(start, plan) if plan.needed else start + stored = dev.config.cached + if stored is not None and serialize_config(stored) == serialize_config(config): + self._done.add(Step.CONFIGURE_DISPLAY) # nothing to write; the device says otherwise + return None + await write_and_verify(dev, config) + return None + + async def _verify(self, dev: Any) -> rq.Request: + profile = dev.profile + image, names = panel_pattern(profile.width or 400, profile.height or 300, profile.color_scheme) + await dev.display.show(image, dither_mode=DitherMode.NONE) + return rq.NeedConfirmation( + reason="panel_ok", + detail="The display shows bands, left to right: " + ", ".join(names) + ". Do they look right?", + ) + + async def _claim(self, dev: Any) -> rq.Request: + status = dev.security.status + if status is None or not status.claim_mode: + return rq.NeedGesture() + flow = await dev.security.claim() + await flow.begin() + code = await flow.exchange_nonces() + self._live_flow = flow + return rq.NeedClaimCode(has_panel=bool(code.has_panel), retry=self._claim_retry) + + async def _finish_claim(self) -> None: + """Confirm a claim on the link that asked for the code, then close it.""" + if self._live is None: + return + stack, _ = self._live + flow, self._live = self._live_flow, None + code, self._claim_code = self._claim_code, None + try: + if code is None: + await flow.abort() # run again without an answer: start the claim over + return + try: + await flow.confirm(code) + self._claim_retry = False + except Sec2CodeMismatchError: + self._claim_retry = True # confirm() sent ABORT; the next claim asks again + finally: + await stack.aclose() diff --git a/tests/unit/test_setup_runner.py b/tests/unit/test_setup_runner.py new file mode 100644 index 0000000..085f37c --- /dev/null +++ b/tests/unit/test_setup_runner.py @@ -0,0 +1,532 @@ +"""The setup runner: one scripted run per starting state, each saved and restored mid-way. + +A ``_World`` is the display across connections (firmware, security state, stored config); every +``run_until_input`` opens a fresh ``_Dev`` on it, as the runner re-reads the device each time. +""" + +from __future__ import annotations + +import dataclasses +import hashlib +import json +from collections.abc import AsyncIterator +from contextlib import asynccontextmanager +from pathlib import Path +from types import SimpleNamespace +from typing import Any + +import pytest +from test_profile import _config, _display + +from opendisplay.firmware.releases import ReleaseManifest +from opendisplay.models.config import GlobalConfig, SecurityConfig +from opendisplay.models.enums import ColorScheme, ICType +from opendisplay.models.ident import FirmwareTarget +from opendisplay.sec2.errors import Sec2CodeMismatchError +from opendisplay.sec2.wire import SecState, SecStatus +from opendisplay.setup import requests as rq +from opendisplay.setup import runner as runner_mod +from opendisplay.setup.runner import SetupError, SetupRun + +KEY = bytes(range(1, 17)) +MANIFEST = ReleaseManifest.parse( + (Path(__file__).parents[1] / "fixtures" / "firmware" / "manifest-3.0.2.json").read_bytes() +) + + +def _keyed(ic_type: int = ICType.ESP32_S3) -> GlobalConfig: + security = SecurityConfig( + encryption_enabled=1, + encryption_key=KEY, + session_timeout_seconds=0, + flags=0, + reset_pin=0xFF, + reserved=bytes(43), + ) + return _config(ic_type=ic_type, displays=[_display(panel_ic_type=0x0037)], security_config=security) + + +@dataclasses.dataclass +class _World: # pylint: disable=too-many-instance-attributes + major: int = 3 + target: int = FirmwareTarget.ESP32 + state: SecState = SecState.UNCLAIMED + claim_mode: bool = False + fresh: bool = False + key_legacy: bool = False + config: GlobalConfig | None = None + needs_migration: bool = False + code: str = "123456" + calls: list[str] = dataclasses.field(default_factory=list) + on_wired_install: Any = None # what the USB install leaves behind + + def status(self) -> SecStatus | None: + if self.major < 3: + return None + flags = (0x01 if self.claim_mode else 0) | (0x20 if self.fresh else 0) + return SecStatus( + 2, + self.state, + flags, + 300 if self.claim_mode else 0, + bytes(8), + 3600, + (0x04 if self.key_legacy else 0) | (0x01 if self.config else 0), + 3, + ) + + +class _Flow: + def __init__(self, world: _World) -> None: + self.world = world + + async def begin(self) -> None: + self.world.calls.append("claim_begin") + + async def exchange_nonces(self) -> Any: + return SimpleNamespace(has_panel=self.world.config is not None) + + async def confirm(self, typed: str) -> None: + if typed != self.world.code: + await self.abort() # as ClaimFlow.confirm does + raise Sec2CodeMismatchError() + self.world.calls.append("claim_confirm") + self.world.state, self.world.claim_mode, self.world.fresh = SecState.CLAIMED, False, False + + async def abort(self) -> None: + self.world.calls.append("claim_abort") + + +class _Dev: + def __init__(self, world: _World) -> None: + w = self.world = world + self.profile = SimpleNamespace( + firmware={"major": w.major, "minor": 0, "patch": 2, "sha": ""}, + ident=None, + target=w.target, + configured=w.config is not None, + needs_migration=w.needs_migration, + color_scheme=ColorScheme.BWRY, + width=800, + height=480, + ) + + async def use_without_key() -> None: + w.calls.append("use_without_key") + w.claim_mode = w.fresh = False + + async def claim() -> _Flow: + return _Flow(w) + + async def rotate_key() -> bytes: + w.calls.append("rotate_key") + w.key_legacy = False + return bytes(16) + + async def read() -> GlobalConfig | None: + return w.config + + async def write(config: GlobalConfig) -> None: + w.calls.append("config_write") + w.config, w.needs_migration = config, False + + async def trigger_dfu_bootloader() -> None: + w.calls.append("enter_dfu") + + async def read_ident() -> None: + w.calls.append("read_ident") + + async def show(image: Any, **kw: Any) -> None: + w.calls.append(f"show:{image.size[0]}x{image.size[1]}") + + self.security = SimpleNamespace( + status=w.status(), + sec2_session_open=w.state == SecState.CLAIMED, + use_without_key=use_without_key, + claim=claim, + rotate_key=rotate_key, + ) + self.config = SimpleNamespace(cached=w.config, read=read, write=write) + self.legacy = SimpleNamespace( + mac_address="AA:BB:CC:DD:EE:FF", + trigger_dfu_bootloader=trigger_dfu_bootloader, + read_ident=read_ident, + _redraw_keys=lambda: ("AA:BB:CC:DD:EE:FF",), + ) + self.display = SimpleNamespace(show=show) + + +def _factory(world: _World) -> Any: + @asynccontextmanager + async def open_device() -> AsyncIterator[_Dev]: + world.calls.append("connect") + yield _Dev(world) + world.calls.append("disconnect") + + return open_device + + +@pytest.fixture(autouse=True) +def _migration(monkeypatch: pytest.MonkeyPatch) -> list[Any]: + """plan_migration as a script: needed when the device needs it, equivalent data for 0x0037.""" + seen: list[Any] = [] + + def plan(config: Any, profile: Any, db: Any, *, panel_ic_type: int | None = None) -> Any: + seen.append(panel_ic_type) + needed = config is not None and (profile.needs_migration or not profile.configured) + blocked = config is None or not config.displays + return SimpleNamespace( + needed=needed or blocked, + blocked=blocked, + reason="no panel" if blocked else "Panel EP397YR_800x480 (0x0037)", + needs_confirmation=needed, + entry=SimpleNamespace(name="EP397YR_800x480", panel_ic_type=panel_ic_type or 0x0037), + panel_ic_type=panel_ic_type or 0x0037, + ) + + monkeypatch.setattr(runner_mod, "plan_migration", plan) + monkeypatch.setattr(runner_mod, "apply_migration", lambda config, plan: config) + monkeypatch.setattr(runner_mod.PanelDatabase, "load", classmethod(lambda cls, path=None: None)) + return seen + + +def _restart(run: SetupRun, **kw: Any) -> SetupRun: + """Save and restore, as Home Assistant does across a restart.""" + data = run.to_json() + json.loads(data) # plain JSON + return SetupRun.from_json( + data, + backup_sink=kw.get("sink", lambda b: None), + manifest=MANIFEST, + fetch_image=kw.get("fetch"), + find_device=kw.get("find"), + ) + + +# ── 3.0 devices ────────────────────────────────────────────────────────────── + + +async def test_a_virgin_device_is_configured_checked_and_claimed() -> None: + world = _World(claim_mode=True, fresh=True) + run = SetupRun.start(want_key=True, backup_sink=lambda b: None, manifest=MANIFEST) + + req = await run.run_until_input(_factory(world)) + assert isinstance(req, rq.NeedConfig) # no config on the device and no backup + run.answer(req, _config(displays=[_display(panel_ic_type=0x0037)])) + + req = await run.run_until_input(_factory(world)) + assert isinstance(req, rq.NeedConfirmation) and req.reason == "untested_panel" + run = _restart(run) + run.answer(run.pending, True) + + req = await run.run_until_input(_factory(world)) + assert isinstance(req, rq.NeedConfirmation) and req.reason == "panel_ok" + assert "show:800x480" in world.calls and "config_write" in world.calls + run.answer(req, True) + + req = await run.run_until_input(_factory(world)) + assert isinstance(req, rq.NeedClaimCode) and req.has_panel + run.answer(req, "123456") + + assert await run.run_until_input(_factory(world)) is None + assert run.finished and world.state is SecState.CLAIMED + assert world.calls.count("claim_confirm") == 1 + + +async def test_a_claim_code_is_confirmed_on_the_link_that_asked_for_it() -> None: + world = _World(claim_mode=True, config=_keyed()) # GESTURE, configured + run = SetupRun.start(want_key=True, backup_sink=lambda b: None) + + req = await run.run_until_input(_factory(world)) + assert isinstance(req, rq.NeedClaimCode) + connects = world.calls.count("connect") + assert world.calls[-1] != "disconnect" # held open across the request + run.answer(req, "123456") + await run.run_until_input(_factory(world)) + + assert world.calls.index("claim_confirm") < world.calls.index("disconnect", world.calls.index("claim_begin")) + assert world.calls.count("connect") >= connects + + +async def test_a_wrong_claim_code_is_asked_again() -> None: + world = _World(claim_mode=True, config=_keyed()) + run = SetupRun.start(want_key=True, backup_sink=lambda b: None) + + req = await run.run_until_input(_factory(world)) + run.answer(req, "000000") + again = await run.run_until_input(_factory(world)) + + assert isinstance(again, rq.NeedClaimCode) and again.retry + assert "claim_abort" in world.calls and world.state is SecState.UNCLAIMED + + +async def test_an_open_device_asks_for_the_key_choice_then_needs_the_gesture() -> None: + world = _World(config=_keyed()) + run = SetupRun.start(want_key=None, backup_sink=lambda b: None) + + req = await run.run_until_input(_factory(world)) + assert isinstance(req, rq.NeedKeyChoice) + run.answer(req, True) + + req = await run.run_until_input(_factory(world)) + assert isinstance(req, rq.NeedGesture) and req.gesture == "claim_mode" + world.claim_mode = True # the user power-cycles twice + run.answer(req, None) + + assert isinstance(await run.run_until_input(_factory(world)), rq.NeedClaimCode) + + +async def test_claim_mode_without_a_key_is_left_and_the_device_configured() -> None: + # The EN05 on 2026-11-18: fresh 3.0, no config, in claim mode, owner wants no key. + world = _World(claim_mode=True, fresh=True) + run = SetupRun.start(want_key=False, backup_sink=lambda b: None) + + req = await run.run_until_input(_factory(world)) + + assert world.calls.count("use_without_key") == 1 and not world.claim_mode + assert isinstance(req, rq.NeedConfig) # no config, no backup: the caller supplies one + + +async def test_a_claimed_device_with_a_2x_key_is_rotated() -> None: + world = _World(state=SecState.CLAIMED, key_legacy=True, config=_keyed()) + run = SetupRun.start(want_key=True, backup_sink=lambda b: None) + + assert await run.run_until_input(_factory(world)) is None + assert run.finished and world.calls.count("rotate_key") == 1 + + +async def test_a_locked_device_finishes_with_the_factory_reset_note() -> None: + world = _World(state=SecState.LOCKED, config=_keyed()) + run = SetupRun.start(want_key=True, backup_sink=lambda b: None) + + assert await run.run_until_input(_factory(world)) is None + assert run.finished and "factory_reset" in run.notes + + +async def test_a_declined_panel_check_stops_the_run_and_asks_again_on_resume() -> None: + world = _World(claim_mode=True, fresh=True, config=_keyed()) # FRESH: verify, claim + run = SetupRun.start(want_key=True, backup_sink=lambda b: None) + + req = await run.run_until_input(_factory(world)) + assert isinstance(req, rq.NeedConfirmation) and req.reason == "panel_ok" + run.answer(req, False) + + assert await run.run_until_input(_factory(world)) is None + assert not run.finished and run.stopped == "panel_ok" + run = _restart(run) + again = await run.run_until_input(_factory(world)) + assert isinstance(again, rq.NeedConfirmation) and again.reason == "panel_ok" + + +# ── from 2.x ───────────────────────────────────────────────────────────────── + + +async def test_a_2x_esp32_is_backed_up_then_asked_for_a_wired_install_and_resumed_on_3_0() -> None: + world = _World(major=2, target=FirmwareTarget.ESP32, config=_keyed()) + sunk: list[bytes] = [] + run = SetupRun.start(want_key=False, backup_sink=sunk.append, manifest=MANIFEST) + + req = await run.run_until_input(_factory(world)) + assert isinstance(req, rq.NeedBoardChoice) # several ESP32-S3 boards + assert "s3-n32r8-extuart" in req.candidates + run.answer(req, "s3-n32r8-extuart") + + req = await run.run_until_input(_factory(world)) + assert isinstance(req, rq.NeedWiredInstall) + assert req.files == ("opendisplay-s3-n32r8-extuart-merged.bin",) and req.erases_config + assert req.url.startswith("https://opendisplay.org/firmware/install") + + # The backup went to the sink with its key; the saved run holds none. + assert len(sunk) == 1 and KEY.hex() in json.dumps(json.loads(sunk[0])) + saved = run.to_json() + assert KEY.hex() not in saved and KEY.hex().upper() not in saved + + run = _restart(run, sink=sunk.append) + world.major, world.claim_mode, world.fresh, world.config = 3, True, True, None # flashed, config gone + run.answer(run.pending, None) + + req = await run.run_until_input(_factory(world)) + assert "use_without_key" in world.calls + assert isinstance(req, rq.NeedConfirmation) and req.reason == "untested_panel" # from the backup + assert len(sunk) == 1 # not backed up twice + + +async def test_a_saved_wired_install_request_is_not_repeated_once_the_device_runs_3_0() -> None: + world = _World(major=2, config=_keyed()) + run = SetupRun.start(want_key=False, backup_sink=lambda b: None, manifest=MANIFEST) + run.answer(await run.run_until_input(_factory(world)), "s3-n32r8-extuart") + assert isinstance(await run.run_until_input(_factory(world)), rq.NeedWiredInstall) + + run = _restart(run) + world.major, world.config = 3, _keyed() # updated meanwhile, config kept, open + req = await run.run_until_input(_factory(world)) # the request is not answered + + assert not isinstance(req, rq.NeedWiredInstall) + + +async def test_a_2x_bg22_is_installed_over_bluetooth_after_the_no_rollback_confirmation( + monkeypatch: pytest.MonkeyPatch, +) -> None: + world = _World(major=2, target=FirmwareTarget.EFR32BG22, config=_keyed(ICType.EFR32BG22)) + sent: list[tuple[int, Any]] = [] + + async def fake_ota(image: bytes, ble_device: Any, progress: Any) -> None: + sent.append((len(image), ble_device)) + world.major, world.needs_migration = 3, True # BG22 keeps its config; it needs drive data + + monkeypatch.setattr(runner_mod, "perform_silabs_ota", fake_ota) + monkeypatch.setattr(runner_mod.redraw, "mark_redrawing", lambda *k, allowance: None) + fetched: list[str] = [] + + image = b"\xeb\x17\xa6\x03" + bytes(60) + + async def fetch(name: str) -> bytes: + fetched.append(name) + return image + + async def find(address: str) -> Any: + return SimpleNamespace(address=address, name="OTA") + + run = SetupRun.start( + want_key=False, backup_sink=lambda b: None, manifest=_manifest_with(image), fetch_image=fetch, find_device=find + ) + req = await run.run_until_input(_factory(world)) + assert isinstance(req, rq.NeedConfirmation) and req.reason == "no_rollback" + assert not sent + run.answer(req, True) + + req = await run.run_until_input(_factory(world)) + assert fetched == ["opendisplay-bg22-ota.gbl"] and len(sent) == 1 + assert "enter_dfu" in world.calls + assert isinstance(req, rq.NeedConfirmation) and req.reason == "untested_panel" + + +def _manifest_with(image: bytes, name: str = "opendisplay-bg22-ota.gbl") -> ReleaseManifest: + """The 3.0.2 manifest with ``name`` standing for ``image`` (size and SHA-256).""" + digest = hashlib.sha256(image).hexdigest() + artefacts = tuple( + dataclasses.replace(a, size=len(image), sha256=digest) if a.file == name else a for a in MANIFEST.artefacts + ) + return dataclasses.replace(MANIFEST, artefacts=artefacts) + + +async def test_an_image_that_does_not_match_the_manifest_is_not_sent(monkeypatch: pytest.MonkeyPatch) -> None: + world = _World(major=2, target=FirmwareTarget.EFR32BG22, config=_keyed(ICType.EFR32BG22)) + sent: list[bytes] = [] + + async def fake_ota(image: bytes, ble_device: Any, progress: Any) -> None: + sent.append(image) + + async def fetch(name: str) -> bytes: + return b"not the release" + + async def find(address: str) -> Any: + return SimpleNamespace(address=address) + + monkeypatch.setattr(runner_mod, "perform_silabs_ota", fake_ota) + run = SetupRun.start( + want_key=False, backup_sink=lambda b: None, manifest=MANIFEST, fetch_image=fetch, find_device=find + ) + run.answer(await run.run_until_input(_factory(world)), True) # no_rollback + + with pytest.raises(SetupError, match="SHA-256"): + await run.run_until_input(_factory(world)) + assert not sent and "enter_dfu" not in world.calls + + +async def test_a_2x_device_without_a_manifest_is_an_error() -> None: + world = _World(major=2, config=_keyed()) + run = SetupRun.start(want_key=False, backup_sink=lambda b: None) + + with pytest.raises(SetupError, match="manifest"): + await run.run_until_input(_factory(world)) + + +async def test_a_claimed_device_that_lost_its_config_is_configured_from_the_backup_without_its_0x27() -> None: + world = _World(state=SecState.CLAIMED, config=None) + run = SetupRun.start(want_key=True, backup_sink=lambda b: None) + run.answer(await run.run_until_input(_factory(world)), _keyed()) # NeedConfig + run.answer(await run.run_until_input(_factory(world)), True) # untested_panel + + await run.run_until_input(_factory(world)) + + assert world.config is not None and world.config.security_config is None # the device keeps its key + + +async def test_a_panel_the_database_cannot_place_is_asked_for(_migration: list[Any]) -> None: + world = _World(config=_config(displays=[]), needs_migration=True) + run = SetupRun.start(want_key=False, backup_sink=lambda b: None) + + req = await run.run_until_input(_factory(world)) + assert isinstance(req, rq.NeedPanelChoice) and req.reason == "no panel" + run.answer(req, 0x0037) + await run.run_until_input(_factory(world)) + + assert _migration[-1] == 0x0037 + + +async def test_a_step_the_device_never_takes_is_an_error_not_a_loop() -> None: + world = _World(claim_mode=True, fresh=True, config=_keyed()) + + async def ignored() -> None: + world.calls.append("use_without_key") # claim mode stays on + + run = SetupRun.start(want_key=False, backup_sink=lambda b: None) + + @asynccontextmanager + async def open_device() -> AsyncIterator[_Dev]: + dev = _Dev(world) + dev.security.use_without_key = ignored + yield dev + + with pytest.raises(SetupError, match="use_without_key"): + await run.run_until_input(open_device) + assert world.calls.count("use_without_key") == 2 + + +async def test_a_2x_nrf54_is_installed_over_smp(monkeypatch: pytest.MonkeyPatch) -> None: + from opendisplay.firmware import smp # pylint: disable=import-outside-toplevel + + world = _World(major=1, target=FirmwareTarget.NRF54, config=_keyed(ic_type=0xFF)) + image = bytes.fromhex("3db8f396") + bytes(60) + done: list[str] = [] + + @asynccontextmanager + async def session(ble_device: Any, **kw: Any) -> AsyncIterator[str]: + done.append(f"session:{ble_device.address}") + yield "client" + + async def upload(client: Any, data: bytes, **kw: Any) -> None: + done.append(f"upload:{len(data)}") + + async def test_and_reset(client: Any) -> bytes: + done.append("test_and_reset") + world.major = 3 + return b"" + + monkeypatch.setattr(smp, "session", session) + monkeypatch.setattr(smp, "upload", upload) + monkeypatch.setattr(smp, "test_and_reset", test_and_reset) + monkeypatch.setattr(runner_mod.redraw, "mark_redrawing", lambda *k, allowance: None) + + async def fetch(name: str) -> bytes: + return image + + async def find(address: str) -> Any: + return SimpleNamespace(address=address) + + name = "opendisplay-xiao_nrf54l15-ota.bin" + run = SetupRun.start( + want_key=False, + backup_sink=lambda b: None, + manifest=_manifest_with(image, name), + fetch_image=fetch, + find_device=find, + ) + req = await run.run_until_input(_factory(world)) + assert isinstance(req, rq.NeedBoardChoice) # an unknown chip: every board is offered + run.answer(req, "xiao_nrf54l15") + await run.run_until_input(_factory(world)) + + assert done == ["session:AA:BB:CC:DD:EE:FF", f"upload:{len(image)}", "test_and_reset"] + assert "enter_dfu" not in world.calls # 1.1.x serves SMP in its app From 23efb8be55c787a83b50bf21daed80508eabb516 Mon Sep 17 00:00:00 2001 From: gabriel Date: Wed, 18 Nov 2026 13:28:04 +0100 Subject: [PATCH 5/9] feat: fetch release files from GitHub, checked against the manifest and cached ReleaseDownloader reads a Firmware_Unified release manifest (a given tag, or the latest) and fetches its files with the standard library, refusing and not caching a file whose SHA-256 differs from the manifest. Files are kept per tag under the user cache directory ($OPENDISPLAY_CACHE, ~/Library/Caches, $XDG_CACHE_HOME, %LOCALAPPDATA%). SetupRun now also takes the manifest as an async callable, called once and only when a 2.x device needs it, so a run on a 3.0 device contacts nothing. Claude-Session: https://claude.ai/code/session_01Ap1E7UWkx9cYSPdYvmgmu3 --- src/opendisplay/firmware/download.py | 105 +++++++++++++++++++++++++++ src/opendisplay/setup/runner.py | 26 +++++-- tests/unit/firmware/test_download.py | 81 +++++++++++++++++++++ tests/unit/test_setup_runner.py | 19 +++++ 4 files changed, 223 insertions(+), 8 deletions(-) create mode 100644 src/opendisplay/firmware/download.py create mode 100644 tests/unit/firmware/test_download.py diff --git a/src/opendisplay/firmware/download.py b/src/opendisplay/firmware/download.py new file mode 100644 index 0000000..3984039 --- /dev/null +++ b/src/opendisplay/firmware/download.py @@ -0,0 +1,105 @@ +"""Release files from GitHub (``OpenDisplay/Firmware_Unified`` releases), checked and cached. + +The release's ``manifest.json`` names every file with its SHA-256; a file that does not match is +refused and not cached. Files are kept under the user's cache directory, per release tag, so a +second run sends nothing. Standard library only; Home Assistant passes its own fetcher instead. +""" + +from __future__ import annotations + +import asyncio +import hashlib +import json +import os +import sys +import urllib.request +from collections.abc import Callable +from pathlib import Path +from typing import Final + +from ..exceptions import OpenDisplayError +from .releases import ReleaseManifest + +REPO: Final = "OpenDisplay/Firmware_Unified" +LATEST_URL: Final = f"https://api.github.com/repos/{REPO}/releases/latest" +_DOWNLOAD_URL: Final = f"https://github.com/{REPO}/releases/download/" +_USER_AGENT: Final = "py-opendisplay" +_TIMEOUT_S: Final = 60.0 + +Get = Callable[[str], bytes] + + +class DownloadError(OpenDisplayError): + """A release file could not be fetched, or did not match the manifest.""" + + +def cache_dir() -> Path: + """``$OPENDISPLAY_CACHE/firmware``, else the platform's user cache directory.""" + override = os.environ.get("OPENDISPLAY_CACHE") + if override: + return Path(override) / "firmware" + if sys.platform == "darwin": + base = Path.home() / "Library" / "Caches" + elif sys.platform == "win32": + base = Path(os.environ.get("LOCALAPPDATA") or Path.home() / "AppData" / "Local") + else: + base = Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache") + return base / "opendisplay" / "firmware" + + +def _get(url: str) -> bytes: + request = urllib.request.Request(url, headers={"User-Agent": _USER_AGENT}) + try: + with urllib.request.urlopen(request, timeout=_TIMEOUT_S) as response: # noqa: S310 (https only) + data: bytes = response.read() + return data + except OSError as err: + raise DownloadError(f"Could not fetch {url}: {err}") from err + + +class ReleaseDownloader: + """One release: its manifest and its files. + + Args: + tag: The release tag (``"3.0.2"``); ``None`` takes the latest release. + cache: Where files are kept; by default :func:`cache_dir`. + get: Fetches a URL's bytes (blocking; run in a thread); for tests. + """ + + def __init__(self, tag: str | None = None, *, cache: Path | None = None, get: Get | None = None) -> None: + self.tag = tag + self._cache = cache if cache is not None else cache_dir() + self._get = get or _get + self._manifest: ReleaseManifest | None = None + + async def _fetch(self, url: str) -> bytes: + return await asyncio.to_thread(self._get, url) + + async def manifest(self) -> ReleaseManifest: + """The release's manifest (and, for the latest release, its tag).""" + if self._manifest is None: + if self.tag is None: + self.tag = str(json.loads(await self._fetch(LATEST_URL))["tag_name"]) + self._manifest = ReleaseManifest.parse(await self._fetch(f"{_DOWNLOAD_URL}{self.tag}/manifest.json")) + return self._manifest + + async def fetch(self, name: str) -> bytes: + """The release file ``name``, from the cache when it is there. + + Raises: + DownloadError: The release has no such file, it could not be fetched, or its SHA-256 + differs from the manifest's. + """ + manifest = await self.manifest() + artefact = manifest.artefact(name) + if artefact is None: + raise DownloadError(f"Release {self.tag} has no file {name!r}") + path = self._cache / str(self.tag) / name + if path.is_file() and hashlib.sha256(path.read_bytes()).hexdigest() == artefact.sha256: + return path.read_bytes() + data = await self._fetch(f"{_DOWNLOAD_URL}{self.tag}/{name}") + if hashlib.sha256(data).hexdigest() != artefact.sha256: + raise DownloadError(f"{name} from release {self.tag} does not match the manifest's SHA-256") + path.parent.mkdir(parents=True, exist_ok=True) + path.write_bytes(data) + return data diff --git a/src/opendisplay/setup/runner.py b/src/opendisplay/setup/runner.py index f993cca..e9df2f7 100644 --- a/src/opendisplay/setup/runner.py +++ b/src/opendisplay/setup/runner.py @@ -80,6 +80,7 @@ } DeviceFactory = Callable[[], AbstractAsyncContextManager[Any]] +ManifestSource = ReleaseManifest | Callable[[], Awaitable[ReleaseManifest]] FetchImage = Callable[[str], Awaitable[bytes]] FindDevice = Callable[[str], Awaitable[Any]] @@ -108,14 +109,15 @@ def __init__( # pylint: disable=too-many-arguments want_key: bool | None, rotate_legacy_key: bool, backup_sink: Callable[[bytes], None], - manifest: ReleaseManifest | None, + manifest: ManifestSource | None, fetch_image: FetchImage | None, find_device: FindDevice | None, ) -> None: self.want_key = want_key self.rotate_legacy_key = rotate_legacy_key self._sink = backup_sink - self._manifest = manifest + self._manifest_source = manifest + self._manifest: ReleaseManifest | None = manifest if isinstance(manifest, ReleaseManifest) else None self._fetch = fetch_image self._find = find_device self._done: set[Step] = set() @@ -145,7 +147,7 @@ def start( # pylint: disable=too-many-arguments *, want_key: bool | None, backup_sink: Callable[[bytes], None], - manifest: ReleaseManifest | None = None, + manifest: ManifestSource | None = None, fetch_image: FetchImage | None = None, find_device: FindDevice | None = None, rotate_legacy_key: bool = True, @@ -157,7 +159,8 @@ def start( # pylint: disable=too-many-arguments (``None``: an open device then pauses on ``NeedKeyChoice``). backup_sink: Receives the 2.x config backup, with its secrets, as JSON bytes. The run never writes it anywhere else. - manifest: The release to install from a 2.x device (``ReleaseManifest.parse``). + manifest: The release to install from a 2.x device (``ReleaseManifest.parse``), or + an async callable returning it, called once and only for a 2.x device. fetch_image: Returns a release file's bytes by name, for an install over Bluetooth. find_device: Finds the display's ``BLEDevice`` by address (Home Assistant passes its own); needed for an install over Bluetooth. @@ -199,7 +202,7 @@ def from_json( # pylint: disable=too-many-arguments data: str, *, backup_sink: Callable[[bytes], None], - manifest: ReleaseManifest | None = None, + manifest: ManifestSource | None = None, fetch_image: FetchImage | None = None, find_device: FindDevice | None = None, ) -> SetupRun: @@ -355,9 +358,16 @@ def _back_up(self, dev: Any) -> None: self._sink(json.dumps(config_to_json(config), indent=2).encode()) self._backup = config_to_json(strip_secrets(config)) - def _choose_board(self, dev: Any) -> BoardRelease | rq.NeedBoardChoice: + async def _release(self) -> ReleaseManifest: if self._manifest is None: - raise SetupError("Installing 3.0 needs the release manifest (SetupRun.start(manifest=...))") + if self._manifest_source is None or isinstance(self._manifest_source, ReleaseManifest): + raise SetupError("Installing 3.0 needs the release manifest (SetupRun.start(manifest=...))") + self._manifest = await self._manifest_source() + return self._manifest + + async def _choose_board(self, dev: Any) -> BoardRelease | rq.NeedBoardChoice: + await self._release() + assert self._manifest is not None if self._board is not None: chosen = self._manifest.board(self._board) if chosen is None: @@ -371,7 +381,7 @@ def _choose_board(self, dev: Any) -> BoardRelease | rq.NeedBoardChoice: return rq.NeedBoardChoice(candidates=tuple(b.board for b in boards)) async def _install(self, dev: Any, close: Callable[[], Awaitable[None]]) -> rq.Request | None: - board = self._choose_board(dev) + board = await self._choose_board(dev) if isinstance(board, rq.NeedBoardChoice): return board assert self._manifest is not None diff --git a/tests/unit/firmware/test_download.py b/tests/unit/firmware/test_download.py new file mode 100644 index 0000000..6f9ddc3 --- /dev/null +++ b/tests/unit/firmware/test_download.py @@ -0,0 +1,81 @@ +"""Release files from GitHub: the manifest by tag (or the latest), files checked and cached.""" + +from __future__ import annotations + +import hashlib +import json +from pathlib import Path + +import pytest + +from opendisplay.firmware import download + +MANIFEST = (Path(__file__).parents[2] / "fixtures" / "firmware" / "manifest-3.0.2.json").read_bytes() +BASE = "https://github.com/OpenDisplay/Firmware_Unified/releases/download/3.0.2/" +GBL = "opendisplay-bg22-ota.gbl" + + +class _Web: + def __init__(self, files: dict[str, bytes]) -> None: + self.files = files + self.asked: list[str] = [] + + def __call__(self, url: str) -> bytes: + self.asked.append(url) + if url not in self.files: + raise download.DownloadError(f"404 {url}") + return self.files[url] + + +def _manifest_for(image: bytes) -> bytes: + doc = json.loads(MANIFEST) + for artefact in doc["artefacts"]: + if artefact["file"] == GBL: + artefact["sha256"], artefact["size"] = hashlib.sha256(image).hexdigest(), len(image) + return json.dumps(doc).encode() + + +async def test_the_latest_release_is_resolved_then_its_manifest_read(tmp_path: Path) -> None: + web = _Web({download.LATEST_URL: json.dumps({"tag_name": "3.0.2"}).encode(), BASE + "manifest.json": MANIFEST}) + + manifest = await download.ReleaseDownloader(cache=tmp_path, get=web).manifest() + + assert manifest.version == "3.0.2" + assert web.asked == [download.LATEST_URL, BASE + "manifest.json"] + + +async def test_a_file_is_checked_against_the_manifest_and_cached(tmp_path: Path) -> None: + image = b"\xeb\x17\xa6\x03" + bytes(60) + web = _Web({BASE + "manifest.json": _manifest_for(image), BASE + GBL: image}) + releases = download.ReleaseDownloader("3.0.2", cache=tmp_path, get=web) + + assert await releases.fetch(GBL) == image + again = download.ReleaseDownloader("3.0.2", cache=tmp_path, get=web) + assert await again.fetch(GBL) == image + + assert web.asked.count(BASE + GBL) == 1 # the second came from the cache + assert (tmp_path / "3.0.2" / GBL).read_bytes() == image + + +async def test_a_file_that_does_not_match_is_refused_and_not_cached(tmp_path: Path) -> None: + web = _Web({BASE + "manifest.json": _manifest_for(b"the real one"), BASE + GBL: b"something else"}) + + with pytest.raises(download.DownloadError, match="SHA-256"): + await download.ReleaseDownloader("3.0.2", cache=tmp_path, get=web).fetch(GBL) + assert not (tmp_path / "3.0.2" / GBL).exists() + + +async def test_a_file_the_release_does_not_have_is_refused(tmp_path: Path) -> None: + web = _Web({BASE + "manifest.json": MANIFEST}) + + with pytest.raises(download.DownloadError, match="no file"): + await download.ReleaseDownloader("3.0.2", cache=tmp_path, get=web).fetch("nope.bin") + + +def test_the_cache_follows_the_platform_or_the_override(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None: + monkeypatch.setenv("OPENDISPLAY_CACHE", str(tmp_path)) + assert download.cache_dir() == tmp_path / "firmware" + monkeypatch.delenv("OPENDISPLAY_CACHE") + monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg")) + monkeypatch.setattr(download.sys, "platform", "linux") + assert download.cache_dir() == tmp_path / "xdg" / "opendisplay" / "firmware" diff --git a/tests/unit/test_setup_runner.py b/tests/unit/test_setup_runner.py index 085f37c..0583f78 100644 --- a/tests/unit/test_setup_runner.py +++ b/tests/unit/test_setup_runner.py @@ -530,3 +530,22 @@ async def find(address: str) -> Any: assert done == ["session:AA:BB:CC:DD:EE:FF", f"upload:{len(image)}", "test_and_reset"] assert "enter_dfu" not in world.calls # 1.1.x serves SMP in its app + + +async def test_the_manifest_may_be_fetched_only_when_a_2x_device_needs_it() -> None: + asked: list[str] = [] + + async def manifest() -> ReleaseManifest: + asked.append("manifest") + return MANIFEST + + open_device = _World(config=_keyed()) # 3.0, open, configured: nothing to install + run = SetupRun.start(want_key=False, backup_sink=lambda b: None, manifest=manifest) + assert await run.run_until_input(_factory(open_device)) is None + assert asked == [] + + legacy = _World(major=2, config=_keyed()) + run = SetupRun.start(want_key=False, backup_sink=lambda b: None, manifest=manifest) + assert isinstance(await run.run_until_input(_factory(legacy)), rq.NeedBoardChoice) + assert isinstance(await run.run_until_input(_factory(legacy)), rq.NeedBoardChoice) + assert asked == ["manifest"] # once From 9ddd24fdd0e227035eba110c6e54d97cf64cd9f6 Mon Sep 17 00:00:00 2001 From: gabriel Date: Wed, 18 Nov 2026 13:32:38 +0100 Subject: [PATCH 6/9] feat: opendisplay setup, upgrade and update setup runs the setup flow and turns each request into a prompt: the key choice, the claim-mode gesture, the claim code, the panel check, untested drive data, a board, a config file. upgrade is the same flow for a 2.x display: it backs the config up (mode 0600, never over an earlier file), installs 3.0 over Bluetooth where the release allows it or names the USB install files and the website flasher, saves its state, and goes on from it when run again once the display runs 3.0. update sends one 3.x image with dev.firmware.update() and asks first on a display that cannot return to its old image. README: a CLI list entry and a section on setting up a display. Claude-Session: https://claude.ai/code/session_01Ap1E7UWkx9cYSPdYvmgmu3 --- README.md | 47 ++++++ src/opendisplay/cli.py | 2 + src/opendisplay/cli_setup.py | 250 ++++++++++++++++++++++++++++++++ tests/unit/test_cli_setup.py | 167 +++++++++++++++++++++ tests/unit/test_setup_runner.py | 2 +- 5 files changed, 467 insertions(+), 1 deletion(-) create mode 100644 src/opendisplay/cli_setup.py create mode 100644 tests/unit/test_cli_setup.py diff --git a/README.md b/README.md index 978cb36..46be53e 100644 --- a/README.md +++ b/README.md @@ -113,6 +113,13 @@ opendisplay backup-config --device OD4064C9 backup.json opendisplay migrate --device OD4064C9 --dry-run opendisplay migrate --device OD4064C9 +# Set up a 3.0 display, or move a 2.x one to 3.0 (see "Setting up a display" below) +opendisplay setup --device OD4064C9 --claim +opendisplay upgrade --device OD5A2F4C --no-key --state-file en05.json + +# Send a firmware 3.x image (see "Firmware 3.x updates" below) +opendisplay update --device OD4064C9 --file opendisplay-s3-n32r8-extuart-app.bin + # Firmware 3.0 device keys (see "Firmware 3.0 security" below) opendisplay claim --device OD4064C9 opendisplay rotate-key --device OD4064C9 @@ -534,6 +541,46 @@ async with opendisplay.connect(name="OD4064C9") as dev: - **Home Assistant** passes `find_device=` (a coroutine giving the `BLEDevice` for an address), so the update works through an ESPHome Bluetooth proxy. +### Setting up a display (setup and upgrade) + +`opendisplay setup` takes a display from wherever it stands to set up, one step at a time: + +- **No config, or a config that needs migration:** configure the panel. +- **Check the panel:** draw a test pattern and ask whether it looks right. +- **Key:** claim it, or use it without a key. +- **A claimed display with a 2.x key:** rotate that key. + +`opendisplay upgrade` is the same flow for a 2.x display: + +1. **Back up** the config to `--backup` (default `opendisplay-backup-.json`). The backup + holds the key, so it is written with mode 0600 and never over an earlier file. +2. **Install 3.0.** A BG22 is installed over Bluetooth through its AppLoader, after you type + `yes`, since it has no old image to return to. A board that needs USB pauses: the command names + the files and the website flasher and saves its state to `--state-file`. +3. **Go on.** Once the display runs 3.0, run the same command again. It goes on from the state + file, restores the config from the backup, then sets the display up. + +```bash +opendisplay upgrade --device OD5A2F4C --no-key --state-file en05.json +# ... install over USB as it says, then (the display may advertise under a new name): +opendisplay upgrade --device ODD2292B --no-key --state-file en05.json +``` + +`--claim` / `--no-key` decide the key, otherwise it asks. `--board` names the board when several +share a chip (ESP32-S3), `--config FILE` gives a config when the display has none and there is no +backup, `--release TAG` picks a Firmware_Unified release (default: the latest; files are checked +against its manifest and cached), and `--yes-untested` writes drive data not yet seen on a panel +without asking. + +In Python the flow is `opendisplay.setup`: + +- `device_state()` and `plan_setup()` say where a device stands and which steps it needs. +- `SetupRun` performs those steps. `run_until_input(open_device)` returns the next request + (`NeedClaimCode`, `NeedConfirmation`, `NeedWiredInstall`, ...), or `None` once the display is + set up or the user declined a confirmation. `answer(request, value)` answers it. +- `to_json()` / `from_json()` save and restore a run across a restart; the saved run never holds a + secret. A resumed run reads the device again, so it never repeats a step the device shows as done. + ### Encryption (firmware 2.x) Firmware 2.x devices with encryption enabled require authentication before accepting any commands (except `read_firmware_version`). For firmware 3.0, see "Firmware 3.0 security" above. Pass the 16-byte AES-128 master key to the constructor — authentication and session setup happen automatically before the first interrogation. diff --git a/src/opendisplay/cli.py b/src/opendisplay/cli.py index e55722f..e40694b 100644 --- a/src/opendisplay/cli.py +++ b/src/opendisplay/cli.py @@ -35,6 +35,7 @@ from .cli_info import _build_info_tree, _info_to_json, _InfoContext from .cli_migrate import add_backup_config_parser, add_migrate_parser from .cli_sec2 import add_sec2_parsers +from .cli_setup import add_setup_parsers from .device import OpenDisplayDevice from .discovery import discover_devices_with_adv from .exceptions import ( @@ -823,6 +824,7 @@ def _build_parser() -> argparse.ArgumentParser: add_backup_config_parser(subparsers) add_migrate_parser(subparsers) add_sec2_parsers(subparsers) + add_setup_parsers(subparsers) return parser diff --git a/src/opendisplay/cli_setup.py b/src/opendisplay/cli_setup.py new file mode 100644 index 0000000..c9e62dc --- /dev/null +++ b/src/opendisplay/cli_setup.py @@ -0,0 +1,250 @@ +"""`opendisplay setup`, `opendisplay upgrade` and `opendisplay update`. + +``setup`` and ``upgrade`` run the setup flow (``opendisplay.setup.SetupRun``) and turn each request +into a prompt. ``upgrade`` is the same flow for a 2.x device: it keeps its state in a file, since +the move to 3.0 may need a USB install in the middle, after which the same command goes on. +``update`` sends one firmware 3.x image with ``dev.firmware.update()``. +""" + +from __future__ import annotations + +import argparse +import json +import os +from collections.abc import Callable +from pathlib import Path +from typing import Any, Final + +from .cli_common import _add_device_options, _console, _error, _handle_ble_error, _run +from .cli_sec2 import _add_key_store_option, _connect_kwargs, _input +from .device import connect +from .exceptions import OpenDisplayError +from .firmware.download import ReleaseDownloader +from .models.config_json import config_from_json +from .setup import requests as rq +from .setup.runner import SetupError, SetupRun + +_YES: Final = ("y", "yes") +_KEY_CHOICE: Final = ( + "Claim this display? It then answers only to clients that hold its key; without a key anyone " + "nearby can change it. [y/N] " +) +_GESTURE: Final = ( + "Put the display in claim mode: power-cycle it twice quickly (off, on, off, on). " + "Press Enter when it shows that it waits to be claimed. " +) +_RESUME: Final = ( + "When the display runs 3.0, run the same command again (with --device set to its new name if it " + "advertises under another one); it goes on from {state}." +) + + +async def _find(address: str) -> Any: + """The display after a reboot, by address (a bleak scan, as the CLI connects everywhere).""" + from bleak import BleakScanner # pylint: disable=import-outside-toplevel + + return await BleakScanner.find_device_by_address(address, timeout=30.0) + + +def _ask(prompt: str) -> bool: + return _input(prompt).strip().lower() in _YES + + +def add_setup_parsers(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None: + """Register ``setup``, ``upgrade`` and ``update``.""" + for name, help_text in ( + ("setup", "Set up a firmware 3.0 display: configure, check the panel, claim (or use without a key)"), + ("upgrade", "Move a firmware 2.x display to 3.0 and set it up (resumable with --state-file)"), + ): + p = subparsers.add_parser(name, help=help_text) + _add_device_options(p) + _add_key_store_option(p) + choice = p.add_mutually_exclusive_group() + choice.add_argument("--claim", dest="want_key", action="store_const", const=True, help="Claim the display") + choice.add_argument( + "--no-key", dest="want_key", action="store_const", const=False, help="Use the display without a key" + ) + p.set_defaults(want_key=None) + p.add_argument("--state-file", metavar="PATH", help="Save the run here and go on from it when run again") + p.add_argument("--backup", metavar="PATH", help="Where the 2.x config backup goes (it holds the key)") + p.add_argument("--config", metavar="FILE", help="A config JSON to start from when the display has none") + p.add_argument("--board", metavar="NAME", help="The board, when several share the chip (s3-n32r8, ...)") + p.add_argument("--release", metavar="TAG", help="The Firmware_Unified release (default: the latest)") + p.add_argument("--yes-untested", action="store_true", help="Do not ask before drive data not seen on a panel") + p.set_defaults(func=lambda args: _run(_setup(args)), upgrade=name == "upgrade") + + update = subparsers.add_parser("update", help="Send a firmware 3.x image to a 3.x display over Bluetooth") + _add_device_options(update) + _add_key_store_option(update) + update.add_argument("--file", required=True, metavar="IMAGE", help="The board's ble-ota file from the release") + update.add_argument("--yes", action="store_true", help="Do not ask, also on a device that cannot roll back") + update.set_defaults(func=lambda args: _run(_update(args))) + + +# ── files ──────────────────────────────────────────────────────────────────── + + +def _backup_sink(path: Path) -> Callable[[bytes], None]: + """Write the backup to ``path``, or ``path-1``, ``path-2``... if taken: never over an earlier one.""" + + def sink(data: bytes) -> None: + target, n = path, 0 + while target.exists(): + n += 1 + target = path.with_name(f"{path.stem}-{n}{path.suffix}") + fd = os.open(target, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600) + with os.fdopen(fd, "wb") as out: + out.write(data) + _console.print(f"Config backup written to [bold]{target}[/bold]. It holds the display's key: keep it safe.") + + return sink + + +def _state_path(args: argparse.Namespace) -> Path | None: + if args.state_file: + return Path(args.state_file) + if args.upgrade: + return Path(f"opendisplay-upgrade-{args.device or args.host}.json") + return None + + +# ── the requests as prompts ────────────────────────────────────────────────── + + +class _Paused(Exception): + """The run waits for something outside the terminal (a USB install).""" + + +def _confirm(request: rq.NeedConfirmation, args: argparse.Namespace) -> bool: + if request.reason == "untested_panel" and args.yes_untested: + return True + _console.print(request.detail) + if request.reason == "no_rollback": + return _input("Type yes to install anyway: ").strip().lower() == "yes" + return _ask("Continue? [y/N] " if request.reason != "panel_ok" else "[y/N] ") + + +def _choose(candidates: tuple[str, ...], given: str | None, what: str) -> str: + if given is not None and given in candidates: + return given + _console.print(f"Which {what}? " + ", ".join(candidates)) + return _input(f"{what.capitalize()}: ").strip() + + +def _answer(request: rq.Request, args: argparse.Namespace) -> Any: # pylint: disable=too-many-return-statements + """The answer to ``request``, from the options or the terminal.""" + if isinstance(request, rq.NeedKeyChoice): + return _ask(_KEY_CHOICE) + if isinstance(request, rq.NeedGesture): + _input(_GESTURE) + return None + if isinstance(request, rq.NeedClaimCode): + if not request.has_panel: + _error("The display cannot show a claim code; claim it with `opendisplay claim` instead.") + if request.retry: + _console.print("That code did not match; the display shows a new one.") + return _input("The 6-digit code on the display: ") + if isinstance(request, rq.NeedConfirmation): + return _confirm(request, args) + if isinstance(request, rq.NeedBoardChoice): + return _choose(request.candidates, args.board, "board") + if isinstance(request, rq.NeedPanelChoice): + _console.print(request.reason) + return int(_input("Panel id (for example 0x0037): ").strip(), 0) + if isinstance(request, rq.NeedConfig): + path = args.config or _input("A config JSON to start from (Config Builder export): ").strip() + return config_from_json(json.loads(Path(path).read_text(encoding="utf-8"))) + _wired_install(request) + raise _Paused + + +def _wired_install(request: rq.NeedWiredInstall) -> None: + _console.print(f"Install firmware 3.0 on board [bold]{request.board}[/bold] over USB:") + for name in request.files: + _console.print(f" {name}") + _console.print(f"Flasher: {request.url}" + (f" Release: {request.release_url}" if request.release_url else "")) + if request.protocol: + _console.print(f"Method: {request.protocol}") + if request.erases_config: + _console.print("This erases the display's config; the backup restores it afterwards.") + + +# ── setup / upgrade ────────────────────────────────────────────────────────── + + +async def _setup(args: argparse.Namespace, *, open_device: Any = None, releases: Any = None) -> None: + releases = releases or ReleaseDownloader(args.release) + state = _state_path(args) + sink = _backup_sink(Path(args.backup or f"opendisplay-backup-{args.device or args.host}.json")) + common: dict[str, Any] = { + "backup_sink": sink, + "manifest": releases.manifest, + "fetch_image": releases.fetch, + "find_device": _find, + } + if state is not None and state.exists(): + run = SetupRun.from_json(state.read_text(encoding="utf-8"), **common) + _console.print(f"Going on from {state}.") + else: + run = SetupRun.start(want_key=args.want_key, **common) + factory = open_device or (lambda: connect(**_connect_kwargs(args))) + + def save() -> None: + if state is not None: + state.write_text(run.to_json(), encoding="utf-8") + + try: + while (request := await run.run_until_input(factory)) is not None: + save() + try: + value = _answer(request, args) + except _Paused: + if state is None: + _error("This step needs a USB install: run again with --state-file PATH to go on afterwards.") + _console.print(_RESUME.format(state=state)) + return + run.answer(request, value) + except SetupError as exc: + save() + _error(str(exc)) + except OpenDisplayError as exc: + save() + _handle_ble_error(exc) + save() + if run.stopped: + _console.print(f"Stopped ({run.stopped}). Run the same command again to go on.") + elif run.finished: + _console.print("The display is set up.") + if state is not None and state.exists(): + state.unlink() + + +# ── update ─────────────────────────────────────────────────────────────────── + + +async def _update(args: argparse.Namespace) -> None: + image = Path(args.file).read_bytes() + try: + async with connect(**_connect_kwargs(args)) as dev: + if dev.firmware.can_roll_back: + _console.print("If the new image does not start, the display returns to its old one by itself.") + else: + _console.print( + "This display cannot return to its old image by itself: if the new one does not start, " + "it waits in its bootloader, and without USB only a debugger recovers it." + ) + if not args.yes and _input("Type yes to send it anyway: ").strip().lower() != "yes": + _error("Not sent.") + last = [-1] + + def progress(done: int, total: int) -> None: + if done * 10 // total != last[0]: + last[0] = done * 10 // total + _console.print(f" {done * 100 // total}%") + + result = await dev.firmware.update(image, on_progress=progress) + except OpenDisplayError as exc: + _handle_ble_error(exc) + _console.print(f"{result.outcome.value}: {result.detail}") + if result.outcome.value != "updated": + raise SystemExit(1) diff --git a/tests/unit/test_cli_setup.py b/tests/unit/test_cli_setup.py new file mode 100644 index 0000000..d8ecc5f --- /dev/null +++ b/tests/unit/test_cli_setup.py @@ -0,0 +1,167 @@ +"""`opendisplay setup`, `upgrade` and `update`: the setup flow's requests as terminal prompts.""" + +from __future__ import annotations + +import json +import stat +from pathlib import Path +from types import SimpleNamespace +from typing import Any + +import pytest +from test_profile import _config, _display +from test_setup_runner import KEY, MANIFEST, _factory, _keyed, _migration, _World # noqa: F401 (autouse fixture) + +from opendisplay import cli, cli_setup +from opendisplay.firmware import UpdateOutcome, UpdateResult +from opendisplay.models.config_json import config_to_json +from opendisplay.models.ident import FirmwareTarget + + +class _Releases: + def __init__(self) -> None: + self.asked = 0 + + async def manifest(self) -> Any: + self.asked += 1 + return MANIFEST + + async def fetch(self, name: str) -> bytes: + raise AssertionError("no download expected") + + +def _args(argv: list[str]) -> Any: + return cli._build_parser().parse_args(argv) + + +def _answers(monkeypatch: pytest.MonkeyPatch, *typed: str) -> list[str]: + prompts: list[str] = [] + queue = list(typed) + + def fake_input(prompt: str) -> str: + prompts.append(prompt) + if not queue: + raise AssertionError(f"Unexpected prompt: {prompt}") + return queue.pop(0) + + monkeypatch.setattr(cli_setup, "_input", fake_input) + return prompts + + +def test_the_key_choice_options() -> None: + assert _args(["setup", "--device", "OD1"]).want_key is None + assert _args(["setup", "--device", "OD1", "--claim"]).want_key is True + assert _args(["setup", "--device", "OD1", "--no-key"]).want_key is False + with pytest.raises(SystemExit): + _args(["setup", "--device", "OD1", "--claim", "--no-key"]) + + +async def test_an_upgrade_pauses_for_the_wired_install_and_resumes_from_the_state_file( + monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture[str] +) -> None: + world = _World(major=2, target=FirmwareTarget.ESP32, config=_keyed()) + state, backup = tmp_path / "run.json", tmp_path / "backup.json" + argv = [ + "upgrade", + "--device", + "OD1", + "--no-key", + "--board", + "s3-n32r8-extuart", + "--state-file", + str(state), + "--backup", + str(backup), + "--yes-untested", + ] + releases = _Releases() + + await cli_setup._setup(_args(argv), open_device=_factory(world), releases=releases) + + out = capsys.readouterr().err + assert "opendisplay-s3-n32r8-extuart-merged.bin" in out and "opendisplay.org/firmware/install" in out + assert "run the same command again" in out + assert state.exists() and KEY.hex() not in state.read_text() + assert KEY.hex() in backup.read_text() + assert stat.S_IMODE(backup.stat().st_mode) == 0o600 + + world.major, world.claim_mode, world.fresh, world.config = 3, True, True, None # flashed over USB + _answers(monkeypatch, "y") # the panel check + await cli_setup._setup(_args(argv), open_device=_factory(world), releases=releases) + + assert "use_without_key" in world.calls and "config_write" in world.calls + assert "set up" in capsys.readouterr().err.lower() + assert releases.asked == 1 # the second run went on from the saved state without a manifest + + +async def test_a_backup_never_overwrites_an_earlier_one(tmp_path: Path) -> None: + first = tmp_path / "backup.json" + first.write_text("earlier") + sink = cli_setup._backup_sink(first) + + sink(b"{}") + + assert first.read_text() == "earlier" + assert (tmp_path / "backup-1.json").read_text() == "{}" + + +async def test_a_bg22_install_needs_the_word_yes(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None: + from opendisplay.setup import requests as rq # pylint: disable=import-outside-toplevel + + _answers(monkeypatch, "y") + request = rq.NeedConfirmation(reason="no_rollback", detail="no old image", subject="bg22") + assert cli_setup._answer(request, _args(["setup", "--device", "OD1", "--yes-untested"])) is False + + _answers(monkeypatch, "yes") + assert cli_setup._answer(request, _args(["setup", "--device", "OD1"])) is True + + +async def test_a_config_file_answers_the_config_request(tmp_path: Path) -> None: + from opendisplay.setup import requests as rq # pylint: disable=import-outside-toplevel + + path = tmp_path / "config.json" + path.write_text(json.dumps(config_to_json(_config(displays=[_display(panel_ic_type=0x0037)])))) + + config = cli_setup._answer(rq.NeedConfig(), _args(["setup", "--device", "OD1", "--config", str(path)])) + + assert config.displays[0].panel_ic_type == 0x0037 + + +async def test_a_claim_reads_the_code_from_the_terminal(monkeypatch: pytest.MonkeyPatch) -> None: + world = _World(claim_mode=True, config=_keyed()) + _answers(monkeypatch, "123 456") + + await cli_setup._setup( + _args(["setup", "--device", "OD1", "--claim"]), open_device=_factory(world), releases=_Releases() + ) + + assert "claim_confirm" in world.calls + + +async def test_update_says_whether_the_device_can_roll_back_and_asks_on_a_bg22( + monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture[str] +) -> None: + image = tmp_path / "ota.gbl" + image.write_bytes(b"\xeb\x17\xa6\x03" + bytes(10)) + sent: list[bytes] = [] + + async def update(data: bytes, **kw: Any) -> UpdateResult: + sent.append(data) + return UpdateResult(UpdateOutcome.UPDATED, "3.0.1", "3.0.2", "The display runs 3.0.2.") + + class _Conn: + async def __aenter__(self) -> Any: + return SimpleNamespace(firmware=SimpleNamespace(can_roll_back=False, update=update)) + + async def __aexit__(self, *exc: object) -> None: + return None + + monkeypatch.setattr(cli_setup, "connect", lambda **kw: _Conn()) + _answers(monkeypatch, "no") + with pytest.raises(SystemExit): + await cli_setup._update(_args(["update", "--device", "OD1", "--file", str(image)])) + assert not sent and "cannot return to its old image" in capsys.readouterr().err + + _answers(monkeypatch, "yes") + await cli_setup._update(_args(["update", "--device", "OD1", "--file", str(image)])) + assert sent and "The display runs 3.0.2." in capsys.readouterr().err diff --git a/tests/unit/test_setup_runner.py b/tests/unit/test_setup_runner.py index 0583f78..4eaff02 100644 --- a/tests/unit/test_setup_runner.py +++ b/tests/unit/test_setup_runner.py @@ -87,7 +87,7 @@ async def exchange_nonces(self) -> Any: return SimpleNamespace(has_panel=self.world.config is not None) async def confirm(self, typed: str) -> None: - if typed != self.world.code: + if "".join(typed.split()) != self.world.code: # as kdf.normalize_typed_code ignores spaces await self.abort() # as ClaimFlow.confirm does raise Sec2CodeMismatchError() self.world.calls.append("claim_confirm") From b08afac0de6bc8e192b3a0d8aaaf76423b0f628b Mon Sep 17 00:00:00 2001 From: gabriel Date: Wed, 18 Nov 2026 20:47:56 +0100 Subject: [PATCH 7/9] feat: dev.config.clear() (CONFIG_CLEAR 0x0045) and `opendisplay raw` ConfigView.clear() erases the stored config and refreshes the profile; a NACK raises ConfigClearError. OpenDisplayDevice.send_raw() sends one frame (encrypted with a session) and returns the reply unchecked, and `opendisplay raw --cmd HEX [--payload HEX] [--no-reply]` prints it, as a debugging aid. The README covers both, and the setup step lines. Claude-Session: https://claude.ai/code/session_01Ap1E7UWkx9cYSPdYvmgmu3 --- README.md | 11 ++++++ src/opendisplay/__init__.py | 2 + src/opendisplay/cli.py | 2 + src/opendisplay/cli_raw.py | 54 +++++++++++++++++++++++++ src/opendisplay/device/api.py | 12 ++++++ src/opendisplay/device/facade.py | 27 +++++++++++++ src/opendisplay/exceptions.py | 7 ++++ src/opendisplay/protocol/__init__.py | 2 + src/opendisplay/protocol/commands.py | 10 +++++ tests/unit/data/public_api.json | 3 ++ tests/unit/test_cli_raw.py | 59 ++++++++++++++++++++++++++++ tests/unit/test_device_api.py | 47 ++++++++++++++++++++++ 12 files changed, 236 insertions(+) create mode 100644 src/opendisplay/cli_raw.py create mode 100644 tests/unit/test_cli_raw.py diff --git a/README.md b/README.md index 46be53e..fe48158 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,9 @@ async with opendisplay.connect("AA:BB:CC:DD:EE:FF") as dev: config = await dev.config.read() # raises NoStoredConfigError when the device has none ``` +`await dev.config.clear()` erases the stored config (CONFIG_CLEAR 0x0045) and refreshes the +profile. A claimed firmware 3.0 device keeps its reset-pin settings (the 0x27 packet). + `dev.profile` is built from the firmware version, the stored config and, on firmware 3.0 and up, the device identity. Everything not yet on the new surface is reached through `dev.legacy`, the wrapped `OpenDisplayDevice`. `OpenDisplayDevice` remains supported. @@ -120,6 +123,10 @@ opendisplay upgrade --device OD5A2F4C --no-key --state-file en05.json # Send a firmware 3.x image (see "Firmware 3.x updates" below) opendisplay update --device OD4064C9 --file opendisplay-s3-n32r8-extuart-app.bin +# Debugging: send one command frame and print the reply as hex (nothing checks it) +opendisplay raw --device OD4064C9 --cmd 0043 +opendisplay raw --device OD4064C9 --cmd 000f --no-reply + # Firmware 3.0 device keys (see "Firmware 3.0 security" below) opendisplay claim --device OD4064C9 opendisplay rotate-key --device OD4064C9 @@ -550,6 +557,9 @@ async with opendisplay.connect(name="OD4064C9") as dev: - **Key:** claim it, or use it without a key. - **A claimed display with a 2.x key:** rotate that key. +It prints a line as each step starts. When it wrote the config itself, it always checks the panel +afterwards, with a key or without. + `opendisplay upgrade` is the same flow for a 2.x display: 1. **Back up** the config to `--backup` (default `opendisplay-backup-.json`). The backup @@ -578,6 +588,7 @@ In Python the flow is `opendisplay.setup`: - `SetupRun` performs those steps. `run_until_input(open_device)` returns the next request (`NeedClaimCode`, `NeedConfirmation`, `NeedWiredInstall`, ...), or `None` once the display is set up or the user declined a confirmation. `answer(request, value)` answers it. +- `on_step`, if set, is called with each step just before it runs. - `to_json()` / `from_json()` save and restore a run across a restart; the saved run never holds a secret. A resumed run reads the device again, so it never repeats a step the device shows as done. diff --git a/src/opendisplay/__init__.py b/src/opendisplay/__init__.py index 1552996..c4e80a6 100644 --- a/src/opendisplay/__init__.py +++ b/src/opendisplay/__init__.py @@ -27,6 +27,7 @@ AuthenticationRequiredError, BLEConnectionError, BLETimeoutError, + ConfigClearError, ConfigKeyMismatchError, ConfigParseError, ConfigSecretNeedsClaimError, @@ -181,6 +182,7 @@ def _package_version() -> str: "InvalidResponseError", "ImageEncodingError", "IntegrityCheckError", + "ConfigClearError", "ConfigWriteBusyError", "DriveModeSubstitutedError", "DriveModeTemperatureError", diff --git a/src/opendisplay/cli.py b/src/opendisplay/cli.py index e40694b..26d03aa 100644 --- a/src/opendisplay/cli.py +++ b/src/opendisplay/cli.py @@ -34,6 +34,7 @@ from .cli_drive import cmd_upload_mode from .cli_info import _build_info_tree, _info_to_json, _InfoContext from .cli_migrate import add_backup_config_parser, add_migrate_parser +from .cli_raw import add_raw_parser from .cli_sec2 import add_sec2_parsers from .cli_setup import add_setup_parsers from .device import OpenDisplayDevice @@ -825,6 +826,7 @@ def _build_parser() -> argparse.ArgumentParser: add_migrate_parser(subparsers) add_sec2_parsers(subparsers) add_setup_parsers(subparsers) + add_raw_parser(subparsers) return parser diff --git a/src/opendisplay/cli_raw.py b/src/opendisplay/cli_raw.py new file mode 100644 index 0000000..982f56b --- /dev/null +++ b/src/opendisplay/cli_raw.py @@ -0,0 +1,54 @@ +"""`opendisplay raw`: send one command frame and print the reply (a debugging aid). + +The frame is ``[cmd:2 big-endian][payload]``. On a device with a session it goes out encrypted +like any other command. The reply is printed as it arrived; nothing checks or interprets it, and +nothing stops a command that changes or erases the device. +""" + +from __future__ import annotations + +import argparse +import re + +from .cli_common import _add_device_options, _console, _handle_ble_error, _run +from .cli_sec2 import _add_key_store_option, _connect_kwargs +from .device import connect +from .exceptions import OpenDisplayError + + +def _command(text: str) -> int: + value = int(text, 16) if re.fullmatch(r"(0x)?[0-9a-fA-F]{1,4}", text) else -1 + if not 0 <= value <= 0xFFFF: + raise argparse.ArgumentTypeError(f"{text!r} is not a 2-byte hex command such as 0045") + return value + + +def _payload(text: str) -> bytes: + try: + return bytes.fromhex(text) + except ValueError as err: + raise argparse.ArgumentTypeError(f"{text!r} is not hex bytes") from err + + +def add_raw_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None: + """Register ``raw``.""" + p = subparsers.add_parser("raw", help="Debug: send one command frame and print the reply as hex") + _add_device_options(p) + _add_key_store_option(p) + p.add_argument("--cmd", required=True, type=_command, metavar="HEX", help="The command code, e.g. 0045") + p.add_argument("--payload", type=_payload, default=b"", metavar="HEX", help="Bytes after the command code") + p.add_argument("--no-reply", action="store_true", help="Send and wait for nothing (e.g. a reboot)") + p.add_argument("--reply-timeout", type=float, default=10.0, metavar="S", help="How long to wait for the reply") + p.set_defaults(func=lambda args: _run(_raw(args))) + + +async def _raw(args: argparse.Namespace) -> None: + frame = args.cmd.to_bytes(2, "big") + args.payload + try: + async with connect(**_connect_kwargs(args)) as dev: + reply = await dev.legacy.send_raw(frame, reply=not args.no_reply, timeout=args.reply_timeout) + except OpenDisplayError as exc: + _handle_ble_error(exc) + _console.print(f"sent {frame.hex(' ')}") + if reply is not None: + print(f"reply {reply.hex(' ')}") diff --git a/src/opendisplay/device/api.py b/src/opendisplay/device/api.py index 58bf8a0..6b05115 100644 --- a/src/opendisplay/device/api.py +++ b/src/opendisplay/device/api.py @@ -115,6 +115,18 @@ async def write(self, config: GlobalConfig) -> None: await self._device.legacy.write_config(config) await self._device.refresh() + async def clear(self) -> None: + """Erase the device's stored config (CONFIG_CLEAR), then refresh the profile from the device. + + A claimed firmware 3.0 device keeps its reset-pin settings (the 0x27 packet). + + Raises: + ConfigClearError: The device refused; its config is unchanged. + """ + await self._device.legacy.clear_config() + self._cached = None + await self._device.refresh() + _RESERVED_MODES = { "fast": "'fast' is reached with refresh_mode=RefreshMode.FAST", diff --git a/src/opendisplay/device/facade.py b/src/opendisplay/device/facade.py index c848013..36fb4d4 100644 --- a/src/opendisplay/device/facade.py +++ b/src/opendisplay/device/facade.py @@ -19,6 +19,7 @@ ) from ..exceptions import ( BLEConnectionError, + ConfigClearError, IdentNotSupportedError, ImageEncodingError, OpenDisplayConnectionError, @@ -41,6 +42,7 @@ OD_LAN_TCP_PORT, CommandCode, build_buzzer_activate_command, + build_config_clear_command, build_deep_sleep_command, build_enter_dfu_command, build_led_activate_command, @@ -1243,6 +1245,31 @@ async def write_config(self, config: GlobalConfig) -> None: # SHOW_KEY_ON_SCREEN change); noting it lets the next replies and connects wait. redraw.mark_redrawing(*self._redraw_keys()) + @_serialized + async def send_raw(self, frame: bytes, *, reply: bool = True, timeout: float = 10.0) -> bytes | None: + """Send ``frame`` (``[cmd:2 BE][payload]``, encrypted with a session) and return one reply, unchecked. + + A debugging aid: ``reply=False`` waits for nothing; a reboot or redraw it causes is not noted. + """ + await self._channel.write(frame) + return await self._channel.read(timeout) if reply else None + + @_serialized + async def clear_config(self) -> None: + """Erase the stored config (CONFIG_CLEAR 0x0045); a claimed device keeps its 0x27 reset-pin fields. + + Raises: + ConfigClearError: The device answered with a NACK; nothing was erased. + InvalidResponseError: Any other reply. + """ + await self._channel.write(build_config_clear_command()) + response = await self._channel.read(self.TIMEOUT_ACK) + if len(response) >= 2 and response[0] == 0xFF and response[1] == CommandCode.CONFIG_CLEAR & 0xFF: + raise ConfigClearError() + validate_ack_response(response, CommandCode.CONFIG_CLEAR) + self._config = None + _LOGGER.info("Config cleared on %s", self.mac_address) + def export_config_json(self, file_path: str) -> None: """Export device config to JSON file (Open Display Config Builder format). diff --git a/src/opendisplay/exceptions.py b/src/opendisplay/exceptions.py index 7c3ad39..db312cf 100644 --- a/src/opendisplay/exceptions.py +++ b/src/opendisplay/exceptions.py @@ -233,6 +233,13 @@ def __init__( super().__init__(message) +class ConfigClearError(ProtocolError): + """The device refused or failed to erase its stored config (CONFIG_CLEAR 0x0045 NACK).""" + + def __init__(self, message: str = "The device did not erase its config.") -> None: + super().__init__(message) + + class ConfigSecretNeedsClaimError(ProtocolError): """An unclaimed firmware 3.0 device refused a config that carries a secret; nothing was stored. diff --git a/src/opendisplay/protocol/__init__.py b/src/opendisplay/protocol/__init__.py index 94edfcd..05d7e33 100644 --- a/src/opendisplay/protocol/__init__.py +++ b/src/opendisplay/protocol/__init__.py @@ -35,6 +35,7 @@ build_authenticate_step1, build_authenticate_step2, build_buzzer_activate_command, + build_config_clear_command, build_deep_sleep_command, build_direct_write_data_command, build_direct_write_end_command, @@ -105,6 +106,7 @@ "build_enter_dfu_command", "build_deep_sleep_command", "build_power_off_command", + "build_config_clear_command", "build_reboot_command", "build_write_config_command", "build_direct_write_start_compressed", diff --git a/src/opendisplay/protocol/commands.py b/src/opendisplay/protocol/commands.py index e47d21d..ddf1782 100644 --- a/src/opendisplay/protocol/commands.py +++ b/src/opendisplay/protocol/commands.py @@ -21,6 +21,7 @@ class CommandCode(IntEnum): # Firmware commands READ_FW_VERSION = 0x0043 # Read firmware version READ_MSD = 0x0044 # Read the 16-byte manufacturer-specific data record + CONFIG_CLEAR = 0x0045 # Erase the stored config (claimed: keeps the 0x27 reset-pin fields) READ_IDENT = 0x0046 # Read device identity (plaintext; 3.0 adds a tail) REBOOT = 0x000F # Reboot device @@ -157,6 +158,15 @@ def build_read_msd_command() -> bytes: return CommandCode.READ_MSD.to_bytes(2, byteorder="big") +def build_config_clear_command() -> bytes: + """Build the CONFIG_CLEAR command (0x0045), which erases the stored config. + + Returns: + Command bytes: 0x0045 (2 bytes, big-endian) + """ + return CommandCode.CONFIG_CLEAR.to_bytes(2, byteorder="big") + + def build_reboot_command() -> bytes: """Build command to reboot device. diff --git a/tests/unit/data/public_api.json b/tests/unit/data/public_api.json index 5805235..fda1a51 100644 --- a/tests/unit/data/public_api.json +++ b/tests/unit/data/public_api.json @@ -19,6 +19,7 @@ "activate_led": "async (self, led_instance: 'int', flash_config: 'LedFlashConfig', timeout: 'float | None' = None) -> 'bytes'", "authenticate": "async (self, key: 'bytes') -> 'None'", "capabilities": "property", + "clear_config": "async (self) -> 'None'", "clear_gatt_cache": "async (self) -> 'bool'", "color_scheme": "property", "config": "property", @@ -41,6 +42,7 @@ "read_sensors": "async (self) -> 'list[SensorReading]'", "reboot": "async (self) -> 'None'", "rotation": "property", + "send_raw": "async (self, frame: 'bytes', *, reply: 'bool' = True, timeout: 'float' = 10.0) -> 'bytes | None'", "trigger_dfu_bootloader": "async (self) -> 'None'", "upload_image": "async (self, image: 'Image.Image', refresh_mode: 'RefreshMode' = , dither_mode: 'DitherMode' = , compress: 'bool' = True, serpentine: 'bool' = True, exposure: 'float' = 1.0, saturation: 'float' = 1.0, shadows: 'float' = 0.0, highlights: 'float' = 0.0, tone: 'float' = 0.0, gamut: 'float' = 0.0, fit: 'FitMode' = , rotate: 'Rotation' = , progress_callback: 'Callable[[int, int], None] | None' = None, state: 'PartialState | None' = None, dbs: 'DbsParams | bool | None' = None) -> 'Image.Image'", "upload_prepared_image": "async (self, prepared_data: 'tuple[bytes, bytes | None, Image.Image]', refresh_mode: 'RefreshMode' = , compress: 'bool' = True, progress_callback: 'Callable[[int, int], None] | None' = None, state: 'PartialState | None' = None) -> 'None'", @@ -71,6 +73,7 @@ "BuzzerStep", "CalibrationEntry", "ColorScheme", + "ConfigClearError", "ConfigKeyMismatchError", "ConfigParseError", "ConfigSecretNeedsClaimError", diff --git a/tests/unit/test_cli_raw.py b/tests/unit/test_cli_raw.py new file mode 100644 index 0000000..441171a --- /dev/null +++ b/tests/unit/test_cli_raw.py @@ -0,0 +1,59 @@ +"""`opendisplay raw`: one command frame out, its reply printed as hex.""" + +from __future__ import annotations + +from types import SimpleNamespace +from typing import Any + +import pytest + +from opendisplay import cli, cli_raw + + +def _args(argv: list[str]) -> Any: + return cli._build_parser().parse_args(argv) + + +def _fake_connect(monkeypatch: pytest.MonkeyPatch, reply: bytes | None) -> list[tuple[bytes, bool]]: + sent: list[tuple[bytes, bool]] = [] + + async def send_raw(frame: bytes, *, reply: bool = True, timeout: float = 10.0) -> bytes | None: + sent.append((frame, reply)) + return reply_bytes if reply else None + + reply_bytes = reply + + class _Conn: + async def __aenter__(self) -> Any: + return SimpleNamespace(legacy=SimpleNamespace(send_raw=send_raw)) + + async def __aexit__(self, *exc: object) -> None: + return None + + monkeypatch.setattr(cli_raw, "connect", lambda **kw: _Conn()) + return sent + + +async def test_the_command_and_payload_are_sent_as_one_frame_and_the_reply_printed( + monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + sent = _fake_connect(monkeypatch, bytes.fromhex("00450000")) + + await cli_raw._raw(_args(["raw", "--device", "OD1", "--cmd", "0x0045", "--payload", "01 02"])) + + assert sent == [(bytes.fromhex("00450102"), True)] + assert "00 45 00 00" in capsys.readouterr().out + + +async def test_no_reply_waits_for_nothing(monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]) -> None: + sent = _fake_connect(monkeypatch, None) + + await cli_raw._raw(_args(["raw", "--device", "OD1", "--cmd", "000f", "--no-reply"])) + + assert sent == [(bytes.fromhex("000f"), False)] + + +@pytest.mark.parametrize("cmd", ["12345", "zz", "0x10000"]) +def test_a_command_that_is_not_two_bytes_of_hex_is_refused(cmd: str) -> None: + with pytest.raises(SystemExit): + _args(["raw", "--device", "OD1", "--cmd", cmd]) diff --git a/tests/unit/test_device_api.py b/tests/unit/test_device_api.py index 7b4e550..cc0094c 100644 --- a/tests/unit/test_device_api.py +++ b/tests/unit/test_device_api.py @@ -252,6 +252,53 @@ async def test_config_write_refreshes_the_profile(fake_transport) -> None: assert dev.config.cached is not None +CONFIG_CLEAR = b"\x00\x45" + + +async def test_clearing_the_config_sends_config_clear_and_refreshes_the_profile(fake_transport) -> None: + fake = fake_transport( + [_version(3, 0), SEC_UNCLAIMED, _config_reply(ESP32_CONFIG), IDENT_V3_NO_DISPLAY] + + [bytes.fromhex("00450000")] + + [_version(3, 0), NO_CONFIG, IDENT_V3_NO_DISPLAY] + ) + + async with opendisplay.connect(transport=fake) as dev: + assert dev.profile.configured is True + written_before = len(fake.written) + + await dev.config.clear() + + assert fake.written[written_before] == CONFIG_CLEAR + assert dev.config.cached is None + assert dev.profile.configured is False + + +async def test_a_refused_config_clear_raises_and_reads_nothing_more(fake_transport) -> None: + from opendisplay.exceptions import ConfigClearError + + fake = fake_transport( + [_version(3, 0), SEC_UNCLAIMED, _config_reply(ESP32_CONFIG), IDENT_V3_NO_DISPLAY, bytes.fromhex("ff450000")] + ) + + async with opendisplay.connect(transport=fake) as dev: + with pytest.raises(ConfigClearError): + await dev.config.clear() + + assert _opcodes(fake.written)[-1] == CONFIG_CLEAR + assert dev.config.cached is not None + + +async def test_a_raw_command_is_sent_verbatim_and_its_reply_returned(fake_transport) -> None: + fake = fake_transport([bytes.fromhex("00450000")]) + device = OpenDisplayDevice(transport=fake, auto_interrogate=False) + await device.__aenter__() + + assert await device.send_raw(bytes.fromhex("0045")) == bytes.fromhex("00450000") + assert await device.send_raw(bytes.fromhex("000f"), reply=False) is None + + assert fake.written == [bytes.fromhex("0045"), bytes.fromhex("000f")] + + def _write_acks(config: GlobalConfig) -> list[bytes]: blob = serialize_config(config) chunks = 1 + max(0, (len(blob) - 200 + 199) // 200) From 7f8f8c20aa0eb1e0f24477e4bd24e76ba078d4fd Mon Sep 17 00:00:00 2001 From: gabriel Date: Wed, 18 Nov 2026 20:48:08 +0100 Subject: [PATCH 8/9] fix(setup): check the panel after the run wrote the config, and print each step Once the run had written the config, the device no longer planned the panel check itself, so a setup without a key (or any open-device path) finished without ever drawing the test pattern. Seen on the E1002 on 2026-11-18. The run now owes the check after its own write, and saves that across a restart. SetupRun.on_step is called before each step; `setup` and `upgrade` print one line per step. Claude-Session: https://claude.ai/code/session_01Ap1E7UWkx9cYSPdYvmgmu3 --- src/opendisplay/cli_setup.py | 20 +++++++++++++++++ src/opendisplay/setup/runner.py | 16 +++++++++++-- tests/unit/test_cli_setup.py | 6 ++++- tests/unit/test_setup_runner.py | 40 +++++++++++++++++++++++++++++++++ 4 files changed, 79 insertions(+), 3 deletions(-) diff --git a/src/opendisplay/cli_setup.py b/src/opendisplay/cli_setup.py index c9e62dc..4e67909 100644 --- a/src/opendisplay/cli_setup.py +++ b/src/opendisplay/cli_setup.py @@ -21,6 +21,7 @@ from .exceptions import OpenDisplayError from .firmware.download import ReleaseDownloader from .models.config_json import config_from_json +from .setup import Step from .setup import requests as rq from .setup.runner import SetupError, SetupRun @@ -33,6 +34,17 @@ "Put the display in claim mode: power-cycle it twice quickly (off, on, off, on). " "Press Enter when it shows that it waits to be claimed. " ) +_STEP_LINES: Final = { + Step.BACK_UP: "Backing up the config...", + Step.INSTALL_3_0: "Installing firmware 3.0...", + Step.CONFIRM_IMAGE: "Checking that firmware 3.0 runs...", + Step.USE_WITHOUT_KEY: "Leaving claim mode (no key)...", + Step.CONFIGURE_DISPLAY: "Configuring the display...", + Step.VERIFY_PANEL: "Checking the panel with a test pattern...", + Step.CLAIM: "Claiming the display...", + Step.ROTATE_KEY: "Replacing the 2.x key...", + Step.SECRETS: "Entering the secrets...", +} _RESUME: Final = ( "When the display runs 3.0, run the same command again (with --device set to its new name if it " "advertises under another one); it goes on from {state}." @@ -188,6 +200,14 @@ async def _setup(args: argparse.Namespace, *, open_device: Any = None, releases: else: run = SetupRun.start(want_key=args.want_key, **common) factory = open_device or (lambda: connect(**_connect_kwargs(args))) + announced: set[Step] = set() + + def announce(step: Step) -> None: + if step not in announced: # a step that paused runs again once answered + announced.add(step) + _console.print(_STEP_LINES.get(step, f"{step.value}...")) + + run.on_step = announce def save() -> None: if state is not None: diff --git a/src/opendisplay/setup/runner.py b/src/opendisplay/setup/runner.py index e9df2f7..f45105d 100644 --- a/src/opendisplay/setup/runner.py +++ b/src/opendisplay/setup/runner.py @@ -130,6 +130,7 @@ def __init__( # pylint: disable=too-many-arguments self._live: tuple[AsyncExitStack, Any] | None = None # the claim link and its device self._live_flow: Any = None self._stop_pending = False + self._verify_owed = False # the run wrote a config; its panel check is still to come #: The request the run waits for, or ``None``. self.pending: rq.Request | None = None #: The confirmation the user declined, which stopped the run; cleared when it runs again. @@ -138,6 +139,8 @@ def __init__( # pylint: disable=too-many-arguments self.finished = False #: The planner's text keys for the device as last seen. self.notes: tuple[str, ...] = () + #: Called with each step just before it runs (a step that pauses runs again on resume). + self.on_step: Callable[[Step], None] | None = None # ── making, saving, answering ──────────────────────────────────────────── @@ -191,6 +194,7 @@ def to_json(self) -> str: "pending": rq.to_dict(self.pending) if self.pending is not None else None, "stopped": self.stopped, "stop_pending": self._stop_pending, + "verify_owed": self._verify_owed, "finished": self.finished, "notes": list(self.notes), } @@ -231,6 +235,7 @@ def from_json( # pylint: disable=too-many-arguments run.pending = rq.from_dict(doc["pending"]) if doc["pending"] is not None else None run.stopped = doc["stopped"] run._stop_pending = doc["stop_pending"] + run._verify_owed = doc.get("verify_owed", False) run.finished = doc["finished"] run.notes = tuple(doc["notes"]) return run @@ -311,15 +316,21 @@ async def _next(self, dev: Any, close: Callable[[], Awaitable[None]]) -> tuple[S rotate_legacy_key=self.rotate_legacy_key, ) self.notes = plan.notes - if not plan.steps: + steps = plan.steps + if self._verify_owed and Step.VERIFY_PANEL not in steps and Step.VERIFY_PANEL not in self._done: + # Once configured, the device no longer plans the check of the config this run wrote. + steps = (Step.VERIFY_PANEL, *(steps or (Step.DONE,))) + if not steps: if "claim_choice" in plan.notes: return None, rq.NeedKeyChoice() self.finished = True return None, None - step = next((s for s in plan.steps if s not in self._done), Step.DONE) + step = next((s for s in steps if s not in self._done), Step.DONE) if step is Step.DONE: self.finished = True return None, None + if self.on_step is not None: + self.on_step(step) request = await self._perform(step, dev, close) if request is None and step in _REMEMBERED: self._done.add(step) @@ -460,6 +471,7 @@ async def _configure(self, dev: Any) -> rq.Request | None: self._done.add(Step.CONFIGURE_DISPLAY) # nothing to write; the device says otherwise return None await write_and_verify(dev, config) + self._verify_owed = True return None async def _verify(self, dev: Any) -> rq.Request: diff --git a/tests/unit/test_cli_setup.py b/tests/unit/test_cli_setup.py index d8ecc5f..5c00de2 100644 --- a/tests/unit/test_cli_setup.py +++ b/tests/unit/test_cli_setup.py @@ -80,6 +80,7 @@ async def test_an_upgrade_pauses_for_the_wired_install_and_resumes_from_the_stat out = capsys.readouterr().err assert "opendisplay-s3-n32r8-extuart-merged.bin" in out and "opendisplay.org/firmware/install" in out + assert out.index("Backing up the config") < out.index("Installing firmware 3.0") assert "run the same command again" in out assert state.exists() and KEY.hex() not in state.read_text() assert KEY.hex() in backup.read_text() @@ -90,7 +91,10 @@ async def test_an_upgrade_pauses_for_the_wired_install_and_resumes_from_the_stat await cli_setup._setup(_args(argv), open_device=_factory(world), releases=releases) assert "use_without_key" in world.calls and "config_write" in world.calls - assert "set up" in capsys.readouterr().err.lower() + out = capsys.readouterr().err + assert "set up" in out.lower() + for line in ("Leaving claim mode", "Configuring the display", "Checking the panel"): + assert out.count(line) == 1, line assert releases.asked == 1 # the second run went on from the saved state without a manifest diff --git a/tests/unit/test_setup_runner.py b/tests/unit/test_setup_runner.py index 4eaff02..f602567 100644 --- a/tests/unit/test_setup_runner.py +++ b/tests/unit/test_setup_runner.py @@ -24,6 +24,7 @@ from opendisplay.models.ident import FirmwareTarget from opendisplay.sec2.errors import Sec2CodeMismatchError from opendisplay.sec2.wire import SecState, SecStatus +from opendisplay.setup import Step from opendisplay.setup import requests as rq from opendisplay.setup import runner as runner_mod from opendisplay.setup.runner import SetupError, SetupRun @@ -287,6 +288,45 @@ async def test_claim_mode_without_a_key_is_left_and_the_device_configured() -> N assert isinstance(req, rq.NeedConfig) # no config, no backup: the caller supplies one +async def test_a_config_the_run_wrote_is_checked_on_the_panel_also_without_a_key() -> None: + # The E1002 on 2026-11-18: once configured, the device no longer plans a panel check itself. + world = _World(claim_mode=True, fresh=True) + run = SetupRun.start(want_key=False, backup_sink=lambda b: None) + + req = await run.run_until_input(_factory(world)) + assert isinstance(req, rq.NeedConfig) + run.answer(req, _config(displays=[_display(panel_ic_type=0x0037)])) + req = await run.run_until_input(_factory(world)) + assert isinstance(req, rq.NeedConfirmation) and req.reason == "untested_panel" + run.answer(req, True) + + req = await run.run_until_input(_factory(world)) + assert "config_write" in world.calls + assert isinstance(req, rq.NeedConfirmation) and req.reason == "panel_ok" + run.answer(req, False) # not yet: the user stops, and goes on later + assert await run.run_until_input(_factory(world)) is None and run.stopped == "panel_ok" + + run = _restart(run) # the owed check survives a save + req = await run.run_until_input(_factory(world)) + assert isinstance(req, rq.NeedConfirmation) and req.reason == "panel_ok" + run.answer(req, True) + + assert await run.run_until_input(_factory(world)) is None + assert run.finished and world.calls.count("show:800x480") == 2 + + +async def test_each_step_is_announced_before_it_runs() -> None: + world = _World(claim_mode=True, fresh=True) + run = SetupRun.start(want_key=False, backup_sink=lambda b: None) + seen: list[tuple[Step, int]] = [] + run.on_step = lambda step: seen.append((step, world.calls.count("use_without_key"))) + + await run.run_until_input(_factory(world)) + + assert seen[0] == (Step.USE_WITHOUT_KEY, 0) # announced, then performed + assert [s for s, _ in seen] == [Step.USE_WITHOUT_KEY, Step.CONFIGURE_DISPLAY] + + async def test_a_claimed_device_with_a_2x_key_is_rotated() -> None: world = _World(state=SecState.CLAIMED, key_legacy=True, config=_keyed()) run = SetupRun.start(want_key=True, backup_sink=lambda b: None) From 38ead90c523e55f5fb4afc1b867141cb5980c617 Mon Sep 17 00:00:00 2001 From: gabriel Date: Sat, 21 Nov 2026 21:50:23 +0100 Subject: [PATCH 9/9] fix(cli): setup, upgrade, update and raw take --key-store from the shared device options The device options gained --key-store in #237, so adding it again made argparse refuse to build the parser. Claude-Session: https://claude.ai/code/session_01Ap1E7UWkx9cYSPdYvmgmu3 --- src/opendisplay/cli_raw.py | 3 +-- src/opendisplay/cli_setup.py | 4 +--- 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/src/opendisplay/cli_raw.py b/src/opendisplay/cli_raw.py index 982f56b..4ddcb0f 100644 --- a/src/opendisplay/cli_raw.py +++ b/src/opendisplay/cli_raw.py @@ -11,7 +11,7 @@ import re from .cli_common import _add_device_options, _console, _handle_ble_error, _run -from .cli_sec2 import _add_key_store_option, _connect_kwargs +from .cli_sec2 import _connect_kwargs from .device import connect from .exceptions import OpenDisplayError @@ -34,7 +34,6 @@ def add_raw_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParse """Register ``raw``.""" p = subparsers.add_parser("raw", help="Debug: send one command frame and print the reply as hex") _add_device_options(p) - _add_key_store_option(p) p.add_argument("--cmd", required=True, type=_command, metavar="HEX", help="The command code, e.g. 0045") p.add_argument("--payload", type=_payload, default=b"", metavar="HEX", help="Bytes after the command code") p.add_argument("--no-reply", action="store_true", help="Send and wait for nothing (e.g. a reboot)") diff --git a/src/opendisplay/cli_setup.py b/src/opendisplay/cli_setup.py index 4e67909..5ec32d4 100644 --- a/src/opendisplay/cli_setup.py +++ b/src/opendisplay/cli_setup.py @@ -16,7 +16,7 @@ from typing import Any, Final from .cli_common import _add_device_options, _console, _error, _handle_ble_error, _run -from .cli_sec2 import _add_key_store_option, _connect_kwargs, _input +from .cli_sec2 import _connect_kwargs, _input from .device import connect from .exceptions import OpenDisplayError from .firmware.download import ReleaseDownloader @@ -70,7 +70,6 @@ def add_setup_parsers(subparsers: argparse._SubParsersAction[argparse.ArgumentPa ): p = subparsers.add_parser(name, help=help_text) _add_device_options(p) - _add_key_store_option(p) choice = p.add_mutually_exclusive_group() choice.add_argument("--claim", dest="want_key", action="store_const", const=True, help="Claim the display") choice.add_argument( @@ -87,7 +86,6 @@ def add_setup_parsers(subparsers: argparse._SubParsersAction[argparse.ArgumentPa update = subparsers.add_parser("update", help="Send a firmware 3.x image to a 3.x display over Bluetooth") _add_device_options(update) - _add_key_store_option(update) update.add_argument("--file", required=True, metavar="IMAGE", help="The board's ble-ota file from the release") update.add_argument("--yes", action="store_true", help="Do not ask, also on a device that cannot roll back") update.set_defaults(func=lambda args: _run(_update(args)))