Using Keyboard Macro Keys To Control HomeAssistant

I recently purchased a Logitech keyboard and while I didn’t particularly care for the macro keys I decided to look into whether I could program them to control HomeAssistant.

This proved to be rather painless but there are a few steps necessary so I wanted to throw up a short guide. While this is specific to Logitech keyboards I’m confident the same can done for other brands by substituting the correct software to program the keys, the rest of the steps will be identical.

We will need to set up a few of things to make this work:

1. Enabling the HomeAssistant REST API
2. Setting up scripts to call the API
3. Installing Logitech (or other manufacturer) control software
4. Mapping the keys to the scripts

Enabling HomeAssistant REST API

Enabling the API as is quick as adding api: to the configuration.yaml file. I did this using the File Editor add-on.

Once enabled head over to your profile within the UI and create a Long Lived Access Token.

With the access token we can now use simple curl.exe commands to make requests to to the API. In the commands below, replace instances of <HABearerToken> with your HA token.

Setting up scripts to call the API

The HomeAssistant REST API documentation covers what is possible via the API.

To trigger an action we need to to query the /api/services/<domain>/<service> endpoint. The best way I found to query all the available domains and services was via the the /api/services endpoint. This produces a lot of unformatted JSON output so we’re going to send it to a file.

curl.exe -X GET -H "Authorization: Bearer <HABearerToken>" -H "Content-Type: application/json" http://homeassistant.local:8123/api/services > services.txt

There will be a generic light domain which contains a toggle service, this can be used to toggle the power state of a specified light. If you wish to achieve something different you’ll need to dig through your domains and services and find the appropriate endpoints.

We’re going to create a batch file and once again use curl.exe to make an API call, but this time it will toggle a smart light.

curl.exe -X POST -H "Authorization: Bearer <HABearerToken>" -H "Content-Type: application/json" http://homeassistant.local:8123/api/services/light/toggle -d "{\"entity_id\":\"light.officelight1\"}"

To get the entity_id of a device within HA, navigate to the device properties and look at the Entities section.

Save the file somewhere appropriate on your system with a .bat extension.

Installing Logitech (or other manufacturer) control software

For Logitech keyboards we need to install the G Hub software. This will enable us to program the Macro keys.

Other manufacturers will have equivalent applications.

Mapping the keys to the scripts

The last step is to map our batch file to a macro key. Within G Hub, navigate to Assignments > System > Launch Application > Add Application. Specify a name and set the path to the batch file.

Finally, click on the Macro key you wish to assign the function to and select the newly created application.

That’s it! Pressing the G1 button now toggles the office lights on and off. Next step will be to set G2 to turn on the coffee machine 😀.