Host Lighting (HLP v1.1) test builds - 16 Aug 2026

HLP v1.1

Released 16 August 2026. Host Lighting Protocol v1.1 for GP2040-CE 0.7.12. Additive over v1.0: command IDs and payload layouts are unchanged, the capability format byte stays at 2, and host software written against v1.0 works against these images unmodified.

Built from 20260811-host-lighting-protocol, the branch behind OpenStickCommunity#1691.

HLP version history

	v1.0	v1.1
Released	11 Aug 2026	16 Aug 2026
Commands	14	14
Capability pages	0-4	0-5 (+ light table)
Page 1 runtime state	mode, profile, brightness, player, fingerprint, animation index	+ feature bitmask, LED framework, animation namespace, render Hz
Per-light visibility	one range per control (page 2)	every light named, with owner, GPIO, position and flags (page 5)
Per-light addressing	raw index (SET_RANGE)	raw index (SET_RANGE)
Staging reply detail	applied/skipped counts	unchanged
Stageable button IDs	0-17 + specials 24-29	same (18-19, 30-41 report-only)
Fingerprint scope	per-control lookups	whole pin map; also echoed on page 5
Caps format byte	2	2
Detection	PING magic GPHL	minor >= 1
Round-trip / 60 fps stream	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.1 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.1 adds

Capability page 5 - the light table. One record per light, naming the control that owns it along with the GPIO, action, player index, case group and grid position. Page 2 carries one range per button ID, so it cannot describe a control that owns several lights - which happens whenever a board wires two physical buttons to the same action. Both reference boards here do exactly that, with a second Up and a second L3.

The record flags are positive assertions: a set bit is the board vouching for something, so a record asserting nothing reads as the weaker case. A board with no per-light table rebuilds records from its per-control configuration and does not set the per-light flag, so a host can tell "one light per control" from "this board cannot see duplicates".

Runtime state fields. Page 1 now reports a feature bitmask, the LED framework, the animation namespace and the render rate. Each reserves zero for "not reported", so a v1.0 board's zero-fill is never read as a value. The animation namespace matters: the index SET_ANIMATION takes selects built-in effects on the classic pipeline and stored user profiles on the LED refactor. An animation index of 0xFF means none selected.

Extended button IDs. 18-19 name A3 and A4, 30-41 name E1-E12. They appear in the light table only; SET_BUTTONS stages the IDs v1.0 could.

Changed

Observable to a v1.0 host, listed here rather than left to be discovered:

• Page 2 [6] reports the extent of the mapped range (highest LED index in use, plus one) rather than the sum of the ranges above it. On a board with a gap in its LED chain this is a larger, and correct, number - it is what a host needs to size a frame.
• SET_MODE's timeout gains a 10 s ceiling. To idle longer, send PING.
• FILL's buttons scope covers every button light, including lights on controls page 2 cannot name.
• The map fingerprint covers the whole pin map, so switching profiles invalidates a cached LED map even though no stored LED index moved.

Fixed

• Staged writes are bounds-checked against the addressable LED space, so a stored configuration naming an index past the end of the chain is a lighting fault rather than a memory fault.
• A case strip configured outside that space reports as having no light instead of publishing a range no pixel occupies.
• The takeover is released when the USB host disconnects or suspends, rather than waiting out the keepalive.

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.1_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 Haute42 B16 and a COSMOX M Ultra Gen 2 across both LED pipelines - four combinations, 50 protocol assertions each, all passing. Covers every command, every capability page, paged walks, out-of-range requests, reserved button IDs, and a v1.0 host reading a v1.1 board.

No latency change: streaming holds 60 fps with 300 of 300 commits acknowledged on both pipelines, unchanged from v1.0, and the input loop and per-frame render path are untouched.

Host tools: OpenStickCommunity/gp2040ce-binary-tools#12 packages hlp-caps and friends, which decode everything above. The attached hlp-tools zip carries self-contained reference clients for quick testing.

docs/host-lighting.md carries the full protocol reference and this changelog.