Perilla Zigbee como dimmer en Home Assistant (ZHA): por qué parpadea y cómo resolverlo

Una perilla Zigbee barata puede ser un excelente dimmer físico para Home Assistant, pero la primera automatización que uno escribe casi nunca funciona bien: la luz parpadea, se apaga sola o ignora toques. Esta nota resume qué eventos manda realmente el dispositivo y cómo armé dos automatizaciones que lo resuelven.

1. El problema

La perilla se empareja sin dificultad, pero el selector de dispositivos de Home Assistant (Agregar disparador → Dispositivo) no ofrece disparadores de giro ni de toque para este modelo: solo los genéricos de batería. Hay que escribir los disparadores a mano, escuchando eventos de ZHA, y para eso hace falta saber qué evento llega con cada gesto.

2. Qué eventos manda en realidad

La forma más directa de averiguarlo es Herramientas para desarrolladores → Eventos, escuchando zha_event mientras se usa la perilla. En mi caso:

3. Por qué fallan las primeras automatizaciones

• Leer args en lugar de params. La plantilla falla en silencio y la rotación no hace nada.
• Filtrar el toque por value: true. Como el valor alterna, hay toques que quedan descartados sin querer.
• Separar el toque y el doble toque en dos automatizaciones. Un doble toque dispara las dos al mismo tiempo, compiten, y el resultado es la luz que sube al 100 % y se apaga sola con un fundido.

4. La solución: dos automatizaciones

La idea es una automatización para el botón (toque y doble toque juntos, en modo single, para que el primer evento bloquee a los rezagados) y otra aparte para el giro (modo queued, para no perder pasos cuando se gira rápido). Reemplazá la dirección IEEE y light.dimmer_lamp por los de tu instalación.

Botón:

alias: Perilla - boton
mode: single
max_exceeded: silent
triggers:
  - trigger: event
    event_type: zha_event
    event_data:
      device_ieee: "AA:BB:CC:DD:EE:FF:00:11"
      command: remote_button_double_press
    id: doble
  - trigger: event
    event_type: zha_event
    event_data:
      device_ieee: "AA:BB:CC:DD:EE:FF:00:11"
      command: attribute_updated
      args:
        attribute_name: on_off
    id: click
actions:
  - if:
      - condition: trigger
        id: doble
    then:
      - action: light.turn_on
        target: { entity_id: light.dimmer_lamp }
        data: { brightness_pct: 100 }
    else:
      - wait_for_trigger:
          - trigger: event
            event_type: zha_event
            event_data:
              device_ieee: "AA:BB:CC:DD:EE:FF:00:11"
              command: remote_button_double_press
        timeout: { milliseconds: 400 }
      - if:
          - condition: template
            value_template: "{{ wait.trigger is none }}"
        then:
          - action: light.toggle
            target: { entity_id: light.dimmer_lamp }
        else:
          - action: light.turn_on
            target: { entity_id: light.dimmer_lamp }
            data: { brightness_pct: 100 }
  - delay: { milliseconds: 600 }

Giro:

alias: Perilla - giro
mode: queued
max: 25
triggers:
  - trigger: event
    event_type: zha_event
    event_data:
      device_ieee: "AA:BB:CC:DD:EE:FF:00:11"
      command: step
conditions:
  - condition: template
    value_template: >
      {{ is_state('light.dimmer_lamp', 'on')
         or trigger.event.data.params.step_mode == 0 }}
actions:
  - action: light.turn_on
    target: { entity_id: light.dimmer_lamp }
    data:
      brightness_step: >
        {{ (trigger.event.data.params.step_size * 2.5) | round(0)
           * (1 if trigger.event.data.params.step_mode == 0 else -1) }}
      transition: 0.2

El factor 2,5 ajusta la sensibilidad. La condición hace que, con la lámpara apagada, girar hacia arriba la encienda y girar hacia abajo no haga nada.

Con esta configuración, en mi instalación girar sube y baja el brillo, el toque simple alterna la luz sin parpadeo y el doble toque la lleva al 100 %.

5. Limitaciones

• El delay de 600 ms al final de la automatización del botón absorbe los eventos rezagados de un doble toque. A cambio, dos toques simples deliberados necesitan cerca de un segundo de separación.
• El comportamiento descripto corresponde a un modelo, un firmware y una versión de ZHA. Si tu perilla es distinta, empezá por mirar sus eventos como en la sección 2 antes de copiar el código.
• El mismo patrón sirve como punto de partida para más perillas del mismo modelo: una automatización de botón y una de giro por dispositivo.

Más sobre el trabajo de desarrollo a medida: IoT, sistemas embebidos y domótica.

Fernando BergamiIngeniero de Sonido (UNTREF). Diseño sistemas embebidos y telemetría desde 2012. Vive y trabaja en Salta.