# How to Set Up Home Assistant with ESPHome Devices: Complete Self-Hosted Integration Guide

> Integrate ESPHome devices with Home Assistant and control your smart home for free. Install the ESPHome add-on flash devices OTA for native entity discovery.

- Repository: [Michael Royal/Self-Hosting-Guide](https://github.com/mikeroyal/Self-Hosting-Guide)
- Tags: tutorial
- Published: 2026-06-17

---

**Install the ESPHome add-on from Home Assistant’s Supervisor, configure your ESP8266/ESP32 devices via YAML, and flash them over-the-air (OTA) to automatically discover native entities in Home Assistant without requiring an external MQTT broker.**

The mikeroyal/Self-Hosting-Guide repository provides comprehensive documentation for building a privacy-focused smart home infrastructure. When you set up Home Assistant with ESPHome devices, you create a tightly integrated local network where microcontrollers communicate directly through Home Assistant’s native API, eliminating cloud dependencies and external brokers.

## Architecture Overview

Home Assistant with ESPHome operates as a unified ecosystem with three core components:

- **Home Assistant Core** – The central hub running the UI, automation engine, and entity registry.
- **ESPHome Add-on** – A container managed by the Home Assistant Supervisor that hosts the ESPHome compiler and exposes an HTTP API on port `6052`.
- **ESP8266/ESP32 Devices** – Microcontrollers running firmware compiled from YAML configurations that register themselves with the ESPHome API over your local network.

When an ESP device boots, it automatically registers with the ESPHome API. Home Assistant then discovers the device and creates native entities under **Configuration → Entities**, enabling immediate use in dashboards and automations. This architecture delivers **zero-configuration OTA updates** and **secure local communication** that never leaves your LAN.

## Installation Methods

According to the [`README.md`](https://github.com/mikeroyal/Self-Hosting-Guide/blob/main/README.md) in the Self-Hosting-Guide repository, you have three supported methods to deploy ESPHome:

**Add-on (Recommended)** – Install directly from Home Assistant’s Supervisor. This bundles the ESPHome compiler and provides a web UI at `http://<HA-IP>:6052`. Best for Home Assistant OS or Supervised installations.

**Docker** – Run the official `esphome/esphome` image as a standalone container. Ideal for custom container management or Docker-only Home Assistant deployments.

**Python (`pip`)** – Install with `pip install esphome` for direct CLI access on macOS/Linux development machines.

### Home Assistant Add-On Installation

This method references the section *“Install ESPHome using Home Assistant”* in the repository’s [`README.md`](https://github.com/mikeroyal/Self-Hosting-Guide/blob/main/README.md).

1. Open Home Assistant and navigate to **Supervisor → Add-on Store**.
2. Search for **ESPHome**, click **Install**, then **Start**.
3. Click **Open Web UI** to access the dashboard at port `6052`.
4. Click **Add Node** and enter your device name.
5. Select **ESP8266** or **ESP32** as the platform and enter your Wi-Fi credentials.
6. Define your sensors, switches, or binary sensors in the generated YAML configuration.
7. Click **Install** → **Wirelessly** to compile and flash the firmware OTA.
8. Once the device boots, Home Assistant automatically creates entities for each component defined in your YAML.

### Docker Installation

For containerized deployments, pull the official image as documented in the *“Install ESPHome using Docker”* section.

```bash

# Pull the ESPHome image

docker pull esphome/esphome

# Run the container (replace <path> with your config directory)

docker run -d \
  --name esphome \
  -v <path>:/config \
  -p 6052:6052 \
  --restart always \
  esphome/esphome

```

Navigate to `http://<host-IP>:6052` to access the ESPHome dashboard and follow the device configuration steps above.

### Python Installation

For development environments, use the method documented in *“Install ESPHome using Python”*.

```bash

# Install ESPHome (requires Python 3.7+)

pip install esphome

# Start the interactive configuration wizard

esphome wizard

```

The wizard prompts for device type, name, Wi-Fi details, and generates a `.yaml` file. Compile and flash using `esphome run mydevice.yaml`.

## ESPHome YAML Configuration Example

Save this configuration as [`living_room_temp.yaml`](https://github.com/mikeroyal/Self-Hosting-Guide/blob/main/living_room_temp.yaml) in your ESPHome configuration folder (mounted at `/config` in Docker or accessible via the Add-on UI):

```yaml
esphome:
  name: living_room_temp
  platform: ESP8266
  board: nodemcuv2

wifi:
  ssid: "YourWiFi"
  password: "SuperSecret"

# Enable OTA updates

ota:

# Example DHT22 sensor configuration

sensor:
  - platform: dht
    pin: D2
    temperature:
      name: "Living Room Temperature"
    humidity:
      name: "Living Room Humidity"
    update_interval: 60s

```

After flashing, Home Assistant exposes `sensor.living_room_temperature` and `sensor.living_room_humidity` as native entities you can place in dashboards or automation triggers.

## Summary

- **ESPHome runs as an Add-on** within Home Assistant’s Supervisor ecosystem, providing a web UI on port `6052` for device management.
- **Native API communication** eliminates the need for MQTT brokers, keeping all traffic local to your network.
- **Three installation paths** exist: Home Assistant Add-on (recommended), Docker container, and Python pip installation for CLI workflows.
- **Automatic entity discovery** occurs when devices boot and register with the ESPHome API, creating immediate usable sensors and switches in Home Assistant.
- **OTA updates** are managed directly through the ESPHome dashboard, allowing wireless firmware updates without physical device access.

## Frequently Asked Questions

### Do I need an MQTT broker to connect ESPHome devices with Home Assistant?

No. ESPHome communicates directly with Home Assistant through the ESPHome API, which is a custom protocol running over TCP. This native integration eliminates the need for external MQTT brokers, though MQTT remains available as an optional fallback for advanced use cases.

### What is the default port for the ESPHome dashboard?

The ESPHome dashboard runs on port `6052` by default. When using the Home Assistant Add-on, access it via **Supervisor → ESPHome → Open Web UI**. For Docker or standalone installations, navigate to `http://<host-ip>:6052`.

### Can I run ESPHome without installing it as a Home Assistant Add-on?

Yes. You can deploy ESPHome using the official Docker image (`esphome/esphome`) or install it via `pip install esphome` on any Linux/macOS system. These methods provide the same compilation and OTA capabilities while running outside the Home Assistant Supervisor ecosystem.

### How do I update firmware on ESPHome devices after initial setup?

Click **Update** in the ESPHome dashboard for any configured node. The add-on will compile the updated firmware and upload it over-the-air (OTA) to the device. This zero-configuration update process works for all devices configured through the YAML editor and previously flashed with OTA support enabled.