[Accessories] 7 - Separate firmware device profiles

[KacperKozak]

Parent

#475

What to build

Refactor vescape-app/vescape-accessories into shared firmware libraries and explicitly selected device profiles. Preserve working ground-clearance behavior and protocol v1. This work prepares the firmware structure used by #480 and #481.

Separate BLE transport, protocol/session/lease runtime, ground-clearance capability behavior, and VL53L0X hardware I/O. Keep runtime state owned by one loop/task, with bounded queued BLE events and serialized outgoing messages. Use small concrete interfaces and explicit capability composition; no dynamic plugin system or hypothetical joystick implementation.

Provide separately buildable clearance and explicitly development-only fake rear-light profiles for XIAO ESP32-S3. Isolate sensor dependencies from the light build. Preserve existing supported board configurations where practical. The clearance profile must not advertise the spike's dummy brake light. Keep accessory identity and clearance capability IDs stable across ordinary updates.

Likely files

All paths below are in vescape-app/vescape-accessories.

• src/main.cpp — current mixed entrypoint to reduce to composition/startup.
• lib/accessory/ — existing Arduino-free protocol library and extension starting point.
• platformio.ini — device profiles and scoped dependencies.
• test/ — protocol fixtures and new meaningful runtime regression tests.
• docs/accessories.md — architecture, profiles, capability declarations and extension instructions.
• docs/flashing.md — exact build/upload commands and existing XIAO automatic reset settings.

Acceptance criteria

• Ground-clearance measurement rates/statuses, standby, session sequencing and lease behavior remain intact.
• Session reset, disconnect, command expiry and duplicate commands are covered with deterministic desktop tests.
• BLE callbacks cannot concurrently mutate capability or protocol runtime; stale connection events cannot affect a new session.
• Clearance and fake rear-light XIAO firmware both compile, with VL53L0X excluded from the light build.
• The fake profile is explicitly labeled as development-only; full brake-light rendering remains [Accessories] 5 - Drive brake-light states #480.
• Protocol fixtures pass without changes to the wire contract.
• Build/flash documentation and instructions for adding a driver versus adding a capability are current.
• No flashing or claims of hardware validation in this task; those belong to [Accessories] 6 - Validate connected riding #481.

Related

• [Accessories] 3 - Calibrate live ground clearance #478
• [Accessories] 5 - Drive brake-light states #480
• [Accessories] 6 - Validate connected riding #481

[KacperKozak]

Implemented locally in vescape-app/vescape-hardware and reviewed. No commit, push or device flashing yet; this issue remains open until the implementation is saved to GitHub.

• Shared Arduino-free runtime owns framing, sessions, per-capability leases and command dispatch.
• BLE callbacks queue bounded, generation-tagged events. Failed generations cannot be revived by queued commands, and outbound traffic carries connection identity.
• Ground-clearance capability and VL53L0X driver are separate. Lease release preserves sequence/session time; reconnect resets sampling and stops old measurement state.
• xiao-clearance and xiao-rear-light-dev build separately. The light dependency graph excludes VL53L0X. Its fake state-only behavior is explicitly development-only.
• Existing esp32c3 and esp32 clearance builds remain supported. Hardware/build/flash and extension docs updated.

Verification independently rerun by the parent reviewer:

• pio test -e native: 19/19 protocol and runtime tests passed, using accessory fixtures extracted from the app's accessories branch through VESCAPE_APP_ROOT because the working app checkout is on dev.
• pio run -e xiao-clearance -e xiao-rear-light-dev: both passed.
• git diff --check: passed.
• Sol also built esp32c3 and esp32 successfully.

Review fixes covered terminal malformed-input handling, queue overflow before a connect event is consumed, stale generation events, fresh-session sensor restart, lease expiry without sequence reset, clock wrap and failed notification handling. Desktop tests exercise the runtime through fake I/O; physical BLE/LED validation remains #481. Full brake-light rendering remains #480.

[KacperKozak]

Implemented and verified in vescape-app/vescape-hardware@c455744, pushed to main. Native tests 19/19 and all four firmware profiles passed. Physical validation remains #481.