Skip to main content
Archived

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):

  1. Read LampArrayAttributesReport — get lamp count, device kind
  2. Read LampAttributesResponseReport for each lamp — get position, RGB level counts, programmability
  3. Disable AutonomousMode — take control from device firmware
  4. Send LampRangeUpdateReport or LampMultiUpdateReport with color data
  5. Re-enable AutonomousMode when 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

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)

Source distribution for hid-rgb-ctl 0.1.2
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)

Table of built distributions (wheels) for hid-rgb-ctl 0.1.2
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page