# Home Assistant + Elgato Stream Deck — Setup Guide

Free. No coding. About 10 minutes.

## What you need
- Any Stream Deck (Mini, MK.2, Plus, XL — all work)
- Home Assistant already running on your network (this guide does not cover installing it)
- That's it. The plugin is free — no subscription, no cloud account, no sign-up.

Note: Home Assistant does not need special hardware. Mine runs on a 12-year-old
Dell OptiPlex 7020 bought off Facebook Marketplace for about $50.

---

## Step 1 — Install the Home Assistant plugin
1. Open the Stream Deck app.
2. Go to the **Store** (Marketplace) and search **Home Assistant**.
3. Install the plugin by **Christoph G.**
4. It appears in your actions list with two options:
   - **Entity generic**
   - **Entity custom icons** ← use this one if you want the button to swap
     between two different images for on/off.

## Step 2 — Create a Long-Lived Access Token
1. In Home Assistant, click **your name** at the bottom of the sidebar.
2. Open the **Security** tab.
3. Scroll to the very bottom: **Long-Lived Access Tokens**.
4. Click **Create Token**, name it `Stream Deck`, and **copy it immediately**.
   Home Assistant shows it exactly once. Close the window and you'll have to
   make a new one.
5. The token is valid for 10 years, so this is a one-time job.

## Step 3 — Connect a button
1. Drag the Home Assistant action onto any empty button.
2. Enter your Home Assistant address and paste the token.
   - Example: `http://192.168.1.50:8123` — local IP, port 8123, plain http.
3. Save. If the entity dropdown fills with your real devices, you're connected.

## Step 4 — Configure the three fields
- **Domain** — the type of thing: `light`, `switch`, `fan`
- **Service** — what it should do: `toggle` (also `turn_on`, `turn_off`)
- **Entity** — which specific device

Tip: a regular lamp on a ~$15 smart plug shows up under `switch`, not `light`.
That's how any dumb fixture you already own becomes a button.

---

## The mistake that makes buttons look broken
Every button has **two** entity settings, not one:

| Tab | What it controls |
| --- | --- |
| **Short Press** | What the button *does* when pressed |
| **Appearance** | What the icon *watches* to decide on/off |

If you duplicate a button to save time, one of those comes along and the other
doesn't. The button still works — the light turns on — but the icon sits frozen
and it looks like the plugin is broken. It isn't. It's watching a different
device.

**If the button works but the picture never changes: check the Appearance tab.**

## Rename your devices first
Four of my bulbs were all named "Smart RGBTW Bulb." Identical. A few buttons
ended up crossed because I couldn't tell which was which. Give every entity a
custom name in Home Assistant *before* you start wiring buttons.

## Custom icons (animated GIFs work)
- Stream Deck accepts animated GIFs as button images.
- You get two images per button — one per state.
- You can only set the image for the state the device is in **right now**.
  The two dots under the icon aren't a picker; they show the current state.
- So: turn the device **on**, set image one. Turn it **off**, set image two.

Make the icons look like the actual fixtures — the floor lamp, the umbrella
light, the spinning ceiling fan. Animation sells it.

---

## The shortcut: let an AI assistant do it
An AI assistant with access to your computer (Claude with computer use, for
example) can drive the Stream Deck app directly:

- Find every device and fill in domain / service / entity for each button
- Save the configs
- Audit each button one at a time and catch crossed wiring (press one light,
  watch another)
- Generate the custom icons from a plain-English description

It can't press a physical key on the deck, but it can do all the tedious
middle part — seven buttons, four fields each.

### Prompt to paste

```
You have access to my computer. The Elgato Stream Deck app and Home Assistant
are both open.

1. List every Home Assistant entity available in the plugin dropdown, grouped
   by domain (light, switch, fan).
2. For each button I name below, configure the Home Assistant "Entity custom
   icons" action: set Domain, Service (toggle), and Entity on the Short Press
   tab, AND set the matching entity on the Appearance tab.
3. When done, go through every button one at a time and verify the Short Press
   entity and the Appearance entity are the same. Report any mismatches.

Buttons:
- [button name] -> [device]
```

---

Everything here is free. Full walkthrough: https://chadesheppard.com/home-assistant-stream-deck