Automazione non funziona in Home Assistant: come leggere le tracce e trovare la causa

Introduzione

Quando un’automazione non funziona in Home Assistant, abbiamo la possibilità di leggere le tracce e trovare la causa. Questo strumento ci consente di diagnosticare e di seguire, anche in modo grafico, tutto il percorso e i nodi dell’automazione, così da poterla ricostruire e trovare il punto in cui si interrompe o non funziona. Se parti da zero e non hai mai creato un’automazione, comincia dalla guida all’editor delle automazioni.

Per esempio, qualche tempo fa ho avuto un problema con l’automazione della luce di cortesia, che accende le luci esterne al mio rientro grazie a un radar (se vuoi approfondire, trovi tutto nella guida alla luce ingresso con radar mmWave). L’automazione era tutta funzionante fino alla fine, solo che mi ero dimenticato di aver cambiato il nome ad alcune entità, comprese le luci esterne, e in pratica l’automazione non funzionava. Con la traccia è stato molto facile trovare il nodo che non funzionava (che poi era l’ultimo) e aggiustarlo.

Prima di tutto: apri la traccia dell’automazione

Dove si trova

Alla schermata delle tracce si arriva in tre modi:

1. Dalla lista delle automazioni: ogni riga ha i tre puntini alla fine. Cliccando si apre il menu contestuale, poi si sceglie Traces.
2. Dall’automazione vera e propria, cioè dall’editor: in alto a destra c’è il pulsante Traces.
3. Dalle Attività: si apre la voce causata dall’automazione e si clicca su View trace (ne parlo nell’articolo sul Registro Attività di Home Assistant).

Come si legge una traccia

A sinistra abbiamo il grafico del percorso: possiamo cliccare sui nodi per vedere cosa fanno e quali sono le variabili, per esempio uno stato, un’attesa o una scelta, che vengono visualizzate nella parte centrale, in Step details. In alto ci sono le schede Step details, Trace timeline, Related activity e Automation config. Dentro Step details, sotto, ce ne sono altre tre: la configurazione del passaggio (Step config), le attività collegate e un tab importante, Changed variables, che ci mostra le variabili che cambiano o che sono cambiate durante l’esecuzione dell’automazione.

La Trace timeline mette tutto in ordine cronologico: nell’automazione delle luci di cortesia al rientro si vedono il trigger del portone, il controllo sulla posizione del sole, la scena, l’attesa di 20 secondi e lo spegnimento, fino a Finished.

Nell’esempio della luce di cortesia esterna, in Changed variables trovo:

1. trigger.id = 'off': quale trigger ha avviato l’automazione.
2. from_state = 'on': lo stato prima del cambiamento.
3. to_state = 'off': lo stato dopo, cioè il radar non rileva più nessuno.

Il tab Related activity, invece, ci fa vedere tutte le attività primarie e secondarie coinvolte nell’automazione, come per esempio le luci che vengono accese o spente.

Quante tracce restano

Di default si possono consultare al massimo le ultime 5 tracce di ogni automazione, ma il valore può essere cambiato aggiungendo l’opzione stored_traces nello YAML dell’automazione, come spiega la documentazione ufficiale sulle tracce. Sulle automazioni che scattano spesso, come un dimmer, cinque tracce si esauriscono in pochi secondi.

trace:
  stored_traces: 20

Accanto a ogni esecuzione, nell’elenco, c’è l’esito. Ecco come leggerlo:

Il metodo: tre domande, in quest’ordine

Allora analizziamo la traccia dell’automazione e poniamoci queste tre domande: per ognuna, secondo la risposta, analizziamo e cerchiamo di trovare il problema. Tratteremo i prossimi capitoli rispettando questo ordine per la ricerca dell’errore.

1. C’è una traccia? Se non c’è, il trigger non è scattato.
2. Se c’è, dove si ferma? A una condizione o a un’azione.
3. Se arriva in fondo, l’azione ha cambiato davvero il dispositivo?

Alcune precisazioni. Quando si usa Run actions per testare, questo salta trigger e condizioni e non ha i dati del trigger: quindi, se l’automazione funziona da lì ma non parte da sola, il problema risiede proprio nel trigger o in una condizione.

Per testare con dati veri puoi cambiare lo stato dell’entità da Strumenti → States (Set state): così l’automazione parte con il trigger reale.

Attenzione però: se quello stato è collegato ad altre automazioni, involontariamente farai partire anche quelle.

L’automazione non parte (nessuna traccia)

Se l’automazione non funziona e nell’elenco non c’è nessuna traccia nuova, il trigger non è mai scattato. Lo vedi anche dalla colonna Last triggered nella lista delle automazioni: se c’è scritto Never, o una data molto vecchia, parti da qui.

È disattivata

Il primo caso è il più banale e il più facile da risolvere: a volte l’automazione è semplicemente disattivata. Nella pagina con tutte le automazioni c’è un toggle con cui possiamo attivarla e disattivarla, molto utile. Se è disattivata, riattivala.

Lo stato scritto non è quello reale

Per far scattare un’automazione abbiamo bisogno di un trigger. A volte nell’interfaccia troviamo stati come Aperto o Rilevato, e come stato di cambiamento mettiamo Aperto o Chiuso, ma l’automazione molto spesso confronta lo stato a livello grezzo: on o off. Sono questi i valori che dobbiamo confrontare. Per vedere gli stati reali devi andare in Impostazioni → Strumenti, scheda States. Per esempio, per il mio radar lo stato grezzo è off, mentre l’interfaccia scrive Clear (e on quando scrive Detected).

Se nell’editor visuale scegli lo stato dal menu a tendina, Home Assistant inserisce già il valore giusto: il problema nasce quando lo scrivi a mano, in YAML o in un template. Questo è il trigger della mia luce di cortesia esterna (l’entità è quella del mio radar: sostituiscila con la tua):

triggers:
  - trigger: state
    entity_id: binary_sensor.0xa4c138e9e1c7c89d_presence
    to: "on"

I trigger reagiscono ai cambiamenti, non agli stati

I trigger si attivano quando c’è un cambiamento di stato. Prendiamo per esempio la temperatura: attiviamo un’automazione se la temperatura passa da meno di 20 gradi a più di 20, e fin qui tutto bene. Il problema sorge se, quando si accende Home Assistant, magari dopo un blackout, ci troviamo già sopra i 20 gradi: l’automazione non parte. Ecco perché si inserisce un secondo trigger, che si attiva all’avvio di Home Assistant, insieme a una condizione che deve essere soddisfatta, cioè (nel nostro esempio) la temperatura sopra i 20 gradi.

triggers:
  - trigger: numeric_state
    entity_id: sensor.temperatura_n_2_aqara_temperature
    above: 20
  - trigger: homeassistant
    event: start
conditions:
  - condition: numeric_state
    entity_id: sensor.temperatura_n_2_aqara_temperature
    above: 20

Se serve un controllo più granulare, possiamo aggiungere anche un trigger Time pattern, per esempio ogni 10 minuti (/10), sempre con la stessa condizione: dipende dai casi d’uso. Comunque, devi sapere che se un’automazione non si avvia, forse è perché ci troviamo già nella condizione del trigger.

Pulsanti: il trigger giusto e le azioni che non compaiono

Se abbiamo dei pulsanti remoti che, quando vengono premuti, non fanno nulla, oppure ignorano la seconda pressione uguale, il motivo di solito è il tipo di trigger.

Perché la seconda pressione si perde? Zigbee2MQTT memorizza l’ultima azione come stato. Se premi due volte lo stesso tasto, lo stato resta 1_single: un trigger di stato sul vecchio sensore action non vede nessun cambiamento e non scatta. Questo sensore oggi esiste solo se hai attivato l’opzione legacy_action_sensor, che è deprecata.

La soluzione è il trigger device: è il metodo raccomandato da Zigbee2MQTT e quello attivo di default. Non confronta stati, ma reagisce a ogni messaggio del pulsante, quindi ogni pressione fa partire l’automazione.

Molto spesso, poi, le azioni disponibili per un dispositivo come un pulsante Moes o Tuya non compaiono tra i trigger semplicemente perché non sono mai state usate: Home Assistant crea il trigger solo dopo che il pulsante ha inviato quell’azione almeno una volta. Bisogna quindi premere ogni tasto e ogni combinazione (single, double e hold) almeno una volta per farli comparire. Questa è una regola quasi generale per tutti i dispositivi basati sulle azioni di Zigbee2MQTT. Per vedere quali trigger sono già stati scoperti: pagina del dispositivo, menu ⋮, MQTT info.

Un piccolo appunto personale. L’azione Hold in questi dispositivi, che prima non c’era e poi è comparsa, mancava per un motivo semplice: personalmente non amo usare tanto le azioni che si innescano con la pressione lunga. Non è niente di rotto o non funzionante, è semplicemente un mio modo personale di vedere il trigger, più immediato: una pressione lunga implica l’attesa di qualche secondo. La uso solo in circostanze eccezionali, a volte per il debug o per automazioni che mi servono poche volte all’anno.

Per quanto riguarda il pulsante Moes che ho in dotazione (un Tuya TS0044 con marchio Moes), dopo mesi di prova funziona bene. A volte può sembrare lento nella risposta, ma è solo per un leggero ritardo dovuto all’attesa di un secondo click consecutivo, quello che innesca l’azione double. Nel complesso fa, e fa bene, il suo dovere. Ho apprezzato che la pressione consecutiva di tasti diversi non faccia perdere l’azione, come succede invece con altri pulsanti che hanno anche le combinazioni tra più tasti.

L’automazione parte ma non fa nulla

In questa sezione, invece, analizziamo il caso in cui l’automazione parte, quindi il trigger funziona, ma non succede niente.

Stopped because a condition failed

Stop perché la condizione è fallita. Ovviamente può essere fallita per un motivo che non volevamo, oppure proprio perché la condizione era quella giusta da rispettare. Facciamo un caso reale: questa automazione mi accende le luci di cortesia esterne al mio rientro, o quando il radar rileva una persona, solo che lo fa a una condizione: che la luminosità esterna sia inferiore ai 50 lux (ovviamente tarata per me). Non avrebbe senso accendere le luci di giorno, quindi l’automazione parte ma si blocca, perché la condizione (voluta) non passa.

condition: numeric_state
entity_id: sensor.0xa4c138e9e1c7c89d_illuminance
below: 50
enabled: true

Con gli ultimi aggiornamenti, Home Assistant ha aggiunto la verifica della condizione in tempo reale: sull’icona della condizione compare una spunta o una X, così nell’editor abbiamo subito il responso visivo, senza nemmeno aprire la traccia.

Fai attenzione al below: 50 che ho usato io, perché esclude il 50: un valore di 50 lux esatti non fa passare la condizione.

Fai attenzione anche ai dispositivi unavailable: se il sensore non è raggiungibile, la condizione non passa. Per buona pratica, se vuoi, inserisci un fallback. Nel mio caso non l’ho fatto: preferisco non far accendere le luci.

Attenzione anche se usi gli helper, come nella mia automazione che non rispondeva perché nell’helper di scelta era selezionata la modalità sbagliata (numero 1 invece di 2). Questa automazione è soggetta a una condizione che proviene da un helper: se è impostato su 1 l’automazione non funziona, se è su 2 funziona. La selezione la cambio con un doppio click sullo stesso dispositivo (mi passa dal controllo della luminosità al controllo dei Kelvin). Trovi tutte le automazioni della manopola nella guida al Tuya Smart Knob ZG-101Z/D.

Ti lascio lo YAML completo, un po’ complesso: la parte che conta qui è il blocco conditions sull’helper input_select.modalita_dimmer. Gli ID di dispositivi ed entità sono quelli della mia installazione: per usarla devi sostituirli con i tuoi.

alias: Dimmer Cucina
description: Cambia la luminosità della cucina attraverso il Dimmer Cucina
triggers:
  - alias: Dimmer 1 Ruota a Destra
    domain: mqtt
    device_id: 1d6e5e4f362ff45658ec45f65fd7d989
    type: action
    subtype: rotate_right
    trigger: device
    id: Ruota a Destra
  - alias: Dimmer 1 Ruota a Sinistra
    domain: mqtt
    device_id: 1d6e5e4f362ff45658ec45f65fd7d989
    type: action
    subtype: rotate_left
    trigger: device
    id: Ruota a Sinistra
conditions:
  - condition: state
    entity_id: input_select.modalita_dimmer
    state:
      - "2"
actions:
  - alias: Scelta tra Ruota a Destra o a Sinistra
    choose:
      - conditions:
          - condition: trigger
            id:
              - Ruota a Destra
        sequence:
          - parallel:
              - device_id: 78fc0b906936f77b905de019b854cc89
                domain: light
                entity_id: a227f7848a76f272a0f91be40d8b98f5
                type: brightness_increase
              - action: light.turn_on
                metadata: {}
                target:
                  entity_id: light.yeelight_color_0x36ed322
                data:
                  brightness_step_pct: 20
              - action: light.turn_on
                metadata: {}
                target:
                  entity_id: light.cucina_luce_parete_n_2
                data:
                  brightness_step_pct: 20
      - conditions:
          - condition: trigger
            id:
              - Ruota a Sinistra
        sequence:
          - parallel:
              - device_id: 78fc0b906936f77b905de019b854cc89
                domain: light
                entity_id: a227f7848a76f272a0f91be40d8b98f5
                type: brightness_decrease
              - action: light.turn_on
                metadata: {}
                target:
                  entity_id: light.cucina_luce_parete_n_2
                data:
                  brightness_step_pct: -20
              - action: light.turn_on
                metadata: {}
                target:
                  entity_id: light.yeelight_color_0x36ed322
                data:
                  brightness_step_pct: -20
mode: queued
max: 3

Stopped because an error was encountered

Stop per errore. Nelle automazioni (e negli script, le tracce funzionano allo stesso modo) è possibile che ci si fermi per errori sulle entità, perché queste non esistono più, o per altri errori. Negli esempi qui sotto, nel primo abbiamo un errore di API, cioè di collegamento con l’AI (“Error talking to API”): erano scadute le API di test. Nel secondo c’è l’errore “Error: AI Task entity ai_task.google_ai_task not found”: praticamente l’entità non esiste più, l’ho cancellata. L’errore si legge in Step details, cliccando il nodo con il punto esclamativo rosso, oppure in fondo alla Trace timeline.

C’è la possibilità di proseguire con continue_on_error: l’errore resta solo nella traccia e l’automazione prosegue (ne parlo nella guida agli script di Home Assistant). Nel nostro caso, però, non porterà a niente, perché è un errore bloccante: se l’AI non funziona non avremo risposte, e l’automazione non sarà portata a termine comunque. Quindi si può usare, ma a volte non è risolutivo.

Dispositivo sostituito, rinominato o non disponibile

A volte può capitare che l’automazione sia scritta perfettamente, ma alla fine non succede niente. Succede quando il dispositivo finale è irraggiungibile, cioè unavailable. A me è accaduto quando ho sostituito la lampada esterna e non ho cambiato nell’automazione il nome del nuovo dispositivo, o meglio, più precisamente, nella scena associata all’automazione. Se non sai cosa sono le scene, leggi il mio articolo sulle scene di Home Assistant.

Bisogna fare attenzione però a una cosa: nella traccia dell’automazione può non apparire che il dispositivo è unavailable finché non ci si clicca sopra. Accade quando, per esempio, il dispositivo si trova dentro uno script o una scena, come nel mio caso. Ti mostro una schermata di esempio (ho cambiato di proposito il dispositivo della lampadina, mettendone uno non disponibile, Luce Retro, ma il senso non cambia; per lo stesso motivo ho disattivato temporaneamente la condizione sulla luminosità, così la traccia arriva fino in fondo).

Per questo, se un’automazione non funziona, verifica anche i log di sistema in Impostazioni → Sistema → Log: Home Assistant salta le entità non disponibili e lo segnala con un avviso del tipo “Referenced entities … are missing or not currently available”. Se hai rinominato un’entità o un dispositivo, le automazioni vanno riparate, perché Home Assistant non le aggiorna da solo. Come ti dicevo, quando sostituisci per esempio una luce LED o un sensore di temperatura, a volte questi sono collegati a più automazioni e qualcosa va perso. Ricontrolla sempre due volte.

L’automazione parte due volte, troppo spesso o viene ignorata

“Already running” nei log

Quando premiamo un tasto per accendere la luce o attivare un’automazione, se questa è impostata in modalità single (quella predefinita) e non ha ancora terminato, la seconda pressione ravvicinata non porta a niente: viene ignorata e nel log compare “Already running”. Con queued e parallel, oltre il limite, compare invece “Maximum number of runs exceeded”, come spiega la documentazione sulle modalità di esecuzione.

Per esempio, nel mio dimmer che cambia la luminosità ho impostato la modalità queued con max: 3: gestisce fino a 3 esecuzioni (quella in corso più quelle in coda), dopodiché ignora le altre. Girando una manopola, è la modalità che ha più senso. Ovviamente puoi scoprire tutto questo nelle tracce e nel log. Per approfondire, ne parlo nell’errore n. 7 degli errori comuni e nelle modalità di esecuzione degli script.

Un’automazione che ha come trigger un cambiamento di stato, senza specificare to, reagisce a qualsiasi cambiamento, anche degli attributi. Qual è il meccanismo? Ogni entità ha uno stato, per esempio on e off, e degli attributi, per esempio la temperatura. Se crei un trigger senza specificare, per esempio, to: "on", l’automazione scatterà anche quando cambia uno qualsiasi dei suoi attributi, anche se lo stato resta uguale. Il rimedio è scegliere, nel campo To del trigger, Any state (ignoring attribute changes), che in YAML diventa to: null:

triggers:
  - trigger: state
    entity_id: climate.aqara_termostato
    to: null

L’automazione scatta all’orario sbagliato o si perde dopo un riavvio

Attenzione all’impostazione di automazioni che scattano a determinati orari: si possono perdere o ripetere, per esempio quando si cambia l’ora legale/solare. Quando alle 03:00 gli orologi tornano alle 02:00, un trigger impostato tra le 02:00 e le 02:59 scatta due volte.

Attenzione anche ai riavvii, per esempio quelli dopo un aggiornamento o quelli manuali, perché interrompono le automazioni in corso, e un delay lungo si perde. Per timer di pochi secondi è ininfluente, ma per timer lunghi valuta soluzioni paracadute a seconda delle esigenze: per esempio, un helper timer che riparte all’avvio.

In sintesi: sintomo, causa, rimedio

Ecco tutti i casi visti in questo articolo, più qualcuno in più preso dalla guida ufficiale alla risoluzione dei problemi delle automazioni.

Conclusione

Come tutte le cose, anche le automazioni si possono rompere: per esempio, cambiamo qualcosa e smettono di funzionare. Quando non funzionano più, la prima cosa che faccio è andare a vedere le tracce, e poi testare manualmente. Con un’automazione che non funziona in Home Assistant, seguendo questo articolo, si trova facilmente il colpevole. Io personalmente non lo faccio spesso, ma se una cosa non funziona più vado a controllare: avendo tante automazioni, non si può passare a testarle tutte ogni volta. Come strumento di diagnostica, però, quando ci si accorge che non funzionano, si possono aggiustare con pochi minuti di lavoro. E se vuoi evitare i problemi prima che arrivino, leggi anche i 10 errori comuni in Home Assistant che ho fatto e risolto.