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](#architecture-de-lextension)
2. [Comprendre le code](#comprendre-le-code)
3. [Installation pas à pas](#installation-pas-à-pas)
4. [Personnalisation](#personnalisation)
5. [Dépannage](#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

```javascript
// 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

```javascript
// 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

```javascript
// 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

```javascript
// 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

```bash
# 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) :**

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

**Méthode manuelle :**

```bash
# 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

```bash
# 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](yamlConfig.js#L25-L32) :

```javascript
_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](serviceManager.js#L9) :

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

### Changer l'icône du panel

Éditez [extension.js:40-43](extension.js#L40-L43) :

```javascript
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](stylesheet.css) :

```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

```bash
# 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"

```bash
# 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

```bash
# 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_*`)

```bash
# 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 :

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

---

## Ressources utiles

### Documentation GNOME

- [GNOME Shell Extensions](https://gjs.guide/extensions/)
- [GJS Guide](https://gjs.guide/)
- [GTK4 Documentation](https://docs.gtk.org/gtk4/)
- [Libadwaita Documentation](https://gnome.pages.gitlab.gnome.org/libadwaita/)

### Outils de développement

```bash
# 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**
```javascript
const MyClass = GObject.registerClass(
class MyClass extends ParentClass {
    _init() {
        super._init();
        // Initialisation
    }
});
```

**Pattern 2 : Callbacks (connect)**
```javascript
button.connect('clicked', () => {
    // Action au clic
});
```

**Pattern 3 : Timeout**
```javascript
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 ! 🚀