Come creare il primo flow Node-RED per Home Assistant

Introduzione alla programmazione visuale con Node-RED

Node-RED rappresenta uno strumento formidabile per estendere le logiche di automazione all'interno di un sistema basato su Home Assistant. A differenza delle automazioni native scritte in YAML, l'approccio visuale basato su flussi, nodi e messaggi offre una visione d'insieme immediata e strumenti di debug avanzati in tempo reale. Questa guida è pensata per utenti di livello intermedio che possiedono già un'istanza di Home Assistant correttamente configurata, preferibilmente eseguita su hardware dedicato come un Home Assistant Green o un Home Assistant Yellow, e che desiderano sfruttare la potenza del componente aggiuntivo Node-RED.

Prima di iniziare, è indispensabile chiarire i prerequisiti: occorre avere installato il pacchetto ufficiale Node-RED tramite gliAdd-on di Home Assistant e aver installato la palette di nodi node-red-contrib-home-assistant-websocket, solitamente inclusa di default nelle installazioni standard recenti. I limiti di questo sistema riguardano principalmente la gestione della memoria in caso di flussi enormi non ottimizzati e la necessità di comprendere il formato dei messaggi in formato JSON che viaggiano tra i nodi. Non affronteremo installazioni da zero di Docker o Node.js standalone, concentrandoci esclusivamente sull'ambiente integrato.

Architettura e logica di un flow Node-RED

Per comprendere come strutturare un'automazione, bisogna analizzare i tre componenti fondamentali di ogni logica Node-RED: il nodo di input (Trigger), i nodi di elaborazione (Funzioni, Switch, Change) e il nodo di output (Azione). Nel contesto di Home Assistant, il flusso parte solitamente da un evento scatenato da un sensore fisico reale, come ad esempio la rilevazione di movimento da parte di un Aqara Motion Sensor P1 o il cambio di stato di un dispositivo di controllo come un Shelly Plus 1. Il messaggio attraversa il flusso sotto forma di oggetto JavaScript (msg), dove msg.payload trasporta il valore principale e msg.data contiene i metadati completi dello stato del dispositivo.

La gestione dei messaggi e del contesto

Ogni nodo riceve un input, elabora i dati e passa il risultato al nodo successivo tramite l'uscita (wire). È fondamentale comprendere che le modifiche apportate a msg si ripercuotono lungo tutto il percorso. Per evitare comportamenti anomali, si utilizzano nodi di controllo come lo Switch per smistare i flussi in base a condizioni booleane o numeriche, e nodi Change per manipolare le variabili prima di inviare un comando di servizio a Home Assistant.

Procedura passo dopo passo

1. Accedi al pannello di controllo di Home Assistant e apri l'interfaccia web di Node-RED dal menu laterale dei componenti aggiuntivi.
2. Trascina un nodo server-state-changed (denominato solitamente Current State o Events: State) dall'area sinistra dei nodi dedicati a Home Assistant verso la griglia centrale di lavoro.
3. Fai doppio clic sul nodo appena posizionato per aprire il pannello di configurazione, seleziona il server Home Assistant predefinito e inserisci l'entity_id del dispositivo di riferimento, ad esempio un Aqara Motion Sensor P1.
4. Imposta i parametri di filtraggio dello stato lasciando i campi vuoti se desideri catturare qualsiasi variazione, oppure specificando lo stato esatto come on per attivare il trigger solo al rilevamento di movimento.
5. Trascina un nodo api-call-service (chiamato Call Service) sulla griglia e posizionalo a destra del nodo di evento appena configurato.
6. Collega l'uscita del nodo di evento all'ingresso del nodo di servizio tracciando una linea (wire) tra i due punti di connessione.
7. Fai doppio clic sul nodo Call Service, imposta il dominio su light, il servizio su turn_on e specifica l'entity_id del dispositivo da azionare, come ad esempio una presa intelligente gestita tramite un Shelly Plus Plug IT.
8. Trascina un nodo debug dalla sezione comune della barra laterale e collegalo all'uscita del nodo di servizio per monitorare la risposta e i dati restituiti dall'API.
9. Clicca sul pulsante rosso Deploy situato in alto a destra nell'interfaccia di Node-RED per salvare e attivare ufficialmente il nuovo flusso nel sistema.
10. Effettua un test fisico attivando il sensore di movimento di riferimento e controlla la scheda Debug di Node-RED per verificare il passaggio corretto dei messaggi e l'effettiva esecuzione del comando.

Verifica del risultato e diagnostica

Una volta completato il deploy, la verifica del corretto funzionamento richiede l'utilizzo combinato del pannello Debug di Node-RED e dei log di Home Assistant. Nel pannello di debug, contrassegnato dall'icona a forma di insetto nella barra laterale destra, vedrai comparire i pacchetti JSON ogni volta che il trigger si attiva. Se il campo payload mostra lo stato atteso e il nodo di servizio restituisce una risposta positiva (spesso indicata da un punto verde e dalla scritta success), l'automazione è formalmente operativa.

Nel caso in cui il flusso non produca gli effetti desiderati, il primo controllo da effettuare riguarda la correttezza degli entity_id. Spesso una digitazione errata o un cambio di nome del entità in Home Assistant interrompe la comunicazione tra i due sistemi. Ricorda inoltre che i nodi di servizio richiedono spesso payload specifici in formato JSON nel campo dati (Data) se desideri passare parametri avanzati come la luminosità o il colore di una lampadina.

Problemi comuni e risoluzione

FAQ - Domande frequenti

Posso usare Node-RED senza Home Assistant?

No, nella specifica implementazione trattata in questa guida, Node-RED si appoggia interamente all'infrastruttura di Home Assistant per la gestione dei dispositivi fisici tramite WebSocket.

Cosa succede ai miei flussi se riavvio Home Assistant?

I flussi rimangono salvati sul disco fisso nel volume persistente del componente aggiuntivo e si riattivano automaticamente al riavvio del sistema operativo.

È possibile disattivare temporaneamente un singolo flow senza cancellarlo?

Sì, l'interfaccia di Node-RED permette di modificare le proprietà di un flusso o di singoli nodi impostando la loro disattivazione (Disable) prima di eseguire il deploy.

Come posso gestire automazioni complesse con condizioni temporali?

Puoi inserire nodi specifici come time-range-switch o utilizzare nodi di funzione JavaScript per valutare l'orario corrente prima di inoltrare il comando di servizio.