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".

{"ok": true, "version": "0.2.0"}

GET /summary

Valori pronti per la dashboard.

{
  "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": false,
    "force_heating_remaining": "0s",
    "inline_heater": false,
    "hot_water_heating": true,
    "configured_modes": "PUMP_MODE_STATE_HEATING",
    "pump_active_state": "PUMP_ACTIVE_STATE_IDLE",
    "outdoor_defrost": false,
    "signature_lights": true,
    "led_pattern": "LED_PATTERN_NORMAL",
    "zones": 1,
    "zone1_setpoint": 19.0,
    "zone1_temperature": 23.0,
    "zone1_mode": "PUMP_MODE_STATE_HEATING",
    "zone1_cooling_setpoint": 22.0,
    "zone2_setpoint": 0.0,
    "zone2_temperature": 0.0,
    "zone2_mode": "PUMP_MODE_STATE_IDLE",
    "zone2_cooling_setpoint": 0.0,
    "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

{"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
`set_heating_setpoint`	5–30	temperatura obiettivo della casa (zona, default 1)
`set_cooling_setpoint`	5–30	temperatura obiettivo del raffrescamento (zona, default 1)
`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

Riscaldamento: come si invia il comando per zona

Il messaggio ZoneTemperatures contiene sempre entrambe le zone:

{"id": "set_heating_setpoint", "value": 21.5, "zone": 1}

zone è opzionale (default 1) e accetta 1 o 2. La zona che non si sta modificando viene rimandata con il suo valore attuale, letto dall'ultimo stato disponibile: inviarla a zero la spegnerebbe. Per questo il bridge tiene in memoria l'ultima lettura, e il comando va costruito con quel contesto.

Il campo kind distingue riscaldamento (1) da raffrescamento (2).

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": "..."}.

3.7 KiB Raw Blame History Unescape Escape