asrock-led-server/README.md

ASRock LED Server

Drive the motherboard LEDs of an ASRock board equipped with the USB Polychrome LED controller (USB vendor 26ce, product 01a2) from the command line. Any script can flash, blink, pulse or animate the LEDs by invoking one command.

Designed for a server kept behind glass, but works for any use where you want system state visible on the motherboard lighting.

Files

File	Purpose
asrock_hid.py	Low level HID driver for the Polychrome controller
asrock-led.py	Manual CLI for raw read/write/commit against the device
asrock-indicator.py	Daemon with socket API plus the ctl client
asrock-led.service	systemd unit for the daemon (system-wide, installed to /etc/systemd/system)
99-asrock-led.rules	udev rule giving the plugdev group access to the hidraw node

Requirements

• Linux
• ASRock board with the USB Polychrome LED controller (26ce:01a2, e.g. 10th gen Intel ASRock boards)
• The controller exposed as a HID device, typically /dev/hidraw0
• python3

Install

1. Install the udev rule so your user can open the device:

sudo install -m 644 99-asrock-led.rules /etc/udev/rules.d/
sudo udevadm control --reload
sudo udevadm trigger

Your user must be a member of the plugdev group.

2. Install the systemd unit and start it:

sudo cp asrock-led.service /etc/systemd/system/asrock-led.service
sudo systemctl daemon-reload
sudo systemctl enable --now asrock-led.service

The daemon runs as root. If you prefer it to run unprivileged, add User= and Group= under the [Service] section (your user must then be in the plugdev group for the udev rule above to apply).

3. Put asrock-indicator (client shim) somewhere on your PATH, pointing at the daemon:

#!/bin/sh
exec python3 /path/to/asrock-led-server/asrock-indicator.py ctl "$@"

Usage

asrock-indicator static <color>
asrock-indicator off
asrock-indicator idle <color>            # rest state after one-shot effects
asrock-indicator pulse <color> [count] [period_seconds]
asrock-indicator blink <color> [count] [period_seconds]
asrock-indicator flash <color>           # one quick flash, then idle
asrock-indicator wave|rainbow|cycle|random|breath|strobe|scan|neon|water|spring|stack|cram|music|direct [speed]
asrock-indicator zone <n|all> <command>  # scope to one header
asrock-indicator query|state|commit

Colors accept a name (red, green, blue, yellow, cyan, magenta, orange, purple, pink, amber, black, white) or a six digit hex value such as #ff5566, or three decimals such as 255 100 50.

Speed is a byte: 0 is fastest, 255 is slowest.

Zones

Zone	Name
0	RGB LED 1 header
1	RGB LED 2 header
2	Addressable header 1
3	Addressable header 2
4	PCH heatsink
5	IO cover
6	PCB
7	Audio / addressable header 3

Examples

asrock-indicator flash cyan       # job started
asrock-indicator blink red 3 0.2  # failure
asrock-indicator wave             # long running job
asrock-indicator static green     # steady healthy state

Protocol

The controller is a 64 byte interrupt out report on hidraw with no report id. Byte 0 is the command: 0x10 write, 0x11 read, 0x12 commit to NVM. Layout:

Byte	Field
0	Command (10 write, 11 read, 12 commit)
1	Reserved (00)
2	Zone (or 00 with the all flag set)
3	Mode
4	Red
5	Green
6	Blue
7	Speed
8	ff
9	All zones flag (01 applies to every zone)

Modes: 00 off, 01 static, 02 breathing, 03 strobe, 04 spectrum cycle, 05 random, 06 music, 07 wave, 08 spring, 09 stack, 0a cram, 0b scan, 0c neon, 0d water, 0e rainbow, 0f direct.

Notes

• LED changes are volatile by design so the daemon keeps ownership. Run asrock-indicator commit to persist the current state to NVM across reboots.
• The protocol's all-zones flag lives at byte 9 on this controller (some upstream tools use a different offset; verify against your board).