corrige temperature
This commit is contained in:
433
gnome-pilot-extension/GUIDE_DEBUTANT.md
Normal file
433
gnome-pilot-extension/GUIDE_DEBUTANT.md
Normal file
@@ -0,0 +1,433 @@
|
||||
# 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 ! 🚀
|
||||
Reference in New Issue
Block a user