231 lines
7.7 KiB
Markdown
231 lines
7.7 KiB
Markdown
# 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
|
|
|
|
```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 ! 🌈⌨️**
|