Add Host Lighting add-on: live RGB LED control from host software over a vendor HID interface

[djGLiTCH]

Summary

Host Lighting is an optional add-on that exposes a second, vendor-defined HID interface (usage page 0xFF47, usage 0x0002, fixed 64-byte reports) through which host software drives the board's RGB LEDs while the controller interface works normally. Hosts stage colours by LED run, light, GPIO pin, action or light kind, in whole-frame or overlay takeover, and publish each frame atomically. The board's own animations resume when the host releases control, disconnects, or goes quiet past a keepalive timeout.

The board describes itself over the same interface - identity, state, input modes, LED summary, profiles, controls, lights and animations, read from the live configuration - and signals every change with a state token and an optional event, so hosts need no per-board data and follow user remaps. Discovery is by usage page and usage, which are stable across input modes and VID/PID overrides.

Status

• Draft. The branch now holds only docs/host-lighting.md, the Host Lighting Protocol 2.0 specification, as 1 commit on current main, so the wire format can be reviewed before the code. Inline comments on the doc are welcome.
• The firmware follows as approx. 7 commits. The add-on, its settings and its web configurator section, which docs/host-lighting.md describes, arrive with those commits.
• 2.0 replaces the 1.x pre-release protocol this PR initially carried and is not compatible with it. 1.x hosts, which match usage 0x4C, never see a 2.0 board. v1.4 stays on my fork for historical purposes: branch 20260921-hlp-v1-4, release HLP_v1.4.

What the current version (v2.x) consolidates from before (v1.x)

• Capabilities, not versions: HELLO lists every command, page, request flag, addressing mode, pixel format and event the board implements. Every number space is grouped by function with spare numbers, and an addition never changes a meaning or a layout.
• Request flags on every command: COMMIT_AFTER publishes the frame with its last report, NO_REPLY suppresses the reply, KEEPALIVE refreshes a takeover. A streamed frame costs one acknowledged report.
• Guaranteed replies: a 16-reply queue, its limit stated in HELLO.
• Pages with field groups and a state token: a host reads only the fields it needs, and an expected token makes a multi-read walk restart rather than mix two states. SUBSCRIBE and a STATE_CHANGED event replace polling.
• CLAIM: applications sharing a board coordinate through a lease on the keepalive timeout; a change of holder ends the takeover and clears the frame. An exclusive claim also has the board refuse changes from applications that do not claim (status 4, naming the holder); the holder marks its requests with the HOLDER flag.
• Board features: SET_PROFILE, SET_ANIMATION, SET_ANIMATION_SPEED and a saved SET_BRIGHTNESS apply as the hotkeys do; an unsaved SET_BRIGHTNESS dims for a session without writing flash and ends with the session; SET_INPUT_MODE and REBOOT are magic-guarded and validated from the firmware's own driver mapping and reboot modes.
• 16-bit LED indexes and counts throughout; the addressable limit (100 today) follows the render pipeline.

Related

• Add Host Lighting add-on documentation Site#119: the companion documentation.
• Add tools for the GP2040-CE Host Lighting add-on gp2040ce-binary-tools#12: the reference host tools, moving to 2.0 with the firmware once the code has been committed.

[djGLiTCH]

This PR now carries Host Lighting Protocol v2.0, the consolidation effort I mentioned recently, with the prior v1.x branch removed. For now the branch holds only the specification (docs/host-lighting.md), so the wire format can be reviewed ahead of the code and while awaiting other PRs to be merged that HLP relies on.

HLP v2.0 uses a new top-level usage (0x0002) and renumbers every command, so the v1.x details no longer apply. I have updated the PR description to suit only the new v2.0 specification.

I have a working v2.0 HLP enabled firmware, which currently follows as 7 commits. Currently, I am including #1719, #1721, and #1733 in the alpha HLP v2.0 firmware, as these include fixes or changes that impact HLP. I will post this as a pre-release on my fork later this week (likely over the weekend) once I have rebuilt firmware for all boards.

Any inline comments or suggestions for docs/host-lighting.md are welcome.

[djGLiTCH]

HLP v2.0-rc4 is built as a pre-release on my fork (which implements the same spec shown in this PR), with firmware for all 55 boards:
https://github.com/djGLiTCH/GP2040-CE/releases/tag/HLP_v2.0-rc4

FYI, rc4 is built from the following (20261006-hlp-v2-rc4):

Part	Content
Base	main at 3d1f32f7
Merged PR	#1733 at 02f908cf
Merged PR	#1719 at bd07bb3a
Standalone changes	Three small commits, listed in the release notes. I will raise them as separate PRs after the above PRs are merged into main.
Host Lighting	Seven commits, the series that will come to this PR

The rc4 release includes the v2.0 host tools as a zip, with hlp-conformance to check a board against the specification.

I'll keep this PR as draft with the HLP specification only until 1733 and 1719 are merged. I will then rebase the series onto main, push it here and change the PR to be ready for review.