Add first-class support for MQTT Device Triggers (to have feature parity with legacy triggers)


Both HA and Z2M recommend using non-legacy MQTT Device Triggers.

Unfortunately, as things stand now, things are bad with device triggers.

There are very few examples in the docs (if any). E.g. it’s not particularly easy finding discovery_id or even device_id (1 2 3 4). At least those are created by UI editor, but are not documented in here. You need to first “click” it with a UI and then reuse in yaml. The trigger variables do not cover Device Triggers at all, I had to deduce that it’s “same” as MQTT (which does make sense in the retrospect given it works through mqtt, but at least a sentence there would help).

Device Triggers basically cannot be used in blueprints due to the fact that discovery_id is needed while entity_id is missing, which is what all other platforms use in blueprints. Instead device_id is needed but that is a source of confusion elsewhere too. It seems that even plain mqtt events are now easier to deal with than device triggers.

Relevant discussions:

  1. Device triggers from zigbee2mqtt vs mqtt listen, and sometimes a bit about blueprints
  2. Zigbee2Mqtt - IKEA five button remote - #26 by dedi
  3. Modifying trigger in automation - #9 by steeveno
  4. MQTT Device Trigger combined with action/choose syntax

I think that either feature parity should be added or the recommendation of not using Legacy triggers should be removed until there is a plan to actually make device triggers the replacement.

Example of a simple automation:

alias: A single button with click, hold, release actions via z2m
mode: restart
max_exceeded: silent
  - platform: device
    domain: mqtt
    type: action
    subtype: button_1_single
    device_id: "d54bba99c4c741b8bc41118918730630"  # hard to fine - can be only found via first selecting the device via UI 
    discovery_id: 0x04cf8cdf3c7d8f7a action_button_1_single  # this is available only via UI and can't be reasonably templated in blueprints
    # generally a lot of duplication above (see the repeated "action" and "button_1_single"), adding additional actions for this
    # switch with short press/long press stuff results in 3 almost identical blocks (click, hold, release)
    # that means 6 very same blocks for a simple dimming button
  - variables:
      command: '{{ trigger.payload }}'  # trigger variables are same as MQTT, attributes like `type` or `subtype` are not available
  - choose:
      - conditions:
          - condition: template
            value_template: '{{ command == ''button_1_single'' }}'
          - service: mqtt.publish
              topic: dummyTopic
              payload: 'Hello world'

Can you post a link to this recommendation for Home Assistant?

MQTT Device trigger - Home Assistant states

An MQTT device trigger is a better option than a binary sensor for buttons, remote controls etc.

You appear to have misinterpreted the meaning of this sentence:

An MQTT device trigger is a better option than a binary sensor for buttons, remote controls etc.

You believe it recommends one type of trigger over another.

It is not recommending the avoidance of “Legacy triggers”. It’s stating that to model a button or remote control, it’s preferable to use a Device Trigger than a binary_sensor (that’s a type of entity, not a type of trigger).

For future reference, Device Triggers are simply a relatively recent addition to the available set of automation triggers. There’s no such thing as “legacy triggers”. That adjective implies something is outdated and it simply doesn’t apply here.

Device Triggers were designed for use with the Automation Editor; they reference device_id which is stored in the device registry and neither accessible via a template or revealed anywhere in the UI. Long story short, they weren’t meant to be composed by hand.

Some of that may change in the near future because there’s a PR in the works to allow templates to access information in the device_registry, such as device_id. In other words, some of what you are requesting may come to pass but not because there was ever a recommendation to avoid using other kinds of triggers.

Having said that, it won’t change the fact that Device Triggers are verbose and tedious to compose by hand compared to State Trigger, Event Trigger, Numeric State Trigger, etc.

I see, thank you for the explanation. Would you therefore say that the legacy is an unfortunate choice of words and should be ideally changed in zigbee2mqtt world to something else?

Is the word ‘legacy’ used to describe triggers in Home Assistant’s documentation or zigbee2mqtt’s documentation?

If it’s in zigbee2mqtt’s documentation then post a link to it because I would like to understand the context of its usage.

It’s right in the config docs:

  # Optional: Home Assistant legacy entity attributes, (default: shown below), when enabled:
  # Zigbee2MQTT will send additional states as attributes with each entity. For example,
  # A temperature & humidity sensor will have 2 entities for the temperature and
  # humidity, with this setting enabled both entities will also have
  # an temperature and humidity attribute.
  # Note: Disabling this option, requires a Home Assistant restart
  homeassistant_legacy_entity_attributes: true
  # Optional: Home Assistant legacy triggers (default: shown below), when enabled:
  # - Zigbee2mqt will send an empty 'action' or 'click' after one has been send
  # - A 'sensor_action' and 'sensor_click' will be discoverd
  homeassistant_legacy_triggers: true

here is the relevant discussion (I think) on github when this was added to z2m.

I regret to inform you but you misunderstood that description.

The word ‘legacy’ is not used in reference to Home Assistant’s triggers but to z2m’s own previous (legacy) method of processing information intended for Home Assistant.

No need to regret anything :man_shrugging: . I am just not sure it’s solved though. I am clearly not only one who’s confused (see the posts linked in the first thread) and therefore think that this should be dealt with somehow. Given how prominent z2m integration is (even per statistics), it would be good to have this clarified.

1 Like

If I understand the situation correctly, over a year ago they made the switch to modeling a button as a Device Trigger (as recommended in Home Assistant’s documentation) as opposed to their legacy method of modeling it as a binary_sensor with attributes. They maintain options to allow the user to switch back to the legacy method. Seems clear to me.

1 Like

Well, OK. Let this thread be a clarification for anyone else who might get confused.


Also officially recommended here: Home Assistant |

That page moved to here: Home Assistant | Zigbee2MQTT

So can I safely uncheck “Home Assistant legacy entity attributes” and “Home Assistant legacy triggers” in zigbee2mqtt? Or should I leave them on? What do I need to do differently when these checkboxes are switched off?