shelly_pool/CLAUDE.md

Shelly Pool — Automatisation de la pompe de piscine

Vue d'ensemble

Script JavaScript (pool.js) tournant sur un Shelly Pro 1PM (Gen2) pour piloter automatiquement la pompe de filtration d'une piscine en fonction de la température de l'eau.

Contrainte principale : résilience

Le Shelly fonctionne de manière totalement autonome. Home Assistant n'intervient pas dans la logique de contrôle — c'est uniquement un frontend de visualisation.

Si le capteur, Zigbee2MQTT, le broker MQTT ou le réseau tombent, le Shelly continue à filtrer selon le dernier planning calculé. Ce planning est matérialisé par des schedules natifs Shelly (Schedule.Create) qui persistent dans le firmware et s'exécutent même sans script actif ni réseau.

La conception doit toujours respecter ce principe :

• Pas de dépendance à Home Assistant pour le fonctionnement
• Toute mise à jour du planning est un effet de bord d'une nouvelle mesure de température — le planning précédent reste actif en cas de silence
• Les données critiques (temp_today, temp_yesterday) sont persistées dans le KVS du Shelly pour survivre à un redémarrage

Architecture

Sonde Zigbee (immergée)
        │
        ▼
Zigbee2MQTT ──► MQTT broker ──► Shelly Pro 1PM ──► Pompe
                                      │
                               Home Assistant (frontend)

• Capteur : sonde Zigbee waterproof immergée, publie sur zigbee2mqtt/Piscine
• Shelly Pro 1PM : exécute pool.js en natif (ShellyScript), contrôle la pompe via le relais
• Input 0 : interrupteur physique raccordé à l'entrée du Shelly (déclenche un toggle event)
• MQTT : broker géré par Zigbee2MQTT / Home Assistant

Logique principale (pool.js)

Calcul de la durée de filtration

Table de correspondance température → durée (filt_time) avec interpolation linéaire :

Temp (°C)	Durée (h)
≤ 5	2
10	4
12	6
16	8
24	12
27	20
≥ 30	24

Calcul du planning

Une seule plage de filtration centrée sur 17h00 :

• start = 17 - duration/2
• stop = 17 + duration/2

Les horaires sont convertis en crontab Shelly (Schedule.Create) après suppression de tous les schedules existants (Schedule.DeleteAll).

Température de référence

La durée de filtration est calculée sur temp_max = max(temp_today, temp_yesterday) pour éviter de sous-filtrer le lendemain d'une journée chaude.

Les maxima journaliers sont persistés dans le KVS (Key-Value Store) du Shelly :

• pool.temp_today
• pool.temp_yesterday

Comportement au démarrage

1. Restauration de temp_yesterday et temp_today depuis le KVS
2. Si temp_today est disponible, appel immédiat de update_temp() pour recalculer le planning

Verrouillage manuel

Quand l'interrupteur physique (input0) génère un événement toggle, les mises à jour automatiques sont désactivées pendant 10 minutes pour ne pas contrecarrer une action manuelle.

TODOs

• Force ON si duration == 24 : quand il fait très chaud, mettre la pompe en marche continue sans schedule
• Mode antigel si temp < 1°C : protection contre le gel (marche continue ou intermittente)

Fichiers

Fichier	Rôle
pool.js	Script principal (déployé sur le Shelly)
shelly.conf	Config locale (gitignored) — host, script ID, port UDP
shelly.conf.example	Modèle de configuration
upload_script	Envoie pool.js sur le Shelly via put_script
put_script	Script Python (Allterco) — upload par chunks de 1024 octets
exec_script	Stop + Start du script sur le Shelly
restart_script	Redémarre le script s'il n'est pas en cours d'exécution
eval_script	Évalue du JS arbitraire sur le Shelly (debug)
inspect_script	Affiche status du script + état système Shelly
shelly_log	Écoute les messages UDP de debug du Shelly (port 6901)
follow_log	Tail du log filtré sur les lignes [POOL] et script
fake_mqtt_pool	Simule une mesure de température via mosquitto_pub
kvs_list	Liste toutes les clés KVS du Shelly
kvs_set	Positionne une clé KVS
kvs_delete	Supprime une clé KVS
reboot	Redémarre le Shelly

Workflow de développement

# 1. Modifier pool.js
# 2. Déployer
./upload_script

# 3. Redémarrer le script
./exec_script

# 4. Observer les logs (dans un autre terminal)
./shelly_log          # écoute UDP
./follow_log          # filtre les lignes pertinentes

# 5. Simuler une température pour tester
./fake_mqtt_pool 24.5

# 6. Inspecter l'état interne
./inspect_script

Branches Git

• dev : branche active, code en production sur le Shelly
• main / prod : non maintenues à jour

Configuration (shelly.conf)

Copier shelly.conf.example vers shelly.conf et adapter :

• SHELLY_HOST : hostname ou IP du Shelly (ex: shelly_pool ou 192.168.1.x)
• SCRIPT_ID : ID du script sur le Shelly (défaut: 1)
• UDP_LOG_PORT : port UDP configuré sur le Shelly pour les logs (défaut: 6901)

Le fichier shelly.conf est gitignored.