Home Assistant
Included with Macro DeckSwitch lights, run scenes and scripts, and show live states from your Home Assistant on your deck.
The Connect Home Assistant dialog with the Address and Long-lived access token fields
- Turn entities on, off or toggle them, with buttons that show their state
- Set lights, covers, thermostats and media players
- Run scenes, scripts and automations, or call any service
- Live variables for any entity state or attribute
- Triggers on state changes and on events from the event bus
The Home Assistant integration connects Macro Deck to your Home Assistant over its WebSocket API. Macro Deck keeps one connection open, so states arrive the moment they change in Home Assistant, and actions run right away. Home Assistant can run anywhere Macro Deck can reach it: on the same computer, a Raspberry Pi or server in your network, or a remote address.
What you can do
- Turn one or more entities on or off, or toggle them. A button with Toggle lights up while the entity is on.
- Set a light's state, brightness, color, color temperature and transition with Set Light.
- Open, close, stop or position a cover, set a thermostat's temperature, mode, fan mode and preset, and control the playback and volume of a media player.
- Activate a scene, run a script with variables, and trigger, enable or disable an automation.
- Call any service with Call Service, with entities, devices or areas as the target and data as JSON.
- Read an entity's state or attribute into a Macro Deck variable with Get Entity State.
Some example setups:
- A button with Toggle for your desk lamp that shows whether the lamp is on.
- A Movie button that activates your movie scene and pauses the music on a media player.
- A slider bound to a light's brightness, so you dim it from the deck and see changes made in Home Assistant.
- A button whose label shows the temperature of a sensor, and a flow on Entity State Changed that shows a notification when the front door opens.
Variables and live updates
Home Assistant offers far more values than Macro Deck lists up front. You find every entity in the collapsed Unbound variables group of the integration's variables, on the Variables page and in every variable picker. Open an entity to see its state and attributes and choose Bind on the one you need: it becomes a normal variable that updates live. A slider can control a light's brightness, a fan's speed, a cover's position, a media player's volume or a thermostat's temperature this way.
When the connection drops, Macro Deck reconnects by itself, waiting a little longer after each failed try, up to one minute. The Connected and Disconnected triggers fire when that happens, and actions fail with a message while Home Assistant is not connected. You can connect one Home Assistant.
What you need
- A running Home Assistant that Macro Deck can reach, for example
http://homeassistant.local:8123. - A Home Assistant user account to create a long-lived access token with.
- For an
https://address: a certificate your computer trusts.
Set it up
Step 1: Create a long-lived access token
In Home Assistant, open your profile and go to the Security tab. Scroll to Long-lived access tokens, create a token, name it
Macro Deckand copy it. Home Assistant shows it only once.Step 2: Open the Home Assistant integration
In Macro Deck, click Integrations in the sidebar and click Home Assistant. On the Overview tab, click Set up in the Configuration section. Turning on the switch at the top right opens the same dialog, and the integration is turned on once the setup is done.
Step 3: Enter the address and token
In the Connect Home Assistant dialog, enter:
- Address: the address you open Home Assistant with, including the port, for example
http://homeassistant.local:8123. - Long-lived access token: the token you just copied.
When you click Continue, Macro Deck tests the connection and saves it as Home Assistant with your home's name in parentheses.
- Address: the address you open Home Assistant with, including the port, for example
Step 4: Add an action to a button
On the Deck page, click a button. The deck must be unlocked: when the Lock button shows at the top right, it is. The editor opens with Short Press selected. Click + Add action, select Home Assistant on the left of the Add action dialog, pick Toggle and choose one or more Entities, for example a light.
Step 5: Press the button
Press the button on your deck. The light switches in Home Assistant, and the button shows whether it is on.
Step 6: Bind a value to show on a button
To show a value, open the Variables tab of the Home Assistant page and open the Unbound variables group. Open an entity and click Bind on its state or an attribute. Use the new variable in a label, for example
{{ vars.ha_sensor_living_room_temperature }}.
Actions12
Put these on a button or run them from a flow.
- Call Service
- Calls any Home Assistant service with optional entities, devices, areas and data as JSON.
- Turn On
- Turns one or more entities on.
- Turn Off
- Turns one or more entities off.
- Toggle
- Toggles one or more entities, and shows on the button whether they are on.
- Set Light
- Switches a light and sets its brightness, color, color temperature and transition.
- Control Cover
- Opens, closes or stops a cover, or sets its position or tilt position.
- Control Media Player
- Plays, pauses, stops, skips, mutes or sets the volume of a media player.
- Set Thermostat
- Sets the target temperature, mode, fan mode and preset of a thermostat.
- Activate Scene
- Activates a scene, with an optional transition.
- Run Script
- Runs a script, optionally with variables as a JSON object.
- Control Automation
- Triggers, enables, disables or toggles an automation, optionally ignoring its conditions.
- Get Entity State
- Reads an entity's state or one of its attributes into a Macro Deck variable.
Triggers4
A button or flow can react to these events.
- Connected
- Macro Deck connected to Home Assistant.
- Disconnected
- The connection to Home Assistant was lost.
- Entity State Changed
- An entity changed state, optionally only for a domain, an entity, or a change from or to a certain state.
- Home Assistant Event
- Anything on the Home Assistant event bus, such as automations, scripts, ZHA and deCONZ button presses or custom events, optionally only one event type.
Variables5
Show these values on buttons and widgets, or use them in conditions.
homeassistant_is_connected- Whether Macro Deck is connected to Home Assistant.
homeassistant_version- The version of your Home Assistant.
homeassistant_location_name- The name of your home.
homeassistant_entity_count- How many entities your Home Assistant has.
ha_<entity>,ha_<entity>_<attribute>- The state or any attribute of an entity, once you bind it from Unbound variables. The name is suggested from the entity id, for example
ha_light_office_lamporha_light_office_lamp_brightness_pct. Many can also be set, for example a light'sbrightness_pct.
Frequently asked questions
Does Home Assistant have to run on the same computer?
No. Macro Deck connects over the network, so Home Assistant can run on a Raspberry Pi, a server or a remote address, as long as Macro Deck can reach it.
Can I connect more than one Home Assistant?
No. The integration supports one Home Assistant. Running the setup again replaces the connection, and your buttons keep working.
Setup says the certificate could not be validated. What can I do?
Your computer does not trust the certificate of your https:// address. Trust it in your operating system's certificate store, or connect over http:// on your local network.
Home Assistant behind a reverse proxy does not connect. Why?
Some proxies block requests they take for automated traffic. Open Settings > Advanced > HTTP and enter a value the proxy accepts under HTTP User-Agent.
What happens when the connection drops?
Macro Deck reconnects by itself and fires the Disconnected and Connected triggers. When it cannot reach Home Assistant for a while, the integration shows Home Assistant is unreachable and keeps trying in the background.
Where is my access token stored?
The token is stored encrypted on your computer and never leaves it except to talk to your Home Assistant. When Home Assistant rejects it, the integration shows an issue: create a new token and run the setup again.
More in Smart home and web
AdGuard Home
Included with Macro DeckTurn AdGuard Home protection on, off or pause it, and show its statistics on your deck.
RSS feeds
Included with Macro DeckFollow RSS and Atom feeds, show their newest articles in widgets and react when new articles arrive.
HTTP
Included with Macro DeckSend HTTP requests from a button and save values from the response into variables.
Weather
Included with Macro DeckShow the current weather and the forecast for your locations on your deck, without an API key.