# 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](#lextension-ne-saffiche-pas)
2. [Message "Permissions insuffisantes"](#message-permissions-insuffisantes)
3. [Message "Matériel non supporté"](#message-matériel-non-supporté)
4. [Les sliders ne fonctionnent pas](#les-sliders-ne-fonctionnent-pas)
5. [La couleur ne change pas](#la-couleur-ne-change-pas)
6. [Les paramètres ne sont pas sauvegardés](#les-paramètres-ne-sont-pas-sauvegardés)
7. [Erreurs dans les logs](#erreurs-dans-les-logs)
8. [L'extension se désactive automatiquement](#lextension-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

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

Si elle n'apparaît pas :

```bash
gnome-extensions enable asus-kbd-rgb@gilles
```

#### 2. Vérifier l'installation

```bash
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

```bash
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

```bash
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

```bash
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 :

```bash
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

```bash
getent group kbdled
```

Si le groupe n'existe pas :

```bash
sudo groupadd -f kbdled
```

#### 3. Vérifier l'appartenance au groupe

```bash
groups | grep kbdled
```

Si vous n'êtes pas dans le groupe :

```bash
sudo usermod -aG kbdled $USER
```

**Important** : Déconnexion/Reconnexion requise !

#### 4. Recharger udev

```bash
sudo udevadm control --reload-rules
sudo udevadm trigger
```

#### 5. Vérifier les permissions finales

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

Test d'écriture :

```bash
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

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

Devrait afficher `asus::kbd_backlight`

Si absent :

```bash
ls -la /sys/class/leds/
```

Cherchez un dossier similaire pour votre clavier.

#### 2. Vérifier le module kernel

```bash
lsmod | grep asus
```

Devrait afficher `asus_nb_wmi` ou `asus_wmi`

Si absent, charger le module :

```bash
sudo modprobe asus-nb-wmi
```

#### 3. Vérifier le matériel

```bash
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

```bash
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

```bash
# 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

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

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

#### 3. Redémarrer l'extension

```bash
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

```bash
gsettings list-schemas | grep asuskbdrgb
```

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

#### 2. Vérifier les valeurs stockées

```bash
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

```bash
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

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

---

## Erreurs dans les logs

### Comment voir les logs

```bash
# 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 :

```bash
./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é

```bash
gnome-shell --version
```

Doit afficher : `GNOME Shell 48.x`

Si version différente, modifier `metadata.json` :

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

#### 2. Vérifier les erreurs JavaScript

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

#### 3. Mode debug

Activer avec verbose logging :

```bash
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** :

```bash
# 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 :

```bash
# 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
```