From 52d17e70ebced97798074ca4186241aad47050b3 Mon Sep 17 00:00:00 2001 From: Brandon Harvey <8107750+bharvey88@users.noreply.github.com> Date: Thu, 21 May 2026 08:59:43 -0500 Subject: [PATCH] docs: add Connect to Home Assistant tutorial + HA Integration Learn the Basics page (#845) Adds two Starter Kit pages covering how the device shows up in Home Assistant: - tutorials/connect-to-home-assistant.md: step-by-step for accepting the device into Home Assistant, confirming entities, and a small troubleshooting section. - learning-the-basics/how-esphome-talks-to-home-assistant.md: the conceptual companion, titled "HA Integration" in the nav. Covers auto-discovery, the encryption key, how components become entities, and how the on-device web page coexists with Home Assistant. Network edge cases collapsed into a single admonition that links to the UniFi mDNS troubleshooting guide. Both pages use my.home-assistant.io My redirect links and badges for any "open X in Home Assistant" reference, so readers land at the right spot in their own instance without clicking around. Other touch-ups in the same PR: - setup/first-steps.md footer: three buttons (Back - Start Here, Add More Modules, Connect to Home Assistant). - learning-the-basics/explaining-esphome.md: cross-link to the new HA Integration page from the "From Home Assistant" subsection, and link the on-device web page hostname so readers can click straight to it. Same actionable-URL fix on the new HA Integration page. Co-authored-by: Brandon Harvey --- .../learning-the-basics/explaining-esphome.md | 4 +- .../how-esphome-talks-to-home-assistant.md | 57 +++++++++++++++++++ .../ESPHome-Starter-Kit/setup/first-steps.md | 2 +- .../tutorials/connect-to-home-assistant.md | 50 ++++++++++++++++ mkdocs.yml | 2 + 5 files changed, 113 insertions(+), 2 deletions(-) create mode 100644 docs/products/ESPHome-Starter-Kit/learning-the-basics/how-esphome-talks-to-home-assistant.md create mode 100644 docs/products/ESPHome-Starter-Kit/tutorials/connect-to-home-assistant.md diff --git a/docs/products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md b/docs/products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md index 2a1f1d7647..ff37dc751b 100644 --- a/docs/products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md +++ b/docs/products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md @@ -23,12 +23,14 @@ Once your device is flashed, you can control it two ways: #### From any web browser -ESPHome's built-in **Web Server** component (the Starter Kit's First Steps walks you through adding it) makes your device serve its own local web page. Open `esphome-starter-kit.local` or its IP address in any browser on your network, on a phone or PC, and you can toggle the LED, view sensor readings, and control the device directly. No Home Assistant required. +ESPHome's built-in **Web Server** component makes your device serve its own local web page. Open esphome-starter-kit.local (or the device's IP address) in any browser on your network, on a phone or PC, and you can toggle the LED, view sensor readings, and control the device directly. No Home Assistant required. See the [Web Server in Core Components](core-components.md#web-server) for more. #### From Home Assistant Home Assistant discovers your device automatically through the **ESPHome integration**. Each of your device's sensors, switches, and lights then appears in Home Assistant as an entity you can use in dashboards and automations. +For more on how this works under the hood, see [the Home Assistant integration](how-esphome-talks-to-home-assistant.md). + A typical flow looks like this: 1. Click **Add component** in **ESPHome Device Builder** and pick what is connected to your device. No code or YAML required. diff --git a/docs/products/ESPHome-Starter-Kit/learning-the-basics/how-esphome-talks-to-home-assistant.md b/docs/products/ESPHome-Starter-Kit/learning-the-basics/how-esphome-talks-to-home-assistant.md new file mode 100644 index 0000000000..fbd070a697 --- /dev/null +++ b/docs/products/ESPHome-Starter-Kit/learning-the-basics/how-esphome-talks-to-home-assistant.md @@ -0,0 +1,57 @@ +--- +title: HA Integration +description: A conceptual overview of how ESPHome devices announce themselves to Home Assistant, what the encryption key is for, and how device components turn into Home Assistant entities. +--- +# HA Integration + +The **ESPHome integration** is what makes your Starter Kit visible to Home Assistant. Once it's set up, every switch, sensor, and light you defined in ESPHome Device Builder appears in Home Assistant as something you can read, control, or automate against. This page explains how that handoff actually works. + +## Auto-discovery + +When your Starter Kit boots, it announces itself on your local network. Home Assistant listens for those announcements and shows your device under **Settings → Devices & services** as soon as it sees one. + +This is why most users do not have to type anything in to add their device. The device says "I'm here, here are my details" and Home Assistant picks it up. + +The protocol that does this is called **mDNS** (multicast DNS). It's the same standard that makes `.local` hostnames work on a Mac or iPhone. + +If your router or network setup blocks mDNS across subnets (some VLAN configurations do), auto-discovery does not work. In that case you add the integration manually using the device's IP address. + +## Encryption + +The link between your Starter Kit and Home Assistant is encrypted. Both ends use the same shared key (the `api_encryption_key` in your `secrets.yaml`) to talk to each other. + +When Home Assistant configures the device for the first time, it prompts you for that key. If Home Assistant and ESPHome Device Builder run on the same machine, the key is often pre-filled. Otherwise, copy it from `secrets.yaml` in Device Builder and paste it into the Home Assistant prompt. + +If the keys do not match, Home Assistant cannot read from or write to the device. The fix is to copy the current `api_encryption_key` value from Device Builder, install firmware to the device, and re-enter the key in Home Assistant. + +For more on `secrets.yaml`, see [What is secrets.yaml?](what-is-secrets-yaml.md). + +## Components and entities + +Every component you added in ESPHome Device Builder becomes an entity in Home Assistant: + +* A **switch** (like the Accessory Power switch) becomes a **switch entity**. +* A **sensor** (temperature, humidity, voltage, and so on) becomes a **sensor entity** with its unit of measurement. +* A **light** (like the Onboard RGB LED) becomes a **light entity** with color and brightness controls. +* A **button** becomes a **button entity** you can trigger from a dashboard. + +The entity's name in Home Assistant comes from the **Name** field you set in Device Builder. If you renamed **Accessory Power** to **Bedroom Lamp Power**, that is what it is called in Home Assistant too. + +## Controlling your device + +You have two ways to control your Starter Kit, and both keep working at the same time: + +* Open the **on-device web page** at esphome-starter-kit.local to control your device directly from any browser on your network. No Home Assistant required. See the [Web Server in Core Components](core-components.md#web-server) for more. +* Your Starter Kit appears as a new device under the **ESPHome integration** in Home Assistant. Each switch, sensor, and light becomes an entity you can use in dashboards, automations, voice control, history, and alerts. + + [![Open the ESPHome integration in your Home Assistant.](https://my.home-assistant.io/badges/integration.svg)](https://my.home-assistant.io/redirect/integration/?domain=esphome) + +For a single device, the on-device web page is often enough. For anything that ties together with other devices or runs on a schedule, Home Assistant is the place. + +!!! info "If auto-discovery doesn't work" + + Some router setups (notably VLANs and segmented networks) block mDNS broadcasts. If your device never shows up under **Discovered**, add the integration manually using the device's IP address. + + For UniFi networks specifically, see our [UniFi mDNS troubleshooting guide](../../../general/troubleshooting/ubiquiti-unifi-mdns-auto-discover-issue/). + + Back - What is secrets.yaml? Tutorial - Connect to Home Assistant diff --git a/docs/products/ESPHome-Starter-Kit/setup/first-steps.md b/docs/products/ESPHome-Starter-Kit/setup/first-steps.md index cd17bc4a37..d92495d263 100755 --- a/docs/products/ESPHome-Starter-Kit/setup/first-steps.md +++ b/docs/products/ESPHome-Starter-Kit/setup/first-steps.md @@ -202,4 +202,4 @@ Example of the light changing colors below! ![](../../../assets/esphome-starter-kit-onboard-rgb-led-light-up.webp) - Back - Start Here Next - Add Button Module \ No newline at end of file + Back - Start Here Add More Modules Connect to Home Assistant \ No newline at end of file diff --git a/docs/products/ESPHome-Starter-Kit/tutorials/connect-to-home-assistant.md b/docs/products/ESPHome-Starter-Kit/tutorials/connect-to-home-assistant.md new file mode 100644 index 0000000000..fd33ee6e41 --- /dev/null +++ b/docs/products/ESPHome-Starter-Kit/tutorials/connect-to-home-assistant.md @@ -0,0 +1,50 @@ +--- +title: Connect to Home Assistant +description: Step by step guide to adding your ESPHome Starter Kit to Home Assistant so its sensors, switches, and LEDs show up as entities. +--- +# Connect to Home Assistant + +Once your ESPHome Starter Kit is flashed and on Wi-Fi, Home Assistant sees it automatically. This page walks through accepting the device into Home Assistant and confirming your sensors and switches show up as entities you can use in dashboards and automations. + +## Before you start + +* Home Assistant is running on the same network as your Starter Kit. If you can open the Home Assistant UI from a browser on the same Wi-Fi as the device, you're good. +* Your Starter Kit is flashed and reachable. The fastest check: open `http://esphome-starter-kit.local/` in a browser, you should see the device's built-in web page. + +## Add your device + +1. Open [Devices & services](https://my.home-assistant.io/redirect/integrations/) in Home Assistant. Look for a card titled **ESPHome** under **Discovered** listing `esphome-starter-kit`. + * If you do not see the card, [add the ESPHome integration manually](https://my.home-assistant.io/redirect/config_flow_start/?domain=esphome). Enter the device's hostname (`esphome-starter-kit.local`) or its IP address. +2. Click **Configure** on the discovered card. +3. When prompted for the encryption key, paste the value of your `api_encryption_key` from `secrets.yaml` in ESPHome Device Builder. If Home Assistant and Device Builder run on the same machine, the key is often pre-filled. +4. Pick an **Area** for the device (optional), like Living Room or Office. +5. Click **Submit**. + + + +## Confirm it worked + +Open the [ESPHome integration](https://my.home-assistant.io/redirect/integration/?domain=esphome) in Home Assistant and pick your device. You should see: + +* Every component you added in ESPHome Device Builder as an entity (the **GPIO Switch** for accessory power, the **AHT10** temperature and humidity sensors, the **Onboard RGB LED**). +* A green status indicator showing the device is online. + +Toggle the **Onboard RGB LED** light entity and confirm the LED responds on the board. That's the round trip working: Home Assistant talks to your device, your device talks back. + +## Troubleshooting + +#### The device never appears under Discovered + +* Confirm Home Assistant is on the same Wi-Fi network as the device. +* Some routers and VLAN setups block mDNS broadcasts across subnets. Add the integration manually using the device's IP address. Look the IP up on your router's client list or in the **Device Information** section of the ESPHome Device Builder info panel. +* The device's web page should still load at the hostname or IP. If it does not, the device is not reachable from your computer yet and Home Assistant will not find it either. + +#### The encryption key is rejected + +Open `secrets.yaml` in Device Builder, copy the `api_encryption_key` value, and paste it back into the Home Assistant prompt. If the value in Device Builder has changed since you last flashed, install the firmware again so the device knows the new key. + +--- + +Want to understand what just happened under the hood? Read [the Home Assistant integration](../learning-the-basics/how-esphome-talks-to-home-assistant.md). + + Back - First Steps diff --git a/mkdocs.yml b/mkdocs.yml index c5a4f68da0..5908a00e7a 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -511,12 +511,14 @@ nav: - LED & Buzzer: products/ESPHome-Starter-Kit/modules/rgb-buzzer-module.md - Tutorials: - Using Secrets: products/ESPHome-Starter-Kit/tutorials/using-secrets.md + - Connect to Home Assistant: products/ESPHome-Starter-Kit/tutorials/connect-to-home-assistant.md - Learn the Basics: - Explaining ESPHome: products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md - Device Builder Tour: products/ESPHome-Starter-Kit/learning-the-basics/device-builder-tour.md - Core Components: products/ESPHome-Starter-Kit/learning-the-basics/core-components.md - What is YAML?: products/ESPHome-Starter-Kit/learning-the-basics/what-is-yaml.md - What is secrets.yaml?: products/ESPHome-Starter-Kit/learning-the-basics/what-is-secrets-yaml.md + - HA Integration: products/ESPHome-Starter-Kit/learning-the-basics/how-esphome-talks-to-home-assistant.md - Holiday Ornaments: - H-1: - Introduction: products/h1/introduction.md