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

Guide de Dépannage - Extension ASUS Keyboard RGB

Ce document vous aide à résoudre les problèmes courants avec l'extension GNOME Shell ASUS Keyboard RGB.

Table des matières

1. L'extension ne s'affiche pas
2. Message "Permissions insuffisantes"
3. Message "Matériel non supporté"
4. Les sliders ne fonctionnent pas
5. La couleur ne change pas
6. Les paramètres ne sont pas sauvegardés
7. Erreurs dans les logs
8. L'extension se désactive automatiquement

---

L'extension ne s'affiche pas

Symptômes

• L'icône de clavier n'apparaît pas dans la barre supérieure
• L'extension est activée mais rien ne se passe

Solutions

1. Vérifier que l'extension est activée

gnome-extensions list
gnome-extensions info asus-kbd-rgb@gilles

Si elle n'apparaît pas :

gnome-extensions enable asus-kbd-rgb@gilles

2. Vérifier l'installation

ls -la ~/.local/share/gnome-shell/extensions/asus-kbd-rgb@gilles/

Fichiers requis :

• extension.js
• ui.js
• backend.js
• metadata.json
• schemas/org.gnome.shell.extensions.asuskbdrgb.gschema.xml
• schemas/gschemas.compiled

3. Recompiler le schéma GSettings

cd ~/.local/share/gnome-shell/extensions/asus-kbd-rgb@gilles/schemas/
glib-compile-schemas .

4. Recharger GNOME Shell

X11 : Alt+F2, tapez r, Entrée

Wayland : Déconnexion/Reconnexion

5. Vérifier les logs

journalctl -f -o cat /usr/bin/gnome-shell | grep -i asus

---

Message "Permissions insuffisantes"

Symptômes

• Le menu affiche "⚠️ Permissions insuffisantes"
• Message : "Impossible d'accéder au rétroéclairage"

Cause

L'utilisateur n'a pas les droits d'écriture sur les fichiers sysfs.

Solutions

1. Vérifier la règle udev

cat /etc/udev/rules.d/99-asus-kbd.rules

Devrait contenir :

SUBSYSTEM=="leds", KERNEL=="asus::kbd_backlight", GROUP="kbdled", MODE="0660"

Si le fichier n'existe pas, créez-le :

echo 'SUBSYSTEM=="leds", KERNEL=="asus::kbd_backlight", GROUP="kbdled", MODE="0660"' | sudo tee /etc/udev/rules.d/99-asus-kbd.rules

2. Vérifier le groupe kbdled

getent group kbdled

Si le groupe n'existe pas :

sudo groupadd -f kbdled

3. Vérifier l'appartenance au groupe

groups | grep kbdled

Si vous n'êtes pas dans le groupe :

sudo usermod -aG kbdled $USER

Important : Déconnexion/Reconnexion requise !

4. Recharger udev

sudo udevadm control --reload-rules
sudo udevadm trigger

5. Vérifier les permissions finales

ls -l /sys/class/leds/asus::kbd_backlight/brightness
# Devrait afficher : -rw-rw---- 1 root kbdled

Test d'écriture :

echo 2 > /sys/class/leds/asus::kbd_backlight/brightness

Si erreur "Permission denied", vérifiez que vous êtes bien déconnecté/reconnecté.

---

Message "Matériel non supporté"

Symptômes

• Le menu affiche "❌ Matériel non supporté"
• Message : "Aucun clavier ASUS RGB détecté"

Cause

Le kernel ne détecte pas le clavier ASUS ou le module asus-nb-wmi n'est pas chargé.

Solutions

1. Vérifier les fichiers sysfs

ls -la /sys/class/leds/ | grep asus

Devrait afficher asus::kbd_backlight

Si absent :

ls -la /sys/class/leds/

Cherchez un dossier similaire pour votre clavier.

2. Vérifier le module kernel

lsmod | grep asus

Devrait afficher asus_nb_wmi ou asus_wmi

Si absent, charger le module :

sudo modprobe asus-nb-wmi

3. Vérifier le matériel

sudo dmesg | grep -i asus
sudo dmesg | grep -i keyboard

Cherchez des messages indiquant la détection du clavier.

4. Vérifier dans le BIOS

Certains ordinateurs ASUS permettent de désactiver le rétroéclairage RGB dans le BIOS. Vérifiez les options "Keyboard Backlight" ou "RGB Lighting".

---

Les sliders ne fonctionnent pas

Symptômes

• Les sliders bougent mais la couleur ne change pas
• Pas de feedback visuel

Solutions

1. Vérifier la brightness

Si la brightness est à 0 (OFF), les changements RGB sont mémorisés mais non appliqués. Augmentez d'abord la brightness.

2. Vérifier les logs

journalctl -f -o cat /usr/bin/gnome-shell | grep RGB

Vous devriez voir des messages comme :

RGB mis à (255, 165, 0) [master: 100%]

3. Tester manuellement

# Test RGB rouge
echo "1 0 255 0 0 0" > /sys/class/leds/asus::kbd_backlight/kbd_rgb_mode

Si cela ne fonctionne pas, le problème est au niveau matériel/kernel, pas de l'extension.

---

La couleur ne change pas

Symptômes

• Les sliders fonctionnent mais la couleur reste la même

Solutions

1. Vérifier le master slider

Si le master slider est à 0%, toutes les couleurs seront noires. Augmentez-le à 100%.

2. Vérifier la valeur brightness

cat /sys/class/leds/asus::kbd_backlight/brightness

Si c'est 0, la couleur ne s'affichera pas.

3. Redémarrer l'extension

gnome-extensions disable asus-kbd-rgb@gilles
gnome-extensions enable asus-kbd-rgb@gilles

Puis recharger GNOME Shell (Alt+F2, r).

---

Les paramètres ne sont pas sauvegardés

Symptômes

• À chaque redémarrage, les couleurs reviennent aux valeurs par défaut

Solutions

1. Vérifier GSettings

gsettings list-schemas | grep asuskbdrgb

Devrait afficher : org.gnome.shell.extensions.asuskbdrgb

2. Vérifier les valeurs stockées

gsettings get org.gnome.shell.extensions.asuskbdrgb red
gsettings get org.gnome.shell.extensions.asuskbdrgb green
gsettings get org.gnome.shell.extensions.asuskbdrgb blue

3. Définir manuellement

gsettings set org.gnome.shell.extensions.asuskbdrgb red 255
gsettings set org.gnome.shell.extensions.asuskbdrgb green 165
gsettings set org.gnome.shell.extensions.asuskbdrgb blue 0

4. Recompiler le schéma

cd ~/.local/share/gnome-shell/extensions/asus-kbd-rgb@gilles/schemas/
glib-compile-schemas .

---

Erreurs dans les logs

Comment voir les logs

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

# Dernières erreurs
journalctl -xe | grep -E "(error|Error|ERROR)"

Erreurs courantes

"Extension asus-kbd-rgb@gilles had error: ..."

Réinstaller l'extension :

./tools/install-local.sh

"Failed to load schema org.gnome.shell.extensions.asuskbdrgb"

Recompiler le schéma GSettings (voir ci-dessus).

"Permission denied" dans les logs

Problème de permissions (voir section correspondante).

---

L'extension se désactive automatiquement

Symptômes

• L'extension s'active puis se désactive immédiatement
• Ou se désactive après un certain temps

Solutions

1. Vérifier la compatibilité

gnome-shell --version

Doit afficher : GNOME Shell 48.x

Si version différente, modifier metadata.json :

"shell-version": [
  "48",
  "47"  // Ajouter votre version
]

2. Vérifier les erreurs JavaScript

journalctl -f -o cat /usr/bin/gnome-shell | grep -i "syntax\|error"

3. Mode debug

Activer avec verbose logging :

gnome-extensions enable asus-kbd-rgb@gilles
journalctl -f /usr/bin/gnome-shell

---

Obtenir de l'aide

Si aucune solution ne fonctionne :

1. Collecter les informations de debug :

# Créer un fichier de debug
{
  echo "=== System Info ==="
  uname -a
  gnome-shell --version

  echo -e "\n=== Hardware ==="
  ls -la /sys/class/leds/asus::kbd_backlight/

  echo -e "\n=== Permissions ==="
  ls -l /sys/class/leds/asus::kbd_backlight/brightness
  groups

  echo -e "\n=== Extension Status ==="
  gnome-extensions info asus-kbd-rgb@gilles

  echo -e "\n=== GSettings ==="
  gsettings list-recursively org.gnome.shell.extensions.asuskbdrgb

  echo -e "\n=== Recent Logs ==="
  journalctl -xe --no-pager | grep -i asus | tail -20
} > ~/asus-kbd-rgb-debug.txt

2. Ouvrir une issue sur GitHub avec le fichier asus-kbd-rgb-debug.txt

3. Forum GNOME : https://discourse.gnome.org/

---

Réinstallation complète

Si tout échoue, réinstallation complète :

# 1. Désactiver et supprimer
gnome-extensions disable asus-kbd-rgb@gilles
rm -rf ~/.local/share/gnome-shell/extensions/asus-kbd-rgb@gilles

# 2. Nettoyer GSettings
gsettings reset-recursively org.gnome.shell.extensions.asuskbdrgb

# 3. Réinstaller
cd ~/Documents/gnome-asus-kbd-rgb
./tools/install-local.sh

# 4. Recharger GNOME Shell
# X11: Alt+F2, r
# Wayland: logout/login

# 5. Réactiver
gnome-extensions enable asus-kbd-rgb@gilles