RGB-Tastatursteuerung für den ASUS ROG Flow Z13, ganz ohne Armoury Crate

Mein ASUS ROG Flow Z13 hat zwei RGB-Zonen — die Tastatur und eine Lightbar rund um die Kante des Tablets — und die Linux-Standardunterstützung für beide lautet „viel Glück”. Armoury Crate gibt es hier nicht. Also habe ich es selbst geschrieben: eine CLI, eine GTK4-App und ein Browser-Panel, die direkt mit der Hardware sprechen, dazu den Teil, um den sich sonst niemand kümmert: dafür zu sorgen, dass die Farbe Suspend, Neustart und das Abdocken der Tastatur übersteht.

Was am Ende dabei herauskommt

Hier erledigt das Browser-Panel seinen Job:

Ehrlicher Hinweis: Oben zeigen beide Zonen Weiß (#ffffff). Kein Bug. Diese Screenshots stammen von einer sandboxed Instanz mit leerer State-Datei, und man kann das Aura-Protokoll nicht fragen, welche Farbe es gerade zeigt. Was das Tool zuletzt geschrieben hat, ist die einzige Wahrheit, die existiert — genau das ist das Designproblem, um das dieses ganze Projekt herum gebaut ist. Mehr dazu weiter unten.

Vier Wege, die Farbe zu ändern

Dasselbe Backend, vier Eingänge:

Interface	Befehl / Zugriff	Am besten für
CLI	rgb set all '#00ddcc'	Skripte, eingespielte Handgriffe, SSH
GTK4 GUI	rgb-gui	ein echter Farbwähler mit Reglern, kein Terminal nötig
Web-Panel	http://127.0.0.1:3003	Handy auf demselben Schreibtisch, keine App zu installieren
Party-Modus	rgb-reactive.py	bei jedem Tastendruck eine neue zufällige Farbe, nur zum Spaß

# the CLI in one breath
rgb list                       # what zones exist, current known state
rgb set all '#00ddcc'          # set every zone to teal
rgb brightness keyboard 2      # 0-3
rgb on / rgb off               # per-zone or all
rgb restore                    # reapply the last saved color (what the restore service runs)

Die GUI verpackt dieselben Operationen in einen Farbdialog pro Zone, Helligkeitsregler, neun Preset-Farbfelder und einen Sync-Schalter, der eine Änderung auf alle Zonen anwendet. Das Web-Panel setzt dieselbe Idee in einem Tab um: Farbwähler, Hex-Feld, Helligkeitsregler, Aus-Schalter, Preset-Zeile, All On / All Off.

Das Aura-HID-Protokoll

Beide Zonen — Tastatur (USB 0b05:1a30) und Lightbar (USB 0b05:18c6) — sprechen das Aura-HID-Protokoll, das die Projekte g-helper und z13ctl als Erste per Reverse Engineering entschlüsselt haben. Offiziell dokumentiert ist davon nichts; Leute haben es sich durch das Anstarren von USB-Mitschnitten erarbeitet, und dieses Tool baut auf ihrer Arbeit auf, statt sie noch einmal zu machen.

Die Mechanik ist fast beleidigend einfach:

• 64-Byte-Output-Reports, Report-ID 0x5D, mit Nullen aufgefüllt.
• SetMode-Paket: 5d b3 <zone> <mode> <r> <g> <b> <speed> — Modus 0x00 ist statische Farbe, und mehr benutzt dieses Tool nicht.
• Danach ein Save-Paket (5d b5) und ein Apply-Paket (5d b4), um zu übernehmen.
• Zonen-Byte: 0x00 Tastatur, 0x01 Lightbar. Beide hidraw-Knoten sitzen hinter einem USB-gemultiplexten „N-KEY Device” und ignorieren still Pakete, die an die jeweils andere Zone adressiert sind — sodass derselbe Drei-Pakete-Schreibvorgang auf beiden Knoten funktioniert.

Die Tatsache, die hier jede Designentscheidung antreibt: Das Protokoll ist nur schreibend. Man kann eine Farbe setzen, aber niemals eine zurücklesen. Also führt das Tool sein eigenes Gedächtnis — jede angewendete Farbe und Helligkeit landet in ~/.local/state/rgb-control/state.json, und diese Datei, nicht die Hardware, ist der einzige Nachweis, wie die Tastatur eigentlich aussehen soll. Der Restore-Dienst, der Idle-Daemon, die Behandlung des erneuten Andockens: All das existiert nur, um diese Datei immer wieder einer Hardware entgegenzudrücken, die ständig vergisst.

Die Discovery durchläuft /sys/class/hidraw, gleicht Vendor-/Product-ID ab und prüft dann, ob Report-ID 0x5D im Report-Descriptor des Knotens tatsächlich existiert, bevor sie ihm vertraut. Es gibt außerdem ein Fallback-Backend: Der asus-wmi-Treiber des Kernels stellt unter /sys/class/leds/asus-*:rgb:* eine Multicolor-LED-Klasse bereit, mit den Dateien multi_intensity und brightness. Das Schreiben übernimmt hidraw, wenn verfügbar; sysfs liefert den Anfangszustand, weil es sich — anders als HID — auslesen lässt.

Wie aus einem Klick eine Farbe wird

Der vollständige Weg vom Klick bis zur LED:

Suspend und erneutes Andocken überstehen

Jedes RGB-Tool, das ich unter Linux gefunden habe, konnte eine Farbe setzen. Keines erinnerte sich daran über den nächsten Suspend, Neustart oder — weil die Tastatur des Z13 abnehmbar ist — das nächste erneute Andocken hinaus. Jedes davon setzt die Hardware auf Dunkel zurück, und ein rein schreibendes Protokoll bedeutet, dass sie keine Ahnung hat, was sie zuletzt gezeigt hat. Die Lösung muss außerhalb der Hardware leben:

Das ~6-Sekunden-Retry-Budget ist wichtig: Eine frisch angedockte Tastatur braucht einen Moment, um auf dem Bus zu erscheinen, und udev feuert beim Enumerieren einen Schwall von Events. Die Restore-Unit schläft 1 Sekunde, damit sich der Schwall legt, und wiederholt dann die Erkennung, statt beim ersten Fehlschlag aufzugeben.

Es gibt außerdem einen Idle-Daemon, rgb-idled, nur für GNOME/Wayland, weil er auf zwei bestimmte D-Bus-Signale lauscht: org.gnome.ScreenSaver ActiveChanged (Bildschirm sperren → auf Helligkeit 1 dimmen) und org.gnome.Mutter.IdleMonitor WatchFired (dieselbe Idle-Uhr, mit der GNOME den Bildschirm abdunkelt → Licht aus). Beim Entsperren wird aus state.json wiederhergestellt. Das Detail, das mir wirklich gefällt: Dimmen und Aus laufen über einen persist=False-Pfad, sodass diese vorübergehenden Zustände die gespeicherte Farbe nie überschreiben. Beim Aufwachen ist es die selbst gewählte Farbe, nicht das, was der Daemon zuletzt gemacht hat.

Einrichtung

Schnelltest, ohne Installation:

cd rgb-control
./rgb-cli list
./rgb-cli set all '#00ddcc'

Die vollständige Installation verdrahtet die udev-Regel, rgb-restore.service, den Sleep-Hook, eine tmpfiles-Regel, einen Symlink ~/.local/bin/rgb, einen Desktop-Eintrag und den rgb-idled-User-Service:

cd rgb-control
sudo ./install.sh

Die Pfade des Installers sind templated (__RGB_DIR__, __RGB_STATE__) und werden zur Installationszeit ausgefüllt, sodass es funktioniert, egal wohin man es entpackt hat. Das Web-Panel ist ein separater, optionaler Schritt:

cd rgb-web
node server.js
# → http://127.0.0.1:3003
# PORT= and RGB_CLI= env vars override the defaults

Es unterstützt außerdem systemd-Socket-Aktivierung — null Ressourcenverbrauch, bis die erste Anfrage eintrifft, beendet sich nach 10 Leerlaufminuten. Und der Party-Modus, eine frische Zufallsfarbe bei jedem Tastenanschlag, ist nur einen Befehl entfernt: ./rgb-toggle.sh start (fragt nach sudo).

Stolperfallen

• Berechtigungen bei strengeren Distros. Auf Fedora/Bazzite ist /dev/hidraw* von Haus aus für alle beschreibbar, also funktioniert es einfach. Andere Distros brauchen meist eine udev-uaccess-Regel (Beispiel im Setup-Guide). Das ist die Ursache Nummer eins für „es tut einfach nichts”.
• Die sysfs-LED-Knoten gehören root. Die mitgelieferte udev-Regel macht per chgrp die Gruppe wheel zum Besitzer. Nicht in dieser Gruppe? Sich selbst hinzufügen oder die Regel bearbeiten.
• LED-Knotennamen tragen ein maschinenspezifisches Suffix. Etwas wie asus-0003:0B05:18C6.0008 — die abschließende Zahl kann sich von Maschine zu Maschine unterscheiden. Mit ls /sys/class/leds nachsehen und die Konfiguration anpassen, wenn das Fallback-Backend nichts findet.
• rpm-ostree-Maschinen (Bazzite, Silverblue) haben ein schreibgeschütztes /usr. Der Installer zielt für den Sleep-Hook absichtlich auf /etc. Das nicht aus gutem Willen wieder „reparieren”.
• rgb-idled feuert nur unter GNOME. Unter KDE oder nacktem X11 startet es problemlos und tut dann nie etwas. Erwartet, nicht kaputt.
• Das Web-Panel hat absichtlich kein Login. Es bindet ausschließlich an 127.0.0.1, weil es ohne vorgeschaltete Authentifizierung Hardware-Steuerung per Shell ausführt. Der Server-Code sagt es unverblümt: nicht an 0.0.0.0 binden, ohne vorher eine Authentifizierung hinzuzufügen. Es gibt einen Path-Traversal-Schutz für statische Dateien, aber ein Schutz ist kein Login.
• Erneutes Andocken gerät ein wenig mit sich selbst ins Rennen. Ein physisches erneutes Andocken kann mehrere udev-Events auslösen; der Restore-Pfad schläft kurz, um sie zusammenzufassen, sodass die Lichter mit einem Takt Verzögerung wieder aufblinken können. Das ist das Zusammenfassungsfenster bei der Arbeit, keine Verzögerung im schlechten Sinn.

Downloads

• rgb-keyboard-Quellcode herunterladen (zip) 39 KB

Kostenlos für die private Nutzung. Wenn es dir einen Nachmittag erspart, ist der Kaffee-Button gleich in der Nähe.