115 lines
4.0 KiB
Markdown
115 lines
4.0 KiB
Markdown
# 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). |