ESPHome на сервере: частые ошибки и решения

MAATRIX

ESPHome обещает прошивку ESP8266/ESP32 без единой строчки C++ — просто YAML-конфиг и кнопка «Install». Ровно до момента, пока вы не переносите проект с ноутбука на сервер: mDNS перестаёт находить устройства, OTA виснет на 30%, а Home Assistant ругается на «Handshake failed». Разбираем, откуда берутся эти ошибки и как настроить связку сервер + ESPHome + умный дом так, чтобы она действительно работала, а не требовала переподключения флешки при каждом обновлении прошивки.

Как запустить ESPHome на сервере: Docker и сеть

ESPHome можно поставить как аддон Home Assistant, но на отдельном сервере (VPS, мини-ПК дома, выделенный сервер) удобнее контейнер. Рабочий docker-compose.yml:

services:
  esphome:
    image: ghcr.io/esphome/esphome:latest
    container_name: esphome
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./esphome-config:/config
    environment:
      - TZ=Europe/Moscow

Ключевая деталь, о которую спотыкается почти каждый: network_mode: host. По умолчанию Docker сажает контейнер в отдельную bridge-сеть — mDNS-пакеты (multicast, 224.0.0.251) через неё не проходят, поэтому ESPHome не видит ни одного устройства в сети, хотя те прекрасно откликаются на ping. С bridge-сетью придётся либо пробрасывать порты вручную (6052 для веб-интерфейса, плюс диапазон для OTA — не всегда предсказуем), либо смириться с тем, что автообнаружение не работает и IP устройств придётся указывать вручную. Если хотите разобраться в разнице режимов подробнее — у нас есть отдельный разбор типов Docker-сетей.

Поднимаете контейнер:

docker compose up -d
docker compose logs -f esphome

Веб-интерфейс дашборда — на http://<ip-сервера>:6052. Если сервер смотрит в интернет напрямую, закройте порт файрволом и заходите через VPN или SSH-туннель — дашборд не имеет встроенной аутентификации по умолчанию, только если вы явно не добавили dashboard_use_ping: true и логин/пароль в конфиг сборщика (esphome: ... dashboard_use_ping).

Ошибка: ESPHome не видит устройства по mDNS / OTA зависает

Самая частая жалоба: «дашборд показывает устройство offline, хотя оно точно работает» или OTA зависает на «Uploading... 0%». Причины по убыванию частоты:

• Сервер и ESP-устройства в разных L2-сегментах. mDNS не маршрутизируется — если сервер арендован в дата-центре, а датчики стоят у вас дома, они физически не могут увидеть друг друга по мультикасту. Здесь два варианта: (1) держать ESPHome-сервер локально, в той же сети, что и устройства, (2) поднять VPN (WireGuard) между домашней сетью и сервером и указывать устройствам статический IP вместо автообнаружения. Мы разбирали, когда IoT-устройствам вообще имеет смысл жить за VPN, в статье про VPN для IoT-устройств — та же логика применима и к ESPHome-хосту.
• Docker в режиме bridge — см. предыдущий пункт, лечится network_mode: host.
• ESP-устройство ушло в deep sleep между опросами — если в конфиге есть deep_sleep:, устройство физически недоступно большую часть времени, и это нормально, а не баг.
• Роутер режет multicast между VLAN/гостевой сетью — если умные розетки на гостевом Wi-Fi, а сервер в основной сети, mDNS туда не дойдёт даже в пределах одной квартиры.

Если автообнаружение принципиально не заводится, обходной путь — прописать IP вручную при загрузке через дашборд (кнопка «Manual» вместо «Wirelessly») или добавить в конфиг устройства:

api:
  encryption:
    key: "ваш-base64-ключ"

ota:
  - platform: esphome

и заливать прошивку командой с явным адресом:

esphome upload my-device.yaml --device 192.168.1.45

Это работает даже без mDNS, потому что вы сами указываете, куда стучаться.

Первая прошивка ESP32/ESP8266: без USB на сервере не обойтись

Вот честный нюанс, который редко проговаривают: первую прошивку устройства нельзя залить по воздуху. Пока на чипе нет ESPHome-прошивки с настроенным OTA и Wi-Fi, единственный путь — по USB. Если ESPHome крутится на удалённом сервере без физического доступа к плате, это создаёт проблему.

Рабочая схема:

1. Установите ESPHome локально на компьютер (pip install esphome или docker run --device=/dev/ttyUSB0 ...), подключите ESP по USB и один раз залейте базовую прошивку с Wi-Fi и OTA-настройками.
2. Устройство перезагружается, подключается к вашей Wi-Fi сети — с этого момента оно доступно по сети.
3. Переносите .yaml-файл устройства в /config на сервере (просто скопируйте файл в volume esphome-config), и дальше все обновления идут через ota: — сервер прошивает устройство удалённо, USB больше не нужен.

Если серверов для флэша под рукой вообще нет — flash можно сделать и с телефона: ESPHome Web (esphome.io/web) позволяет прошить плату через USB прямо из браузера по Web Serial API (Chrome/Edge), без установки чего-либо. Подходит для разового первого флэша, дальше конфиг всё равно ведите централизованно на сервере — так проще держать версии прошивок в git и не терять YAML при поломке одного устройства.

Ошибки компиляции YAML: платы, пины и память

Типичные ошибки при esphome compile и что за ними стоит:

Компиляция на слабом VPS (1 vCPU, 1 ГБ RAM) для ESP8266 иногда занимает несколько минут — PlatformIO собирает C++ из исходников, а не просто копирует бинарник. Если сервер регулярно уходит в своп во время сборки, это заметно по логам (docker compose logs esphome | grep -i memory) — в таком случае стоит смотреть в сторону сервера с 2+ ГБ RAM, особенно если устройств в конфиге десятки и вы часто пересобираете прошивки пачками.

Wi-Fi не подключается или «Component was marked failed»

Строка в логах вида [W][wifi:xxx]: Component wifi was marked failed означает, что устройство прошилось, но не смогло присоединиться к сети. Причины:

• Сеть 5 ГГц. ESP8266 и большинство ESP32 (кроме отдельных моделей с двухдиапазонным модулем) поддерживают только 2.4 ГГц. Если роутер настроен на один SSID с автовыбором диапазона, устройство может пытаться подключиться к 5 ГГц-сегменту и падать.
• WPA3-only сеть. Часть старых прошивок ESP не умеет WPA3 — переключите точку доступа на WPA2/WPA3-mixed.
• Неверный пароль в секретах. Проверьте secrets.yaml — частая ошибка, когда пароль обновили в роутере, но не в конфиге:

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

  ap:
    ssid: "Device Fallback Hotspot"
    password: "12345678"

Обратите внимание на блок ap: — это резервная точка доступа, которая поднимается, если основной Wi-Fi недоступен. Подключитесь к ней с телефона (SSID будет виден в списке сетей), зайдите на 192.168.4.1 и перепропишите Wi-Fi-данные через встроенный портал — не придётся тащить устройство обратно к компьютеру с USB-кабелем.

• Недостаточное питание. Если устройство подключается, работает пару секунд и уходит в reboot loop с ошибками brownout (Brownout detector was triggered), это почти всегда просадка питания — особенно на длинных USB-кабелях или дешёвых блоках питания на 500 мА для ESP32, который в пике потребляет больше при работе радиомодуля.

Handshake failed / API encryption key не совпадает

После включения шифрования API (по умолчанию с 2022 года ESPHome генерирует ключ автоматически) Home Assistant иногда не может подключиться к устройству с ошибкой Handshake failed: Bad MAC или Encryption key not set. Обычно это значит одно из двух:

1. Устройство перепрошили с новым сгенерированным ключом, а в интеграции Home Assistant остался старый — удалите интеграцию устройства в HA и добавьте заново, ключ подтянется автоматически при обнаружении через дашборд.
2. Ключ в secrets.yaml на сервере отличается от того, что реально зашито в устройство (например, конфиг редактировали на двух разных машинах и потеряли синхронизацию) — сверьте значение api.encryption.key в собранном YAML устройства с тем, что видит Home Assistant в Settings → Devices → интеграция ESPHome.

Если Home Assistant тоже развёрнут на этом сервере (частая связка — Home Assistant в Docker Compose и ESPHome рядом на том же хосте), убедитесь, что оба контейнера в одной сети или оба в network_mode: host — иначе HA просто не достучится до API устройства даже с правильным ключом. Похожие сетевые грабли на стороне самого HA разобраны в статье про частые ошибки Home Assistant на сервере.

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