This project has been archived by its maintainers, and is no longer receiving any updates.
hid-rgb-ctl
Linux command-line tool for controlling RGB lighting via standard HID protocols.
Supported Protocols
-
HID LampArray (Usage Page 0x59) — Modern Dynamic Lighting standard from the USB HID Usage Tables v1.4 (Section 26). Supports device interrogation, per-lamp attributes, autonomous/manual mode, and color updates.
-
HID LED Page RGB (Usage Page 0x08, Usage 0x52) — Legacy RGB LED control per HID Usage Tables Section 11.7. Simpler protocol with direct R/B/G channel writes.
Features
- Auto-discovers devices by parsing HID report descriptors — no hardcoded vendor/product IDs
- Supports preset colors, decimal RGB, hex color codes, and intensity control
- Toggle autonomous/manual mode on LampArray devices
- Zero external dependencies — Python 3.9+ standard library only
Install
pipx install git+https://github.com/xz-dev/hid-rgb-ctl.git
# or from local clone
pipx install .
Usage
# List detected devices
hid-rgb-ctl list
# Show device attributes and lamp info
hid-rgb-ctl get
# Set color by preset name
hid-rgb-ctl set red
# Set color by RGB values (0-255)
hid-rgb-ctl set 255 165 0
# Set color by hex code
hid-rgb-ctl set ff6400
# Set color with custom intensity
hid-rgb-ctl set cyan -i 128
# Turn off
hid-rgb-ctl set off
# Specify device path (when multiple devices present)
hid-rgb-ctl -p /dev/hidraw1 set blue
# Toggle autonomous mode (LampArray only)
hid-rgb-ctl auto off # host takes control
hid-rgb-ctl auto on # device resumes built-in effects
Permissions
HID device access requires read/write permission on /dev/hidrawN.
Add a udev rule for your device, for example:
# /etc/udev/rules.d/99-hid-rgb.rules
# ASUS Vivobook keyboard (0B05:5570)
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="0b05", ATTRS{idProduct}=="5570", TAG+="uaccess"
Then reload:
sudo udevadm control --reload-rules && sudo udevadm trigger
Verified Devices
| Device | Bus | VID:PID | Protocol | Lamps | Status |
|---|---|---|---|---|---|
| ASUS Vivobook S 16 (M5606WA) keyboard | I2C | 0B05:5570 | LampArray | 1 (single-zone) | Verified |
Contributions welcome — please open an issue or PR with your device info.
Protocol Notes
LampArray (Usage Page 0x59)
The typical operation flow (Section 26.6):
- Read
LampArrayAttributesReport— get lamp count, device kind - Read
LampAttributesResponseReportfor each lamp — get position, RGB level counts, programmability - Disable
AutonomousMode— take control from device firmware - Send
LampRangeUpdateReportorLampMultiUpdateReportwith color data - Re-enable
AutonomousModewhen done (optional)
LampCount (Usage 0x03) tells you how many independently controllable zones
the device has. A single-zone keyboard has LampCount=1; a per-key RGB
keyboard may have 100+.
LED Page RGB (Usage Page 0x08, Section 11.7)
Simpler protocol — the RGB LED collection (Usage 0x52) directly contains:
- Red LED Channel (Usage 0x53)
- Blue LED Channel (Usage 0x54) — note: Blue before Green in the spec
- Green LED Channel (Usage 0x55)
- LED Intensity (Usage 0x56, optional)
No autonomous mode or lamp enumeration.
References
- USB HID Usage Tables v1.4 — Section 26 (Lighting and Illumination), Section 11.7 (Multicolor RGB LED)
- Microsoft Dynamic Lighting — Windows implementation guide for the same HID LampArray standard
License
MIT
Metadata
Release files for hid-rgb-ctl 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hid_rgb_ctl-0.1.2.tar.gz | 14.7 kB | Without provenance | Details for hid_rgb_ctl-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hid_rgb_ctl-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for hid_rgb_ctl-0.1.2-py3-none-any.whl |
Total release size: 29.6 kB
Release files / hid_rgb_ctl-0.1.2.tar.gz
| Download URL | hid_rgb_ctl-0.1.2.tar.gz |
|---|---|
| Size | 14.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d05709f9a2a22970e8f075d8fedea9b5ae3a175b73e0e9d4ff3c465ad8cd80ea
|
|
BLAKE2b-256 checksum How to use checksums |
0f2ade13628f6c1bd18f16038fd4b147e1220110566f15ed1d7835436d202ae0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.12 {"installer":{"name":"uv","version":"0.10.12","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Gentoo","version":"2.18","id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / hid_rgb_ctl-0.1.2-py3-none-any.whl
| Download URL | hid_rgb_ctl-0.1.2-py3-none-any.whl |
|---|---|
| Size | 14.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
53d73fbe76efd25be2de9f668c5a03e8a451e64a8ab669257a980bb9bb35c189
|
|
BLAKE2b-256 checksum How to use checksums |
e1803fa885c251bc08bd73c46e483f8edf7c86eb33d883a6a0895289f5d4b026
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.12 {"installer":{"name":"uv","version":"0.10.12","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Gentoo","version":"2.18","id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for hid-rgb-ctl 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.