Add tools for the GP2040-CE Host Lighting add-on

CHANGELOG.md

@@ -3,6 +3,28 @@
 Included is a summary of changes to the project. For full details, especially on behind-the-scenes code changes and
 development tools, see the commit history.
 
+## Unreleased
+
+### Features
+
+* New `hlp-*` tools for the GP2040-CE Host Lighting add-on: `hlp-ping`, `hlp-caps`, `hlp-fill`,
+  `hlp-input-mode`, `hlp-reboot-webconfig`, and `hlp-reboot-bootsel` talk to the add-on's vendor HID
+  interface to verify a board, decode its self-reported LED capabilities, run a quick visual test, and
+  manage the board. Adds a dependency on `hidapi`.
+* `hlp-caps` decodes everything Host Lighting Protocol v1.1 added: the light table, which names every
+  individual light and the control that owns it; the per-light grid positions; and the feature bitmask,
+  LED framework, animation namespace and render rate on the runtime state page. Boards speaking v1.0 are
+  handled unchanged - fields they never sent are reported as absent rather than guessed, and the light
+  table reads as unsupported rather than as an error.
+* `hlp-set-light` stages per-light colours with Host Lighting Protocol v1.2's SET_LIGHT command, which
+  addresses one light of a control that owns several by its light-table ordinal. Ordinals a board does
+  not have are counted as skipped rather than erroring, matching the protocol's SET_BUTTONS semantics,
+  and the tool refuses cleanly on firmware that predates v1.2.
+* Host Lighting Protocol v1.3 support: an eight-digit `RRGGBBWW` colour stages through the new
+  SET_LIGHT_RGBW command (boards without a white channel ignore W), and on v1.3 firmware the reply's
+  per-entry outcome mask is decoded to name any skipped ordinals instead of only counting them.
+  `set_lights` and the new `set_lights_rgbw` return the raw masks alongside the counts.
+
 ## v0.11.1
 
 ### Miscellaneous

README.md

@@ -119,6 +119,67 @@ Sample usage:
 % dump-gp2040ce `date +%Y%m%d`-backup.bin
 ```
 
+### hlp-* (Host Lighting tools)
+
+The `hlp-*` tools talk to a board running the GP2040-CE Host Lighting add-on, which exposes a vendor HID
+interface for driving the board's RGB LEDs from host software. They require the `hidapi` package and a board
+with the add-on enabled (Configuration -> Add-Ons -> Host Lighting in the web configurator). If more than one
+board is connected, select one with `--board-id <hex prefix of its factory ID>`.
+
+* `hlp-ping` verifies the protocol handshake (magic, version) and measures the command round-trip.
+* `hlp-caps` decodes the board's self-reported capabilities: identity, runtime state, the LED map (buttons,
+  case, player LEDs), animation selection, per-light positions where supported, and the light table, which
+  names every individual light and the control that owns it. A board that keeps no per-light table rebuilds
+  those records from its per-control configuration and says so, because duplicates cannot be seen that way.
+* `hlp-fill` fills the LEDs with a colour (`--scope all|buttons|case|pleds`) as a quick visual test, then
+  restores the board's own animations.
+* `hlp-set-light` colours individual lights by their light-table ordinal (protocol v1.2) - the way to
+  address one light of a control that owns several - then restores the board's own animations. An
+  eight-digit colour (`RRGGBBWW`) stages through the v1.3 RGBW variant, and on v1.3 firmware any
+  skipped ordinals are named from the reply's outcome mask. For white-channel chains send the
+  subtractive conversion (W = min(R,G,B), RGB reduced by W) - v1.3 firmware renders it; earlier
+  firmware maps plain-RGB whites to the white emitter itself, so send six-digit colours there.
+* `hlp-input-mode` sets the board's input mode and reboots into it.
+* `hlp-reboot-webconfig` / `hlp-reboot-bootsel` reboot the board into the web configurator or the BOOTSEL
+  bootloader for flashing.
+
+Sample usage:
+
+```
+% hlp-ping
+Haute42 COSMOX (v0.7.12), board ID 433031343539302E
+magic GPHL, protocol 1.1
+100 pings in 207 ms (2.1 ms average)
+
+% hlp-caps
+page 0 (identity): Haute42 COSMOX (v0.7.12), board ID 433031343539302E
+page 1 (runtime state): input mode XINPUT, profile 1, brightness step 0, host player 2, map fingerprint 0x92207B00
+  offers positions, light table; renders at 40 Hz; animations are stored profiles; LED-refactor LED framework
+page 2 (LED map): addresses 16 LEDs, 1 per button, colour format GRB, brightness maximum 100, layout enum 27
+  buttons: Up=3, Down=1, Left=0, Right=2, B1=8, B2=9, B3=4, B4=5, L1=7, R1=6, L2=11, R2=10, L3=13, R3=14
+page 3 (animations): index 0 of 1 available
+page 4 (positions): 16 lights
+  LED 0@(0,2), LED 1@(2,2), ...
+page 5 (light table): 16 lights, fingerprint 0x92207B00
+  LED 0 button Left GP5 at (0,2)
+  LED 3 button Up GP2 at (5,7) (duplicate)
+  ...
+  Up owns 2 lights: LEDs 3, 12
+  L3 owns 2 lights: LEDs 13, 15
+
+% hlp-fill --scope case 00FF00
+filled case with #00FF00 for 3.0s
+released - on-board animations restored
+
+% hlp-set-light 3:FF0000 12:0000FF
+2 applied, 0 skipped for 3.0s
+released - on-board animations restored
+```
+
+The light table is what reveals that this board wires two physical buttons to `Up` and two to `L3`; the LED
+map on page 2 can only report one range per control, so it cannot express that. On v1.2 firmware
+`hlp-set-light` addresses those lights one at a time by their position in the table.
+
 ### summarize-gp2040ce
 
 `summarize-gp2040ce` prints information regarding the provided USB device or file. It attempts to detect the firmware