308 lines
13 KiB
Markdown
308 lines
13 KiB
Markdown
# Structure de l'extension Pilot Control
|
|
|
|
## Arborescence des fichiers
|
|
|
|
```
|
|
gnome-pilot-extension/
|
|
│
|
|
├── metadata.json # Métadonnées de l'extension (UUID, version, etc.)
|
|
├── extension.js # Point d'entrée principal (bouton panel + menu)
|
|
├── prefs.js # Fenêtre de préférences (optionnel V1)
|
|
├── yamlConfig.js # Module de lecture/écriture YAML
|
|
├── serviceManager.js # Gestion du service systemd
|
|
├── stylesheet.css # Styles CSS personnalisés
|
|
│
|
|
├── ui/ # Composants d'interface utilisateur
|
|
│ ├── pilotWindow.js # Fenêtre principale (3 sections)
|
|
│ ├── metricEditDialog.js # Dialogue d'édition des métriques
|
|
│ └── commandEditDialog.js # Dialogue d'édition des commandes
|
|
│
|
|
├── schemas/ # GSettings schema (optionnel, vide pour V1)
|
|
│
|
|
├── install.sh # Script d'installation automatique
|
|
├── README.md # Documentation complète
|
|
├── GUIDE_DEBUTANT.md # Guide pour débutants
|
|
└── STRUCTURE.md # Ce fichier (vue d'ensemble)
|
|
```
|
|
|
|
## Diagramme de flux
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ GNOME Shell Panel │
|
|
│ │
|
|
│ [Icon] Pilot Control ▼ │
|
|
│ ├─ Status: 🟢 Running │
|
|
│ ├─ Start Service │
|
|
│ ├─ Stop Service │
|
|
│ ├─ Restart Service │
|
|
│ ├─ Open Control Panel ──────────┐ │
|
|
│ └─ Reload Config │ │
|
|
└──────────────────────────────────────────┼──────────────────┘
|
|
│
|
|
▼
|
|
┌──────────────────────────────────────────────────────────────┐
|
|
│ Pilot Control Panel │
|
|
│ ┌────────────────────────────────────────────────────────┐ │
|
|
│ │ [Refresh] [Save] │ │
|
|
│ └────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─ Service Control ──────────────────────────────────────┐ │
|
|
│ │ Service Status [Switch ON/OFF] │ │
|
|
│ │ Auto-start Service [Switch ON/OFF] │ │
|
|
│ │ Restart Service [Button: Restart] │ │
|
|
│ └─────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─ Telemetry Metrics ────────────────────────────────────┐ │
|
|
│ │ Enable Telemetry [Switch ON/OFF] │ │
|
|
│ │ │ │
|
|
│ │ CPU Usage [Switch] [Edit...] │ │
|
|
│ │ Memory Usage [Switch] [Edit...] │ │
|
|
│ │ Battery [Switch] [Edit...] │ │
|
|
│ │ Temperature [Switch] [Edit...] │ │
|
|
│ │ IP Address [Switch] [Edit...] │ │
|
|
│ └─────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─ Commands ─────────────────────────────────────────────┐ │
|
|
│ │ Enable Commands [Switch ON/OFF] │ │
|
|
│ │ Allowed Commands [Edit...] │ │
|
|
│ │ → shutdown, reboot, sleep, hibernate, screen │ │
|
|
│ └─────────────────────────────────────────────────────────┘ │
|
|
└──────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Flux de données
|
|
|
|
```
|
|
┌──────────────┐
|
|
│ User │
|
|
│ Action │
|
|
└──────┬───────┘
|
|
│
|
|
▼
|
|
┌──────────────────────────────────────────┐
|
|
│ extension.js │
|
|
│ (PilotIndicator: Panel Button + Menu) │
|
|
└──────┬───────────────────────────────────┘
|
|
│
|
|
├─────────────────────┐
|
|
│ │
|
|
▼ ▼
|
|
┌──────────────┐ ┌──────────────┐
|
|
│ Service │ │ ui/ │
|
|
│ Manager │ │ pilotWindow │
|
|
└──────┬───────┘ └──────┬───────┘
|
|
│ │
|
|
│ ▼
|
|
│ ┌──────────────┐
|
|
│ │ yamlConfig │
|
|
│ │ (Parser) │
|
|
│ └──────┬───────┘
|
|
│ │
|
|
▼ ▼
|
|
┌──────────────┐ ┌──────────────┐
|
|
│ systemctl │ │ config.yaml │
|
|
│ commands │ │ (Pilot V2) │
|
|
└──────────────┘ └──────────────┘
|
|
│ │
|
|
└─────────┬───────────┘
|
|
│
|
|
▼
|
|
┌──────────────┐
|
|
│ mqtt_pilot │
|
|
│ .service │
|
|
│ (Pilot V2) │
|
|
└──────────────┘
|
|
```
|
|
|
|
## Interactions entre modules
|
|
|
|
### 1. extension.js → serviceManager.js
|
|
```javascript
|
|
// Contrôle du service systemd
|
|
serviceManager.startService()
|
|
serviceManager.stopService()
|
|
serviceManager.restartService()
|
|
serviceManager.isServiceActive()
|
|
```
|
|
|
|
### 2. extension.js → ui/pilotWindow.js
|
|
```javascript
|
|
// Ouvre la fenêtre principale
|
|
new PilotWindow(extension, yamlConfig, serviceManager)
|
|
window.show()
|
|
```
|
|
|
|
### 3. ui/pilotWindow.js → yamlConfig.js
|
|
```javascript
|
|
// Lecture de la config
|
|
yamlConfig.load()
|
|
yamlConfig.getTelemetryMetrics()
|
|
yamlConfig.getCommandsAllowlist()
|
|
|
|
// Modification de la config
|
|
yamlConfig.updateTelemetryMetric(name, updates)
|
|
yamlConfig.setTelemetryEnabled(enabled)
|
|
yamlConfig.updateCommandsAllowlist(newList)
|
|
|
|
// Sauvegarde
|
|
yamlConfig.save()
|
|
```
|
|
|
|
### 4. ui/pilotWindow.js → ui/metricEditDialog.js
|
|
```javascript
|
|
// Édition d'une métrique
|
|
const dialog = new MetricEditDialog(parent, metricName, config)
|
|
dialog.connect('response', (dlg, responseId) => {
|
|
const updates = dialog.getUpdates()
|
|
// Appliquer les modifications
|
|
})
|
|
```
|
|
|
|
### 5. ui/pilotWindow.js → ui/commandEditDialog.js
|
|
```javascript
|
|
// Édition de la allowlist
|
|
const dialog = new CommandEditDialog(parent, currentAllowlist)
|
|
dialog.connect('response', (dlg, responseId) => {
|
|
const newAllowlist = dialog.getAllowlist()
|
|
// Appliquer les modifications
|
|
})
|
|
```
|
|
|
|
## Cycle de vie de l'extension
|
|
|
|
```
|
|
1. GNOME Shell démarre
|
|
↓
|
|
2. Extension activée (enable())
|
|
↓
|
|
3. PilotIndicator créé
|
|
↓
|
|
4. Icône ajoutée au panel
|
|
↓
|
|
5. Menu construit
|
|
↓
|
|
6. Config chargée (yamlConfig.load())
|
|
↓
|
|
7. Status du service vérifié
|
|
↓
|
|
8. Extension prête
|
|
|
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
|
|
User clique sur "Open Control Panel"
|
|
↓
|
|
PilotWindow créée
|
|
↓
|
|
Sections construites (Service, Telemetry, Commands)
|
|
↓
|
|
Données chargées depuis config.yaml
|
|
↓
|
|
Interface affichée
|
|
|
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
|
|
User modifie un paramètre
|
|
↓
|
|
Config marquée comme "dirty"
|
|
↓
|
|
User clique "Save"
|
|
↓
|
|
Backup créé (config.yaml.backup_timestamp)
|
|
↓
|
|
Nouveau config.yaml écrit
|
|
↓
|
|
Service redémarré (systemctl restart)
|
|
↓
|
|
Interface mise à jour
|
|
|
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
|
|
Extension désactivée (disable())
|
|
↓
|
|
Fenêtre détruite
|
|
↓
|
|
Indicateur supprimé du panel
|
|
↓
|
|
Extension arrêtée
|
|
```
|
|
|
|
## Technologies utilisées
|
|
|
|
| Technologie | Version | Usage |
|
|
|-------------|---------|-------|
|
|
| **GJS** | - | JavaScript runtime pour GNOME |
|
|
| **GTK4** | 4.x | Toolkit d'interface graphique |
|
|
| **Libadwaita** | 1.x | Composants UI modernes GNOME |
|
|
| **GLib** | 2.x | Utilitaires système (fichiers, processus) |
|
|
| **Gio** | 2.x | I/O (lecture/écriture fichiers) |
|
|
| **GNOME Shell** | 45+ | Environnement de bureau |
|
|
|
|
## Dépendances externes
|
|
|
|
L'extension **n'a pas** de dépendances externes npm/node. Tout est fourni par :
|
|
|
|
- GNOME Shell
|
|
- GJS (inclus avec GNOME)
|
|
- GTK4 et Libadwaita (librairies système)
|
|
|
|
## Permissions requises
|
|
|
|
L'extension nécessite :
|
|
|
|
1. **Accès fichiers** :
|
|
- Lecture : `~/app/pilot/pilot-v2/config.yaml`
|
|
- Écriture : `~/app/pilot/pilot-v2/config.yaml`
|
|
- Création de backups : `~/app/pilot/pilot-v2/config.yaml.backup_*`
|
|
|
|
2. **Commandes systemctl** :
|
|
- `systemctl --user start mqtt_pilot.service`
|
|
- `systemctl --user stop mqtt_pilot.service`
|
|
- `systemctl --user restart mqtt_pilot.service`
|
|
- `systemctl --user status mqtt_pilot.service`
|
|
- `systemctl --user is-active mqtt_pilot.service`
|
|
- `systemctl --user enable mqtt_pilot.service`
|
|
- `systemctl --user disable mqtt_pilot.service`
|
|
|
|
3. **Logs** :
|
|
- `journalctl --user -u mqtt_pilot.service`
|
|
|
|
## Sécurité
|
|
|
|
### Ce que l'extension PEUT faire :
|
|
- ✅ Lire et modifier le fichier config.yaml de l'utilisateur
|
|
- ✅ Contrôler le service systemd de l'utilisateur (--user)
|
|
- ✅ Créer des sauvegardes des fichiers de configuration
|
|
|
|
### Ce que l'extension NE PEUT PAS faire :
|
|
- ❌ Accéder aux services système (nécessite sudo)
|
|
- ❌ Modifier des fichiers en dehors du home directory
|
|
- ❌ Exécuter des commandes arbitraires non validées
|
|
- ❌ Accéder au réseau (pas d'API MQTT directe)
|
|
|
|
## Limites de V1
|
|
|
|
1. **Parser YAML simple** : Ne gère que la structure de config.yaml de Pilot V2
|
|
2. **Pas de validation avancée** : Entrées utilisateur validées basiquement
|
|
3. **Rechargement par redémarrage** : Nécessite un restart du service (pas de reload à chaud)
|
|
4. **Une seule instance** : Gère uniquement un service Pilot à la fois
|
|
5. **Pas de logs temps réel** : Pas d'affichage des logs dans l'interface
|
|
|
|
## Extensions futures possibles
|
|
|
|
- Support de plusieurs instances de Pilot
|
|
- Visualisation des logs en temps réel
|
|
- Notifications pour événements importants
|
|
- Graphiques de métriques (historique)
|
|
- Export/import de configurations
|
|
- Validation avancée des entrées (regex, ranges)
|
|
- Thèmes sombres/clairs personnalisés
|
|
- Support de configurations complexes (YAML avancé)
|
|
|
|
## Ressources
|
|
|
|
- [Documentation GNOME Extensions](https://gjs.guide/extensions/)
|
|
- [GTK4 Documentation](https://docs.gtk.org/gtk4/)
|
|
- [Libadwaita Documentation](https://gnome.pages.gitlab.gnome.org/libadwaita/)
|
|
- [GJS Examples](https://gitlab.gnome.org/GNOME/gjs/-/tree/master/examples)
|