From 3e7ae7550b88f67c2a14aba31a3140055d200c04 Mon Sep 17 00:00:00 2001
From: Pierre Gironde <pierre@pgironde.fr>
Date: Sat, 26 Sep 2026 11:44:52 +0200
Subject: [PATCH] add some doc

---
 vscode-appdaemon/README.md | 96 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 vscode-appdaemon/README.md

diff --git a/vscode-appdaemon/README.md b/vscode-appdaemon/README.md
new file mode 100644
index 0000000..23237fc
--- /dev/null
+++ b/vscode-appdaemon/README.md
@@ -0,0 +1,96 @@
+# Extension VS Code AppDaemon
+
+Extension VS Code pour développer et administrer les applications AppDaemon
+utilisées avec Home Assistant.
+
+Version documentée : `0.1.0`
+
+## Installation
+
+1. Ouvrir **Extensions** dans VS Code (`Ctrl+Shift+X` / `Cmd+Shift+X`).
+2. Cliquer sur `...`, puis **Install from VSIX...**.
+3. Sélectionner `vscode-appdaemon-0.1.0.vsix` dans ce dossier.
+4. Recharger VS Code si nécessaire.
+
+## Configuration
+
+Les réglages sont disponibles dans **Paramètres → Extensions → AppDaemon**, ou
+dans `.vscode/settings.json` :
+
+```json
+{
+  "appdaemon.haUrl": "http://homeassistant:8123",
+  "appdaemon.haToken": "<TOKEN_HOME_ASSISTANT>",
+  "appdaemon.adUrl": "http://localhost:5050",
+  "appdaemon.errorLogPath": "logs/error.log",
+  "appdaemon.mainLogPath": "logs/appdaemon.log",
+  "appdaemon.entityRefreshInterval": 300
+}
+```
+
+| Réglage | Défaut | Description |
+| --- | --- | --- |
+| `appdaemon.haUrl` | `http://localhost:8123` | URL de Home Assistant |
+| `appdaemon.haToken` | vide | Jeton longue durée Home Assistant |
+| `appdaemon.adUrl` | `http://localhost:5050` | URL de l’API HTTP AppDaemon |
+| `appdaemon.errorLogPath` | `logs/error.log` | Journal d’erreurs, relatif au workspace |
+| `appdaemon.mainLogPath` | `logs/appdaemon.log` | Journal principal, relatif au workspace |
+| `appdaemon.entityRefreshInterval` | `300` | Rafraîchissement des entités, en secondes |
+
+Ne pas versionner le jeton Home Assistant. Utiliser de préférence les réglages
+utilisateur ou un fichier local ignoré par Git.
+
+## Raccourcis clavier
+
+| Action | Windows / Linux | macOS |
+| --- | --- | --- |
+| Aller à une application AppDaemon | `Ctrl+Shift+A` | `Cmd+Shift+A` |
+| Aller à un capteur virtuel | `Ctrl+Shift+V` | `Cmd+Shift+V` |
+
+Chaque raccourci ouvre une palette permettant de rechercher puis sélectionner
+l’application ou le capteur souhaité.
+
+Pour modifier un raccourci, ouvrir les raccourcis clavier (`Ctrl+K Ctrl+S`),
+rechercher `AppDaemon`, puis modifier la commande voulue.
+
+## Commandes disponibles
+
+Toutes les commandes sont accessibles avec la palette (`Ctrl+Shift+P` / `Cmd+Shift+P`)
+en recherchant `AppDaemon:`.
+
+- **Go to App** : ouvrir la définition d’une application AppDaemon.
+- **Restart Apps in Current File** : redémarrer les apps du fichier YAML actif.
+- **Reload Apps** : recharger toutes les applications AppDaemon.
+- **Restart Home Assistant** : redémarrer Home Assistant ou l’hôte, après confirmation.
+- **Toggle Production Mode** : activer ou désactiver le mode production.
+- **Show Error Log** : afficher le journal d’erreurs.
+- **Refresh Entity List** : recharger les entités Home Assistant.
+- **Handle Errors** : afficher les erreurs et choisir de les consulter ou de les effacer.
+- **Clear Error Diagnostics** : effacer les diagnostics d’erreur de VS Code.
+
+## Barre d’état
+
+La barre d’état propose des boutons pour recharger AppDaemon, redémarrer Home
+Assistant, basculer le mode production, consulter les erreurs et redémarrer les
+apps trouvées dans le fichier YAML actif.
+
+Quand des erreurs sont détectées, `AD Errors` affiche leur nombre et permet de
+consulter le journal ou d’effacer les diagnostics.
+
+## Fonctionnalités d’aide au développement
+
+Dans les fichiers YAML et Python, l’extension fournit notamment :
+
+- la complétion des entités Home Assistant ;
+- les informations au survol des entités ;
+- la navigation vers les définitions de capteurs virtuels ;
+- les symboles et la navigation vers les applications AppDaemon ;
+- la remontée des erreurs présentes dans le journal AppDaemon.
+
+## Dépannage rapide
+
+- **Aucune entité proposée** : vérifier `haUrl`, le jeton et l’accès réseau, puis lancer `AppDaemon: Refresh Entity List`.
+- **Les commandes AppDaemon échouent** : vérifier que l’API HTTP est active et que `appdaemon.adUrl` correspond à la section `http` de `appdaemon.yaml`.
+- **Les erreurs ne remontent pas** : vérifier `appdaemon.errorLogPath`, relatif à la racine ouverte dans VS Code.
+- **Un raccourci ne fonctionne pas** : rechercher la commande dans les raccourcis VS Code et vérifier les conflits.
+