Tuya Smart Knob ZG-101Z/D: automazioni YAML Home Assistant

Nella recensione completa del Tuya Smart Knob ZG-101Z/D ho spiegato la differenza tra le due varianti — Tuya (_TZ3000_abrsvsou) e Moes (_TZ3000_gwkzibhs) — e le azioni che espongono in Home Assistant. In questo articolo vediamo il lato pratico: come funzionano i trigger in HA, la creazione di un’automazione con l’editor visuale passo dopo passo con screenshot reali, e gli YAML che uso effettivamente in casa.

I knob — queste manopole rotanti — per me sono molto utili, forse anche di più dei classici tasti o pad. O meglio, sono complementari: gestiscono in maniera efficiente la luminosità e i click, sono dispositivi completi, discreti, non ingombrano e possono gestire più eventi per risolvere più esigenze con un solo dispositivo. Li ho installati praticamente in tutte le stanze, sempre insieme ai classici interruttori, per gestire la luminosità della cucina e del soggiorno — che in certi momenti non deve essere per forza al massimo. Aprire un’app sul telefono, cercare il dispositivo e abbassare la luminosità è di gran lunga più lungo e laborioso che agire in pochi secondi su una manopola a portata di mano.

Prerequisiti

Prima di partire, ci servono alcune cose già in ordine — su cui non mi soffermo perché sono già coperte da guide dedicate:

• Home Assistant OS o Supervised aggiornato
• Zigbee2MQTT installato e funzionante — il knob deve essere già associato
• Modalità operativa impostata su event (vedi sezione successiva)
• Sapere quale variante si ha — se non lo hai ancora verificato, il modo per controllarlo è nella recensione linkata sopra

Impostare la modalità event

Di default questi dispositivi sono già preimpostati in modalità event, ma è sempre bene fare un controllo. In modalità command le azioni non arrivano a Home Assistant — tutto rimane silenzioso.

Vai in Zigbee2MQTT → [il tuo knob] → tab Funzioni esposte e verifica che “Operation mode” sia impostato su event.

In alternativa via MQTT, pubblica sul topic zigbee2mqtt/[nome-device]/set:

{"operation_mode": "event"}

Come funzionano i trigger in Home Assistant

Il knob espone le proprie azioni come device trigger in Home Assistant. Questo è il modo corretto di usarli con Zigbee2MQTT — non come sensor.action su cui fare platform: state.

Le azioni disponibili variano leggermente tra le due varianti:

Variante Tuya _TZ3000_abrsvsou:

• "single" action — pressione singola
• "double" action — doppia pressione
• "hold" action — pressione prolungata
• "rotate_left" action — rotazione antioraria
• "rotate_right" action — rotazione oraria
• Battery battery level changes
• Operation mode option changed

Variante Moes _TZ3000_gwkzibhs — tutto quanto sopra, più:

• "toggle" action
• Action transition time value changes

Per creare una nuova automazione con questi device, andiamo su Impostazioni → Automazioni e clicchiamo su Crea nuova automazione.

Aggiungiamo un trigger, cerchiamo “Dispositivo” nel campo di ricerca e lo selezioniamo.

Nel pannello a destra scegliamo il nostro knob dal menu Device e nel dropdown selezioniamo l’azione che ci interessa.

Semplice. Il codice YAML prodotto dall’editor per un trigger di esempio è questo:

triggers:
- domain: mqtt
  device_id: IL_TUO_DEVICE_ID
  type: action
  subtype: rotate_right
  trigger: device

Supervisione umana: il device_id è l’identificativo univoco del tuo knob in HA. Lo trovi in Impostazioni → Dispositivi → [il tuo knob], oppure direttamente nell’editor automazioni quando selezioni il dispositivo. Non è trasferibile tra installazioni diverse — ogni knob ha il proprio.

Automazione 1 — Toggle luci con click singolo

Un click accende se la luce è spenta, spegne se è accesa. L’automazione controlla lo stato corrente e agisce di conseguenza.

alias: Dimmer Cucina Click Spegni e Accendi tutte le luci
description: Dimmer Cucina Click Spegni e Accendi tutte le luci
triggers:
- domain: mqtt
  device_id: IL_TUO_DEVICE_ID
  type: action
  subtype: single
  trigger: device
conditions: []
actions:
- if:
    - condition: state
      entity_id: light.cucina_tutte_le_luci
      state:
        - "on"
  then:
    - action: light.turn_off
      target:
        entity_id: light.cucina_tutte_le_luci
      data: {}
  else:
    - action: light.turn_on
      target:
        entity_id: light.cucina_tutte_le_luci
      data: {}
mode: single

Supervisione umana: sostituisci light.cucina_tutte_le_luci con l’entità luce reale. Se vuoi controllare un’area invece di una singola entità, usa area_id nel target al posto di entity_id.

Automazione 2 — Dimmer con rotazione su più luci in parallelo

Ruota a destra = aumenta luminosità, ruota a sinistra = diminuisce. L’automazione agisce su più luci contemporaneamente in parallelo, non in sequenza, così la risposta è immediata su tutti i dispositivi.

mode: queued con max: 3 garantisce che le rotazioni rapide vengano accodate invece di essere scartate: se ruoti veloce, gli step si accumulano fino a 3 in coda e vengono eseguiti in ordine senza perdere nulla.

alias: Dimmer Cucina
description: Cambia la luminosità della Cucina attraverso il Dimmer Cucina
triggers:
- alias: Dimmer 1 Ruota A Destra
  domain: mqtt
  device_id: IL_TUO_DEVICE_ID
  type: action
  subtype: rotate_right
  trigger: device
  id: Ruota a Destra
- alias: Dimmer 1 Ruota a Sinistra
  domain: mqtt
  device_id: IL_TUO_DEVICE_ID
  type: action
  subtype: rotate_left
  trigger: device
  id: Ruota a Sinistra
conditions: []
actions:
- alias: Scelta tra Ruota a Destra o a Sinistra
  choose:
    - conditions:
        - condition: trigger
          id:
            - Ruota a Destra
      sequence:
        - parallel:
            - device_id: ID_LUCE_1
              domain: light
              entity_id: ENTITY_ID_LUCE_1
              type: brightness_increase
            - action: light.turn_on
              target:
                entity_id: light.seconda_luce_cucina
              data:
                brightness_step_pct: 20
            - action: light.turn_on
              target:
                entity_id: light.terza_luce_cucina
              data:
                brightness_step_pct: 20
    - conditions:
        - condition: trigger
          id:
            - Ruota a Sinistra
      sequence:
        - parallel:
            - device_id: ID_LUCE_1
              domain: light
              entity_id: ENTITY_ID_LUCE_1
              type: brightness_decrease
            - action: light.turn_on
              target:
                entity_id: light.seconda_luce_cucina
              data:
                brightness_step_pct: -25
            - action: light.turn_on
              target:
                entity_id: light.terza_luce_cucina
              data:
                brightness_step_pct: -25
mode: queued
max: 3

Supervisione umana: sostituisci device_id, entity_id e i nomi delle luci con i valori reali. Il blocco parallel agisce su tutte le luci contemporaneamente — aggiungi o rimuovi voci in base alle luci che vuoi controllare. Il valore 20 / -25 è la percentuale di step per ogni rotazione: regolalo in base alla sensibilità che preferisci.

Nota su brightness_step_pct negativo: funziona da Home Assistant 2025.6+. Su versioni precedenti, usa brightness_step con valore negativo oppure due sequenze separate.

Automazione avanzata — Controllo Kelvin con la rotazione

Questa è la parte che preferisco: usare il knob per cambiare la temperatura colore delle luci in Kelvin, non solo la luminosità. Con le lampadine giuste — quelle che supportano CCT, cioè la regolazione del bianco caldo/freddo — la differenza di atmosfera in una stanza è notevole.

Servono due automazioni e un helper.

Step 1 — Creare l’helper input_number

Andiamo in Impostazioni → Helper → Crea helper → Numero e creiamo un input number che rappresenta il valore Kelvin corrente. Questo helper fa da “memoria” del valore tra un’azione e l’altra del knob.

Configurazione consigliata:

• Nome: Kelvin
• Entity ID: input_number.kelvin
• Valore minimo: 2700 (bianco caldo)
• Valore massimo: 6500 (bianco freddo/luce giorno)
• Step: 200 (incremento per ogni rotazione)

Step 2 — Automazione per aggiornare il valore Kelvin

Creiamo l’automazione che incrementa o decrementa l’helper ruotando il knob. Fondamentale: assegnare un ID ai due trigger (aumento e diminuisce) — serve per distinguerli nel blocco choose dell’azione.

alias: kelvin aumento/diminuzione
description: ""
triggers:
- domain: mqtt
  device_id: IL_TUO_DEVICE_ID
  type: action
  subtype: rotate_right
  trigger: device
  id: aumento
- domain: mqtt
  device_id: IL_TUO_DEVICE_ID
  type: action
  subtype: rotate_left
  trigger: device
  id: diminuisce
conditions: []
actions:
- choose:
    - conditions:
        - condition: trigger
          id:
            - aumento
      sequence:
        - action: input_number.increment
          target:
            entity_id: input_number.kelvin
          data: {}
    - conditions:
        - condition: trigger
          id:
            - diminuisce
      sequence:
        - action: input_number.decrement
          target:
            entity_id: input_number.kelvin
          data: {}
mode: queued
max: 3

Step 3 — Automazione per applicare il Kelvin alle luci

Questa seconda automazione si attiva ogni volta che il valore dell’helper cambia e lo passa alle luci. Ho usato il servizio yeelight.set_color_temp_scene perché le mie luci in cucina sono Yeelight — adatta il servizio alle luci che hai.

alias: Cambio Kelvin
description: Applica il valore Kelvin alle luci cucina
triggers:
- trigger: state
  entity_id: input_number.kelvin
conditions: []
actions:
- action: yeelight.set_color_temp_scene
  data:
    kelvin: "{{ states('input_number.kelvin') | int }}"
    brightness: 100
  target:
    entity_id:
      - light.yeelight_color_0x36ed322
      - light.cucina_luce_parete_n_2
mode: queued
max: 3

Supervisione umana: yeelight.set_color_temp_scene è specifico per le luci Yeelight. Per luci Zigbee standard usa light.turn_on con il parametro color_temp_kelvin: "{{ states('input_number.kelvin') | int }}". Verifica che le tue luci supportino la regolazione CCT prima di applicare questa automazione.

Modalità avanzata — Un knob, due funzioni

Con tre eventi fisici (rotazione destra, rotazione sinistra, click) e degli helper, le possibilità si moltiplicano. Un esempio pratico che uso: un helper dropdown che seleziona la modalità del knob, e il doppio click che cicla tra le modalità. Così con lo stesso knob posso sia dimmerare le luci che cambiare il Kelvin, senza toccare nulla altro.

Step 1 — Creare il dropdown input_select

In Impostazioni → Helper → Crea helper → Menu a tendina creiamo un input select con due opzioni, per esempio luminosita e kelvin.

Step 2 — Automazione per ciclare tra le modalità con doppio click

alias: Dimmer cambio modalità
description: ""
triggers:
- domain: mqtt
  device_id: IL_TUO_DEVICE_ID
  type: action
  subtype: double
  trigger: device
conditions: []
actions:
- action: input_select.select_next
  target:
    entity_id: input_select.modalita_dimmer
  data:
    cycle: true
mode: single

Step 3 — Aggiungere la condizione alle automazioni esistenti

Ora basta aggiungere una condizione alle automazioni di rotazione per farle attivare solo quando la modalità corrente corrisponde. L’automazione dimmer (luminosità) si attiverà solo se input_select.modalita_dimmer è su luminosita; l’automazione Kelvin solo se è su kelvin.

Ecco il dimmer aggiornato con la condizione:

alias: Dimmer Cucina
description: Cambia la luminosità della Cucina attraverso il Dimmer Cucina
triggers:
- alias: Dimmer 1 Ruota A Destra
  domain: mqtt
  device_id: IL_TUO_DEVICE_ID
  type: action
  subtype: rotate_right
  trigger: device
  id: Ruota a Destra
- alias: Dimmer 1 Ruota a Sinistra
  domain: mqtt
  device_id: IL_TUO_DEVICE_ID
  type: action
  subtype: rotate_left
  trigger: device
  id: Ruota a Sinistra
conditions:
- condition: state
  entity_id: input_select.modalita_dimmer
  state:
    - "luminosita"
actions:
- alias: Scelta tra Ruota a Destra o a Sinistra
  choose:
    - conditions:
        - condition: trigger
          id:
            - Ruota a Destra
      sequence:
        - parallel:
            - device_id: ID_LUCE_1
              domain: light
              entity_id: ENTITY_ID_LUCE_1
              type: brightness_increase
            - action: light.turn_on
              target:
                entity_id: light.seconda_luce_cucina
              data:
                brightness_step_pct: 20
            - action: light.turn_on
              target:
                entity_id: light.terza_luce_cucina
              data:
                brightness_step_pct: 20
    - conditions:
        - condition: trigger
          id:
            - Ruota a Sinistra
      sequence:
        - parallel:
            - device_id: ID_LUCE_1
              domain: light
              entity_id: ENTITY_ID_LUCE_1
              type: brightness_decrease
            - action: light.turn_on
              target:
                entity_id: light.seconda_luce_cucina
              data:
                brightness_step_pct: -25
            - action: light.turn_on
              target:
                entity_id: light.terza_luce_cucina
              data:
                brightness_step_pct: -25
mode: queued
max: 3

Supervisione umana: il valore della condizione "luminosita" deve corrispondere esattamente alle opzioni che hai definito nell’helper input_select. Se hai chiamato le opzioni diversamente (es. "1" e "2") adatta la condizione di conseguenza. Stessa logica per l’automazione Kelvin — aggiungi la condizione state: "kelvin" sul medesimo input_select.

Il toggle della variante Moes

La variante Moes (_TZ3000_gwkzibhs) espone un’azione aggiuntiva: toggle. A differenza di single — che è un evento puntuale usabile per qualsiasi logica — toggle è semanticamente pensato per accendere/spegnere direttamente. In pratica per chi usa HA la differenza è sottile, ma il nome nell’editor rende l’intenzione immediata.

alias: Dimmer Cucina Toggle
description: Toggle rapido su tutte le luci cucina
triggers:
- domain: mqtt
  device_id: IL_TUO_DEVICE_ID
  type: action
  subtype: toggle
  trigger: device
conditions: []
actions:
- action: light.toggle
  target:
    entity_id: light.cucina_tutte_le_luci
mode: single

Supervisione umana: questo YAML funziona solo con la variante Moes (_TZ3000_gwkzibhs). Su un knob con fingerprint _TZ3000_abrsvsou il trigger non si attiverà mai — usa single con la stessa logica, il risultato è identico.

Conclusioni

Questo tutorial copre gli esempi base da cui partire per sviluppare automazioni più articolate. Siamo partiti da piccole automazioni per costruire una base solida, ma le possibilità sono molte: controllare il volume dei dispositivi, cambiare scena, gestire più dispositivi contemporaneamente.

Con 3 eventi fisici per knob — rotazione destra, rotazione sinistra, click singolo — abbiamo già 3 azioni distinte. Aggiungendo doppio click e pressione prolungata arriviamo a 5. E con un helper dropdown che cambia modalità come abbiamo visto, le combinazioni diventano praticamente infinite. Un dispositivo da meno di 12 €, senza cloud, senza app, senza abbonamenti — che si configura una volta e funziona.

Recensione: Tuya Smart Knob ZG-101Z/D — due varianti, tre esemplari testati

Per approfondire le automazioni luci con Home Assistant.

Documentazione Zigbee2MQTT:

• Variante Tuya: zigbee2mqtt.io/devices/ZG-101Z_D.html
• Variante Moes: zigbee2mqtt.io/devices/ZG-101ZD.html