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