gnome-asus-kbd-rgb/docs/ANALYSE_PERSISTANCE.md

Analyse : Persistance de l'état du clavier RGB au redémarrage

Problème rapporté

Symptôme : Parfois au redémarrage de Debian, le clavier est éteint et ne peut pas être rallumé. L'utilisateur doit redémarrer sous Windows pour le rallumer.

Analyse technique

1. Comment fonctionne actuellement l'extension ?

Au démarrage de GNOME Shell

1. L'extension s'active via enable() dans extension.js
2. Elle crée le KeyboardRGBIndicator qui charge les valeurs depuis GSettings
3. Elle appelle _applyCurrentState() qui :
   • Écrit brightness depuis GSettings
   • Si brightness > 0, écrit les valeurs RGB depuis GSettings

Code actuel (extension/ui.js):

_applyCurrentState() {
    Backend.writeBrightness(this._currentBrightnessLevel);

    if (this._currentBrightnessLevel > 0) {
        Backend.writeRGB(this._currentR, this._currentG, this._currentB, this._currentMasterGain);
    }
}

À l'arrêt du PC

PROBLÈME IDENTIFIÉ : L'extension NE FORCE PAS l'état du clavier avant l'arrêt !

• Quand GNOME Shell se ferme, disable() est appelé
• disable() détruit simplement l'interface, ne touche PAS au matériel
• Les valeurs sysfs restent dans l'état actuel

2. Comportement du noyau Linux (asus-nb-wmi)

Les fichiers sysfs sous /sys/class/leds/asus::kbd_backlight/ sont :

• Éphémères : ils n'existent qu'en RAM, réinitialisés à chaque boot
• État par défaut au boot : Dépend du firmware ASUS et de l'état avant extinction

Observations

-rw-rw-r-- 1 root kbdled 4096  brightness
--w--w---- 1 root kbdled 4096  kbd_rgb_mode

• Permissions OK (groupe kbdled)
• kbd_rgb_mode est write-only : on ne peut pas lire l'état actuel !

3. Comportement au redémarrage

Scénario A : Extinction normale

1. Linux s'éteint
2. Firmware ASUS conserve son dernier état en mémoire volatile
3. Au redémarrage :
   • Si BIOS/UEFI réinitialise le contrôleur RGB → clavier éteint
   • Si BIOS/UEFI préserve l'état → clavier allumé

Scénario B : Extinction brutale ou coupure de courant

1. Contrôleur RGB réinitialisé complètement
2. État par défaut firmware = souvent éteint

Scénario C : Dual-boot avec Windows

1. Windows modifie l'état du clavier RGB via son propre driver
2. Au redémarrage vers Debian :
   • État hardware = celui laissé par Windows
   • Si Windows a éteint le clavier → Debian ne peut pas le lire

4. Pourquoi Windows peut le rallumer ?

Windows utilise probablement :

• WMI (Windows Management Instrumentation) pour communiquer avec le firmware ASUS
• Accès direct au contrôleur RGB via ACPI
• Peut envoyer des commandes d'initialisation au firmware

Linux (asus-nb-wmi) ne fait que :

• Exposer les contrôles via sysfs
• Ne réinitialise PAS le contrôleur au boot

Solutions possibles

✅ Solution A : Forcer l'état au démarrage (RECOMMANDÉ)

Principe : Toujours forcer un état connu au démarrage de l'extension

Implémentation :

_applyCurrentState() {
    // TOUJOURS écrire brightness, même si 0
    Backend.writeBrightness(this._currentBrightnessLevel);

    // TOUJOURS écrire RGB, même si brightness est 0
    // Cela garantit que le contrôleur est dans un état connu
    Backend.writeRGB(this._currentR, this._currentG, this._currentB, this._currentMasterGain);
}

Modification dans backend.js :

export function writeRGB(r, g, b, masterGain = 100) {
    // ...

    // SUPPRIMER cette vérification qui empêche l'écriture si brightness = 0
    // const currentBrightness = readBrightness();
    // if (currentBrightness === 0) {
    //     console.log('Brightness est 0, RGB mémorisé mais non appliqué');
    //     return true;
    // }

    // Toujours écrire RGB même si brightness = 0
    // Cela initialise le contrôleur dans un état connu

    // ... reste du code
}

Avantages :

• Simple à implémenter
• Garantit un état connu au démarrage
• Pas de dépendance système supplémentaire

Inconvénients :

• L'extension doit être activée pour fonctionner
• Délai entre boot et activation de GNOME Shell

❌ Solution B : Service systemd au boot

Principe : Script systemd qui force l'état avant le login

Avantages :

• Indépendant de GNOME Shell
• S'exécute très tôt au boot

Inconvénients :

• Complexe (nécessite root, service systemd)
• Duplique la logique
• Valeurs en dur ou à lire depuis GSettings (complexe)

❌ Solution C : udev rule avec action RUN

Principe : Déclencher un script à la détection du device

Inconvénients :

• Très complexe
• Timing incertain
• Nécessite privilèges root

Recommandation finale

Implémenter la Solution A :

1. Modifier _applyCurrentState() pour toujours écrire RGB
2. Supprimer la vérification if (currentBrightness === 0) dans writeRGB()
3. Ajouter un log explicite au démarrage

Effet attendu :

• Au login GNOME, l'extension force brightness + RGB
• Même si le firmware a réinitialisé le clavier, il sera rallumé
• État cohérent à chaque démarrage

Notes importantes

Comportement actuel problématique

// backend.js ligne 182-186
const currentBrightness = readBrightness();
if (currentBrightness === 0) {
    console.log('Brightness est 0, RGB mémorisé mais non appliqué');
    return true; // ← PROBLÈME : on n'écrit pas RGB si brightness = 0
}

Pourquoi c'est un problème :

• Si au boot le firmware a brightness = 0
• Et que GSettings a aussi brightness-level = 0
• Alors _applyCurrentState() écrit 0 dans brightness
• Mais ne touche pas à kbd_rgb_mode
• Le contrôleur RGB reste dans un état indéfini

Comportement souhaité

// Toujours initialiser le contrôleur RGB, indépendamment de brightness
Backend.writeBrightness(this._currentBrightnessLevel);
Backend.writeRGB(this._currentR, this._currentG, this._currentB, this._currentMasterGain);

Résultat :

• Contrôleur RGB dans un état connu (couleur mémorisée)
• Brightness contrôle uniquement la visibilité
• Au prochain changement de brightness 0 → 1/2/3, la couleur apparaît immédiatement

Vérification après implémentation

Test 1 : Redémarrage normal

# Avant redémarrage
gsettings get org.gnome.shell.extensions.asuskbdrgb brightness-level
# → 2

# Redémarrer le PC

# Après login
cat /sys/class/leds/asus::kbd_backlight/brightness
# Devrait afficher une valeur correspondant au niveau 2

journalctl -f -o cat /usr/bin/gnome-shell | grep -i asus
# Devrait montrer : "RGB mis à (...)" même si brightness = 0

Test 2 : Brightness à 0 au démarrage

# Mettre brightness à 0
gsettings set org.gnome.shell.extensions.asuskbdrgb brightness-level 0

# Redémarrer

# Vérifier que RGB a quand même été écrit
journalctl -b -o cat /usr/bin/gnome-shell | grep "RGB mis à"
# Devrait afficher une ligne même avec brightness = 0

Test 3 : Dual-boot Windows

1. Redémarrer sous Windows
2. Modifier la couleur du clavier via Armoury Crate
3. Éteindre le clavier dans Windows
4. Redémarrer sous Debian
5. Vérifier que l'extension rallume le clavier avec la couleur GSettings

Conclusion

Le problème n'est pas un bug de l'extension, mais une limitation de conception :

• L'extension suppose que le firmware conserve l'état RGB
• En réalité, le firmware ASUS peut réinitialiser le contrôleur
• La solution est de toujours forcer l'état au démarrage, indépendamment de l'état hardware actuel