ESPHome на Ubuntu 24.04: пошаговая установка

MAATRIX

Если вы хоть раз пытались прошить ESP32 через Arduino IDE — знаете это чувство: полчаса на настройку библиотек, ещё столько же на поиск, почему датчик не читается, и в итоге код на C++ ради одной кнопки в Home Assistant. ESPHome убирает всё это: вы описываете устройство в YAML-файле — какие пины, какие датчики, какая логика — а фреймворк сам собирает и заливает прошивку. Ниже — рабочая установка на чистой Ubuntu 24.04, с реальными командами и без сюрпризов с правами на USB.

Что такое ESPHome и зачем он на сервере

ESPHome — это два компонента: инструмент сборки прошивок (компилирует ваш YAML в бинарник для ESP8266/ESP32/ESP32-C3/ESP32-S3 через ESP-IDF или Arduino framework) и веб-дашборд для управления парком устройств. Дашборд удобно держать постоянно запущенным — тогда все конфиги, история версий прошивок и OTA-обновления собраны в одном месте, а не разбросаны по ноутбуку.

Есть два реалистичных сценария:

• Локальный сервер дома (мини-ПК, NUC, старый ноутбук под Ubuntu Server) — ESPHome и Home Assistant стоят рядом, USB-порт физически доступен для первой прошивки, а дальнейшие обновления идут по OTA внутри домашней сети. Это самый простой и предсказуемый вариант.
• Удалённый сервер (VPS или выделенный) — дашборд и хранилище конфигов живут в облаке, а к домашней сети сервер подключается по WireGuard. Первую прошивку всё равно придётся делать локально (USB-порта у облачного сервера физически нет), но дальше все обновления и мониторинг устройств можно вести удалённо через туннель. Честно предупреждаю: это на 15 минут дольше в настройке, зато не зависит от домашнего ПК.

В этой статье ставим ESPHome в Docker — это самый воспроизводимый способ, одинаково работающий что на домашнем мини-ПК, что на арендованном сервере.

Подготовка сервера

Понадобится Ubuntu 24.04 с установленным Docker. Если Docker ещё не стоит — разверните его по нашей инструкции про установку Docker на Ubuntu 24.04, здесь только контрольный минимум:

sudo apt update && sudo apt upgrade -y
docker --version
docker compose version

Если планируете прошивать устройства через USB (первая заливка всегда через USB, даже если потом всё будет по OTA), добавьте своего пользователя в группу dialout — иначе контейнер не увидит порт:

sudo usermod -aG dialout $USER
newgrp dialout

Проверьте, что плата вообще определяется системой после подключения по USB:

dmesg | grep -i tty
# ищите строку вида: cp210x ... ttyUSB0: cp210x converter now attached to ttyUSB0

Если строки нет — драйвер чипа USB-UART (CP2102, CH340 или FTDI, в зависимости от платы) либо не подгрузился, либо кабель «только для зарядки» без линий данных. Смените кабель — на удивление частая причина.

Установка ESPHome через Docker Compose

Создаём рабочую директорию и compose-файл:

mkdir -p ~/esphome/config
cd ~/esphome
nano docker-compose.yml

services:
  esphome:
    image: ghcr.io/esphome/esphome:latest
    container_name: esphome
    restart: unless-stopped
    privileged: true
    network_mode: host
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
    environment:
      - ESPHOME_DASHBOARD_USE_PING=true

Пара пояснений по нестандартным опциям:

• network_mode: host — обязателен, если хотите, чтобы дашборд видел устройства по mDNS (имена вида *.local) и OTA-обновления работали без ручного ввода IP каждой платы. Без host-режима Docker прячет контейнер за NAT и mDNS-пакеты не проходят.
• privileged: true — нужен, чтобы контейнер видел /dev/ttyUSB* и /dev/ttyACM* при подключении платы уже после старта контейнера. Можно заменить точечным devices: - /dev/ttyUSB0:/dev/ttyUSB0, но тогда при каждой новой плате придётся переписывать compose-файл и перезапускать контейнер — на практике privileged проще для домашней лаборатории из десятка устройств.

Поднимаем:

docker compose up -d
docker compose logs -f esphome

Дашборд поднимается на порту 6052. Если сервер локальный — открывайте http://<IP-сервера>:6052. Если сервер удалённый и порт наружу светить не хочется, пробросьте туннель:

ssh -L 6052:localhost:6052 user@ваш-сервер

и откройте http://localhost:6052 в браузере.

Первый запуск и защита дашборда

По умолчанию у ESPHome нет авторизации — на публичном IP это плохая идея, даже если правила брандмауэра ограничивают доступ (см. нашу статью про настройку firewall на Ubuntu 24.04). Добавьте логин прямо в compose-файл:

    environment:
      - USERNAME=admin
      - PASSWORD=замените-на-свой-сложный-пароль

После docker compose up -d перезапустится с базовой авторизацией. Для полноценного HTTPS лучше поставить перед дашбордом обратный прокси — подойдёт связка с Nginx как reverse proxy или Caddy с автоматическим SSL.

Первый YAML-конфиг устройства

В дашборде жмём «New Device», выбираем тип платы (например, ESP32 Dev Module или ESP8266 NodeMCU) — ESPHome сам создаёт базовый файл в ~/esphome/config/. Вот минимальный рабочий пример для ESP32 с датчиком температуры и влажности DHT22 на пине GPIO4:

esphome:
  name: living-room-sensor
  friendly_name: Датчик в гостиной

esp32:
  board: esp32dev
  framework:
    type: arduino

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

logger:
api:
  encryption:
    key: !secret api_key

ota:
  - platform: esphome
    password: !secret ota_password

dht:
  pin: GPIO4
  temperature:
    name: "Температура гостиная"
  humidity:
    name: "Влажность гостиная"
  update_interval: 60s

Файл secrets.yaml в той же папке config/ хранит чувствительные данные отдельно от конфига устройства — так их не утащишь случайно в git:

wifi_ssid: "MyHomeWiFi"
wifi_password: "пароль-от-роутера"
api_key: "сгенерированный-32-байтный-ключ-в-base64"
ota_password: "отдельный-пароль-для-прошивки"

Ключ для api.encryption.key дашборд сгенерирует сам при первом сохранении — не придумывайте его вручную.

Заливка прошивки: USB и OTA

Первая прошивка — всегда через USB, потому что устройству ещё некуда подключаться по Wi-Fi с готовой прошивкой. Подключите плату кабелем к машине, где физически запущен контейнер (это критично: если ESPHome работает на удалённом сервере, USB-прошивку с домашнего ПК придётся делать через локальную установку esphome — pip install esphome в виртуальном окружении, отдельно от серверного дашборда).

В дашборде жмём на устройство → Install → «Plug into this computer». Браузер (Chrome или Edge с поддержкой WebSerial) сам найдёт порт и зальёт прошивку — прогресс виден в реальном времени.

После первой заливки устройство перезагружается, подключается к Wi-Fi и появляется в дашборде со статусом online. Все последующие обновления — уже по воздуху:

# то же самое можно сделать из CLI внутри контейнера
docker exec -it esphome esphome run config/living-room-sensor.yaml

ESPHome сам обнаружит устройство в сети (mDNS) и отправит новую прошивку по OTA — кабель больше не нужен, если только вы не меняете физическую конфигурацию (например, тип платы или framework).

Интеграция с Home Assistant

Если Home Assistant стоит рядом (см. нашу пошаговую установку Home Assistant на Ubuntu 24.04), интеграция автоматическая: как только устройство с блоком api: в конфиге появляется в сети, Home Assistant предлагает добавить его через Settings → Devices → в углу выскочит уведомление «Discovered». Никаких MQTT-брокеров и ручной настройки топиков — ESPHome API работает напрямую поверх локальной сети.

Если автообнаружение не сработало (частая причина — Home Assistant и ESPHome в разных Docker-сетях без network_mode: host), добавьте интеграцию вручную: Settings → Devices & Services → Add Integration → ESPHome → укажите IP устройства и api_key из secrets.yaml.

Для домашней автоматизации без Home Assistant ESPHome тоже полезен сам по себе — у него есть встроенная логика (automation, interval, binary_sensor с триггерами), можно собрать простые сценарии прямо в YAML устройства, без внешнего мозга.

Обновления, бэкапы и типичные проблемы

Обновление самого ESPHome — это подтягивание нового образа:

cd ~/esphome
docker compose pull
docker compose up -d

Все конфиги лежат в ~/esphome/config/ в виде обычных YAML-файлов — бэкапить директорию целиком (git, rsync, или наш гайд по автоматическим бэкапам на Ubuntu 24.04). Это отдельный плюс перед Tasmota или ручными прошивками — вся конфигурация десятков устройств восстанавливается из текстовых файлов за минуты.

Частые грабли:

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