Module driver 

The board-agnostic ULCP session driver (Phase 5, increment C).

This is the extraction of the nRF firmware’s device_task select loop, its apply_effect radio-effect dispatcher, and the Emitter frame stager — the one copy of the session-driving logic shared by every device firmware (T-Echo, T-1000E, Heltec V3). The board personalities that used to be cfg(feature = "t1000e") forks inside the loop are expressed as DeviceEnv hooks with no-op defaults, so a new board supplies exactly the couplings it has and nothing else.

The split of responsibilities:

• This module owns the protocol loop: transport arbitration, frame handling, radio RX/TX-completion processing, every deferred Effect arm (save/clear/wipe/provision/PIN/RSSI/battery/drain), asynchronous property publication (DeviceEnv::battery_event), and the device-domain mirror.
• The board owns the edges: transport tasks feeding InEvents and draining TransportChannels, the radio runner + mux serving the session’s virtual [Channels] bundle, and an DeviceEnv implementation wiring persistence, entropy, pairing, and indicators to its hardware.

Structs

DevDomainSnapshot

The session’s device-domain tables, mirrored to the board’s device node whenever their generation moves (device-node plan increment 3).

DeviceRuntime

The driver’s 'static wiring: the channels and control blocks the loop shares with the board’s transport and radio tasks.

OutFrame

One raw ULCP frame in a transport output queue, stamped with the session generation that produced it so a displaced session’s frames are dropped at the transport edge (transport_policy::generation_checked).

TransportChannels

The per-transport outbound frame queues, drained by the board’s transport output tasks. wired is the physical-possession transport (USB-CDC or UART), ble the bonded GATT transport — the same pairing transport_policy::Transport names.

Enums

InEvent

Framing-free receive path and connection edges into the driver.

PublishEvent

A device-initiated property publication, yielded by DeviceEnv::publish_event.

Constants

FRAME_IN_MAX

Largest raw ULCP frame accepted from a transport.

FRAME_OUT_MAX

Largest ULCP frame the session emits (CMD_STR_RECV around a full-MTU payload).

IDENTITY_BLOB_MAX

Buffer the driver hands DeviceEnv::sign_identity: a node-identity payload plus its 64-octet detached signature, with room for the descriptive options.

SNAPSHOT_FALLBACK_LIMIT

How many older snapshot generations boot will try after the newest one is rejected.

Traits

DeviceEnv

Board couplings of the session driver. Everything the loop needs from the platform, expressed as one trait so the driver itself stays free of HAL types and cfg board forks. Hooks a board doesn’t have keep their no-op defaults (e.g. only the T-1000E implements the attention indicator and transmit-load hooks today).

Functions

device_identity_record

Derive a device identity’s public key and its persisted record from a raw Ed25519 secret.

run

Drive the ULCP session forever: restore persisted state, then select over host frames, radio receptions, and transmit completions, executing every session effect through the board’s DeviceEnv.

Type Aliases

FrameBuf

One raw ULCP frame moving through the driver.

InputChannel

The inbound event channel the board’s tasks feed: every transport task, and whatever owns the buttons on a board with CAP_ALERT.