From a48ec86822de29836718452e15c22b63f24aae19 Mon Sep 17 00:00:00 2001 From: Carlo Baratto Date: Sat, 10 Oct 2026 09:15:48 +0200 Subject: [PATCH] documentazione 0.5.0: PROTOCOL (/stats, campi dispositivo), PIANO, conteggi dei test --- bridge/requirements.txt | 2 +- docs/PIANO.md | 24 +- docs/PROTOCOL.md | 73 +++++- translations/harbour-aira-it.ts | 407 ++++++++++++++++---------------- 4 files changed, 291 insertions(+), 215 deletions(-) diff --git a/bridge/requirements.txt b/bridge/requirements.txt index 4183078..7a730fd 100644 --- a/bridge/requirements.txt +++ b/bridge/requirements.txt @@ -1,4 +1,4 @@ # Dipendenze del bridge. La libreria parla gRPC con il cloud Aira e porta con # se' il resto (grpcio, protobuf, pycognito, boto3, bleak...). -# Versione fissata: e' quella su cui il bridge e' stato provato (27/27). +# Versione fissata: e' quella su cui il bridge e' stato provato (48/48). pyairahome==2.3.0 diff --git a/docs/PIANO.md b/docs/PIANO.md index 7bf5239..d31b3aa 100644 --- a/docs/PIANO.md +++ b/docs/PIANO.md @@ -211,17 +211,23 @@ andrebbe disegnata a mano. 2. **Dati**: "Il tuo riscaldamento (questo mese)" con calore prodotto, elettricità usata, efficienza (COP riscaldamento / acqua calda); "I tuoi risparmi" con il risparmio totale del periodo, la CO₂ evitata e il risparmio Smart Tariff Control. -3. **Impianto**: stato (connessione, modalità, vacanza, messaggi luminosi, ultima - lettura), accessori (termostato: zona, temperatura, umidità, segnale, batteria), - versioni (piattaforma, connettività, controllo climatico, unità esterna, EEPROM, - dispositivo ID) ed errori. +3. **Impianto**: stato (connessione, modalità, assenza, notte, riscaldamento forzato, + resistenza interna, temperature, zone, ultima lettura), accessori (termostato: zona, + temperatura, umidità, segnale, batteria, articolo), versioni (ID dispositivo, + piattaforma, connettività, controllo climatico, unità esterna, EEPROM) ed errori. + Le luci di firma (`signature_lights`, `led_pattern`) restano per ora solo in + `/summary`: la pagina non le mostra. ### Lavoro - **Bridge 0.4.0**: nuova rotta `/stats` (COP, risparmi, ottimizzazione, insight) e - blocco `device` in `/summary` (id breve, versioni, termostato, connessione); - cache breve lato bridge, perché sono chiamate al cloud più lente di `/state`. -- **App 0.5.0**: `MainPage` riordinata, nuove `DataPage.qml` e `InfoPage.qml`, - nuove stringhe nei due cataloghi, anteprime rigenerate, test del nucleo estesi al - parsing dei nuovi campi, versione e README aggiornati. + campi del dispositivo in `/summary` (`device_*`, `version_*`, `thermostat_*`, + `connected_via`, `timezone`); cache di 10 minuti lato bridge, perché sono quattro + chiamate al cloud, più lente di `/state`. +- **App 0.5.0**: `MainPage` riordinata, nuove `DataPage.qml` e `PlantPage.qml` + (quest'ultima si è chiamata `InfoPage` nella prima stesura del piano), nuovo + componente `ValueRow.qml`, 86 stringhe nuove tradotte (170 in totale), anteprime + rigenerate (dati, impianto) in italiano e inglese, test del nucleo estesi al + parsing delle statistiche e alla formattazione di importi e mesi (61/61), versione, + README e `docs/PROTOCOL.md` aggiornati. - Nessun comando nuovo all'impianto: tutto questo è **sola lettura**. diff --git a/docs/PROTOCOL.md b/docs/PROTOCOL.md index 44c9017..93140ff 100644 --- a/docs/PROTOCOL.md +++ b/docs/PROTOCOL.md @@ -16,7 +16,7 @@ Nessuna autenticazione: serve a distinguere "server irraggiungibile" da "token sbagliato". ```json -{"ok": true, "version": "0.2.0"} +{"ok": true, "version": "0.4.0"} ``` ## GET /summary @@ -54,11 +54,80 @@ Valori pronti per la dashboard. "zone2_mode": "PUMP_MODE_STATE_IDLE", "zone2_cooling_setpoint": 0.0, "errors_count": 0, - "pump_updated": "2026-10-09 18:52:17.199340" + "pump_updated": "2026-10-09 18:52:17.199340", + + "device_id": "1f4b26", + "device_uuid": "1f4b26c4-1800-4b21-8ea2-236925a92aeb", + "version_platform": "6.10.0", + "version_connectivity": "3.30.1", + "version_climate_control": "3.9.12", + "version_outdoor_unit": "1.30.0", + "version_outdoor_eeprom": "0.114.0", + "connected_via": "Cloud", + "timezone": "Europe/Rome", + "thermostats_count": 1, + "thermostat_zone": 1, + "thermostat_article": "201884", + "thermostat_temperature": 22.8, + "thermostat_humidity": 73.3, + "thermostat_rssi": -79, + "thermostat_battery_low": false } } ``` +Il blocco del dispositivo serve alle pagine "Impianto" e "Accessori" dell'app: +`device_id` sono le prime 6 cifre dell'UUID (come le mostra l'app ufficiale), +`connected_via` è la via di connessione, le `version_*` sono le versioni del +software e i campi `thermostat_*` descrivono il termostato a parete (assenti se +l'impianto non ne ha: in quel caso `thermostats_count` è 0 e gli altri sono +`null`). Il termostato manda i decimali come interi (228 = 22,8 °C): la +conversione la fa il bridge, non l'app. + +## GET /stats + +I numeri che Aira calcola nel cloud: sono gli stessi della scheda "Dati" +dell'app ufficiale (verificati sullo stesso periodo). Il bridge li tiene in +cache per **10 minuti** (`ttl`), perché sono quattro chiamate e cambiano +lentamente. + +```json +{ + "ok": true, + "stats": { + "period_days": 30, + "currency": "EUR", + "month": { + "label": "2026-10", + "heat_kwh": 70.8, + "energy_kwh": 29.3, + "cop_heating": null, + "cop_dhw": 4.42 + }, + "cop_monthly": [ + {"month": "2026-09", "heating_cop": null, "dhw_cop": 4.42, "avg_outdoor": 21.8} + ], + "insights": [ + {"date": "2026-10-01", "energy_kwh": 29.3, "heat_kwh": 70.8} + ], + "savings": {"amount": 21.78, "co2_kg": 38.1, "show": true, "points": 31}, + "smart_tariff": {"amount": 2.71, "hours": 180}, + "monthly_savings": [{"month": "2026-09", "amount": 3.52}] + } +} +``` + +- `month`: l'ultimo periodo con dati — calore prodotto (`heat_kwh`), elettricità + usata (`energy_kwh`) ed efficienza (COP) di acqua calda e riscaldamento. + **`null` significa "nessun dato"**: su un impianto recente il riscaldamento può + non averne ancora (mentre l'acqua calda sì). `label` è il mese `AAAA-MM`. +- `cop_monthly` e `monthly_savings`: le serie mese per mese, per il dettaglio. +- `savings`: risparmio in bolletta sugli ultimi `period_days` giorni (30), CO₂ + evitata e numero di punti usati dal calcolo; `show` è il permesso di Aira a + mostrare il dato. +- `smart_tariff`: il risparmio del mese mobile dovuto allo Smart Tariff Control. +- Questa rotta è di **sola lettura**: non invia nessun comando all'impianto. + ## GET /state Stato completo e grezzo dal cloud (42 campi: curve climatiche per zona, diff --git a/translations/harbour-aira-it.ts b/translations/harbour-aira-it.ts index 031d6a7..d8df8a6 100644 --- a/translations/harbour-aira-it.ts +++ b/translations/harbour-aira-it.ts @@ -1,64 +1,65 @@ - + + AiraJson - + Automatic Automatico - - + + Heating Riscaldamento - - + + Cooling Raffrescamento - - + + Hot water Acqua calda - - + + Standby Stand-by - - + + Off Spento - + Idle In attesa - + Stopped Ferma - + Running In funzione - + server unreachable server non raggiungibile - + HTTP error %1 errore HTTP %1 @@ -66,66 +67,66 @@ ApiClient - + Bridge address not configured Indirizzo del bridge non configurato - - - + + + Set the bridge address and token Configura indirizzo e token del bridge - + Server unreachable (timeout) Server non raggiungibile (timeout) - - + + Unreadable response from the bridge Risposta del bridge non interpretabile - + Enter the bridge address - Inserisci l'indirizzo del bridge + Inserisci l'indirizzo del bridge - + Timeout: no response Timeout: nessuna risposta - + Unreachable (HTTP %1) Irraggiungibile (HTTP %1) - + Bridge reachable Bridge raggiungibile - - + + Bridge not configured Bridge non configurato - + Timeout: no statistics Timeout: statistiche non disponibili - + Timeout: command not sent Timeout: comando non inviato - + Command sent Comando inviato @@ -133,171 +134,171 @@ CommandsPage - + yes sì - + no no - + Other commands Altri comandi - + Current state Stato attuale - - + + Away mode Assenza - + Night mode Night mode - + Forced heating Riscaldamento forzato - + Hot water active Acqua calda attiva - + Pump Pompa - + Allowed modes Modalità consentite - + Turn away mode on Attiva assenza - + Turn away mode off Disattiva assenza - + Noise Rumore - + Night mode for one hour - Night mode per un'ora + Night mode per un'ora - + Heating Riscaldamento - + Force heating Forza riscaldamento - + Starting forced heating Avvio del riscaldamento forzato - + Stop forced heating Ferma riscaldamento forzato - + Enable heating function Abilita funzione riscaldamento - + Disable heating function Disabilita funzione riscaldamento - + Heating will be disabled Il riscaldamento verrà disabilitato - + Domestic hot water Acqua calda sanitaria - + Legionella cycle Ciclo antilegionella - + Starting the legionella cycle: it takes a while Avvio del ciclo antilegionella: richiede tempo - + Enable DHW heating Abilita riscaldamento ACS - + Disable DHW heating Disabilita riscaldamento ACS - + Domestic hot water will stop being heated - L'acqua calda smetterà di essere riscaldata + L'acqua calda smetterà di essere riscaldata - + Diagnostics Diagnostica - + Plant check Verifica impianto - + Commands go through the bridge and may take a few seconds. The status refreshes by itself afterwards. - I comandi passano dal bridge e possono richiedere qualche secondo. Dopo l'invio lo stato si aggiorna da solo. + I comandi passano dal bridge e possono richiedere qualche secondo. Dopo l'invio lo stato si aggiorna da solo. CoverPage - + house · target %1 °C casa · obiettivo %1 °C - + DHW %1 °C · target %2 °C ACS %1 °C · obiettivo %2 °C - + outdoor %1 °C est. %1 °C @@ -305,127 +306,127 @@ DataPage - + no data nessun dato - + Refresh Aggiorna - + Plant Impianto - + Settings Impostazioni - + Data Dati - + Numbers calculated by Aira in the cloud: the app only reads them from your own bridge. - Numeri calcolati da Aira nel cloud: l'app li legge soltanto dal tuo bridge. + Numeri calcolati da Aira nel cloud: l'app li legge soltanto dal tuo bridge. - + Reading the data... Lettura dei dati in corso... - + Month of %1 Mese di %1 - + This month Questo mese - + Heat produced Calore prodotto - + What the heat pump gave the house Quanto la pompa ha dato alla casa - + Electricity used Elettricità usata - + What the heat pump took from the grid Quanta ne ha presa dalla rete - + Efficiency, domestic hot water Efficienza, acqua calda - + Efficiency, heating Efficienza, riscaldamento - + Efficiency (COP) is how much heat the pump delivers for each unit of electricity: higher is better. - L'efficienza (COP) è quanto calore la pompa produce per ogni unità di elettricità: più alta è, meglio è. + L'efficienza (COP) è quanto calore la pompa produce per ogni unità di elettricità: più alta è, meglio è. - + Your savings, last %1 days I tuoi risparmi, ultimi %1 giorni - + Saved on the bill Risparmiati in bolletta - + Compared with a gas boiler Rispetto a una caldaia a gas - + CO₂ avoided CO₂ evitata - + Not released into the air - Non immessa nell'aria + Non immessa nell'aria - + Smart Tariff Control Smart Tariff Control - + Saving from heating when energy is cheaper - Risparmio scaldando quando l'energia costa meno + Risparmio scaldando quando l'energia costa meno - + Efficiency month by month Efficienza mese per mese - + Savings month by month Risparmi mese per mese @@ -441,135 +442,135 @@ no - + Refresh Aggiorna - - + + Settings Impostazioni - - + + Other commands Altri comandi - + Attention: one error on the plant - Attenzione: un errore sull'impianto + Attenzione: un errore sull'impianto - + Attention: %1 errors on the plant - Attenzione: %1 errori sull'impianto + Attenzione: %1 errori sull'impianto - + Away mode: the house is saving energy. Modalità assenza: la casa sta risparmiando. - + Night mode is on. Modalità notte attiva. - + Boost: the house is heating at full power. Boost: la casa sta scaldando a pieno regime. - + The heat pump is heating the hot water. - La pompa di calore sta scaldando l'acqua calda. + La pompa di calore sta scaldando l'acqua calda. - + The heat pump is working. La pompa di calore sta lavorando. - + Relax: the heat pump is running smoothly. Relax: la pompa di calore funziona regolarmente. - + %1 · last reading %2 %1 · ultima lettura %2 - + Data Dati - + Bridge not configured. Open the settings and enter the server address and the token. - Bridge non configurato. Apri le impostazioni e inserisci l'indirizzo del server e il token. + Bridge non configurato. Apri le impostazioni e inserisci l'indirizzo del server e il token. - + Outside %1 °C Esterno %1 °C - + Away Assente - + At home In casa - + Aira heat pump Aira Pompa di calore - + Connected through the cloud Connessa tramite Cloud - + Room temperature Temperatura stanza - - + + Target %1 °C Obiettivo %1 °C - + Heating the house Riscaldamento della casa - + Heating setpoint %1 °C · %2 Obiettivo riscaldamento %1 °C · %2 - + Details Dettagli - + Plant and accessories Impianto e accessori - + Consumption and savings Consumi e risparmi @@ -582,23 +583,23 @@ obiettivo %1 °C · %2 - + New house target Nuovo obiettivo casa - + Set house to %1 °C Imposta casa a %1 °C - + House temperature to %1 °C Temperatura della casa a %1 °C - - + + Domestic hot water Acqua calda sanitaria @@ -607,42 +608,42 @@ Obiettivo acqua calda - + New target Nuovo obiettivo - + Set target %1 °C Imposta obiettivo %1 °C - + DHW target to %1 °C Obiettivo ACS a %1 °C - + Start DHW boost Avvia boost ACS - + Starting DHW boost Avvio del boost ACS - + Stop DHW boost Ferma boost ACS - + Stopping DHW boost Arresto del boost ACS - + Plant Impianto @@ -687,200 +688,200 @@ Aggiornato alle - + Commands are sent to the bridge and from there to the plant: they may take a few seconds. - I comandi vengono inviati al bridge e da lì all'impianto: possono richiedere qualche secondo. + I comandi vengono inviati al bridge e da lì all'impianto: possono richiedere qualche secondo. PlantPage - + yes sì - + no no - + Refresh Aggiorna - + Data Dati - + Settings Impostazioni - + Plant Impianto - + Status Stato - + Connection Connessione - + Mode Modalità - + Away mode Modalità assenza - + Night mode Modalità notte - + Forced heating Riscaldamento forzato - + Inline heater Resistenza interna - + Outdoor temperature Temperatura esterna - + Indoor temperature (pump) Temperatura interna (pompa) - + Zones Zone - + Last reading Ultima lettura - + Accessories Accessori - + No wall thermostat Nessun termostato a parete - + Aira wall thermostat Termostato a parete Aira - + Zone %1 · Connected Zona %1 · Connesso - + Measured temperature Temperatura misurata - + Humidity Umidità - + Signal Segnale - + Battery Batteria - + low scarica - + ok ok - + Article Articolo - + Versions Versioni - + Device ID ID dispositivo - + Platform Piattaforma - + Connectivity Connettività - + Climate control Controllo climatico - + Outdoor unit Unità esterna - + Outdoor unit EEPROM EEPROM unità esterna - + Errors Errori - + No errors reported by the plant. - Nessun errore segnalato dall'impianto. + Nessun errore segnalato dall'impianto. - + Errors reported Errori segnalati @@ -888,66 +889,66 @@ SettingsPage - + checking… verifico… - + Settings Impostazioni - - + + Language Lingua - - + + System Sistema - + Changing the language reloads the app. - Cambiando la lingua l'app si ricarica. + Cambiando la lingua l'app si ricarica. - + Bridge Bridge - + Bridge address Indirizzo del bridge - + Bridge token Token del bridge - + Address and token live on the server: the token is in aira_bridge.json next to the bridge. Without a scheme, http:// is used. Indirizzo e token si leggono sul server: il token è in aira_bridge.json accanto al bridge. Senza schema viene usato http://. - + Save Salva - + settings saved impostazioni salvate - + Test connection Prova connessione - \ No newline at end of file +