Host Lighting (HLP v1.3) test builds - 17 Aug 2026

HLP v1.3

Released 17 August 2026. Host Lighting Protocol v1.3 for GP2040-CE 0.7.12. Additive over v1.2: command IDs and payload layouts are unchanged, the capability format byte stays at 2, and host software written against v1.0, v1.1 or v1.2 works against these images unmodified. Hosts detect the version by PING minor >= 3.

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

HLP version history

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

Per-entry outcome mask. SET_LIGHT replies define bytes [5..6] as a little-endian mask: bit n set means entry n applied, the popcount equals the applied count, and bits at or above the entry count stay zero. A skipped entry names the stale ordinal directly, so a host re-walks page 5 when its cached table has actually moved rather than on every skip. Earlier firmware zero-filled these bytes - gate on the minor version before reading them.

SET_LIGHT_RGBW (0x16). As SET_LIGHT with a white component, up to 12 entries per report - the RGBW pairing SET_RANGE already had. Boards whose chain has no white channel ignore W, exactly as SET_RANGE_RGBW does, and the reply carries the same counts and outcome mask.

Host-supplied W is honoured on white-format chains. Earlier firmware routed achromatic colours to the white emitter without reading the host's W byte, so the textbook subtractive white (0,0,0,W) rendered dark. From v1.3 a host pixel carrying W composes all four channels; pixels without W render exactly as before. Send subtractive white (W = min(R,G,B), RGB reduced) and gate it on PING minor >= 3 - older boards get plain RGB.

Changed

Nothing observable to a v1.2 host: no command moved, no capability page changed layout, and the mask occupies bytes that were previously zero-fill.

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.3_2026.08.17_<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 - 80 protocol assertions each, all passing. Every staging case asserts its outcome mask, including a mid-batch skip that exercises the mask's high byte, so an endianness swap, an inverted polarity or a stride misread cannot pass. SET_LIGHT_RGBW is covered for apply, skip, mixed batches, the exact-maximum batch of 12 and count rejections; the white byte was proven ignored on the GRB test chain, matching SET_RANGE_RGBW. The same battery still passes 57 checks against a v1.2 board with every v1.3 assertion gated off. The white-honour conversion was exercised live by temporarily switching the board's colour format to GRBW and re-running the full suite on both pipelines; no reference board carries a physical white-format strip, so rendering on real GRBW/RGBW hardware is code-audited rather than visually confirmed.

No latency change, re-measured on v1.3: command round-trip median 2.0 ms, a 60 fps stream lands 300/300 commits with none lost, and the unthrottled rate (125 fps) matches earlier versions, on both pipelines. Both additions are command handlers on the staging path; the input loop and per-frame render path are untouched.

Host tools: OpenStickCommunity/gp2040ce-binary-tools#12's hlp-set-light gains RRGGBBWW colours through SET_LIGHT_RGBW and names skipped ordinals from the outcome mask. The attached hlp-tools zip probes both commands.

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