harbour-aira 0.1.0: client Sailfish per pompa di calore Aira (bridge HTTP + stato e comandi ACS)

2026-10-09 21:00:59 +02:00
commit 15963039ea
27 changed files with 1686 additions and 0 deletions
@@ -0,0 +1,95 @@
+# API del bridge
+
+Servizio: `~/workspace/Carlo/Aira/aira_bridge.py` (Python, solo `pyairahome`).
+Traduce HTTP/1.1 + JSON in gRPC verso il cloud Aira. Tutte le rotte tranne
+`/health` richiedono:
+
+```
+Authorization: Bearer <token>
+```
+
+Token: generato al primo avvio in `~/.hermes/profiles/carlo/aira_bridge.json`.
+
+## GET /health
+
+Nessuna autenticazione: serve a distinguere "server irraggiungibile" da
+"token sbagliato".
+
+```json
+{"ok": true, "version": "0.1.0"}
+```
+
+## GET /summary
+
+Valori pronti per la dashboard.
+
+```json
+{
+  "ok": true,
+  "summary": {
+    "outdoor_temperature": 18.1,
+    "indoor_temperature": 22.5,
+    "dhw_current": 51.0,
+    "dhw_target": 55.0,
+    "operating_status": "OPERATING_STATUS_AUTO",
+    "away_mode": false,
+    "night_mode": false,
+    "manual_mode": false,
+    "force_heating": true,
+    "inline_heater": false,
+    "led_pattern": "LED_PATTERN_NORMAL",
+    "zones": 1,
+    "errors_count": 0,
+    "pump_updated": "2026-10-09 18:52:17.199340"
+  }
+}
+```
+
+## GET /state
+
+Stato completo e grezzo dal cloud (42 campi: curve climatiche per zona,
+versioni firmware, schedulazioni, errori). Per diagnostica.
+
+## GET /commands
+
+Elenco dei comandi ammessi con i loro parametri.
+
+## POST /command
+
+```json
+{"id": "set_hot_water_target", "value": 55}
+```
+
+Risposta: `{"ok": true, "id": "...", "result": {...}}`.
+
+### Comandi ammessi
+
+| id | value | effetto |
+|---|---|---|
+| `ping` | — | verifica che l'impianto risponda |
+| `set_hot_water_target` | 45–60 | temperatura ACS obiettivo |
+| `hot_water_boost_on` / `hot_water_boost_off` | — | boost ACS una tantum |
+| `hot_water_heating_on` / `hot_water_heating_off` | — | riscaldamento ACS |
+| `away_mode_on` / `away_mode_off` | — | modalità assenza |
+| `night_mode_1h` | — | night mode per un'ora |
+| `force_heating_on` / `force_heating_off` | — | riscaldamento forzato |
+| `heating_on` / `heating_off` | — | funzione riscaldamento |
+| `legionella_cycle` | — | ciclo antilegionella |
+
+### Perché una whitelist
+
+La libreria espone ~90 comandi, fra cui `FactoryReset`, `InstallFirmware`,
+`RebootDevice`, `RotateCertificate`, `SetWifiCredentials`. Restano **fuori di
+proposito**: un client mobile non deve poter riformattare l'impianto per un tap
+sbagliato.
+
+## Errori
+
+| stato | significato |
+|---|---|
+| 400 | comando non ammesso, oppure valore fuori intervallo |
+| 401 | token mancante o errato |
+| 404 | rotta sconosciuta |
+| 502 | il bridge non ha potuto parlare con il cloud (dettaglio in `error`) |
+
+Formato: `{"ok": false, "error": "..."}`.