Host Lighting (HLP v1.2) test builds - 16 Aug 2026
Pre-release
HLP v1.2
Released 16 August 2026. Host Lighting Protocol v1.2 for GP2040-CE 0.7.12. Additive over v1.1: command IDs and payload layouts are unchanged, the capability format byte stays at 2, and host software written against v1.0 or v1.1 works against these images unmodified. Hosts detect the version by PING minor >= 2.
Built from 20260811-host-lighting-protocol, the branch behind OpenStickCommunity#1691.
HLP version history
| v1.0 | v1.1 | v1.2 | |
|---|---|---|---|
| Released | 11 Aug 2026 | 16 Aug 2026 | 16 Aug 2026 |
| Commands | 14 | 14 | 15 (+ SET_LIGHT 0x15) |
| Capability pages | 0-4 | 0-5 (+ light table) | 0-5 |
| Page 1 runtime state | mode, profile, brightness, player, fingerprint, animation index | + feature bitmask, LED framework, animation namespace, render Hz | unchanged |
| Per-light visibility | one range per control (page 2) | every light named, with owner, GPIO, position and flags (page 5) | unchanged |
| Per-light addressing | raw index (SET_RANGE) |
raw index (SET_RANGE) |
by page 5 ordinal (SET_LIGHT) |
| Staging reply detail | applied/skipped counts | unchanged | unchanged |
| Stageable button IDs | 0-17 + specials 24-29 | same (18-19, 30-41 report-only) | every named ID, incl. A3/A4 and E1-E12 |
| Fingerprint scope | per-control lookups | whole pin map; also echoed on page 5 | unchanged |
| Caps format byte | 2 | 2 | 2 |
| Detection | PING magic GPHL |
minor >= 1 | minor >= 2 |
| Round-trip / 60 fps stream | 2.0 ms / 300 of 300 | 2.0 ms / 300 of 300 | 2.0 ms / 300 of 300 |
Every version is additive: no command ID or existing payload layout has ever moved, so a v1.0 host works unchanged against a v1.2 board. Builds for every protocol version are published on this fork: HLP v1.0, HLP v1.1, HLP v1.2, HLP v1.3.
What v1.2 adds
SET_LIGHT (0x15). Stages single lights by their page 5 ordinal, so a host can colour one light of a control that owns several without deriving raw LED indexes from the light table first. Entries are batched like SET_BUTTONS - up to 15 per report - and the reply counts applied and skipped the same way. An ordinal at or past the reported total is skipped, exactly as a control without a light is.
Extended button IDs stage. SET_BUTTONS entries naming A3, A4 and E1-E12 now apply on boards that have such lights, through the same action lookup the canonical IDs use, and count as skipped where there is none. They were previously report-only, which made them the one part of the light table a host could see but not act on semantically.
Changed
Nothing observable to a v1.1 host: no command moved, no capability page changed layout, and a host that never sends 0x15 sees identical behaviour.
Which file to download
Filenames carry the GP2040-CE version, the HLP version, the build date and the board config: GP2040-CE-0.7.12_HLP-v1.2_2026.08.16_<Tier>_<Board>.uf2.
Classic images are the PR branch and are what most people want. Refactor images are the same feature built on the LED refactor (OpenStickCommunity#1514) for anyone testing that combination; CI does not build those.
Testing
Validated on a COSMOX M Ultra Gen 2 across both LED pipelines - 57 protocol assertions, all passing. The battery covers every command including SET_LIGHT's ordinal addressing (first, last, out-of-range, mixed batches of applies and skips) and its count rejections, alongside the full v1.1 suite. The extended-ID staging path was rig-proven both ways: with A3 and E3 lights temporarily configured, SET_BUTTONS applied exactly where the light table named a light and skipped everywhere else; with them removed, every extended ID skipped again.
No latency change, re-measured on v1.2: command round-trip median 2.0 ms, a 60 fps stream lands 300/300 commits with none lost, and the unthrottled rate (121-124 fps) matches v1.1, on both pipelines. SET_LIGHT is a staging command on the existing command path, and the input loop and per-frame render path are untouched.
Host tools: OpenStickCommunity/gp2040ce-binary-tools#12 adds hlp-set-light, which stages lights by ordinal from the command line. The attached hlp-tools zip's reference clients probe SET_LIGHT and demonstrate a per-light pass on v1.2 firmware.
docs/host-lighting.md carries the full protocol reference and this changelog.