Contrôle RGB du clavier pour l'ASUS ROG Flow Z13, sans Armoury Crate

Mon ASUS ROG Flow Z13 a deux zones RGB — le clavier et une barre lumineuse autour du bord de la tablette — et le support Linux natif pour l'une ou l'autre se résume à « bonne chance ». Armoury Crate n'existe pas ici. Alors je l'ai écrit moi-même : un CLI, une application GTK4, et un panneau navigateur qui parlent directement au matériel, plus la partie que personne ne prend la peine de faire : faire survivre la couleur à la suspension, au redémarrage, et au débranchement du clavier.

Ce que vous obtenez

Voici le panneau navigateur en train de faire son travail :

Remarque honnête : les deux zones affichent du blanc (#ffffff) ci-dessus. Pas un bug. J'ai capturé ces images depuis une instance isolée avec un fichier d'état vide, et on ne peut pas demander au protocole Aura quelle couleur il affiche actuellement. Ce que l'outil a écrit en dernier est la seule vérité qui existe — ce qui est exactement le problème de conception autour duquel tout ce projet est construit. Plus de détails plus bas.

Quatre façons de changer la couleur

Même backend, quatre portes d'entrée :

Interface	Commande / accès	Idéal pour
CLI	rgb set all '#00ddcc'	scripts, mémoire musculaire, SSH
Interface GTK4	rgb-gui	un vrai sélecteur de couleur avec curseurs, sans terminal
Panneau web	http://127.0.0.1:3003	le téléphone posé sur le même bureau, aucune application à installer
Mode fête	rgb-reactive.py	une nouvelle couleur aléatoire à chaque frappe, pour le plaisir

# 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)

L'interface graphique enveloppe les mêmes opérations dans une boîte de dialogue de couleur par zone, des curseurs de luminosité, neuf nuanciers prédéfinis, et un interrupteur de synchronisation qui applique un changement à toutes les zones. Le panneau web reprend la même idée dans un onglet : sélecteur de couleur, champ hex, curseur de luminosité, bascule off, rangée de préréglages, All On / All Off.

Le protocole HID Aura

Les deux zones — clavier (USB 0b05:1a30) et barre lumineuse (USB 0b05:18c6) — parlent le protocole HID Aura que les projets g-helper et z13ctl ont d'abord rétro-ingénié. Rien d'officiel ne le documente ; des gens l'ont compris en scrutant des captures USB, et cet outil s'appuie sur leur travail plutôt que de le refaire.

Le mécanisme est presque insultant de simplicité :

• Des rapports de sortie de 64 octets, ID de rapport 0x5D, complétés de zéros.
• Paquet SetMode : 5d b3 <zone> <mode> <r> <g> <b> <speed> — le mode 0x00 est la couleur statique, la seule que cet outil utilise.
• Puis un paquet Save (5d b5) et un paquet Apply (5d b4) pour valider.
• Octet de zone : 0x00 pour le clavier, 0x01 pour la barre lumineuse. Les deux nœuds hidraw se trouvent derrière un seul « N-KEY Device » multiplexé en USB, et chacun ignore tranquillement les paquets adressés à l'autre zone — si bien que la même écriture en trois paquets fonctionne sur l'un ou l'autre nœud.

Le fait qui gouverne chaque décision de conception ici : le protocole est en écriture seule. Vous pouvez définir une couleur ; vous ne pouvez jamais en relire une. Donc l'outil garde sa propre mémoire — chaque couleur et luminosité appliquées atterrissent dans ~/.local/state/rgb-control/state.json, et ce fichier, pas le matériel, est le seul enregistrement de ce à quoi votre clavier est censé ressembler. Le service de restauration, le démon d'inactivité, la gestion du re-branchement : tout ça existe pour repousser ce fichier vers un matériel qui n'arrête pas d'oublier.

La découverte parcourt /sys/class/hidraw, fait correspondre l'ID vendeur/produit, puis vérifie que l'ID de rapport 0x5D existe réellement dans le descripteur de rapport du nœud avant de lui faire confiance. Il existe aussi un backend de secours : le pilote asus-wmi du noyau expose une classe LED multicolore à /sys/class/leds/asus-*:rgb:*, avec des fichiers multi_intensity et brightness. Hidraw fait l'écriture quand il est disponible ; sysfs fournit l'état initial, puisque contrairement à HID, il peut être lu.

Comment un clic devient une couleur

Le chemin complet du clic à la LED :

Survivre à la suspension et au re-branchement

Chaque outil RGB que j'ai trouvé sous Linux pouvait définir une couleur. Aucun ne s'en souvenait au-delà de la suspension suivante, du redémarrage, ou — le clavier du Z13 étant détachable — du prochain re-branchement. Chacun de ces événements remet le matériel dans le noir, et un protocole en écriture seule signifie qu'il n'a aucune idée de ce qu'il affichait. La correction doit vivre en dehors du matériel :

Le budget d'environ 6 secondes de nouvelles tentatives compte : un clavier fraîchement rebranché met un instant à apparaître sur le bus, et udev déclenche une rafale d'événements pendant qu'il énumère. L'unité de restauration dort 1 seconde pour laisser la rafale se calmer, puis retente la découverte au lieu d'abandonner au premier échec.

Il existe aussi un démon d'inactivité, rgb-idled, réservé à GNOME/Wayland car il écoute deux signaux D-Bus précis : org.gnome.ScreenSaver ActiveChanged (verrouillage de l'écran → réduction à la luminosité 1) et org.gnome.Mutter.IdleMonitor WatchFired (la même horloge d'inactivité que GNOME utilise pour éteindre l'écran → extinction des lumières). Au déverrouillage, il restaure depuis state.json. Le détail que j'aime vraiment : la réduction et l'extinction empruntent un chemin persist=False, si bien que ces états transitoires n'écrasent jamais votre couleur enregistrée. Au réveil, c'est la couleur que vous aviez choisie, pas ce que le démon a fait en dernier.

Installation

Test rapide, sans installation :

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

L'installation complète met en place la règle udev, rgb-restore.service, le hook de sommeil, une règle tmpfiles, un lien symbolique ~/.local/bin/rgb, une entrée de bureau, et le service utilisateur rgb-idled :

cd rgb-control
sudo ./install.sh

Les chemins de l'installateur sont modélisés (__RGB_DIR__, __RGB_STATE__) et remplis au moment de l'installation, donc ça fonctionne peu importe où vous avez décompressé l'archive. Le panneau web est une étape séparée et facultative :

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

Il prend aussi en charge l'activation par socket systemd — zéro ressource consommée jusqu'à la première requête, extinction après 10 minutes d'inactivité. Et le mode fête, une nouvelle couleur aléatoire à chaque frappe, n'est qu'à une commande : ./rgb-toggle.sh start (il demandera sudo).

Pièges à éviter

• Permissions sur les distributions plus strictes. Sur Fedora/Bazzite, /dev/hidraw* est accessible en écriture à tout le monde par défaut, donc ça fonctionne directement. Les autres distributions ont généralement besoin d'une règle udev uaccess (exemple dans le guide d'installation). C'est la cause numéro un du « ça ne fait rien ».
• Les nœuds LED sysfs appartiennent à root. La règle udev fournie leur fait un chgrp vers wheel. Vous n'êtes pas dans ce groupe ? Ajoutez-vous, ou modifiez la règle.
• Les noms des nœuds LED portent un suffixe propre à chaque machine. Quelque chose comme asus-0003:0B05:18C6.0008 — ce nombre final peut varier d'une machine à l'autre. Vérifiez ls /sys/class/leds et ajustez la configuration si le backend de secours ne trouve rien.
• Les machines rpm-ostree (Bazzite, Silverblue) ont un /usr en lecture seule. L'installateur cible délibérément /etc pour le hook de sommeil. Ne le « corrigez » pas en sens inverse.
• rgb-idled ne se déclenche que sous GNOME. Sous KDE ou X11 nu, il démarre sans problème et ne fait jamais rien. C'est prévu, pas cassé.
• Le panneau web n'a pas d'authentification, exprès. Il ne se lie qu'à 127.0.0.1, car il exécute en sous-processus un contrôle matériel sans aucune authentification devant. Le code du serveur le dit clairement : ne pas se lier à 0.0.0.0 sans d'abord ajouter une authentification. Il y a une protection contre le path-traversal sur les fichiers statiques, mais une protection n'est pas une authentification.
• Le re-branchement se fait un peu concurrence à lui-même. Un seul re-branchement physique peut déclencher plusieurs événements udev ; le chemin de restauration dort brièvement pour les regrouper, donc les lumières peuvent revenir avec un léger temps de retard. C'est la fenêtre de regroupement qui fait son travail, pas un ralentissement.

Téléchargements

• Télécharger le code source de rgb-keyboard (zip) 39 KB

Gratuit pour un usage personnel. Si ça vous fait gagner un après-midi, le bouton café n'est pas loin.