feat: complications, display config, handedness, graceful shutdown (PR 10/10)

[thePunderWoman]

Summary

PR 10 — the final PR of the firmware rewrite (PR 1: #35 ... PR 9: #44). Ties off every remaining thread from the plan: the "normal operating" screen now shows real data instead of a static boot message, and the power-off hold actually shuts the board down instead of just logging that it would.

• complications.h/.cpp: ComplicationRegistry, the smartwatch-style slot→data-source mapping (battery, Left/Right slot label+value from the downlink, local signal strength, connected droid name, handedness). Pure, persisted via a thin NVS adapter (complication_persistence.cpp, joins the native exclusion list).
• Display Config joins the menu tree: Up/Down selects a slot, Enter cycles its source, reusing PR 6's framework. MenuController also now tracks the most recently successfully-switched-to droid's name for the "Droid Name" source, and takes an externally-owned ComplicationRegistry* rather than duplicating slot-assignment state.
• XbeeControl gains queryLocalRssiDbm() (local DB AT command — no round trip to Amidala needed, unlike everything else displayed).
• UplinkPacket gains a flags byte (currently just kFlagShuttingDown) so Amidala can mark a controller disconnected immediately instead of waiting out a timeout.
• SnipsController.ino:
  • The operating screen now renders real complications (fed by battery/RSSI/droid-name every tick, downlink fields on receipt).
  • The status LED reflects real state (error on latched charge fault, charging, connected within a 5s downlink timeout, else disconnected) instead of just settling on "disconnected" forever — this closes out a TODO left over from PR 4.
  • The 3s power-button hold now runs a real graceful shutdown (notify Amidala via the flags bit, "Powering Off" OLED message, capped retries, then cuts the latch) instead of logging that a later PR would handle it.
  • The four menu-nav buttons (Left Up/Down, Stick Click, Bumper) now have their uplink bits suppressed while the menu is open, so navigating it doesn't look like spurious button presses to Amidala — a correctness gap I noticed while reviewing this PR, now that the packet protocol actually exists to expose it.

Test plan

• pio test -e native — all 187 test cases pass
• gcovr --exclude 'src/SnipsController\.ino' --exclude 'src/oled\.cpp' --exclude 'src/rgb_led\.cpp' --exclude 'src/calibration_store\.cpp' --exclude 'src/droid_persistence\.cpp' --exclude 'src/xbee_spi\.cpp' --exclude 'src/xbee_control\.cpp' --exclude 'src/complication_persistence\.cpp' --fail-under-line 90 — 98.6% line coverage
• pio run -e esp32s3 — builds successfully
• Flash to real hardware once boards arrive: confirm the operating screen shows live battery/signal/droid-name data, Display Config cycles and persists slot assignments across reboot, the status LED changes with charge/connection state, and holding the power button 3s actually cuts power after showing "Powering Off..."

This closes out the plan's 10-PR sequence (originally 9; PR 8 split into two once it grew large enough on its own, per the plan's own contingency).

🤖 Generated with Claude Code