Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
djGLiTCH wants to merge 3 commits into
base: main
Choose a base branch
from
+615 −1
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e068fa6
Add tools for the GP2040-CE Host Lighting add-on
djGLiTCH Aug 11, 2026
7238685
Tolerate the board disconnecting during reboot commands
djGLiTCH Aug 11, 2026
c42dccc
Label page 1's brightness field as a step index
djGLiTCH Aug 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,15 @@
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`.

## v0.11.1

### Miscellaneous
Expand Down
29 changes: 29 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,35 @@ 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, and per-light positions where supported.
* `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-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.0
100 pings in 601 ms (6.0 ms average)

% hlp-fill --scope case 00FF00
filled case with #00FF00 for 3.0s
released - on-board animations restored
```

### summarize-gp2040ce

`summarize-gp2040ce` prints information regarding the provided USB device or file. It attempts to detect the firmware
Expand Down
Loading