Add README with install, usage, and protocol docs

2026-09-08 00:07:19 -05:00
parent ed827b0bab
commit 09782b5784
1 changed files with 120 additions and 0 deletions
@@ -0,0 +1,120 @@
+# 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 user unit for the daemon |
+| `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. Copy the service unit and start it:
+
+```
+mkdir -p ~/.config/systemd/user
+cp asrock-led.service ~/.config/systemd/user/
+systemctl --user daemon-reload
+systemctl --user enable --now asrock-led.service
+```
+
+Optionally enable linger so the daemon starts at boot even before login:
+
+```
+sudo loginctl enable-linger $USER
+```
+
+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).