gnome-asus-kbd-rgb/docs/INSTALL.md

Guide d'Installation - Extension ASUS Keyboard RGB

Ce guide vous explique comment installer et configurer l'extension GNOME Shell pour contrôler le rétroéclairage RGB de votre clavier ASUS.

Prérequis

Système

• OS: Debian GNU/Linux 13 (trixie) ou distribution compatible
• GNOME Shell: Version 48
• Matériel: Clavier ASUS avec support RGB via asus-nb-wmi

Vérification du support matériel

Avant l'installation, vérifiez que votre clavier est supporté :

# Vérifier la présence des fichiers sysfs
ls -la /sys/class/leds/asus::kbd_backlight/

Vous devriez voir les fichiers suivants :

• brightness - Intensité du rétroéclairage
• max_brightness - Valeur maximale d'intensité
• kbd_rgb_mode - Contrôle des couleurs RGB

Si ces fichiers n'existent pas, votre matériel n'est pas supporté par cette extension.

Étape 1 : Configuration des permissions

L'extension nécessite des droits d'écriture sur les fichiers sysfs. La méthode recommandée utilise les règles udev.

1.1 Créer une règle udev

Créez le fichier /etc/udev/rules.d/99-asus-kbd.rules avec la règle qui fonctionne :

sudo tee /etc/udev/rules.d/99-asus-kbd.rules > /dev/null << 'EOF'
ACTION=="add", SUBSYSTEM=="leds", KERNEL=="asus::kbd_backlight", TAG+="uaccess", RUN+="/bin/sh -c 'chgrp kbdled /sys/class/leds/asus::kbd_backlight/brightness && chmod g+w /sys/class/leds/asus::kbd_backlight/brightness'"
ACTION=="add", SUBSYSTEM=="leds", KERNEL=="asus::kbd_backlight", TAG+="uaccess", RUN+="/bin/sh -c 'chgrp kbdled /sys/class/leds/asus::kbd_backlight/kbd_rgb_mode && chmod g+w /sys/class/leds/asus::kbd_backlight/kbd_rgb_mode'"
EOF

Cette règle s'exécute lors de l'ajout du device et applique directement les bonnes permissions.

1.2 Créer le groupe kbdled

sudo groupadd -f kbdled

1.3 Ajouter votre utilisateur au groupe

sudo usermod -aG kbdled $USER

1.4 Recharger les règles udev et appliquer les permissions

# Recharger les règles udev
sudo udevadm control --reload-rules

# Retirer et réinsérer le module pour déclencher l'événement "add"
sudo modprobe -r asus_nb_wmi
sudo modprobe asus_nb_wmi

# Attendre 2 secondes que le module se charge
sleep 2

1.5 Déconnexion / Reconnexion

Important: Vous devez vous déconnecter et vous reconnecter pour que l'appartenance au groupe soit prise en compte.

# Vérifier l'appartenance au groupe après reconnexion
groups | grep kbdled

1.5 Vérifier les permissions

Vérifiez que les permissions ont été appliquées correctement :

ls -l /sys/class/leds/asus::kbd_backlight/brightness
ls -l /sys/class/leds/asus::kbd_backlight/kbd_rgb_mode

Résultat attendu :

-rw-rw-r-- 1 root kbdled ... brightness
--w--w---- 1 root kbdled ... kbd_rgb_mode

Le groupe doit être kbdled (et non root).

1.6 Test d'écriture

Testez que vous pouvez contrôler le clavier :

# Test intensité niveau 3 (maximum)
echo 3 > /sys/class/leds/asus::kbd_backlight/brightness
# → Le rétroéclairage doit passer au maximum

# Test intensité niveau 1 (faible)
echo 1 > /sys/class/leds/asus::kbd_backlight/brightness
# → Le rétroéclairage doit diminuer

# Test couleur RGB (orange)
echo "1 0 255 165 0 0" > /sys/class/leds/asus::kbd_backlight/kbd_rgb_mode
# → Le clavier doit devenir orange

# Test couleur RGB (rouge)
echo "1 0 255 0 0 0" > /sys/class/leds/asus::kbd_backlight/kbd_rgb_mode
# → Le clavier doit devenir rouge

Si aucune erreur "Permission denied" n'apparaît et que votre clavier change de couleur/intensité, c'est parfait ! ✅

Étape 2 : Installation de l'extension

2.1 Cloner le dépôt

cd ~/Documents
git clone https://github.com/gilles/gnome-asus-kbd-rgb.git
cd gnome-asus-kbd-rgb

2.2 Compiler le schéma GSettings

cd extension/schemas
glib-compile-schemas .
cd ../..

2.3 Installation automatique

Utilisez le script fourni :

./tools/install-local.sh

2.4 Installation manuelle (alternative)

Si vous préférez installer manuellement :

# Créer le dossier de destination
mkdir -p ~/.local/share/gnome-shell/extensions/asus-kbd-rgb@gilles

# Copier les fichiers
cp -r extension/* ~/.local/share/gnome-shell/extensions/asus-kbd-rgb@gilles/

# Compiler le schéma dans le dossier d'installation
glib-compile-schemas ~/.local/share/gnome-shell/extensions/asus-kbd-rgb@gilles/schemas/

Étape 3 : Activation de l'extension

3.1 Recharger GNOME Shell

Sur X11 :

• Appuyez sur Alt+F2
• Tapez r
• Appuyez sur Entrée

Sur Wayland :

• Déconnectez-vous et reconnectez-vous

3.2 Activer l'extension

Via l'application Extensions :

gnome-extensions enable asus-kbd-rgb@gilles

Ou via l'interface graphique :

1. Ouvrez l'application "Extensions"
2. Recherchez "ASUS Keyboard RGB Control"
3. Activez le bouton

3.3 Vérification

Vous devriez voir une icône de clavier dans la barre supérieure de GNOME Shell (à droite). Cliquez dessus pour ouvrir le menu de contrôle.

Étape 4 : Vérification des logs

Si l'extension ne s'affiche pas ou ne fonctionne pas :

# Voir les logs en temps réel
journalctl -f -o cat /usr/bin/gnome-shell

# Ou voir les dernières erreurs
journalctl -xe | grep -i asus

Désinstallation

Pour désinstaller l'extension :

# Désactiver
gnome-extensions disable asus-kbd-rgb@gilles

# Supprimer
rm -rf ~/.local/share/gnome-shell/extensions/asus-kbd-rgb@gilles

# Optionnel : supprimer le groupe et la règle udev
sudo deluser $USER kbdled
sudo rm /etc/udev/rules.d/99-asus-kbd.rules
sudo udevadm control --reload-rules

Dépannage

Si vous rencontrez des problèmes, consultez le fichier TROUBLESHOOTING.md.

Support

• Issues: https://github.com/gilles/gnome-asus-kbd-rgb/issues
• Documentation: Voir les autres fichiers du dossier docs/