Home Assistant: l'acquario nella smart home, la logica nel controller

Oquari si integra nativamente con Home Assistant: attivi un'opzione sul pannello e le entità dell'acquario compaiono automaticamente in HA — senza scrivere configurazioni, senza cloud, senza plugin di terze parti. Questa guida mostra come attivarla, cosa vedrai esattamente in HA e dove passa il confine: HA supervisiona e aggiunge comodità, ma la logica critica rimane nel controller.

Cos'è Home Assistant (in due paragrafi)

Home Assistant è la piattaforma open source per la smart home più popolare al mondo: software gratuito che installi localmente (Raspberry Pi, mini-PC, NAS) e che unisce dispositivi di diversi produttori in un unico sistema — con dashboard, grafici storici, automazioni e notifiche sul telefono.

Per l'acquariofilo HA significa un unico punto dove l'acquario incontra il resto della casa: il grafico del pH accanto alla temperatura del salotto, la notifica di allagamento sullo stesso telefono dell'allarme domestico, il pulsante "alimentazione" sulla tablet in cucina.

Passo 1: broker MQTT

Oquari comunica con HA tramite MQTT — un protocollo di comunicazione leggero per la smart home. Hai bisogno di un broker (intermediario dei messaggi) nella rete locale; nella pratica è una sola installazione:

1. In Home Assistant: Impostazioni → Add-on Store → Mosquitto broker → installa e avvia.
2. Crea in HA un utente per il controller (es. oquari) — l'add-on Mosquitto userà gli account HA.
3. Abilita in HA l'integrazione MQTT (di solito si suggerisce da sola dopo l'avvio del broker).

Passo 2: attivazione nel pannello Oquari

1. Apri il pannello del controller (oquari-XXXX.local) → scheda Home Assistant.
2. Abilita l'integrazione e inserisci: indirizzo del broker (mqtt://IP-del-tuo-HA:1883), login e password dell'utente MQTT.
3. Salva — il controller si connetterà al broker e annuncerà le sue entità (MQTT Discovery).

Dopo un momento, in HA, in Impostazioni → Dispositivi e servizi → MQTT, apparirà il dispositivo "Oquari" con il completo set di entità.

La connessione al broker non è crittografata (rete locale). Usa questa integrazione solo nel tuo LAN personale e assegna all'utente MQTT una password dedicata. Questo è il modello standard di funzionamento dei dispositivi smart home locali.

Cosa apparirà in HA

Le entità corrispondono alla tua configurazione — il controller le dichiara automaticamente, con le unità di misura e le classi corrette (quindi HA disegna subito i grafici e capisce cosa sia temperatura e cosa energia):

• Sensori: temperatura, pH, ORP, salinità, livelli, portata (l/min), potenza ed energia di ogni presa, contatori di consumo dei liquidi dosati,
• Sensori binari: sensori di livello, sensori di allagamento, allarmi (surriscaldamento, limite ATO, bottiglia vuota), stato "dosaggio in corso",
• Interruttori e luci: prese misurate come switch, canali illuminazione come light,
• Numeri e modalità: dosi di dosaggio come number, modalità operative come select, alimentazione come button.

Inoltre, l'entità di disponibilità: quando il controller scompare dalla rete, HA segna immediatamente le sue entità come non disponibili — che di per sé è un eccellente allarme ("acquario offline").

Esempio: l'alimentazione ferma la circolazione per 5 minuti

Un classico comfort — pulsante in HA che durante l'alimentazione ferma la pompa di circolazione, e HA la riavvia da solo:

alias: Alimentazione — pausa circolazione
trigger:
  - platform: state
    entity_id: input_button.alimentazione
action:
  - service: switch.turn_off
    target:
      entity_id: switch.oquari_circolazione
  - delay: "00:05:00"
  - service: switch.turn_on
    target:
      entity_id: switch.oquari_circolazione

Nella pratica non devi nemmeno scriverlo — Oquari ha una modalità alimentazione integrata (button.oquari_alimentazione) che ferma le pompe e le riavvia automaticamente. Ma l'esempio illustra bene il principio: le entità Oquari si comportano come qualsiasi altra in HA.

Altre automazioni utili: notifica push in caso di allarme temperatura o allagamento, promemoria per la sostituzione della bottiglia quando il contatore di consumo supera la capacità della bottiglia, grafico giornaliero del pH sulla dashboard accanto alla finestra CO₂.

Principio di separazione: HA supervisiona, il controller protegge

Il paragrafo più importante di questa guida. La logica critica — isteresi del riscaldamento, interruzioni di emergenza, limiti ATO, cambio acqua, finestra CO₂, dosaggio — viene eseguita nel controller, localmente. HA è lo strato di supervisione e comodità: dashboard, storico, notifiche, scene tipo alimentazione.

Questa separazione non è un caso, ma il fondamento della sicurezza:

• Se cade il Wi-Fi, il router, il server HA o internet — il riscaldamento mantiene la temperatura, l'ATO continua a vigilare sui limiti, il CO₂ si chiude fuori dalla finestra di luce. L'acquario non noterà il guasto di rete.
• L'automazione HA può commutare le prese, ma non può bypassare lo strato di sicurezza del controller: gli override (interruzione surriscaldamento, blocco allagamento) sono superiori anche ai comandi MQTT.

Non trasferire la logica protettiva in HA, anche se sai scriverla lì. L'automazione "spegni la resistenza a 27,5 °C" in HA cessa di esistere insieme al server HA. La stessa regola nel controller funziona sempre. Usa HA per quello in cui è eccellente: vedere, sapere e semplificare.

Domande frequenti

Devo installare plugin aggiuntivi per far funzionare Oquari con Home Assistant?

No. L'integrazione avviene tramite il protocollo MQTT nativo di Home Assistant. Una volta configurato il broker Mosquitto (incluso negli add-on ufficiali), le entità di Oquari vengono rilevate automaticamente senza bisogno di componenti esterni o configurazioni YAML complesse.

Cosa succede alla logica dell'acquario se si interrompe la connessione con Home Assistant?

Nessuna conseguenza operativa. La logica critica come il controllo della temperatura, l'alimentazione e la sicurezza rimane eseguita localmente sul controller Oquari. Home Assistant funge solo da interfaccia di visualizzazione e notifica; se va offline, l'acquario continua a funzionare normalmente secondo i parametri impostati.

Posso modificare direttamente i setpoint (es. temperatura target) da Home Assistant?

Sì, per i parametri che Oquari espone come entità modificabili (come number o select). Tuttavia, la logica di sicurezza e le protezioni hardware restano gestite dal controller stesso, garantendo che nessun comando esterno possa compromettere la stabilità dell'ambiente acquatico.

È sicuro usare MQTT non crittografato in rete locale?

Sì, purché il broker sia accessibile solo dalla tua rete domestica privata (LAN). Non esporre mai il servizio MQTT direttamente su internet. Utilizzare una password dedicata per l'utente Oquari è una buona pratica per isolare l'accesso dal resto dei dispositivi smart home.

Come faccio a sapere se Oquari è online o offline in Home Assistant?

Home Assistant monitora automaticamente lo stato di disponibilità delle entità MQTT. Se il controller perde la connessione, tutte le relative entità passeranno allo stato "non disponibile", permettendoti di creare facilmente una notifica di allarme per questo specifico evento.