pilot/gnome-pilot-extension/GUIDE_DEBUTANT.md

Guide débutant - Extension Pilot Control pour GNOME

Ce guide explique en détail comment fonctionne l'extension et comment la personnaliser.

📚 Table des matières

1. Architecture de l'extension
2. Comprendre le code
3. Installation pas à pas
4. Personnalisation
5. Dépannage

---

Architecture de l'extension

Vue d'ensemble

Une extension GNOME Shell est composée de plusieurs fichiers JavaScript qui interagissent avec l'environnement GNOME :

Extension Pilot Control
│
├─ extension.js ──────────> Bouton dans le panel GNOME
│                           │
│                           └─> Menu déroulant (Start/Stop/Restart)
│                           └─> Ouvre pilotWindow.js
│
├─ ui/pilotWindow.js ─────> Fenêtre principale
│                           │
│                           ├─> Section Services
│                           ├─> Section Telemetry (avec métriques)
│                           └─> Section Commands
│
├─ yamlConfig.js ─────────> Lecture/Écriture du config.yaml
│
└─ serviceManager.js ─────> Commandes systemctl (start/stop/restart)

Fichiers principaux

Fichier	Rôle	Difficulté
metadata.json	Infos sur l'extension (nom, version, UUID)	⭐ Facile
extension.js	Point d'entrée, crée le bouton panel	⭐⭐ Moyen
yamlConfig.js	Parse et sauvegarde le YAML	⭐⭐⭐ Avancé
serviceManager.js	Contrôle systemd	⭐⭐ Moyen
ui/pilotWindow.js	Interface principale	⭐⭐⭐ Avancé
ui/metricEditDialog.js	Dialogue d'édition métrique	⭐⭐ Moyen
ui/commandEditDialog.js	Dialogue d'édition commandes	⭐⭐ Moyen
prefs.js	Fenêtre de préférences	⭐ Facile

---

Comprendre le code

1. extension.js - Le point d'entrée

// Ce fichier crée le bouton dans le panel GNOME

export default class PilotExtension extends Extension {
    enable() {
        // Appelé quand l'extension est activée
        this._indicator = new PilotIndicator(this);
        Main.panel.addToStatusArea(this.uuid, this._indicator);
    }

    disable() {
        // Appelé quand l'extension est désactivée
        this._indicator.destroy();
    }
}

Concepts clés :

• enable() : Fonction appelée au démarrage de l'extension
• disable() : Fonction appelée à l'arrêt de l'extension
• PilotIndicator : Classe qui crée l'icône + menu dans le panel

2. yamlConfig.js - Parser YAML simple

// Ce fichier lit et écrit le fichier config.yaml

export class YamlConfig {
    load() {
        // 1. Lit le fichier config.yaml
        // 2. Parse le YAML en objet JavaScript
        // 3. Retourne l'objet config
    }

    save(config) {
        // 1. Convertit l'objet JavaScript en YAML
        // 2. Crée une sauvegarde du fichier actuel
        // 3. Écrit le nouveau fichier
    }
}

Fonctions utiles :

• getTelemetryMetrics() : Retourne toutes les métriques
• getCommandsAllowlist() : Retourne la liste des commandes autorisées
• updateTelemetryMetric(name, updates) : Modifie une métrique
• setTelemetryEnabled(enabled) : Active/désactive la télémétrie

3. serviceManager.js - Contrôle systemd

// Ce fichier exécute les commandes systemctl

export class ServiceManager {
    startService() {
        // Exécute: systemctl --user start mqtt_pilot.service
    }

    stopService() {
        // Exécute: systemctl --user stop mqtt_pilot.service
    }

    isServiceActive() {
        // Vérifie si le service est en cours d'exécution
    }
}

Commandes systemctl utilisées :

• systemctl --user start : Démarrer le service
• systemctl --user stop : Arrêter le service
• systemctl --user restart : Redémarrer le service
• systemctl --user is-active : Vérifier le statut

4. ui/pilotWindow.js - Interface graphique

// Fenêtre principale avec GTK4 + libadwaita

export const PilotWindow = GObject.registerClass(
class PilotWindow extends Adw.Window {
    _buildUI() {
        // Construit 3 sections :
        // 1. Service Control
        // 2. Telemetry Metrics
        // 3. Commands
    }

    _loadData() {
        // Charge les données depuis config.yaml
        // Met à jour l'interface
    }

    _saveConfig() {
        // Sauvegarde les modifications
        // Redémarre le service
    }
});

Composants UI utilisés :

• Adw.Window : Fenêtre principale
• Adw.HeaderBar : Barre d'en-tête avec boutons
• Adw.PreferencesGroup : Groupes de préférences
• Adw.ActionRow : Lignes avec titre/sous-titre
• Gtk.Switch : Interrupteur ON/OFF
• Gtk.Button : Boutons

---

Installation pas à pas

Étape 1 : Vérifier les prérequis

# Vérifier que GNOME Shell est installé
gnome-shell --version
# Doit afficher : GNOME Shell 45.x ou supérieur

# Vérifier que le service Pilot existe
systemctl --user status mqtt_pilot.service

Étape 2 : Installer l'extension

Méthode automatique (recommandée) :

cd /home/gilles/app/pilot/gnome-pilot-extension
./install.sh

Méthode manuelle :

# 1. Créer le répertoire
mkdir -p ~/.local/share/gnome-shell/extensions/pilot-control@gnome-shell-extensions

# 2. Copier tous les fichiers
cp -r /home/gilles/app/pilot/gnome-pilot-extension/* \
  ~/.local/share/gnome-shell/extensions/pilot-control@gnome-shell-extensions/

# 3. Vérifier que les fichiers sont bien copiés
ls ~/.local/share/gnome-shell/extensions/pilot-control@gnome-shell-extensions/

Étape 3 : Activer l'extension

# Activer l'extension
gnome-extensions enable pilot-control@gnome-shell-extensions

# Vérifier qu'elle est bien activée
gnome-extensions list --enabled | grep pilot

Étape 4 : Redémarrer GNOME Shell

Sur X11 :

1. Appuyez sur Alt+F2
2. Tapez r
3. Appuyez sur Entrée

Sur Wayland :

1. Déconnectez-vous
2. Reconnectez-vous

Étape 5 : Utiliser l'extension

1. Cherchez l'icône d'ordinateur en haut à droite (dans le panel)
2. Cliquez dessus pour voir le menu
3. Cliquez sur "Open Control Panel" pour ouvrir la fenêtre principale

---

Personnalisation

Modifier le chemin du fichier de configuration

Éditez yamlConfig.js:25-32 :

_findConfigPath() {
    const possiblePaths = [
        '/votre/chemin/personnalisé/config.yaml',  // Ajoutez votre chemin ici
        GLib.build_filenamev([GLib.get_home_dir(), 'app/pilot/pilot-v2/config.yaml']),
        // ... autres chemins
    ];
}

Modifier le nom du service systemd

Éditez serviceManager.js:9 :

constructor() {
    this.serviceName = 'votre_service.service';  // Changez ici
}

Changer l'icône du panel

Éditez extension.js:40-43 :

const icon = new St.Icon({
    icon_name: 'network-server-symbolic',  // Changez l'icône ici
    style_class: 'system-status-icon',
});

Icônes disponibles :

• computer-symbolic
• network-server-symbolic
• preferences-system-symbolic
• system-run-symbolic

Ajouter une nouvelle métrique

1. Ajoutez la métrique dans config.yaml (Pilot V2)
2. L'extension détectera automatiquement la nouvelle métrique
3. Elle apparaîtra dans la section Telemetry

Personnaliser les couleurs

Éditez stylesheet.css :

/* Changer la couleur des warnings */
.warning {
    color: #ff0000;  /* Rouge au lieu d'orange */
}

/* Ajouter des styles personnalisés */
.custom-style {
    background-color: #3584e4;
    color: white;
}

---

Dépannage

L'extension n'apparaît pas dans la liste

# Vérifier que l'extension est bien installée
ls -la ~/.local/share/gnome-shell/extensions/pilot-control@gnome-shell-extensions/

# Vérifier les logs GNOME Shell
journalctl -f -o cat /usr/bin/gnome-shell | grep -i pilot

Solution : Vérifiez que tous les fichiers sont bien copiés, notamment metadata.json.

Erreur "Extension had error"

# Voir les erreurs détaillées
journalctl -f -o cat /usr/bin/gnome-shell

Solutions courantes :

1. Vérifier la syntaxe JavaScript (pas de fautes de frappe)
2. Vérifier que tous les imports sont corrects
3. Redémarrer GNOME Shell

Le service ne démarre pas

# Vérifier que le service existe
systemctl --user list-units | grep mqtt_pilot

# Vérifier les erreurs du service
systemctl --user status mqtt_pilot.service
journalctl --user -u mqtt_pilot.service -n 50

Solution : Assurez-vous que le service mqtt_pilot.service est bien configuré en tant que service utilisateur.

Les modifications ne sont pas sauvegardées

1. Vérifiez les permissions du fichier config.yaml
2. Vérifiez les logs pour voir les erreurs de sauvegarde
3. Vérifiez qu'une sauvegarde a été créée (config.yaml.backup_*)

# Vérifier les permissions
ls -la ~/app/pilot/pilot-v2/config.yaml

# Vérifier les sauvegardes
ls -la ~/app/pilot/pilot-v2/config.yaml.backup_*

L'interface ne se met pas à jour

1. Cliquez sur le bouton "Refresh" (icône refresh dans le header)
2. Fermez et rouvrez la fenêtre de contrôle
3. Redémarrez l'extension :

gnome-extensions disable pilot-control@gnome-shell-extensions
gnome-extensions enable pilot-control@gnome-shell-extensions

---

Ressources utiles

Documentation GNOME

• GNOME Shell Extensions
• GJS Guide
• GTK4 Documentation
• Libadwaita Documentation

Outils de développement

# Looking Glass (debugger GNOME Shell)
# Alt+F2, tapez 'lg'

# Recharger l'extension rapidement
gnome-extensions disable pilot-control@gnome-shell-extensions && \
gnome-extensions enable pilot-control@gnome-shell-extensions

# Voir les logs en temps réel
journalctl -f -o cat /usr/bin/gnome-shell

Exemples de code

L'extension utilise plusieurs patterns courants :

Pattern 1 : GObject.registerClass

const MyClass = GObject.registerClass(
class MyClass extends ParentClass {
    _init() {
        super._init();
        // Initialisation
    }
});

Pattern 2 : Callbacks (connect)

button.connect('clicked', () => {
    // Action au clic
});

Pattern 3 : Timeout

GLib.timeout_add(GLib.PRIORITY_DEFAULT, 500, () => {
    // Exécuté après 500ms
    return GLib.SOURCE_REMOVE;  // Ne pas répéter
});

---

Conclusion

Cette extension est conçue pour être simple et facilement modifiable. N'hésitez pas à :

1. Expérimenter : Modifier les fichiers et tester
2. Consulter les logs : Utiliser journalctl pour comprendre les erreurs
3. Lire le code : Tous les fichiers sont commentés pour faciliter la compréhension

Pour toute question, consultez d'abord ce guide, puis les logs GNOME Shell.

Bon développement ! 🚀