Control RGB de teclado para el ASUS ROG Flow Z13, sin Armoury Crate

Mi ASUS ROG Flow Z13 tiene dos zonas RGB — el teclado y una barra de luz alrededor del borde de la tablet — y el soporte de Linux de fábrica para cualquiera de las dos es «suerte con eso». Armoury Crate no existe aquí. Así que lo escribí yo mismo: un CLI, una app GTK4, y un panel de navegador que hablan directo con el hardware, más la parte que a nadie le importa: hacer que el color sobreviva a la suspensión, el reinicio, y desmontar el teclado.

Lo que obtienes

Aquí está el panel de navegador haciendo su trabajo:

Nota honesta: las dos zonas muestran blanco (#ffffff) ahí arriba. No es un bug. Capturé esto desde una instancia aislada con un archivo de estado vacío, y al protocolo Aura no se le puede preguntar qué color está mostrando en este momento. Lo último que la herramienta escribió es la única verdad que existe — que es exactamente el problema de diseño alrededor del cual está construido todo este proyecto. Más abajo.

Cuatro formas de cambiar el color

Mismo backend, cuatro puertas de entrada:

Interfaz	Comando / acceso	Ideal para
CLI	rgb set all '#00ddcc'	scripts, memoria muscular, SSH
GUI GTK4	rgb-gui	un selector de color de verdad con deslizadores, sin terminal
Panel web	http://127.0.0.1:3003	el teléfono en el mismo escritorio, sin app que instalar
Modo fiesta	rgb-reactive.py	un color aleatorio nuevo en cada tecla, por diversión

# el CLI de un vistazo
rgb list                       # qué zonas existen, estado actual conocido
rgb set all '#00ddcc'          # pone todas las zonas en verde azulado
rgb brightness keyboard 2      # 0-3
rgb on / rgb off               # por zona o todas
rgb restore                    # vuelve a aplicar el último color guardado (lo que corre el servicio de restauración)

La GUI envuelve las mismas operaciones en un diálogo de color por zona, deslizadores de brillo, nueve muestras predefinidas, y un interruptor de sincronía que aplica un cambio a todas las zonas. El panel web es la misma idea en una pestaña: selector de color, caja hex, deslizador de brillo, interruptor de apagado, fila de predefinidos, All On / All Off.

El protocolo HID Aura

Ambas zonas — teclado (USB 0b05:1a30) y barra de luz (USB 0b05:18c6) — hablan el protocolo HID Aura que los proyectos g-helper y z13ctl fueron los primeros en hacer ingeniería inversa. Nada oficial lo documenta; la gente lo descubrió mirando fijamente capturas USB, y esta herramienta se apoya en ese trabajo en vez de rehacerlo.

La mecánica es casi insultantemente simple:

• Reportes de salida de 64 bytes, report ID 0x5D, rellenados con ceros.
• Paquete SetMode: 5d b3 <zona> <modo> <r> <g> <b> <velocidad> — el modo 0x00 es color estático, que es lo único que usa esta herramienta.
• Después un paquete Save (5d b5) y un paquete Apply (5d b4) para confirmar.
• Byte de zona: 0x00 teclado, 0x01 barra de luz. Ambos nodos hidraw están detrás de un mismo «N-KEY Device» multiplexado por USB, y cada uno ignora silenciosamente los paquetes dirigidos a la otra zona — así que la misma escritura de tres paquetes funciona en cualquiera de los dos nodos.

El hecho que impulsa cada decisión de diseño aquí: el protocolo es de solo escritura. Puedes poner un color; nunca puedes volver a leer uno. Así que la herramienta lleva su propia memoria — cada color y brillo aplicado termina en ~/.local/state/rgb-control/state.json, y ese archivo, no el hardware, es el único registro de cómo se supone que se vea tu teclado. El servicio de restauración, el demonio de inactividad, el manejo del redocking: todo eso existe para volver a empujar ese archivo hacia un hardware que no deja de olvidar.

El descubrimiento recorre /sys/class/hidraw, hace coincidir el ID de vendor/product, y después comprueba que el report ID 0x5D realmente exista en el descriptor de reportes del nodo antes de confiar en él. También hay un backend de respaldo: el driver asus-wmi del kernel expone una clase LED multicolor en /sys/class/leds/asus-*:rgb:*, con archivos multi_intensity y brightness. Hidraw hace la escritura cuando está disponible; sysfs aporta el estado inicial, ya que a diferencia de HID sí se puede leer.

Cómo un clic se convierte en un color

El camino completo del clic al LED:

Sobrevivir a la suspensión y al redocking

Todas las herramientas RGB que encontré en Linux podían poner un color. Ninguna lo recordaba después de la siguiente suspensión, el siguiente reinicio, o — como el teclado del Z13 es desmontable — el siguiente redocking. Cada uno de esos eventos resetea el hardware a oscuras, y un protocolo de solo escritura significa que no tiene ni idea de qué estaba mostrando. La solución tiene que vivir fuera del hardware:

El presupuesto de reintento de ~6 segundos importa: un teclado recién acoplado tarda un momento en aparecer en el bus, y udev dispara una ráfaga de eventos mientras enumera. La unidad de restauración duerme 1 segundo para dejar que la ráfaga se asiente, y luego reintenta el descubrimiento en vez de rendirse al primer fallo.

También hay un demonio de inactividad, rgb-idled, solo para GNOME/Wayland porque escucha dos señales D-Bus específicas: org.gnome.ScreenSaver ActiveChanged (bloquear la pantalla → atenuar a brillo 1) y org.gnome.Mutter.IdleMonitor WatchFired (el mismo reloj de inactividad que usa GNOME para apagar la pantalla → luces apagadas). Al desbloquear, restaura desde state.json. El detalle que de verdad me gusta: atenuar y apagar usan un camino persist=False, así que esos estados transitorios nunca sobrescriben tu color guardado. Te despiertas y es el color que elegiste, no lo último que hizo el demonio.

Instalación

Prueba rápida, sin instalar:

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

La instalación completa conecta la regla udev, rgb-restore.service, el hook de sleep, una regla de tmpfiles, un symlink en ~/.local/bin/rgb, una entrada de escritorio, y el servicio de usuario rgb-idled:

cd rgb-control
sudo ./install.sh

Las rutas del instalador están templadas (__RGB_DIR__, __RGB_STATE__) y se rellenan en el momento de instalar, así que funciona desde donde sea que lo hayas descomprimido. El panel web es un paso aparte y opcional:

cd rgb-web
node server.js
# → http://127.0.0.1:3003
# las variables de entorno PORT= y RGB_CLI= sobrescriben los valores por defecto

También soporta activación por socket de systemd — cero recursos hasta que llega la primera petición, y termina tras 10 minutos de inactividad. Y el modo fiesta, un color aleatorio nuevo en cada tecla, está a un comando de distancia: ./rgb-toggle.sh start (te va a pedir sudo).

Trampas comunes

• Permisos en distros más estrictas. En Fedora/Bazzite, /dev/hidraw* es escribible por cualquiera de fábrica, así que esto simplemente funciona. Otras distros suelen necesitar una regla udev uaccess (hay un ejemplo en la guía de instalación). Esta es la causa número uno de «no hace nada».
• Los nodos LED de sysfs son propiedad de root. La regla udev incluida les hace chgrp a wheel. ¿No estás en ese grupo? Agrégate o edita la regla.
• Los nombres de los nodos LED llevan un sufijo específico de cada máquina. Algo como asus-0003:0B05:18C6.0008 — ese número final puede variar de una máquina a otra. Revisa ls /sys/class/leds y ajusta la configuración si el backend de respaldo no encuentra nada.
• Las máquinas rpm-ostree (Bazzite, Silverblue) tienen un /usr de solo lectura. El instalador apunta deliberadamente a /etc para el hook de sleep. No lo «arregles» de vuelta.
• rgb-idled solo se dispara en GNOME. En KDE o X11 puro arranca bien y nunca hace nada. Es lo esperado, no está roto.
• El panel web no tiene login, a propósito. Se enlaza solo a 127.0.0.1, porque ejecuta control de hardware sin ninguna autenticación delante. El código del servidor lo dice sin rodeos: no te enlaces a 0.0.0.0 sin añadir autenticación primero. Hay una protección contra path-traversal en los archivos estáticos, pero una protección no es un login.
• El redocking compite un poco consigo mismo. Un solo redocking físico puede disparar varios eventos udev; el camino de restauración duerme brevemente para colapsarlos, así que las luces pueden volver un pelín tarde. Esa es la ventana de colapso funcionando, no un retraso.

Descargas

• Descargar el código fuente de rgb-keyboard (zip) 39 KB

Gratis para uso personal. Si te ahorra una tarde, el botón del café está aquí cerca.