Плата ESP32 стоит недорого, умеет Wi‑Fi и Bluetooth, а с прошивкой ESPHome превращается в датчик температуры, реле, выключатель или контроллер светодиодной ленты, который Home Assistant находит сам. Именно поэтому подключение ESP32 к Home Assistant через ESPHome считается самым удобным способом собрать собственное устройство для умного дома: код писать почти не нужно, достаточно описать железо в YAML-файле. В статье разберём весь путь: установку ESPHome Device Builder, первую прошивку через браузер, добавление устройства в Home Assistant, готовые примеры конфигурации и типичные ошибки. Это хорошая отправная точка для тех, кто ищет простые ESP32 Home Assistant проекты и хочет понять, как работает связка ESPHome и Home Assistant.

1Что такое ESPHome и как он связан с Home Assistant
ESPHome — отдельный проект, входящий в экосистему Home Assistant. Вы описываете устройство в YAML: к каким выводам платы подключены датчики и реле, какая у вас Wi‑Fi сеть. ESPHome по этому описанию генерирует программу, собирает её и прошивает в микроконтроллер. После этого плата связывается с Home Assistant через собственный «родной» API по локальной сети. Никакого облака и промежуточного брокера (как у MQTT) не требуется: Home Assistant находит устройство автоматически и показывает его сущности — датчики, переключатели, светильники.
Ключевые преимущества подхода:
- Всё работает локально, без интернета.
- Конфигурация текстовая, её легко хранить, копировать и версионировать.
- После первой прошивки обновления идут по воздуху (OTA), без провода.
- Если Home Assistant недоступен, плата продолжает выполнять локальные правила, которые вы описали в YAML.
2Что понадобится
- Работающий Home Assistant с доступом к разделу дополнений (установки Home Assistant OS или Supervised). Если у вас Docker Container, дополнений нет, и ESPHome придётся запускать отдельно — об этом ниже.
- Плата на ESP32: подойдёт любая распространённая отладочная плата, например типа DevKit с чипом ESP32, ESP32-S3 или ESP32-C3. Определить модель можно по маркировке на металлическом экране чипа.
- Кабель USB с передачей данных (не только зарядный — это частая причина «плата не видна»).
- Для примеров: датчик температуры и влажности DHT22, модуль реле, кнопка или геркон, макетная плата и провода.
- Сеть Wi‑Fi на частоте 2,4 ГГц. ESP32 не работает в диапазоне 5 ГГц.
- Компьютер с браузером на основе Chromium (Google Chrome, Microsoft Edge) для прошивки через USB прямо из браузера.

3Шаг 1. Устанавливаем ESPHome Device Builder
В Home Assistant OS ESPHome ставится как дополнение, которое сейчас называется ESPHome Device Builder.
- Откройте Настройки → Дополнения. В некоторых версиях раздел называется «Дополнения» внутри «Настройки», а в новейших релизах пункты могут быть перегруппированы, поэтому, если не нашли, воспользуйтесь поиском по настройкам.
- Нажмите «Магазин дополнений» и найдите в списке ESPHome Device Builder.
- Нажмите «Установить», дождитесь окончания.
- Включите опцию «Показывать в боковой панели» и нажмите «Запустить».
- Откройте ESPHome из боковой панели.
Дополнение откроет веб-интерфейс со списком устройств. Пока он пуст — это нормально.
Если у вас Home Assistant в Docker или без дополнений
В установке Container дополнений нет. Тогда ESPHome запускают отдельным контейнером или через менеджер пакетов Python на любом компьютере. Образ контейнера — ghcr.io/esphome/esphome, интерфейс по умолчанию слушает порт 6052. При запуске в сети хоста нужно сохранить папку с конфигурациями. Пример для Docker Compose:
services:
esphome:
container_name: esphome
image: ghcr.io/esphome/esphome
volumes:
- ./esphome-config:/config
- /etc/localtime:/etc/localtime:ro
restart: unless-stopped
network_mode: host
Интерфейс будет доступен по адресу http://IP-адрес-хоста:6052. Остальные шаги статьи одинаковы для обоих вариантов.
4Шаг 2. Создаём новое устройство
- В интерфейсе ESPHome нажмите кнопку добавления нового устройства («New device» или аналогичную по смыслу).
- Если мастер просит, примите вводный экран и нажмите «Продолжить».
- Введите имя. Допустимы латинские буквы в нижнем регистре, цифры и дефис, например
kitchen-sensor. Имя нельзя будет легко изменить позже, потому что оно участвует в адресе устройства в сети. - Введите название и пароль вашей Wi‑Fi сети (2,4 ГГц). Эти данные ESPHome сохранит в служебном файле
secrets.yaml, а в основной конфигурации подставит ссылки на них. - Выберите тип чипа: ESP32, ESP32-S3, ESP32-C3 и другие. Выбор должен совпадать с вашей платой, иначе прошивка не запустится.
- Мастер покажет сгенерированный ключ шифрования API. Сохраните его в надёжное место: он понадобится при добавлении устройства в Home Assistant, если автоматическая привязка не сработает.
Мастер предложит сразу установить прошивку. Остановимся на этом подробнее.
5Шаг 3. Первая прошивка
Первую прошивку нужно заливать по кабелю. ESPHome предлагает несколько способов, и тексты пунктов могут отличаться в разных версиях, но суть такая:
- Подключение к этому компьютеру («Plug into this computer»). Прошивка собирается на сервере ESPHome, а загружается в плату прямо из браузера через интерфейс Web Serial. Это самый удобный вариант, но у него есть жёсткое ограничение: браузер разрешает Web Serial только на защищённых страницах — по HTTPS или с адреса localhost. Если вы открываете Home Assistant по обычному
http://192.168.1.50:8123, этот пункт работать не будет или будет недоступен. - Подключение к компьютеру, на котором работает ESPHome («Plug into the computer running ESPHome Device Builder»). Плата вставлена в USB-порт самого сервера (например, мини-ПК). Подходит, если вы можете физически подключить плату к серверу, а система прокидывает последовательные порты.
- Ручная загрузка («Manual download»). ESPHome собирает прошивку и отдаёт вам файл. Вы загружаете его на компьютер и прошиваете одним из веб-инструментов для ESP-плат, открывающихся по HTTPS (в документации проекта указан сайт
web.esphome.io), либо программой esptool. Это самый надёжный вариант, если у вас Home Assistant по HTTP.
Порядок действий для ручного варианта:
- Выберите ручную загрузку и дождитесь окончания сборки. Первая компиляция занимает несколько минут, на слабом железе (одноплатники, виртуальные машины с малым числом ядер) — до десяти и больше: ESPHome скачивает инструментарий и собирает всё с нуля.
- Скачайте предложенный образ для первой установки (так называемый factory-образ).
- Подключите плату к компьютеру кабелем.
- Откройте страницу веб-инструмента прошивки в Chrome или Edge, нажмите кнопку подключения, выберите порт платы, нажмите установку и выберите скачанный файл.
- Если плата не входит в режим прошивки сама, удерживайте кнопку BOOT на плате на время подключения, а затем нажмите EN (reset). Расположение кнопок зависит от модели.
- После завершения плата перезапустится и подключится к Wi‑Fi. Обновления дальше идут по воздуху.
Если порт платы не появляется в списке, причина обычно в кабеле «только для зарядки» или в отсутствии драйвера USB‑UART моста. На платах с чипами CP210x и CH340 в Windows иногда требуется установить драйвер производителя моста; в Linux и новых версиях Windows и macOS они чаще всего подхватываются сами.
6Шаг 4. Устройство в Home Assistant
После подключения платы к сети Home Assistant найдёт её самостоятельно по mDNS. В Настройки → Устройства и службы в верхней части появится карточка «Обнаружено» с названием вашего ESPHome-устройства. Нажмите «Настроить», подтвердите, и при необходимости введите ключ шифрования. Если Home Assistant и ESPHome Device Builder работают на одной системе, ключ обычно подставляется автоматически, поскольку интеграция видит конфигурацию в дополнении.
Если автообнаружение не сработало, добавьте устройство вручную: «Добавить интеграцию» → ESPHome → введите IP-адрес или имя хоста платы вида kitchen-sensor.local. IP-адрес платы можно узнать в журнале ESPHome или в списке клиентов роутера. Автообнаружение не работает между разными подсетями и VLAN, если роутер не пересылает mDNS, — в такой сети добавляйте по IP.
После добавления вы получите устройство со всеми сущностями из вашей конфигурации. Присвойте им области (кухня, спальня) и пользуйтесь в автоматизациях, как любыми другими.
7Базовая конфигурация
Файл, который создал мастер, выглядит примерно так. Нажмите «Edit» у карточки устройства и посмотрите на него:
esphome:
name: kitchen-sensor
friendly_name: Kitchen Sensor
esp32:
board: esp32dev
framework:
type: esp-idf
logger:
api:
encryption:
key: !secret api_encryption_key
ota:
- platform: esphome
password: !secret ota_password
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
ap:
ssid: "Kitchen Sensor Fallback"
password: !secret fallback_password
captive_portal:
Что здесь важно:
esphome— имя устройства и дружественное название.esp32— тип платы и фреймворк. Для ESP32-S3 и ESP32-C3 значенияboardдругие (например,esp32-s3-devkitc-1иesp32-c3-devkitm-1); мастер подставит нужное сам. Фреймворк ESP-IDF стоит по умолчанию в новых конфигурациях, Arduino тоже поддерживается.logger— вывод журнала, пригодится для отладки.api— связь с Home Assistant и шифрование.ota— обновление по воздуху.wifiи блокap— подключение к сети и резервная точка доступа, которую плата поднимет, если не найдёт вашу сеть. Подключившись к ней, можно задать другую Wi‑Fi сеть черезcaptive_portal.
Секреты хранятся отдельно, в файле secrets.yaml, который открывается кнопкой «Secrets» в интерфейсе:
wifi_ssid: "MyHomeWiFi"
wifi_password: "your-wifi-password"
api_encryption_key: "сгенерированный-мастером-ключ"
ota_password: "придумайте-пароль"
fallback_password: "ещё-один-пароль"
Не публикуйте secrets.yaml и конфигурации с ключами в открытых репозиториях.
8Примеры: датчик, реле, кнопка
Ниже — фрагменты, которые добавляются к базовой конфигурации. Номера выводов (GPIO) подставьте под свою схему.
Температура и влажность на DHT22
sensor:
- platform: dht
pin: GPIO4
model: DHT22
temperature:
name: "Температура"
humidity:
name: "Влажность"
update_interval: 60s
- platform: wifi_signal
name: "Сигнал Wi-Fi"
update_interval: 120s
entity_category: "diagnostic"
Датчик подключается так: питание 3,3 В, земля и линия данных на GPIO4. Для модулей без собственного резистора нужна подтяжка линии данных к питанию (около 10 кОм). Платформа wifi_signal добавляет полезную диагностику уровня сигнала.
Датчики на шине I²C
Если вы берёте датчик BME280 или подобный, используйте шину I²C:
i2c:
sda: GPIO21
scl: GPIO22
scan: true
sensor:
- platform: bme280_i2c
address: 0x76
temperature:
name: "Температура BME280"
pressure:
name: "Давление"
humidity:
name: "Влажность BME280"
update_interval: 60s
Параметр scan: true заставит плату выводить в журнал адреса найденных на шине устройств — очень удобно, если не уверены, какой адрес у модуля (0x76 или 0x77).
Реле и кнопка
switch:
- platform: gpio
pin: GPIO26
name: "Реле света"
id: relay_light
restore_mode: RESTORE_DEFAULT_OFF
binary_sensor:
- platform: gpio
pin:
number: GPIO27
mode:
input: true
pullup: true
inverted: true
name: "Кнопка"
filters:
- delayed_on_off: 50ms
on_press:
- switch.toggle: relay_light
Здесь реле управляется из Home Assistant, а физическая кнопка (замыкающая вывод на землю) переключает его локально — даже если Home Assistant выключен. Параметр restore_mode определяет, в каком состоянии реле окажется после перезагрузки платы; для освещения безопаснее выключенное. Внимание: модули реле работают с сетевым напряжением 230 В. Подключать нагрузку 230 В нужно только при наличии квалификации, в изолированном корпусе и с защитой; в противном случае ограничьтесь низковольтными цепями.
Какие выводы использовать
У ESP32 есть выводы с ограничениями. Выводы GPIO34–GPIO39 работают только как входы и не имеют встроенной подтяжки. Выводы GPIO6–GPIO11 заняты флеш-памятью на большинстве модулей, использовать их нельзя. Так называемые strapping-выводы (например, GPIO0, GPIO2, GPIO12, GPIO15) влияют на загрузку: подключение к ним нагрузки может помешать запуску платы. Для чипов S3 и C3 схема выводов отличается, сверяйтесь с документацией на ваш модуль и страницей ESPHome о соответствующей плате.
9Шаг 5. Обновление и поддержка по воздуху
После первой прошивки любые правки YAML заливаются по Wi‑Fi: нажмите «Install» у карточки устройства и выберите «Wirelessly». Новая версия соберётся, загрузится в плату, и устройство перезагрузится. Если ESPHome Device Builder показывает, что для устройства доступно обновление (при выходе новой версии ESPHome), нажмите «Update», но делайте это не в последний момент перед отъездом: иногда новая версия меняет синтаксис, и конфигурацию надо править. Изменения описываются в журнале релизов проекта.
Журнал устройства в реальном времени доступен по кнопке «Logs» — по сети, без подключения кабеля. Это главный инструмент отладки: видно, подключился ли Wi‑Fi, с какого вывода пришёл сигнал и какие ошибки возникают.
10Автоматизации на стороне платы и в Home Assistant
ESPHome умеет выполнять простые правила прямо на плате. Например, включать реле, если температура превысила порог, независимо от наличия сети:
sensor:
- platform: dht
pin: GPIO4
model: DHT22
temperature:
name: "Температура"
on_value_range:
- above: 28.0
then:
- switch.turn_on: relay_light
update_interval: 30s
Для остальной логики используйте обычные автоматизации Home Assistant: сущности ESPHome ничем не отличаются от сущностей любой другой интеграции. Принцип такой: критичное и простое — на плате, сложное и зависящее от других устройств — в Home Assistant.
11Типичные ошибки и решения
Не открывается выбор порта при прошивке из браузера
Web Serial работает только в браузерах Chromium и только по HTTPS или localhost. Если у вас обычный HTTP-адрес, воспользуйтесь ручной загрузкой образа и прошивкой через веб-инструмент или esptool.
Плата не видна как USB-устройство
Смените кабель, порт, проверьте, что плата получает питание. Поставьте драйвер USB‑UART моста (CP210x, CH340). Попробуйте войти в режим загрузки: удерживайте BOOT, нажмите и отпустите EN.
Ошибки компиляции
Чаще всего это опечатка в YAML (отступы только пробелами, табуляция не допускается), неверное имя платформы или параметра, устаревший синтаксис после обновления ESPHome. Сообщение об ошибке указывает строку, смотрите именно на неё. Если сборка обрывается без внятной причины, проверьте свободное место на диске и память: компиляция ресурсоёмка.
Плата не подключается к Wi‑Fi
- Сеть должна быть на 2,4 ГГц, имя и пароль точные, с учётом регистра.
- Имена сетей с нестандартными символами иногда вызывают проблемы; попробуйте простое имя.
- Слабый сигнал: расположите плату ближе к роутеру или используйте плату с внешней антенной.
- Если плата не нашла сеть, она поднимает резервную точку доступа из блока
ap; подключитесь к ней с телефона и откройте страницу настроек.
Устройство не появляется в Home Assistant
Проверьте, что плата и сервер в одной подсети, откройте журнал платы и убедитесь, что она получила IP-адрес. Добавьте устройство вручную по IP. Если Home Assistant пишет об ошибке шифрования, значит, ключ в Home Assistant не совпадает с ключом в конфигурации платы: введите актуальный ключ из блока api.
Устройство периодически пропадает
Причиной бывает нестабильное питание: перезагрузки по просадке напряжения («brownout») видны в журнале. Используйте качественный блок питания и короткий толстый кабель. Также проверьте, что у платы зарезервирован адрес в DHCP.
Датчик выдаёт «NaN» или не обновляется
Проверьте проводку, питание датчика, подтяжку линии данных и номер вывода. Для I²C включите scan: true и посмотрите, видит ли плата адрес устройства.
12Итог
Связка ESP32, ESPHome и Home Assistant позволяет собрать собственное устройство для умного дома за один вечер. Порядок такой: установить ESPHome Device Builder, создать устройство мастером, сделать первую прошивку по кабелю (учитывая ограничение Web Serial на HTTPS), дождаться автообнаружения в «Устройствах и службах», а дальше развивать конфигурацию и обновлять плату по воздуху. Начните с одного простого датчика, убедитесь, что устройство стабильно работает, и только потом наращивайте функциональность. Названия кнопок и пунктов в ESPHome Device Builder и Home Assistant со временем меняются, поэтому при расхождениях ориентируйтесь на смысл шагов и документацию проекта.
Вопросы и ответы
Нужен ли MQTT для работы ESP32 с Home Assistant?
Нет. ESPHome использует собственный API, и Home Assistant находит устройство автоматически в разделе «Устройства и службы», без брокера MQTT.
Почему не получается прошить плату из браузера?
Web Serial работает только в браузерах на Chromium и только по HTTPS или с адреса localhost. При доступе к Home Assistant по обычному HTTP используйте ручную загрузку образа и прошейте плату через веб-инструмент или esptool.
Можно ли использовать ESPHome без дополнения Home Assistant?
Да. ESPHome запускается отдельным контейнером или устанавливается как пакет Python на любом компьютере. Интерфейс контейнера по умолчанию работает на порту 6052.
Работает ли ESP32 в сети 5 ГГц?
Нет, ESP32 подключается только к сетям 2,4 ГГц. Если на роутере единое имя для двух диапазонов и есть проблемы с подключением, создайте отдельную сеть 2,4 ГГц.
Нужно ли каждый раз прошивать плату по кабелю?
Только первый раз. После этого обновления прошивки загружаются по Wi-Fi кнопкой Install и выбором варианта Wirelessly.



