ESPHome и ESP32 в Home Assistant

ESPHome превращает плату ESP32 или ESP8266 в устройство Home Assistant: в YAML-конфигурации задаются переключатель GPIO и бинарный датчик, а прошитая плата обнаруживается автоматически. Основной путь: приложение ESPHome Device Builder внутри Home Assistant, мастер создания устройства, первая прошивка по USB - и дальше только обновления по воздуху (OTA). Вся настройка идет в веб-интерфейсе, USB-кабель нужен один раз.

Что понадобится

Нужны Home Assistant, плата ESP32 или ESP8266 с подключением по USB и данные Wi-Fi. Полный список:

• Home Assistant и установленное приложение ESPHome Device Builder. Гайд исходит из того, что ESPHome уже установлен; если нет, начните со страницы установки ESPHome и возвращайтесь к этому гайду. Если Home Assistant еще не установлен, поможет гайд Установка Home Assistant.
• Плата ESP8266 или ESP32: либо отдельная плата с переходником USB to serial (USB - последовательный порт), либо плата со встроенным переходником. Прошивка делается через последовательный порт платы.
• USB-кабель для первой прошивки. Самая первая установка выполняется только по кабелю, все последующие обновления - по воздуху.
• Данные Wi-Fi: имя сети и пароль. Без них плата не выйдет в сеть, не свяжется с Home Assistant и не сможет принимать беспроводные обновления.

Основные шаги

Весь путь проходит в приложении ESPHome Device Builder: от установки приложения до появления устройства в Home Assistant.

1. Установите приложение. Кнопка на странице установки ESPHome открывает приложение ESPHome Device Builder (app, в старых материалах - аддон) внутри вашего Home Assistant. Нажмите Install.
2. Запустите приложение. Нажмите Start, затем Open Web UI - откроется веб-интерфейс Device Builder.
3. Создайте устройство. Пока устройств нет, Device Builder сам предлагает создать первое: нажмите Create device, запустится мастер. Имя должно быть уникальным: одинаковые имена устройств ведут к проблемам с соединением, сбою discovery (автоматического обнаружения) и неожиданному поведению.
4. Выберите способ создания конфигурации. Мастер предлагает три варианта:
   • New Device Setup - управляемый мастер: спросит платформу, плату и Wi-Fi;
   • Import from File - импорт готового файла .yaml или .yml;
   • Empty Configuration - пустая конфигурация с нуля.
5. Проверьте данные Wi-Fi. Если имя сети и пароль не были введены в мастере, добавьте их сейчас, до прошивки.
6. Подключите плату по USB. Вставьте плату или программатор в свободный USB-порт и убедитесь, что компьютер ее определил.
7. Прошейте устройство. Нажмите Install в Device Builder: приложение соберет конфигурацию и запишет прошивку в плату.
8. Добавьте переключатель GPIO. Нажмите Edit у устройства, чтобы открыть конфигурацию, и добавьте переключатель GPIO (GPIO - контакт платы общего назначения) в секцию switch: - с именем и пином. Плейсхолдер GPIOXX замените на пин, к которому подключено железо.
9. Добавьте бинарный датчик. В секцию binary_sensor: добавьте датчик GPIO с блоком pin в форме number, inverted, mode, pullup. Затем нажмите Save.
10. Загрузите изменения в плату. Сохранение конфигурации не меняет само устройство: после каждой правки нажимайте Install, и новая прошивка скомпилируется и запишется в плату.
11. Перейдите на обновления по воздуху. После первой прошивки USB-кабель больше не нужен: ESPHome обновляет устройства по воздуху. Для защиты таких обновлений шифрование предпочтительнее пароля.
12. Дождитесь автоматического обнаружения. Когда конфигурация установлена и плата вышла в Wi-Fi, Home Assistant сам находит устройство (если сеть разрешает mDNS, протокол локального обнаружения) и предлагает его настроить.
13. Добавьте устройство вручную, если оно не нашлось. Откройте Settings > Devices & services, в правом нижнем углу нажмите Add Integration, выберите интеграцию ESPHome и укажите имя хоста (например living-room-lamp.local) или IP-адрес. Подробности - в документации интеграции ESPHome.

Другие способы

Если основной путь не подходит, есть альтернативы: ручная установка приложения, Docker, десктопная версия и командная строка.

• Кнопка установки не сработала. Поставьте приложение ESPHome Device Builder вручную: в Home Assistant откройте Settings → Apps → Install App.
• Приложения нет в списке. Добавьте репозиторий ESPHome https://github.com/esphome/home-assistant-addon в меню Repositories.
• Home Assistant Container. Device Builder запускается как отдельный Docker-контейнер рядом с контейнером Home Assistant.
• Десктопная версия или pip. Device Builder работает и как нативное приложение на macOS, Windows и Linux, а также устанавливается через pip.
• Без Home Assistant. Те же шаги выполняет консольная утилита esphome; YAML-конфигурация при этом та же. Команды для этого приведены в ответе о работе без Home Assistant ниже.

Важные детали

Файлы конфигураций устройств лежат в папке esphome/ внутри каталога конфигурации Home Assistant.

Приложения Home Assistant (apps, в старых материалах - аддоны) работают как отдельные контейнеры, поэтому добраться до их файлов и логов из shell (командной строки) сложнее. Если ради этого вы отключаете Protection Mode на приложении SSH, помните о рисках:

Частые проблемы

Каждая ситуация в таблице встречалась на форуме в двух ветках, а решения - опыт пользователей, который им помогал.

Проблема	Ошибка (дословно)	Что помогало пользователям
После обновления ESPHome устройства не собираются, ошибка версии Python	ERROR: Python version must be between 3.10 and 3.13.	Сбросить окружение сборки: меню в правом верхнем углу > Firmware tasks > Reset Build Env
OTA-обновление падает из-за конфигурации секции ota	At least one platform must be specified for 'ota'; add 'platform: esphome' for original OTA	Добавить platform: esphome в секцию ota
ESPHome отвергает старые конфиги с ключом platform в блоке esphome	Please remove the `platform` key from the [esphome] block and use the correct platform component.	Перенести platform и board в формат на компонентах: блок esp32: или esp8266:
Сборка на Raspberry Pi 3 падает	xtensa-esp32-elf-g++: fatal error: Killed signal terminated program cc1plus	Собрать прошивку на компьютере и прошить по USB; увеличить файл подкачки на Home Assistant OS
OTA-обновление не находит устройство по имени .local	ERROR Error resolving IP address of esphome-web-78cd84.local. Is it connected to WiFi?	Закрепить за платой постоянный адрес в роутере или через manual_ip
ESP32 теряет Wi-Fi вдали от точки доступа	reason='Auth Expired'	Поставить более качественный блок питания USB; снизить мощность передатчика опцией output_power в секции wifi
Дешевая плата реле на ESP32 не прошивается по USB	-	Прошить через переходник USB to TTL: TX к RX, RX к TX, GPIO0 к GND при подаче питания

Частые вопросы

Нужен ли USB-кабель при каждом обновлении?

Нет, кабель нужен один раз: самая первая прошивка выполняется только через USB, а все дальнейшие обновления приходят по воздуху. Условие одно - данные Wi-Fi в конфигурации: если их не ввели в мастере, добавьте до первой прошивки. Каждую следующую правку конфигурации нужно загружать в плату кнопкой Install: само сохранение устройство не меняет.

Где лежат конфигурации устройств?

В папке esphome/ внутри каталога конфигурации Home Assistant - при работе через приложение Device Builder. Учтите, что приложения Home Assistant работают как отдельные контейнеры: добраться до этих файлов из shell сложнее, чем до остальной конфигурации. Если для доступа вы отключаете Protection Mode на приложении SSH, сначала оцените риски.

Почему Home Assistant не находит устройство?

Автоматическое обнаружение работает, если сеть разрешает mDNS. Если обнаружения нет, добавьте устройство вручную через Settings > Devices & services, кнопку Add Integration и интеграцию ESPHome, указав имя хоста вида living-room-lamp.local или IP-адрес. Еще одна возможная причина - дублирующиеся имена устройств: они приводят к проблемам с соединением и обнаружением.

Для OTA выбрать пароль или шифрование?

Шифрование: документация ESPHome рекомендует его вместо пароля. Шифрование сохраняет образ прошивки конфиденциальным при передаче, а не только подтверждает подлинность. Оно работает на устройстве с ESPHome 2026.9.0 или новее и с ключом шифрования: устройство, обновленное по воздуху до такой версии, получает эту возможность и сохраняет ее дальше.

Можно ли работать с ESPHome без Home Assistant?

Да, консольной утилитой esphome: у каждого шага есть прямой аналог в командной строке, а YAML-конфигурация та же. Устройство создается командой esphome wizard livingroom.yaml. Команда esphome run livingroom.yaml проверяет конфигурацию, сообщает о проблемах, затем собирает прошивку и загружает ее в плату.