feat: host-side helpers so callers stop reimplementing the protocol

[g4bri3lDev]

Hosts driving OpenDisplay devices have had to reimplement pieces of the protocol this library already knew: packing an LED colour, sizing an NDEF record, formatting a firmware version to match its release tag, parsing a stored encryption key, and working out when a sleeping device is reachable. Each reimplementation is somewhere a host can drift from the firmware — and the library had drifted from itself, which is what prompted two of these commits.

New API

All additive; no existing signature changes meaning.

• pack_led_color / unpack_led_color / ms_to_loop_delay_units / ms_to_inter_delay_units, plus LedFlashStep.from_rgb() and .rgb
• build_nfc_payload() — the same payload write_nfc_* sends, so a record can be validated before a connection is spent on it
• format_firmware_version() — the single definition of how a version maps to a release tag
• supports_ble_ota_install() — deliberately narrower than "an asset exists": it answers whether a host should offer the install over a Bluetooth proxy, which nRF Legacy DFU cannot survive
• parse_encryption_key() and a typed InvalidEncryptionKeyError
• BinaryInputs.enabled_button_ids, DisplayConfig.canvas_size(), DisplayConfig.supports_compression
• SleepModel — the post-wake window and whether a device has gone dark again, with host-side slack passed in rather than assumed
• prepare_image(compress=None) derives compression from the device config

Two user-visible changes

• opendisplay info always printed three version parts, showing 1.6.0 for a device whose release tag is 1.6. It now formats through the library, so the CLI, a host's device registry and the tag all agree. --json keeps its separate major/minor/patch fields, which is a machine-readable contract rather than a rendering.
• encryption_key accepts hex as well as raw bytes, and a malformed key now raises InvalidEncryptionKeyError at construction instead of TypeError: key must be bytes-like inside authenticate() — after the connection had already been made. On a deep-sleeping device that cost a whole wake window to learn the key was the wrong type. Raw bytes of the wrong length are rejected up front too, rather than reaching AES and failing there.

Internal call sites now use these

The library no longer keeps its own copies of the NFC payload assembly, the compression capability check, the firmware version format, or the key parser. cli.py's _parse_hex_key is gone; it accepted colon- and space-separated hex, so parse_encryption_key accepts those too and nothing regresses.

Firmware verification

The 10 s default wake window and the sleep-entry condition were checked against firmware upstream/main rather than taken from comments: DEFAULT_IDLE_HOLD_MS in src/main.h, and the gate in platformIdle() (src/main.cpp). That also surfaced a nuance worth encoding — the window is measured from the last activity and re-armed by it, and a button wake holds it open for min_wake_time_seconds regardless. So probably_asleep() is documented as a prediction that errs towards asleep, not a fact.

Verification

uv run pytest — 1150 passed (was 1071).
uv run prek run --all-files — ruff, ruff-format, mypy strict and pylint all pass, idempotent on re-run.

[codecov]

Codecov Report

❌ Patch coverage is 97.74436% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/opendisplay/cli.py	50.00%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!