# GNOME Shell Extension - Contrôle RGB Clavier ASUS Extension GNOME Shell pour contrôler le rétroéclairage RGB des claviers ASUS via l'interface kernel `asus-nb-wmi`. ![GNOME Shell 48](https://img.shields.io/badge/GNOME%20Shell-48-blue) ![License](https://img.shields.io/badge/license-GPL--3.0-green) ## 📋 Fonctionnalités - **🎡 Roue chromatique** : Sélection visuelle de 113 couleurs en un clic - **🎨 Mode sliders** : Contrôle RGB précis (0-255) + Master (0-100%) - **💡 Contrôle d'intensité** : 4 niveaux avec surbrillance visuelle (Off, 1, 2, 3) - **🎯 Presets couleur** : 6 couleurs prédéfinies personnalisables - **🌈 Aperçu en temps réel** : Visualisation avec correction gamma sRGB - **💾 Persistance** : Sauvegarde automatique et restauration au démarrage - **⚡ Interface compacte** : Bascule facile entre roue et sliders ## 🎯 Compatibilité ### Système - **OS** : Debian GNU/Linux 13 (trixie) ou compatible - **GNOME Shell** : Version 48 - **Session** : X11 ou Wayland ### Matériel - Ordinateurs portables ASUS avec clavier RGB - Support via le module kernel `asus-nb-wmi` - Testé sur : **ASUS TUF Gaming A16 FA608UH** Vérifiez la présence de `/sys/class/leds/asus::kbd_backlight/` sur votre système. ## 🚀 Installation Rapide ### 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. Configurer les permissions (obligatoire) ```bash # Créer la règle udev (une seule commande) 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 # Créer le groupe et ajouter l'utilisateur sudo groupadd -f kbdled sudo usermod -aG kbdled $USER # Recharger udev et appliquer les permissions sudo udevadm control --reload-rules sudo modprobe -r asus_nb_wmi sudo modprobe asus_nb_wmi # IMPORTANT: Déconnexion/Reconnexion requise pour l'appartenance au groupe ! ``` ### 3. Installer l'extension ```bash ./tools/install-local.sh ``` ### 4. Recharger GNOME Shell - **X11** : `Alt+F2`, tapez `r`, Entrée - **Wayland** : Déconnexion/Reconnexion L'icône devrait apparaître dans la barre supérieure ! 🎨 ## 📖 Documentation - **[INSTALL.md](docs/INSTALL.md)** - Guide d'installation détaillé - **[TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** - Résolution des problèmes - **[TESTING.md](docs/TESTING.md)** - Checklist de tests - **[UI_SCHEMA.md](docs/UI_SCHEMA.md)** - Schéma de l'interface - **[CLAUDE.md](CLAUDE.md)** - Guide pour Claude Code - **[CHANGELOG.md](CHANGELOG.md)** - Historique des modifications ## 🎨 Captures d'écran ### Interface Principale ``` ┌─────────────────────────────────────────────────────┐ │ Rétroéclairage Clavier ASUS │ ├─────────────────────────────────────────────────────┤ │ Intensité: │ │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │ │ │ OFF │ │ 1 │ │ 2 │ │ 3 │ │ │ └─────┘ └─────┘ └─────┘ └─────┘ │ │ │ │ Rouge ●──────────────○ 255 │ │ Vert ●──────────────○ 255 │ │ Bleu ●──────────────○ 255 │ │ Master ●──────────────○ 100% │ │ │ │ RGB=(255,165,0) #FFA500 Intensité=2/3 │ │ │ │ Couleurs prédéfinies: │ │ 🟠 🔴 🟢 🔵 ⚪ 🔵 │ └─────────────────────────────────────────────────────┘ ``` ## 🏗️ Architecture L'extension est structurée en 3 modules principaux : - **`extension/backend.js`** - Interface sysfs et logique métier - Lecture/écriture des fichiers sysfs - Debouncing (75ms) pour éviter le spam - Clamping et validation des valeurs - Gestion du master gain - **`extension/ui.js`** - Interface utilisateur - Construction du popover et des widgets - Gestion des événements utilisateur - Mise à jour du feedback visuel - **`extension/extension.js`** - Point d'entrée GNOME Shell - Lifecycle de l'extension (enable/disable) - Intégration dans le panel - Chargement des settings GSettings ## ⚙️ Configuration Les paramètres sont stockés via GSettings et peuvent être modifiés manuellement : ```bash # Définir la couleur rouge gsettings set org.gnome.shell.extensions.asuskbdrgb red 255 # Définir un preset gsettings set org.gnome.shell.extensions.asuskbdrgb preset-1 "255,100,50" # Lister tous les paramètres gsettings list-recursively org.gnome.shell.extensions.asuskbdrgb ``` ## 🔧 Développement ### Structure du projet ``` gnome-asus-kbd-rgb/ ├── extension/ # Code source de l'extension │ ├── extension.js # Point d'entrée │ ├── ui.js # Interface utilisateur │ ├── backend.js # Logique sysfs │ ├── metadata.json # Métadonnées │ ├── stylesheet.css # Styles CSS │ └── schemas/ # Schéma GSettings ├── docs/ # Documentation ├── tools/ # Scripts utilitaires └── README.md ``` ### Logs de debug ```bash # Voir les logs en temps réel journalctl -f -o cat /usr/bin/gnome-shell | grep -i asus # Activer le mode verbose gnome-extensions enable asus-kbd-rgb@gilles ``` ### Contribuer 1. Forkez le projet 2. Créez une branche (`git checkout -b feature/amelioration`) 3. Committez vos changements (`git commit -am 'Ajout fonctionnalité'`) 4. Pushez vers la branche (`git push origin feature/amelioration`) 5. Ouvrez une Pull Request ## 🐛 Problèmes Courants ### L'extension ne s'affiche pas ```bash # Vérifier l'installation gnome-extensions list | grep asus # Vérifier les logs journalctl -xe | grep -i asus ``` ### Message "Permissions insuffisantes" Voir [INSTALL.md](docs/INSTALL.md) section "Configuration des permissions". ### La couleur ne change pas Vérifiez que : - La brightness n'est pas à 0 (OFF) - Le master slider n'est pas à 0% - Les permissions sont configurées Consultez [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) pour plus d'aide. ## 📜 Licence GPL-3.0 License - voir le fichier LICENSE ## 👤 Auteur **Gilles** - GitHub: [@gilles](https://github.com/gilles) ## 🙏 Remerciements - Équipe GNOME Shell pour l'API d'extensions - Communauté ASUS Linux pour le support du driver `asus-nb-wmi` - Claude Code pour l'assistance au développement ## 📞 Support - **Issues** : https://github.com/gilles/gnome-asus-kbd-rgb/issues - **Documentation** : Dossier `docs/` - **Forum GNOME** : https://discourse.gnome.org/ --- **Profitez de votre clavier RGB ! 🌈⌨️**