7.7 KiB
7.7 KiB
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.
📋 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
cd ~/Documents
git clone https://github.com/gilles/gnome-asus-kbd-rgb.git
cd gnome-asus-kbd-rgb
2. Configurer les permissions (obligatoire)
# 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
./tools/install-local.sh
4. Recharger GNOME Shell
- X11 :
Alt+F2, tapezr, Entrée - Wayland : Déconnexion/Reconnexion
L'icône devrait apparaître dans la barre supérieure ! 🎨
📖 Documentation
- INSTALL.md - Guide d'installation détaillé
- TROUBLESHOOTING.md - Résolution des problèmes
- TESTING.md - Checklist de tests
- UI_SCHEMA.md - Schéma de l'interface
- CLAUDE.md - Guide pour Claude Code
- 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 :
# 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
# 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
- Forkez le projet
- Créez une branche (
git checkout -b feature/amelioration) - Committez vos changements (
git commit -am 'Ajout fonctionnalité') - Pushez vers la branche (
git push origin feature/amelioration) - Ouvrez une Pull Request
🐛 Problèmes Courants
L'extension ne s'affiche pas
# Vérifier l'installation
gnome-extensions list | grep asus
# Vérifier les logs
journalctl -xe | grep -i asus
Message "Permissions insuffisantes"
Voir 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 pour plus d'aide.
📜 Licence
GPL-3.0 License - voir le fichier LICENSE
👤 Auteur
Gilles
- GitHub: @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 ! 🌈⌨️