diff --git a/README.md b/README.md new file mode 100644 index 0000000..d7855cf --- /dev/null +++ b/README.md @@ -0,0 +1,133 @@ +# watermeter_watcher + +Lit l'index d'un compteur d'eau à partir de la photo d'une caméra, puis met à jour +l'index dans Home Assistant. + +La caméra fournit une image du compteur sur laquelle des rectangles bleus entourent les +rouleaux de chiffres à lire. Le programme télécharge cette image, la recadre autour des +rectangles, fait lire les chiffres par un modèle de vision, puis envoie +`lecture × 100` (en litres) à une entité `input_number` de Home Assistant. + +## Fonctionnement + +1. **Téléchargement** de l'image depuis `WATERMETER_URL`. +2. **Détection des rectangles bleus.** S'il n'y en a aucun, nouvel essai 30 s plus tard. +3. **Recadrage** autour des rectangles et agrandissement ×3. +4. **Lecture des chiffres** avec le backend choisi (voir plus bas). +5. **Contrôle de la longueur** : si `WATERMETER_DIGITS` est défini et que la lecture n'a + pas ce nombre de chiffres, nouvel essai 30 s plus tard. +6. **Mise à jour de Home Assistant** si la lecture est complète (aucun `?`) : + - lecture de l'état actuel de l'entité ; + - si `lecture × 100` est à plus de 1000 de l'état actuel (dans un sens ou dans + l'autre), rien n'est modifié : la lecture est considérée comme fausse ; + - sinon, appel de `input_number.set_value`. +7. **Journal** : une ligne ajoutée à `watermeter.log`. + +Le programme abandonne après 10 essais (environ 5 minutes). + +## Backends de lecture + +| Option | Backend | Variables | +|-------------|---------------------------------------------|--------------------------------------------| +| *(aucune)* | Claude (API Anthropic) | `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL` | +| `--mistral` | Mistral (API Mistral) | `MISTRAL_API_KEY`, `MISTRAL_MODEL` | +| `--ollama` | Modèle local via Ollama, `lfm3-vl` par défaut | `OLLAMA_HOST`, `OLLAMA_MODEL` | +| `--ocrs` | OCR local avec [ocrs](https://github.com/robertknight/ocrs) | `OCRS_MODELS_DIR` | + +Pour Ollama, le modèle doit gérer les images (`ollama show ` doit afficher +`vision`) : + +```sh +ollama pull lfm3-vl +``` + +Pour `--ocrs`, il faut d'abord télécharger le modèle de reconnaissance : + +```sh +./download-models.sh +``` + +## Configuration + +Toute la configuration passe par un fichier `.env` dans le dossier depuis lequel le +programme est lancé. Les valeurs du `.env` remplacent celles de l'environnement. + +```sh +# Obligatoire +WATERMETER_URL=http:///img_tmp/alg_roi.jpg + +# Nombre de chiffres attendus (recommandé : rejette les lectures incomplètes) +WATERMETER_DIGITS=4 + +# Home Assistant (sans ces deux variables, l'index n'est pas mis à jour) +HA_URL=http://:8123 +HA_TOKEN= +# HA_ENTITY=input_number.index_compteur_d_eau + +# Selon le backend utilisé +ANTHROPIC_API_KEY=... +MISTRAL_API_KEY=... +# OLLAMA_HOST=http://localhost:11434 +# OLLAMA_MODEL=lfm3-vl + +# Emplacement du journal (par défaut : watermeter.log) +# WATERMETER_LOG=watermeter.log +``` + +Le jeton Home Assistant se crée dans **Profil → Sécurité → Jetons d'accès longue +durée**. Le `max` de l'entité `input_number` doit être assez grand pour contenir +l'index en litres. + +## Utilisation + +```sh +cargo build --release +./target/release/watermeter_watcher --ollama +``` + +L'option `--debug` enregistre les images intermédiaires dans `debug/` (`crop.png` +pour les modèles de vision, une image par rectangle et `full.png` pour `--ocrs`). + +### Codes de sortie + +| Code | Signification | +|------|------------------------------------------------| +| 0 | Lecture complète | +| 1 | Erreur (réseau, API, aucune lecture valide…) | +| 2 | Lecture avec au moins un chiffre illisible (`?`) | + +### Journal + +Chaque lancement ajoute une ligne à `watermeter.log` : + +``` +2026-11-15 14:12:02 [ok] --ollama | reading 6013 | input_number.index_compteur_d_eau already at 601300 +``` + +Le statut entre crochets vaut `ok`, `incomplete` ou `error`. + +## Lancement automatique avec cron + +Le programme lit `.env` dans le dossier courant : il faut donc se placer dans le +dossier du projet avant de le lancer. Exemple pour 7 h et 19 h (`crontab -e`) : + +``` +0 7,19 * * * cd /chemin/vers/watermeter_watcher && ./target/release/watermeter_watcher --ollama >/dev/null 2>&1 +``` + +Après une modification du code, relancer `cargo build --release`. + +## Structure du code + +| Fichier | Rôle | +|------------------------|----------------------------------------------------------| +| `src/main.rs` | Boucle d'essais, choix du backend, mise à jour HA | +| `src/fetch.rs` | Téléchargement de l'image | +| `src/boxes.rs` | Détection des rectangles bleus | +| `src/vision.rs` | Prompt, schéma de réponse et recadrage communs aux LLM | +| `src/claude.rs` | Backend Claude | +| `src/mistral.rs` | Backend Mistral | +| `src/ollama.rs` | Backend Ollama | +| `src/ocr.rs` | Backend ocrs | +| `src/homeassistant.rs` | Lecture et mise à jour de l'entité Home Assistant | +| `src/runlog.rs` | Journal des lancements |