Files
Romulus21andClaude Opus 5.5 5235db1e01 Add README
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 14:33:01 +01:00

134 lines
5.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 <modèle>` 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://<ip-camera>/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://<ip-home-assistant>:8123
HA_TOKEN=<jeton d'accès longue durée>
# 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 |