Set up your Automations

Automations are going to be highly dependent on your specific setup. In this example, we will be using a couple of devices called office_light, which is a switch and test_dimmer, which is a dimmable light. You will want to change these values to suit your specific setup. The code below provides 3 different automations to attach the events from the MacroPad to different actions and will go over those in a bit of detail.

To begin, you'll want to open up the File Editor and add some automations.

Click on the Folder Icon at the top and select automations.yaml, then click on an area to the right of the file list to close it.

Light Toggle Automation

The first automation simply toggles the dimmer light on and off whenever it receives a keypress on key number 0 of the MacroPad, which is the upper right button.

- id: macropad_button_0
  alias: "Demo Light Toggle"
    - platform: mqtt
      topic: "macropad/peripheral"
      payload: "0"
      value_template: "{{ value_json.key_number }}"
  condition: "{{ trigger.payload_json.key_number is defined }}"
    service: light.toggle
    entity_id: light.test_dimmer

The alias is just a friendly name to display in the control panel.

Under the trigger section the code is set up to look for the macropad/peripheral topic on the mqtt server and trigger when it sees a value of 0. The value_template tells the automation where the payload value is in the JSON that is published by the MacroPad.

Under the condition section, The code triggers only if key_number is defined. This is important because when the encoder is used, there is no key_number defined, and it can cause some warnings in Home Assistant. Also, you may note the use of payload_json instead of value_json and that's just one of the quirks of home assistant.

Under the action section, it is just telling the test_dimmer, which is a light, to trigger the light.toggle event.

Switch Toggle Automation

The second automation simply toggles the office light on and off whenever it receives a keypress on key number 1 of the MacroPad, which is the upper center button. This is nearly identical to the light automation, so only the differences are covered.

- id: macropad_button_1
  alias: "Office Light Toggle"
    - platform: mqtt
      topic: "macropad/peripheral"
      payload: "1"
      value_template: "{{ value_json.key_number }}"
  condition: "{{ trigger.payload_json.key_number is defined }}"
    service: switch.toggle
    entity_id: switch.office_light

The main differences here are making use of the switch type of device instead of a light and the payload value waited for is 1.

Dimmer Automation

This one is the trickiest because the MacroPad is only sending the changes in the rotation. This allows other controls such Home Assistant itself to also adjust the dimmer. However, by only sending the changes, you don't need to worry grabbing the current brightness setting, modifying it, and then sending the new absolute value back. However, that would have been another way to do it.

There may be a small bit of lag between adjusting the knob and seeing the change due to going through several layers.
- id: macropad_dimmer
  alias: "Demo Light Dimmer"
    - platform: mqtt
      topic: "macropad/peripheral"
      value_template: "{{ value_json.encoder }}"
  condition: "{{ trigger.payload_json.encoder is defined }}"
    service: light.turn_on
      entity_id: light.test_dimmer
      brightness: >
        {% set current = state_attr('light.test_dimmer', 'brightness') %}
        {% set delta = trigger.payload_json.encoder|int * 10 %}
        {{ current + delta }}

Just like before, the alias, trigger, and condition sections are similar, but this time there is not a specific payload value defined to trigger on. It will trigger based on the condition alone, which is that there is an encoder value defined.

Under the action section is where you will notice most of the differences. To adjust the brightness of the bulb, you need to make use of the light.turn_on service this time. In order to calculate the new brightness, we make use of templates. Templating is powered by the Jinja2 templating engine.

Under the data_template, the code tells which entity to adjust and the brightness value that it should be set to. This is calculated by taking the current value which is between 0-255, taking the delta, or change in the encoder knob, and multiplying by 10 so you don't need to crank the knob 20-30 times to get it to go from full dimness to full brightness. Then the final brightness value that it should adjust to is output.

Save Your Config

Once you're done with adding the automations to your automations.yaml file, you'll want to restart your Home Assistant service.

Click the save button at the top.

From the Developer Tools menu, you can check that the configuration is valid and click on Restart to load the configuration changes you made. You can just click Quick reload to reload any changes you made.

Once you have restarted, make sure the host computer is running its script and try pressing the top buttons on your MacroPad. They should toggle your lights. If you have a dimmer, try turning the encoder and it should dim your lights.


If you see the icons, but there is no data, it is easiest to start by checking the MQTT messages. There is a guide on how to use Desktop MQTT Client for, which can be used for the Home Assistant MQTT server as well.

Go ahead and configure a username and password to match your MQTT server and connect. Under subscribe, you can subscribe to the # topic to get all messages.

If you are seeing messages from the sensor, you may want to double check your Home Assistant configuration.

If you don't see any messages, you will want to follow the debugging section on the Code the Sensor page.

This guide was first published on Aug 11, 2021. It was last updated on Jun 21, 2024.

This page (Home Assistant Configuration) was last updated on Mar 08, 2024.

Text editor powered by tinymce.