Home Assistant: architettura, modello dati e operatività

Home Assistant è una piattaforma centrale di controllo e automazione per dispositivi, reti radio, servizi IP e interfacce utente. L’istanza raccoglie gli stati tramite integrazioni, li normalizza in entità, distribuisce le modifiche tramite un Event Bus ed esegue azioni di conseguenza. In questo contesto, «locale» indica una preferenza architetturale, non una caratteristica generalizzata di ogni integrazione: una lampadina Zigbee può essere raggiungibile interamente in locale, mentre un’integrazione del produttore può ottenere i propri stati esclusivamente da un’API cloud. La panoramica dell’architettura ufficiale separa sistema operativo, Supervisor e Core; l’architettura delle integrazioni descrive l’estensione del Core tramite componenti Python.

Per gli amministratori, Home Assistant non è quindi né soltanto una dashboard né un convertitore universale di protocolli. È un orchestratore con stato e molteplici possibili punti di guasto: runtime Python, integrazioni, registri, database, autenticazione, reti locali, controller radio, broker, cloud dei produttori e, se presenti, app del Supervisor. Un’interfaccia verde dimostra solo che il percorso del frontend funziona. Non dimostra che gli eventi arrivino in tempo, che i dispositivi siano raggiungibili, che le automazioni vengano eseguite in modo deterministico o che un backup, incluse le dipendenze esterne, sia ripristinabile.

La spiegazione segue un evento di dispositivo attraverso integrazione, Event Bus e State Machine fino ad automazione e azione. Successivamente inquadra persistenza, add-on, sicurezza, monitoraggio e ripristino.

Approccio architetturale: nodo centrale di eventi e stati

Home Assistant Core è basato sugli eventi. Quattro componenti documentati costituiscono il nucleo (Core architecture):

1. L’Event Bus distribuisce gli eventi ai listener registrati.
2. La State Machine mantiene l’ultimo stato noto di ogni entità caricata e pubblica state_changed.
3. Il Service Registry gestisce le azioni invocabili ed elabora le chiamate di servizio.
4. Il Timer genera eventi temporali per l’elaborazione dipendente dal tempo.

Le integrazioni traducono gli stati di dispositivi o servizi in questo modello. Un’integrazione può eseguire polling, ricevere eventi push, usare librerie locali o interrogare un’API remota. Home Assistant uniforma lo stato risultante, non il trasporto. Questo è il confine operativo più importante: due entità dello stesso tipo di dominio, ad esempio light, possono avere percorsi di latenza, autenticazione e ripristino completamente diversi.

Livelli di runtime e modelli di installazione

Home Assistant offre due modelli di installazione supportati. Home Assistant OS è un’appliance gestita. Home Assistant Container esegue Home Assistant Core come container su un host di responsabilità dell’operatore. Il confronto ufficiale indica HAOS come raccomandazione per quasi tutte le installazioni e descrive Container come installazione Core autonoma senza app del Supervisor (HAOS o Container).

Home Assistant OS

HAOS è creato con Buildroot ed è composto da Linux, GNU C Library, systemd e Docker. SquashFS ospita le aree di sistema in sola lettura, ZRAM i file system temporanei e lo swap, AppArmor limita i processi e RAUC aggiorna il sistema operativo (Home Assistant Operating System). Al di sopra, il Supervisor gestisce Core, app, DNS, audio, mDNS, backup e aggiornamenti (Supervisor).

Il modello appliance riduce le varianti, ma attribuisce al Supervisor una responsabilità molto ampia. Un errore può trovarsi ad almeno cinque livelli: slot di boot/OS, Docker Engine, Supervisor, container Core o singola app. Il Supervisor può eseguire il rollback di un percorso di aggiornamento Core non riuscito; non riconosce automaticamente un comportamento funzionalmente errato del dispositivo o del database.

Home Assistant Container

Container fornisce solo il Core. Sistema operativo host, container engine, rete, volumi, database, broker, server radio, reverse proxy, backup e aggiornamenti sono di responsabilità dell’operatore. Le app del Supervisor sono servizi pacchettizzati separatamente. In un’architettura Container, Mosquitto, Matter Server, Zigbee2MQTT, Z-Wave JS UI, PostgreSQL o un reverse proxy vengono eseguiti come workload distinti con propri volumi, versioni e health check.

Il vantaggio è un’architettura di piattaforma esplicita; il prezzo è una superficie operativa maggiore. Un backup del volume Core, per esempio, non contiene né il database Recorder esterno né lo stato del broker, la NVM radio o le chiavi del reverse proxy, se questi risiedono all’esterno.

Forme di installazione storiche

La precedente installazione Core in un ambiente Python e l’installazione Supervised su Linux autogestito sono state dismesse nel 2025. Dalla release 2025.12 sono considerate non supportate; le architetture a 32 bit i386, armhf e armv7 hanno contemporaneamente perso il percorso di release. L’annuncio del progetto indica HAOS e Container come modelli rimanenti (disattivazione di Core e Supervised). Un nome storico di installazione non deve quindi essere confuso con il componente software Home Assistant Core, che continua a essere eseguito anche all’interno di HAOS e Container.

Stack tecnologico

Home Assistant Core è un’applicazione Python con licenza Apache-2.0. Il repository Core ufficiale mostra Python, asyncio e la struttura modulare delle integrazioni. Le integrazioni a elevato I/O non devono bloccare: le regole di qualità privilegiano dipendenze asincrone affinché chiamate di rete e dispositivi non blocchino l’Event Loop condiviso (async dependency). Il codice di libreria bloccante viene spostato in thread Executor; il lavoro a elevato impiego di CPU o mal limitato rimane comunque un rischio per capacità e latenza.

Lo stack visibile comprende più di Python:

La Integration Quality Scale valuta le integrazioni in base a flusso di configurazione, test, tipizzazione, diagnostica, uso efficiente dei dati e comportamento asincrono. Un livello elevato migliora la manutenibilità attesa, ma non costituisce uno SLA di disponibilità per il dispositivo o il fornitore cloud sottostante.

Dopo modello di installazione e runtime segue il modello dati. Solo distinguendo Config Entry, dispositivo, entità e stato è possibile spiegare chiaramente entità duplicate, dispositivi mancanti e automazioni errate.

Modello a oggetti: Config Entry, dispositivo, entità e stato

La chiave dell’inventario operativo non è il riquadro visibile, bensì la catena composta da configurazione, identità del dispositivo ed entità.

Config Entries

Un Config Entry memorizza la configurazione persistente di un’istanza di integrazione. Un flusso di configurazione dell’interfaccia lo crea; opzioni, riconfigurazione, reload, unload, rimozione e migrazione sono operazioni del ciclo di vita definite. Le integrazioni non devono modificare direttamente i dati dell’entry, ma devono usare il Config Entry Manager (Config entries). Un errore di autenticazione, un entry non caricato e una controparte non raggiungibile sono quindi stati diversi.

Dispositivi e registri

Il Device Registry raggruppa endpoint tecnici in dispositivi. Identificatori o connessioni, per esempio numero di serie e indirizzo MAC, servono per il matching; via_device può rappresentare una relazione di bridge o genitore (Device registry). Un sensore Zigbee può quindi apparire come dispositivo connesso tramite un coordinator, senza che il coordinator costituisca il suo stato applicativo.

L’Entity Registry attribuisce alle entità un’identità permanente con unique_id e impedisce collisioni tra Entity ID. Indirizzo IP, hostname, URL, nome utente o indirizzo e-mail non sono espressamente considerati Unique ID stabili (Entity registry). Ciò spiega perché rinominare manualmente un host non può sostituire l’identità del dispositivo e perché le migrazioni delle integrazioni richiedono identificatori stabili del produttore.

Entità e stato

Un’entità rappresenta una funzione o una grandezza di misura: sensor, switch, light, climate, binary_sensor oppure un altro dominio. Il suo stato consiste in uno State primario, attributi, orari di modifica e Context. La State Machine conserva soltanto l’ultimo stato noto. unavailable significa che l’entità non è attualmente alimentata da un oggetto Entity attivo; unknown significa che non è disponibile alcun valore utilizzabile. L’«ultimo valore» non equivale quindi automaticamente a una «misurazione recente».

L’interazione documentata tra dispositivi e servizi separa Entity Integration, Entity Component, Entity Platform e integrazione specifica del produttore. Per la diagnosi, si pone quindi sempre la domanda:

• Quale Config Entry possiede l’entità?
• Tramite quale integrazione e piattaforma viene creata?
• Quale ID stabile di dispositivo e di entità collega cronologia e configurazione?
• Viene eseguito polling o push?
• Quale modello di tempo e disponibilità possiede il valore sorgente?
• Quale bridge, libreria, API cloud o collegamento radio si trova a monte?

Integrazioni e isolamento dei guasti

Un’integrazione definisce un dominio e può fornire piattaforme quali sensor, light o switch. La piattaforma astrae il tipo di entità; l’integrazione del dispositivo comunica con il protocollo concreto. Le integrazioni integrate sono distribuite con il Core e testate dal relativo processo di release. Le Custom Integrations, tuttavia, vengono eseguite nello stesso processo Python e possono influire su import, Event Loop, tempo di avvio o consumo di memoria. La directory /config/custom_components è quindi parte di inventario, change management e ripristino.

La panoramica delle integrazioni ufficiale distingue, tra l’altro, classi IoT quali Local Push, Local Polling, Cloud Push e Cloud Polling. Questa classificazione è più utile per i modelli operativi rispetto a un lungo elenco di produttori:

L’integrazione non è un isolatore di processo. Una corretta delimitazione del guasto disabilita o ricarica selettivamente il Config Entry interessato prima di riavviare l’intero Core. Un riavvio distrugge evidenze volatili e può ripristinare timer di automazione dipendenti dal tempo.

Modello di protocollo e rete

Per Home Assistant, un grafo delle dipendenze è più utile di una tabella OSI generalizzata. La piattaforma si trova a livello applicativo, ma i relativi percorsi dati si diramano:

• Frontend, REST e WebSocket usano HTTP su TCP, in genere sulla porta 8123.
• DNS risolve host e servizi cloud; mDNS e SSDP rilevano dispositivi nella rete locale.
• MQTT utilizza un broker separato e un modello publish/subscribe tramite TCP o WebSocket.
• Zigbee, Z-Wave, Thread e Bluetooth richiedono controller radio o proxy di rete.
• Matter utilizza comunicazione IP, ma per provisioning e funzionamento Fabric richiede un Matter Server e, se necessario, un Thread Border Router.
• Le integrazioni dei produttori possono usare HTTPS, protocolli locali proprietari o stream cloud.

Le integrazioni Discovery integrate documentano mDNS/Zeroconf e SSDP. Entrambi dipendono dal segmento e dal multicast. Un reverse proxy per il frontend non ripara la Discovery oltre i confini VLAN. Multicast relay, IGMP snooping, isolamento dei client WLAN, IPv6 RA, suffissi DNS e regole firewall devono essere verificati per ogni percorso effettivo del dispositivo.

MQTT come spazio di stato separato

MQTT non è l’Event Bus interno. È un servizio broker esterno con il quale comunica un’integrazione. L’integrazione MQTT ufficiale descrive Discovery Topics, retained messages, Birth/Last Will, Availability, TLS e MQTT 5. La Discovery retained può ricreare dispositivi dopo un riavvio, ma può anche conservare Ghost Entities obsolete. La disponibilità richiede una semantica propria; la presenza di uno State retained non dimostra che il publisher sia ancora attivo.

Un funzionamento MQTT affidabile inventaria broker, Client ID, autenticazione, CA, topic, QoS, Retain, Expiry, Birth/Will e origine Discovery. Il backup del broker e quello del Core sono oggetti di protezione separati.

Percorsi radio e bridge

ZHA integra un coordinator Zigbee, Z-Wave JS usa un server Z-Wave JS separato e Matter collega un Matter Server. Thread gestisce riferimenti a Border Router e reti, ma non è identico a Matter. Dispositivi radio, firmware dei controller, dati di rete, materiale crittografico e configurazione dei dispositivi formano ciascuno un insieme di ripristino. Spostare una chiavetta USB o sostituire un coordinator non è una normale modifica dell’indirizzo IP.

Le integrazioni forniscono stati ed eventi; le automazioni reagiscono a essi. Il loro flusso, da trigger, condizioni e azioni, deve pertanto essere diagnosticato separatamente dalla configurazione dei dispositivi.

Runtime delle automazioni: trigger, condition, action

Un’automazione è una definizione di esecuzione reattiva. I fondamenti delle automazioni separano trigger, Conditions opzionali e Actions. Il trigger crea un’esecuzione, le Conditions verificano lo stato di ingresso e le Actions usano la semantica sequenziale degli Scripts (Actions).

È importante il momento: State, attributi e valori dei template possono cambiare tra il trigger e un’Action successiva. Un Delay non mantiene aperta una transazione. Esecuzioni multiple della stessa automazione richiedono quindi una modalità come Single, Restart, Queued o Parallel e un modello di conflitto consapevole. Gli attuatori fisici sono raramente transazionali; un’esecuzione parzialmente completata può richiedere azioni compensative.

La documentazione sui trigger segnala che i tempi di attesa for non sopravvivono a un riavvio o a un reload dell’automazione. Chi deve preservare una scadenza oltre i riavvii persiste un orario, per esempio in input_datetime, e attiva rispetto a esso. Le Conditions sono solo verifiche nell’esecuzione corrente; la semantica delle Conditions non le trasforma in un blocco contro modifiche parallele.

In Home Assistant i template vengono valutati con espressioni Jinja. Errori di input e di tipo, unknown, unavailable, fusi orari e conversione implicita delle stringhe devono far parte dei test. La documentazione sul templating descrive variabili dipendenti dai trigger. Un amministratore non testa soltanto l’happy path, ma anche riavvio, entità mancante, evento ritardato, trigger duplicato ed errore dell’attuatore.

Configurazione, registri e source of truth

Home Assistant combina Config Entries guidati dall’interfaccia, dati dei registri e YAML. configuration.yaml è la radice della configurazione manuale, ma non è la source of truth completa. La panoramica della configurazione ufficiale distingue UI e YAML; i Packages possono strutturare blocchi YAML correlati (Packages).

Per Git e review è adatta soltanto la parte testuale priva di segreti. secrets.yaml separa i valori dallo YAML, ma non li cifra; la guida all’hardening lo evidenzia espressamente. Stato UI, registri, token e Config Entries risiedono nell’archivio di configurazione e vengono modificati attraverso percorsi UI/API supportati. La modifica diretta dei file Storage interni mentre il Core è in esecuzione aggira la logica di schema, ciclo di vita e coerenza.

Un inventario di configurazione comprende:

• YAML, Packages, Blueprints e Custom Components,
• Config Entries con origine, owner e autenticazione,
• assegnazioni Device, Entity e Area,
• automazioni, Scripts, scene e dashboard,
• utenti, token, MFA e Identity Provider esterni,
• app del Supervisor o servizi esterni,
• controller radio, broker, database e proxy,
• Secrets, certificati e chiavi di ripristino.

Recorder, cronologia e statistiche a lungo termine

La State Machine mantiene lo stato attuale in memoria. La cronologia nasce soltanto tramite il Recorder. Esso scrive modifiche di stato ed eventi selezionati in un database tramite SQLAlchemy; History, Activity, grafici e statistiche a lungo termine leggono da lì. La documentazione Recorder ufficiale indica SQLite come impostazione predefinita e raccomandazione, nonché MariaDB, MySQL e PostgreSQL come alternative supportate.

I dati Recorder non sono una sorgente di eventi per il controllo in tempo reale. Un database non disponibile può compromettere cronologia e statistiche mentre gli stati correnti e le automazioni continuano parzialmente a funzionare. Viceversa, una cronologia completa non dimostra che un’Action sul dispositivo fisico sia riuscita.

I parametri operativi più importanti sono:

• purge_keep_days per la cronologia grezza,
• filtri Include/Exclude per entità ed eventi,
• commit_interval come rapporto tra I/O e finestra di perdita,
• dimensione del database, spazio libero e latenza di scrittura,
• Purge e Repack,
• sequenza di avvio e raggiungibilità dei database esterni,
• statistiche a lungo termine e coerenza dei metadati.

Un cambio del database Recorder non migra la cronologia esistente in modo supportato. I database esterni richiedono backup coerenti e test di ripristino propri. Per SQLite, la documentazione richiede spazio libero pari ad almeno 2,5 volte la dimensione del database per il trattamento della corruzione. Storage e Recorder sono quindi un percorso separato di capacità e ripristino, non soltanto una cache opzionale.

API, WebSocket e autenticazione

Frontend e API condividono per impostazione predefinita lo stesso listener HTTP. La REST API usa JSON e Bearer Tokens; il percorso base è /api/. La WebSocket API si trova in /api/websocket, passa attraverso auth_required, auth e auth_ok e correla i comandi tramite ID numerici. WebSocket fornisce flussi di eventi e registri in modo più efficiente rispetto al polling REST ripetuto.

I token a lunga durata sono credenziali utente. L’Authentication API descrive OAuth/IndieAuth, Refresh Tokens, Long-Lived Access Tokens e Signed Paths di breve durata. Un token eredita il contesto del proprio utente; un Long-Lived Token valido dieci anni appartiene a un archivio di Secrets, non a YAML, Shell History, URL o JavaScript della dashboard.

Un monitor API verifica almeno autenticazione, /api/config, entità attese, last_updated, sottoscrizione WebSocket e un percorso Read/Action non pericoloso. Un HTTP 200 su / verifica soltanto la raggiungibilità del frontend.

$headers = @{ Authorization = "Bearer $env:HA_TOKEN" }
Invoke-RestMethod -Headers $headers -Uri "https://ha.example.net/api/config"
Invoke-RestMethod -Headers $headers -Uri "https://ha.example.net/api/states/sensor.uptime" |
  ConvertTo-Json -Depth 8

curl --fail --silent --show-error \
  -H "Authorization: Bearer $HA_TOKEN" \
  https://ha.example.net/api/config | jq .
curl --fail --silent --show-error \
  -H "Authorization: Bearer $HA_TOKEN" \
  https://ha.example.net/api/states/sensor.uptime | jq .

Invoke-RestMethod e ConvertTo-Json elaborano la query Windows; curl e jq fanno lo stesso su Unix. Il token è mostrato solo come variabile d’ambiente del processo; in produzione proviene da un archivio di Secrets controllato.

HTTP, TLS e reverse proxy

L’endpoint HTTP ascolta per impostazione predefinita su TCP 8123. TLS diretto, reverse proxy e Home Assistant Cloud sono modelli di accesso diversi. Con un reverse proxy tradizionale, use_x_forwarded_for e trusted_proxies devono essere configurati correttamente; altrimenti l’IP del client è errato o la richiesta viene rifiutata (HTTP integration). Un elenco ampio di proxy attendibili consente la falsificazione delle informazioni Forwarded-For.

La guida alla sicurezza raccomanda password univoche, MFA, privilegi amministrativi minimi e accesso remoto protetto anziché esposizione diretta a Internet. TLS protegge solo il trasporto. Diritti dei token, header del proxy, upgrade WebSocket, rate limit, DNS, rinnovo dei certificati e sicurezza dell’IdP a monte restano controlli separati.

Resolve-DnsName ha.example.net
Test-NetConnection ha.example.net -Port 443
curl.exe -sS -D - -o NUL https://ha.example.net/api/
Get-NetTCPConnection -State Established | Where-Object RemotePort -eq 443

dig +short ha.example.net A ha.example.net AAAA
curl -sS -D - -o /dev/null https://ha.example.net/api/
ss -ntp state established '( dport = :443 )'
openssl s_client -connect ha.example.net:443 -servername ha.example.net -brief

Resolve-DnsName, Test-NetConnection e Get-NetTCPConnection verificano Windows; dig, ss e openssl s_client verificano Unix. La chiamata non autenticata a /api/ può restituire 401; sono determinanti risoluzione dei nomi, identità TLS, percorso proxy e limite di autenticazione atteso.

Diagnostica MQTT

Lo stato del broker viene verificato al di fuori di Home Assistant. Un subscriber osserva Discovery, Availability e State senza modificare i topic. Un test di Publish usa un percorso di test riservato appositamente; i Command Topics produttivi non vengono descritti incidentalmente.

mosquitto_sub.exe -h mqtt.example.net -p 8883 --cafile .\ca.pem `
  -u ha-observer -P $env:MQTT_PASSWORD -v -t "homeassistant/#"
mosquitto_pub.exe -h mqtt.example.net -p 8883 --cafile .\ca.pem `
  -u ha-probe -P $env:MQTT_PASSWORD -t "ops/probe" -m "online" -q 1

mosquitto_sub -h mqtt.example.net -p 8883 --cafile ./ca.pem \
  -u ha-observer -P "$MQTT_PASSWORD" -v -t 'homeassistant/#'
mosquitto_pub -h mqtt.example.net -p 8883 --cafile ./ca.pem \
  -u ha-probe -P "$MQTT_PASSWORD" -t 'ops/probe' -m 'online' -q 1

mosquitto_sub e mosquitto_pub sono i client ufficiali del broker. Le password sulla riga di comando possono essere visibili negli elenchi dei processi o nella cronologia; gli esempi illustrano il percorso, mentre in produzione la chiamata usa un file password, l’archivio di Secrets del sistema operativo o credenziali di breve durata.

Funzionamento di HAOS e Container

HAOS mette a disposizione il comando ha tramite accesso Terminal/SSH. Le installazioni Container vengono gestite con gli strumenti del runtime scelto. Un pacchetto diagnostico mantiene insieme informazioni di sistema, log Core, diagnostica dell’integrazione, stato del container, spazio libero e orario.

docker inspect homeassistant | ConvertFrom-Json
docker logs --since 30m --timestamps homeassistant 2>&1 |
  Select-String -Pattern 'ERROR|WARNING|unavailable|timeout'
docker stats --no-stream homeassistant

docker inspect homeassistant | jq '.[0].State, .[0].Mounts, .[0].NetworkSettings.Networks'
docker logs --since 30m --timestamps homeassistant 2>&1 | grep -E 'ERROR|WARNING|unavailable|timeout'
docker stats --no-stream homeassistant
df -h /path/to/config && du -sh /path/to/config

docker inspect, docker logs e docker stats forniscono lo stato del container. ConvertFrom-Json e Select-String elaborano gli output Windows; grep, df e du integrano Unix. Un container in esecuzione è soltanto il primo controllo; seguono percorsi di integrazione, registry, eventi e dispositivi.

Per la ricerca guasti, il percorso del segnale viene letto a ritroso: azione, Automation Trace, modifica di stato, integrazione, protocollo di rete e dispositivo fisico.

Observability e diagnostica sistematica

System Health raccoglie tipo di installazione, architettura, informazioni su Python, Core e frontend e offre funzioni diagnostiche tramite Impostazioni > Sistema > Riparazioni (System Health). L’integrazione Logger controlla i livelli di log globali e specifici dei componenti. Il debug logging è limitato temporalmente e ai namespace interessati; tempeste radio o di eventi possono altrimenti dominare memoria e I/O.

Una catena diagnostica affidabile è la seguente:

1. Sintomo e stato atteso: quale entità, Action, automazione o interfaccia è interessata?
2. Tempo e scope: da quando, per quali dispositivi, utenti, reti e istanze di integrazione?
3. Identità dell’oggetto: assicurare Config Entry, Device ID, Entity ID, Unique ID e riferimento al bridge.
4. Runtime: verificare Core, Event Loop, memoria, CPU, file system e database.
5. Integrazione: verificare stato dell’Entry, autenticazione, stato Coordinator/Polling e download diagnostico.
6. Trasporto: verificare Discovery, DNS, TCP, TLS, broker, controller radio o API del produttore.
7. Automazione: verificare Trace, dati del trigger, Conditions, Run Mode e risultato dell’Action.
8. Persistenza: valutare Recorder Lag e cronologia separatamente dallo stato live.
9. Test controllato: usare un’entità di test read-only o non pericolosa.
10. Ripristino: Reload prima di Restart, Restart prima di Restore; salvare prima le evidenze.

Un’entità unavailable può derivare da un Config Entry scaricato, un bridge mancante, una perdita radio o un timeout della sorgente. Un vecchio valore visibile è più pericoloso perché appare plausibile. Il monitoraggio richiede quindi limiti di freschezza, non solo limiti di valore.

Aggiornamenti, release e Custom Integrations

Home Assistant pubblica frequenti release del Core e documenta modifiche incompatibili con le versioni precedenti. Un articolo di riferimento statico non fissa deliberatamente una versione momentanea. Al momento della manutenzione, il rollout verifica invece Release Notes, modifiche delle integrazioni e dipendenze target.

Un percorso di aggiornamento controllato comprende:

1. Confermare backup e download indipendente oppure posizione di archiviazione esterna.
2. Verificare spazio libero, stato del database e System Health.
3. Valutare Release Notes, integrazioni interessate e Custom Components.
4. Inventariare dipendenze radio, broker, database e proxy.
5. Aggiornare Core oppure HAOS e app nell’ordine definito.
6. Verificare log di avvio, riparazioni e migrazioni dei registry.
7. Testare i percorsi critici di sensori, attuatori, automazioni, API e accesso remoto.
8. Definire la soglia di errore e solo successivamente avviare rollback o restore.

HAOS usa RAUC con due slot di sistema operativo; ha os info e rauc status rendono visibile lo stato degli slot (HAOS update system). Questo meccanismo protegge il percorso di aggiornamento dell’OS, non automaticamente la configurazione Core, i dati Recorder o lo stato della rete radio.

Una volta noti runtime e percorso dati, è possibile definire l’ambito del backup. Configurazione, registri, Secrets, database e stati degli add-on devono essere coerenti con il modello di installazione scelto.

Backup e ripristino

Home Assistant può scrivere backup automatici e manuali, crittografati, in destinazioni locali o esterne. La guida a backup e restore ufficiale descrive sedi di backup, Emergency Kit, download, restore durante l’onboarding e migrazione verso altro hardware. Dal 2026, il modello crittografico dei backup è stato modernizzato; l’annuncio sulla crittografia dei backup documenta il cambio di formato e i limiti di compatibilità.

Un backup è completo solo in relazione al modello di installazione:

Un test di restore non termina al login. I criteri di accettazione sono: Config Entries caricati, registri coerenti, accesso utente possibile, database senza errori, broker e bridge connessi, dispositivi radio controllabili, automazioni critiche testate e accesso remoto disponibile con certificato corretto. I dispositivi a batteria possono inizialmente dormire dopo una migrazione; un valore immediato mancante non va interpretato prematuramente come perdita di dati.

Get-ChildItem .\ha-backups -File -Recurse |
  Get-FileHash -Algorithm SHA256 |
  Export-Csv .\ha-backups-manifest.csv -NoTypeInformation
Get-Content .\ha-backups-manifest.csv -First 5

find ./ha-backups -type f -print0 | sort -z | xargs -0 sha256sum > ha-backups-manifest.sha256
head -n 5 ha-backups-manifest.sha256
tar -tf ./ha-backups/example-backup.tar | head

Get-FileHash, Export-Csv e Get-Content creano o leggono il manifest Windows. find, sort, xargs, sha256sum e tar si occupano di Unix. Un checksum prova l’immutabilità dell’archivio; decifrabilità e ripristino funzionale sono provati solo dal test di restore.

RPO, RTO e alta disponibilità

Nell’operatività usuale, Home Assistant è una singola istanza con stato. Due istanze Core attive contro gli stessi dispositivi, registri o comandi broker non generano alta disponibilità coordinata automaticamente. Automazioni duplicate possono commutare più volte gli attuatori; controller radio e dispositivi locali consentono spesso una sola proprietà attiva.

Un modello di resilienza realistico combina:

• nodo singolo affidabile o VM con risorse monitorate,
• UPS e storage adeguato anziché supporti flash sensibili,
• backup separati, automatici e crittografati,
• hardware sostitutivo documentato o piattaforma VM di destinazione,
• stati e chiavi dei controller radio esportabili,
• servizi esterni riproducibili,
• restore controllato con acquisizione univoca di dispositivi e rete.

L’RPO dipende dall’ultima copia protetta di configurazione, registry, app e servizi esterni. La cronologia Recorder può avere un RPO diverso dalla configurazione delle automazioni. L’RTO comprende non solo l’avvio del Core, ma anche DNS, proxy, database, broker, controller radio, riconnessione dei dispositivi, sensori dormienti e test di accettazione.

Sicurezza e confini di fiducia

Home Assistant può controllare porte, riscaldamento, sistemi di allarme e flussi energetici. Il suo ambito d’influenza è quindi fisico. Il design della sicurezza separa:

• utenti e amministratori,
• sessioni browser, Companion App e API,
• Long-Lived Tokens e webhook,
• Core e Custom Integrations,
• app del Supervisor o container esterni,
• segmenti IoT, di gestione e degli utenti,
• dispositivi locali e cloud dei produttori,
• reti radio e rispettive chiavi,
• destinazioni di backup ed Emergency Kit.

MFA protegge gli account interattivi, ma non un Long-Lived Token rubato. La segmentazione di rete limita il movimento laterale, ma non deve bloccare senza controllo i necessari canali Discovery e di ritorno. Le Custom Integrations ottengono vicinanza di processo al Core e vengono trattate come deployment di codice. I Secrets non compaiono né in Git né in file diagnostici o post di supporto. I controlli generali sono disponibili in hardening, i fondamenti del trasporto in TLS e i modelli contrattuali API in API.

Storia tecnica

Home Assistant è iniziato nel 2013 come progetto Python di Paulus Schoutsen. La retrospettiva per il decimo anniversario descrive lo sviluppo da piccola applicazione locale di automazione a grande progetto open source (10 anni di Home Assistant). Il Core Python e il modello delle integrazioni sono rimasti il centro funzionale, mentre attorno a essi si sono sviluppati frontend, client mobili, Supervisor, HAOS, hardware per dispositivi e opzioni cloud.

Con Hass.io, poi Home Assistant ovvero Home Assistant OS e Supervisor, è nato uno stack appliance composto da sistema operativo, gestione dei container, Core e servizi aggiuntivi. La distinzione è stata più volte chiarita a livello linguistico: gli «Add-ons» oggi si chiamano Apps, mentre le «integrazioni» restano estensioni Python del Core. Questi termini indicano confini di esecuzione e sicurezza differenti.

Nel 2024 Home Assistant è passato alla fondazione non-profit Open Home Foundation; Nabu Casa è rimasta partner commerciale. L’annuncio del progetto sull’ecosistema Open Home descrive proprietà e governance. Nel 2025 il progetto ha ridotto le varianti di installazione supportate a HAOS e Container. La tendenza storica non va quindi verso un cluster distribuito, ma verso un Core centrale più stabile con pacchetti di runtime chiaramente supportati e server di protocollo autonomi.

Checklist per amministratori

Una dashboard verde non basta come prova operativa. La checklist unisce installazione, percorsi dei dispositivi, automazioni, conservazione dei dati e ripristino in una visione complessiva verificabile.

• Installazione: documentare HAOS o Container, architettura, host, storage, rete e ownership.
• Stack: separare Core, Supervisor, app/container esterni, database, broker, proxy e server radio.
• Inventario: rilevare Config Entry, Device ID, Entity ID, Unique ID, Area e via_device.
• Origine dei dati: contrassegnare Local/Cloud e Push/Polling per ogni integrazione critica.
• Stato: distinguere unknown, unavailable, valore obsoleto e successo confermato sul dispositivo.
• Automazione: testare trigger, Context, Condition, Run Mode, comportamento al riavvio e compensazione.
• API: controllare contesto utente, archiviazione token, WebSocket, reverse proxy e TLS.
• Recorder: monitorare database, filtri, intervallo di commit, Purge, I/O, crescita e backup.
• Rete IoT: verificare esplicitamente mDNS, SSDP, MQTT, VLAN, IPv6 e percorsi radio/bridge.
• Aggiornamenti: riunire Release Notes, Custom Integrations, backup, rollout e accettazione.
• Ripristino: testare insieme Core, servizi esterni, stato radio, chiavi ed Emergency Kit.
• Verifica: non verificare soltanto UI e container, ma almeno un percorso completo di sensore, attuatore, automazione e API.

Fonti

• Home Assistant Developer Docs – panoramica dell’architettura
• Home Assistant Developer Docs – architettura delle integrazioni
• Home Assistant Developer Docs – Core architecture
• Home Assistant – HAOS o Container
• Home Assistant Developer Docs – Operating System
• Home Assistant Developer Docs – Supervisor
• Home Assistant – disattivazione di Core, Supervised e 32 bit
• GitHub – Home Assistant Core
• Home Assistant Developer Docs – Async dependency
• Home Assistant Developer Docs – Integration Quality Scale
• Home Assistant Developer Docs – Config entries
• Home Assistant Developer Docs – Device registry
• Home Assistant Developer Docs – Entity registry
• Home Assistant Developer Docs – dispositivi e servizi
• Home Assistant – integrazioni
• Home Assistant – Zeroconf
• Home Assistant – SSDP
• Home Assistant – MQTT
• Home Assistant – ZHA
• Home Assistant – Z-Wave JS
• Home Assistant – Matter
• Home Assistant – Thread
• Home Assistant – fondamenti delle automazioni
• Home Assistant – Automation actions
• Home Assistant – Automation triggers
• Home Assistant – Conditions
• Home Assistant – Automation templating
• Home Assistant – configurazione
• Home Assistant – Packages
• Home Assistant – proteggere Home Assistant
• Home Assistant – Recorder
• Home Assistant Developer Docs – REST API
• Home Assistant Developer Docs – WebSocket API
• Home Assistant Developer Docs – Authentication API
• Microsoft – Invoke-RestMethod
• Microsoft – ConvertTo-Json
• curl – manuale
• jq – manuale
• Home Assistant – HTTP integration
• Microsoft – Resolve-DnsName
• Microsoft – Test-NetConnection
• Microsoft – Get-NetTCPConnection
• BIND 9 – dig
• Linux man-pages – ss(8)
• OpenSSL – s_client
• Eclipse Mosquitto – mosquitto_sub
• Eclipse Mosquitto – mosquitto_pub
• Docker – inspect
• Docker – logs
• Docker – stats
• Microsoft – ConvertFrom-Json
• Microsoft – Select-String
• GNU Grep – manuale
• GNU Coreutils – df
• GNU Coreutils – du
• Home Assistant – System Health
• Home Assistant – Logger
• Home Assistant Developer Docs – HAOS update system
• Home Assistant – backup e restore
• Home Assistant – crittografia dei backup modernizzata
• Microsoft – Get-FileHash
• Microsoft – Export-Csv
• Microsoft – Get-Content
• Linux man-pages – find(1)
• GNU Coreutils – sort
• Linux man-pages – xargs(1)
• GNU Coreutils – sha2 utilities
• GNU Tar – manuale
• Home Assistant – 10 anni di Home Assistant
• Home Assistant – Open Home Foundation e governance