# 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é :

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

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

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

### 1.3 Ajouter votre utilisateur au groupe

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

### 1.4 Recharger les règles udev et appliquer les permissions

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

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

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

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

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

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

### 2.3 Installation automatique

Utilisez le script fourni :

```bash
./tools/install-local.sh
```

### 2.4 Installation manuelle (alternative)

Si vous préférez installer manuellement :

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

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

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

```bash
# 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](TROUBLESHOOTING.md).

## Support

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