Controllers-Hooks Ecosystem

Introduction

The Controllers-Hooks ecosystem includes a set of blueprints which allow to easily create controller-based automations in just a few clicks. As the name implies, it consists of two main blueprint categories: Controllers and Hooks.

Controllers

Controllers are blueprints which allow to easily integrate a wide range of controllers (wall switches, remotes, dimmers, etc.) and use them to run a set of actions when interacting with them. They consist in a practical abstraction layer for building controlled-based automations without worrying about the handling of RAW controller events and the integration used to connect controllers to Home Assistant (Zigbee2MQTT, ZHA, deCONZ, ZWave, proprietary hubs, etc.).

info

The type of exposed events depends on the controller model. Some controllers can also expose virtual events. You can read more about them here.

Most importantly, beside providing custom action sequences to Controller blueprints, you can connect Controllers with Hooks.

Helper - Last Controller Event Input

The helper_last_controller_event (Helper - Last Controller Event) input is a generic input_text entity which serves as a permanent storage area for a Controller automation. Currently the following information is stored:

• Last Controller event: the latest event which was fired by the controller.
• Last triggered time: the date/time the latest controller event was fired.

The stored info is used in many different ways to implement the blueprint's core functionality:

• Action Recognition: Some controllers use the info contained in the helper to recognize some actions. This varies between different controller models and integrations. Since natively the device doesn't allow to distinguish between certain events, the blueprint needs to store the last event, and take advantage of this information to identify subsequent actions.
• Virtual Events: The last controller event is used to implement virtual events. You can read more about them here.

This field requires that you have an existing text helper. Therefore, before setting up the automation, manually create a brand new input_text entity in your Home Assistant instance (e.g. from the Helpers configuration page), then provide it to the blueprint while configuring the automation.

caution

Make sure the text input is not altered by any other agents. The provided entity is used as a permanent storage area for the controller automation; any change to its state not carried out by the respective automation could lead to inconsistencies and unexpected behaviour.

Therefore, you should create a separate text input for each Controller blueprint you're configuring.

Virtual Events

Virtual events are particular events which are not natively exposed by the controller itself. They're instead generated by the blueprint, which derives them from the incoming RAW controller events and by using the helper_last_controller_event input and additional helpers.

Controllers, depending on the device model and functionality, currently support the following virtual events:

• Virtual button double press:

  Implemented by relying on the helper_last_controller_event input, used to store the last short press event, and a delay (specified with the helper_double_press_delay input), which represents the maximum time gap between the first and second short press required to trigger the virtual double press.

  When double press events are enabled for a specific button, clicking the button results in the automation first waiting for the second button press, then, if none is received within the provided delay, executing the short press action.

  If double press events are disabled for a specific button, the corresponding single press action will be executed immediately when the button is pressed.

tip

Such events can introduce some delay in the automation, therefore they can be disabled when not needed, thanks to a dedicated blueprint input.

Hooks

Hooks are blueprints which seamlessly integrate with Controllers to enable control of lights, media players and much more, without you ever writing a single line of code.

While Controllers are responsible for integrating the hardware and exposing an abstract interface to the user, Hooks can, as the name suggests, link to this interface and listen for events fired by a Controller. With the received events, Hooks take care of providing the actual control functionality for common use cases (eg. controlling a Media Player).

How to build a controller-based automation

Basic Usage: Controller with custom actions

The simplest use case for such blueprints consists in creating an entirely custom controller-based automation, which can be done by using only a Controller blueprint.

When setting up an automation with a Controller blueprint, you'll be asked to select the integration used to connect the controller to Home Assistant, and the device or entity (depending on the integration) representing the Controller. You can then specify a sequence of actions for each of the events the controller exposes.

Each time an event is fired by the controller (eg. button press) the automation will run the provided custom action corresponding to that specific event.

tip

Even in this simple scenario, you can still benefit from most of the features of the ecosystem: the blueprint will take care of handling the RAW events fired by the controller, as well as providing virtual events (eg. double clicks) not natively exposed by the controller.

Controller and Hook

If you want to build a controller-based automation with Hooks, first create an automation with a Controller blueprint. You can then build an automation with the desired Hook blueprint, making sure that you provide the same controller device or entity used in the corresponding Controller blueprint. This key step will link the two automations and ensure the Hook will respond to events fired by the Controller.

info

Please note that not all controllers might be used with each of the available Hooks. Check out the Hook documentation for the list of supported controllers for that specific Hook.

Controller and Hook + Custom actions

If you need to customize certain actions or extend a Hook functionality, you can also provide custom actions to the Controller blueprint, which will be run when a certain event is raised.

Controller with multiple Hooks

For more flexibility, you can link multiple Hooks to the same Controller: just create a Controller automation, then build as many Hook automations as needed.

This might be useful when you'd like to control multiple devices with the same controller (eg. multiple media players or lights) without relying on Home Assistant groups.

Examples

Control a media player with an IKEA E1743

# Controller automation: integrate the IKEA E1743
- alias: Controller - IKEA E1743 Kitchen
  description: ''
  use_blueprint:
    path: EPMatt/ikea_e1743.yaml
    input:
      integration: Zigbee2MQTT
      controller_entity: sensor.ikea_e1743_action
      helper_last_controller_event: input_text.ikea_e1743_helper
      button_up_double_press: true
      button_down_double_press: true

# Hook automation: Link the media player with the Controller
- alias: Hook - Control Kitchen Media Player with E1743
  description: ''
  use_blueprint:
    path: EPMatt/media_player.yaml
    input:
      # Provide the same value used in the Controller automation
      # This ensures this automation will catch events fired by the E1743
      controller_entity: sensor.ikea_e1743_action
      controller_model: IKEA E1743 On/Off Switch
      media_player: media_player.kitchen

Light control with an IKEA E1810 + activate scene with double click

# Controller automation: integrate the IKEA E1810
- alias: Controller - IKEA E1810 Living Room
  description: ''
  use_blueprint:
    path: EPMatt/ikea_e1524_e1810.yaml
    input:
      integration: Zigbee2MQTT
      controller_entity: sensor.ikea_e1810_action
      # Example of custom action
      # activate a scene when double clicking the center button
      action_button_center_double:
        - scene: scene.cinema_mode

# Hook automation: link the light with the Controller
- alias: Hook - Control living room lights with IKEA E1810
  description: ''
  use_blueprint:
    path: EPMatt/light.yaml
    input:
      light_color_mode: RGB
      # Provide the same value used in the Controller automation
      # This ensures this automation will catch events fired by the E1810
      controller_entity: sensor.ikea_e1810_action
      controller_model: IKEA E1524/E1810 5-Button remote
      light: light.livingroom_ceiling

How does it work

note

This section discusses the communication and inner implementation of Controllers and Hooks. You don't need to read or know it to properly use these blueprints.

Note

This documentation section is currently under review.