ikea-e1812-2022.yaml

# Blueprint metadata
blueprint:
  name: Controller - IKEA E1812 TRÅDFRI Shortcut button
  description: |
    # Controller - IKEA E1812 TRÅDFRI Shortcut button

    Controller automation for executing any kind of action triggered by the provided IKEA E1812 TRÅDFRI Shortcut button. 
    Allows to optionally loop an action on a button long press as well as built-in double-click.
    Supports deCONZ, ZHA, Zigbee2MQTT.

    Automations created with this blueprint can be connected with one or more [Hooks](https://epmatt.github.io/awesome-ha-blueprints/docs/blueprints/hooks) supported by this controller.
    Hooks allow to easily create controller-based automations for interacting with media players, lights, covers and more.
    See the list of [Hooks available for this controller](https://epmatt.github.io/awesome-ha-blueprints/docs/blueprints/controllers/ikea_e1812#available-hooks) for additional details.

    📕 Full documentation regarding this blueprint is available [here](https://epmatt.github.io/awesome-ha-blueprints/docs/blueprints/controllers/ikea_e1812).

    🚀 This blueprint is part of the **[Awesome HA Blueprints](https://epmatt.github.io/awesome-ha-blueprints) project**.

    ℹ️ Version 2022.01.02
  source_url: https://github.com/EPMatt/awesome-ha-blueprints/blob/main/blueprints/controllers/ikea_e1812/ikea_e1812.yaml
  domain: automation
  input:
    integration:
      name: (Required) Integration
      description: Integration used for connecting the remote with Home Assistant. Select one of the available values.
      selector:
        select:
          options:
            - deCONZ
            - ZHA
            - Zigbee2MQTT
    controller_device:
      name: (deCONZ, ZHA) Controller Device
      description: The controller device to use for the automation. Choose a value only if the remote is integrated with deCONZ, ZHA.
      default: ''
      selector:
        device:
    controller_entity:
      name: (Zigbee2MQTT) Controller Entity
      description: The action sensor of the controller to use for the automation. Choose a value only if the remote is integrated with Zigbee2MQTT.
      default: ''
      selector:
        entity:
          domain: sensor
    # inputs for custom actions
    action_button_short:
      name: (Optional) Button short press
      description: Action to run on short button press.
      default: []
      selector:
        action:
    action_button_long:
      name: (Optional) Button long press
      description: Action to run on long button press.
      default: []
      selector:
        action:
    action_button_release:
      name: (Optional) Button release
      description: Action to run on button release after long press.
      default: []
      selector:
        action:
    action_button_double:
      name: (Optional) Button double press
      description: Action to run on double button press.
      default: []
      selector:
        action:
    # inputs for looping custom actions on long button press events until the corresponding release event is received
    button_long_loop:
      name: (Optional) Button long press - loop until release
      description: Loop the button action until the button is released.
      default: false
      selector:
        boolean:
    button_long_max_loop_repeats:
      name: (Optional) Button long press - Maximum loop repeats
      description: >-
        Maximum number of repeats for the custom action, when looping is enabled.
        Use it as a safety limit to prevent an endless loop in case the corresponding stop event is not received.
      default: 500
      selector:
        number:
          min: 1
          max: 5000
          mode: slider
          step: 1
    # helpers used to properly recognize the remote button events
    helper_debounce_delay:
      name: (Optional) Helper - Debounce delay
      description:
        Delay used for debouncing RAW controller events, by default set to 0. A value of 0 disables the debouncing feature. Increase this value if you notice custom actions or linked Hooks running multiple times when interacting with the device. When the controller needs to be debounced,
        usually a value of 100 is enough to remove all duplicate events.
      default: 0
      selector:
        number:
          min: 0
          max: 1000
          unit_of_measurement: milliseconds
          mode: box
          step: 10
# Automation schema
variables:
  # convert input tags to variables, to be used in templates
  integration: !input integration
  button_long_loop: !input button_long_loop
  button_long_max_loop_repeats: !input button_long_max_loop_repeats
  helper_debounce_delay: !input helper_debounce_delay
  # integration id used to select items in the action mapping
  integration_id: '{{ integration | lower }}'
  # adjusted debounce delay so that the resulting double press delay is exactly as specified by the user when running the action, taking also account of debouncing
  # make sure it never goes below the minimum double press delay
  # mapping between actions and integrations
  actions_mapping:
    deconz:
      button_short: ['1002']
      button_long: ['1001']
      button_release: ['1003']
      button_double: ['1004']
    zha:
      button_short: ['on']
      button_long: [move_with_on_off_0_83]
      button_release: [stop]
      button_double: ['off']   # UNTESTED
    zigbee2mqtt:
      button_short: ['on']
      button_long: [brightness_move_up]
      button_release: [brightness_stop]
      button_double: ['off']
  # pre-choose actions for buttons based on configured integration
  # no need to perform this task at automation runtime
  button_short: '{{ actions_mapping[integration_id]["button_short"] }}'
  button_long: '{{ actions_mapping[integration_id]["button_long"] }}'
  button_release: '{{ actions_mapping[integration_id]["button_release"] }}'
  button_double: '{{ actions_mapping[integration_id]["button_double"] }}'
  # build data to send within a controller event
  controller_entity: !input controller_entity
  controller_device: !input controller_device
  controller_id: '{% if integration_id=="zigbee2mqtt" %}{{controller_entity}}{% else %}{{controller_device}}{% endif %}'
mode: restart
max_exceeded: silent
trigger:
  # trigger for zigbee2mqtt
  - platform: event
    event_type: state_changed
    event_data:
      entity_id: !input controller_entity
  # trigger for other integrations
  - platform: event
    event_type:
      - deconz_event
      - zha_event
    event_data:
      device_id: !input controller_device
condition:
  - condition: and
    conditions:
      # check that the button event is not empty
      - >-
        {%- set trigger_action -%}
        {%- if integration_id == "zigbee2mqtt" -%}
        {{ trigger.event.data.new_state.state }}
        {%- elif integration_id == "deconz" -%}
        {{ trigger.event.data.event }}
        {%- elif integration_id == "zha" -%}
        {{ trigger.event.data.command }}{{"_" if trigger.event.data.args|length > 0}}{{ trigger.event.data.args|join("_") }}
        {%- endif -%}
        {%- endset -%}
        {{ trigger_action not in ["","None"] }}
      # only for zigbee2mqtt, check if the event is relative to a real state change, and not only some minor changes in the sensor attributes
      # this is required since multiple state_changed events are fired for a single button press, with the result of the automation being triggered multiple times
      - '{{ integration_id != "zigbee2mqtt" or trigger.event.data.new_state.state != trigger.event.data.old_state.state }}'
action:
  # debouncing - when automation is triggered multiple times, the last automation run is the one which completes execution, due to mode restart
  # therefore previous runs must wait for the debounce delay before executing any other action
  # if the delay expires and the automation is still running it means it's the last run and execution can continue
  - delay:
      milliseconds: !input helper_debounce_delay
  # extract button event from the trigger
  # provide a single string value to check against
  - variables:
      trigger_action: >-
        {%- if integration_id == "zigbee2mqtt" -%}
        {{ trigger.event.data.new_state.state }}
        {%- elif integration_id == "deconz" -%}
        {{ trigger.event.data.event }}
        {%- elif integration_id == "zha" -%}
        {{ trigger.event.data.command }}{{"_" if trigger.event.data.args|length > 0}}{{ trigger.event.data.args|join("_") }}
        {%- endif -%}
  # choose the sequence to run based on the received button event
  - choose:
      - conditions: '{{ trigger_action | string in button_short }}'
        sequence:
          # fire the event
          - event: ahb_controller_event
            event_data:
              controller: '{{ controller_id }}'
              action: button_short
          # run the custom action
          - choose:
              - conditions: []
                sequence: !input action_button_short
      - conditions: '{{ trigger_action | string in button_long }}'
        sequence:
          # fire the event only once before looping the action
          - event: ahb_controller_event
            event_data:
              controller: '{{ controller_id }}'
              action: button_long
          - choose:
              # if looping is enabled, loop the action for a finite number of iterations
              - conditions: '{{ button_long_loop }}'
                sequence:
                  - repeat:
                      while: '{{ repeat.index < button_long_max_loop_repeats | int }}'
                      sequence: !input action_button_long
            # if looping is not enabled run the custom action only once
            default: !input action_button_long
      - conditions: '{{ trigger_action | string in button_release }}'
        sequence:
          # fire the event
          - event: ahb_controller_event
            event_data:
              controller: '{{ controller_id }}'
              action: button_release
          # run the custom action
          - choose:
              - conditions: []
                sequence: !input action_button_release
      - conditions: '{{ trigger_action | string in button_double }}'
        sequence:
          # fire the event
          - event: ahb_controller_event
            event_data:
              controller: '{{ controller_id }}'
              action: button_double
          # run the custom action
          - choose:
              - conditions: []
                sequence: !input action_button_double