Как установить и настроить ESPHome на VPS

MAATRIX

Если дома собралось десяток датчиков и реле на ESP8266/ESP32, поддерживать для каждого свою прошивку в Arduino IDE быстро надоедает — один опечатался в пине, и вечер потрачен на отладку. ESPHome решает это через декларативный YAML: описали устройство, компилятор сам собрал firmware. Вопрос в том, где эту компиляцию и управление конфигами держать — Raspberry Pi дома греется и тормозит на компиляции, а VPS даёт постоянно доступный дашборд и мощность, которой хватает на сборку прошивки за секунды, а не минуты.

Что такое ESPHome и зачем выносить его на VPS

ESPHome — это инструмент от команды Home Assistant, который превращает YAML-конфиг в готовый бинарник для ESP8266, ESP32, RP2040 и части устройств на BK72xx/LN882x. Вместо ручного кода вы описываете компоненты — датчик температуры, реле, дисплей — блоками конфигурации, а ESPHome сам генерирует C++ поверх ESP-IDF или Arduino framework и компилирует прошивку.

Смысл переносить его на VPS простой: компиляция даже небольшого проекта на слабом одноплатнике (Raspberry Pi 3/4) занимает заметно больше времени, чем на обычном VPS с нормальным CPU — конкретной цифры не назову, она сильно зависит от модели платы и текущей загрузки, но разница ощущается сразу при первой сборке. Плюс сам дашборд ESPHome становится доступен из любой точки — не нужно поднимать VPN только ради правки одного YAML-файла с ноутбука в кафе.

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

Требования к серверу и подготовка ОС

Для ESPHome с десятком-другим устройств хватает скромного VPS — 1 vCPU и 1-2 ГБ RAM держат Docker-контейнер с дашбордом и очередь компиляций без проблем. Если планируете держать на той же машине ещё и Home Assistant, закладывайте от 2 vCPU и 4 ГБ, компиляция прошивок при этом не станет узким местом даже под нагрузкой.

Дальше — стандартная подготовка Ubuntu 24.04 или Debian 12:

apt update && apt upgrade -y
apt install -y curl ca-certificates gnupg ufw

Если Docker ещё не стоит — ставим его официальным скриптом:

curl -fsSL https://get.docker.com | sh
systemctl enable --now docker

Сразу заводим отдельного пользователя без root и добавляем в группу docker, чтобы не работать под суперпользователем каждый день:

adduser esphome
usermod -aG docker esphome

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

Официальный образ ESPHome собирает прошивки внутри контейнера, поэтому локально ничего компилировать не нужно. Создаём рабочую директорию и файл docker-compose.yml:

mkdir -p /opt/esphome/config
cd /opt/esphome

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:
      - TZ=Europe/Moscow

Несколько нюансов конфигурации:

• network_mode: host — нужен, чтобы дашборд корректно видел устройства в сети через mDNS и мог инициировать OTA-заливку по адресу вроде device.local. Без host-режима mDNS-discovery на новых прошивках работать не будет.
• privileged: true — используется, чтобы контейнер видел USB-устройства, если вы всё же пробрасываете плату напрямую на сервер (например, через USB over IP или если ESPHome стоит на мини-ПК рядом с роутером, а не в облаке).
• Том ./config — здесь будут лежать все YAML-файлы устройств и secrets.yaml с паролями и ключами Wi-Fi.

Поднимаем контейнер и проверяем логи:

docker compose up -d
docker compose logs -f esphome

Дашборд по умолчанию слушает порт 6052. Проверьте curl -I http://127.0.0.1:6052 изнутри сервера — должен вернуться 200 OK.

Первая прошивка ESP32/ESP8266: локальный этап

Открываем http://<IP-сервера>:6052 — попадаем в веб-интерфейс ESPHome. Жмём «New Device», выбираем тип платы (например, ESP32 Dev Module), вводите Wi-Fi SSID и пароль — они уйдут в secrets.yaml, а не будут храниться в конфиге устройства открытым текстом.

Дальше — критичный момент: на экране установки выбираете не «Wirelessly» (недоступно для устройства без прошивки), а «Plug into the computer running ESPHome Dashboard». Поскольку дашборд у нас на VPS, а плата физически у вас на столе, этот вариант не сработает напрямую — вместо этого:

1. В меню устройства выбираете «Download» — получаете скомпилированный .bin-файл прямо из браузера.
2. Переносите его на компьютер, к которому физически подключена плата по USB.
3. Прошиваете через ESPHome Web (работает в Chrome/Edge через WebSerial, ничего локально ставить не нужно) или через esptool.py:

pip install esptool
esptool.py --chip esp32 --port /dev/ttyUSB0 write_flash 0x1000 firmware.bin

После этого шага плата подключится к Wi-Fi и станет видна в сети — дальнейшие обновления уже можно заливать по воздуху (OTA), в том числе с VPS, если сервер видит устройство по IP.

Пример YAML-конфига: датчик температуры и влажности

Вот рабочий минимальный конфиг для ESP32 с датчиком DHT22 — именно такие блоки ESPHome собирает в прошивку без единой строчки C++ с вашей стороны:

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

esp32:
  board: esp32dev
  framework:
    type: arduino

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  fast_connect: true
  ap:
    ssid: "Livingroom-Sensor Fallback"
    password: "12345678"

captive_portal:

logger:
  level: INFO

api:
  encryption:
    key: !secret api_key

ota:
  - platform: esphome
    password: !secret ota_password

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

Файл config/secrets.yaml при этом общий для всех устройств в проекте:

wifi_ssid: "MyHomeWifi"
wifi_password: "supersecretpass"
api_key: "base64-строка-сгенерированная-esphome"
ota_password: "ещё-один-секрет"

Ключ api_key дашборд может сгенерировать сам кнопкой в интерфейсе — не придумывайте его вручную, там нужна конкретная длина под шифрование Noise Protocol, которое использует ESPHome API.

Доступ к дашборду, HTTPS и обновления по сети

Дашборд ESPHome без дополнительной настройки не имеет пароля — если сервер смотрит в интернет, это открытая дверь к вашим Wi-Fi-паролям в secrets.yaml. Минимум — закрыть порт файрволом и пускать только через VPN или SSH-туннель:

ufw allow OpenSSH
ufw allow from 10.0.0.0/24 to any port 6052
ufw enable

Если нужен доступ снаружи без туннеля — добавьте базовую авторизацию прямо в конфиг ESPHome (актуально для standalone-режима, не для Docker-дашборда) или поставьте перед контейнером reverse-proxy с Basic Auth и HTTPS — например, Caddy, который сам получает сертификат: с установкой на VPS разберётесь в статье про Caddy с авто-SSL.

Отдельный вопрос — сетевая доступность самих ESP-устройств для OTA-обновлений с VPS. Если платы сидят дома за NAT, а дашборд — в облаке, напрямую они друг друга не видят. Рабочий вариант — поднять WireGuard-туннель между домашним роутером (или мини-ПК рядом с ним) и VPS, тогда сервер получает прямой сетевой путь до устройств по внутренним IP туннеля. Как это настроить — в статье про установку WireGuard на VPS. Без туннеля обновления придётся катить локально с ноутбука в домашней сети — это тоже рабочий вариант, просто не такой удобный.

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

Главный сценарий использования ESPHome — отдать устройства в Home Assistant. Если он у вас тоже развёрнут на сервере (см. статью про установку Home Assistant на VPS), добавление устройства сводится к интеграции «ESPHome» в настройках HA — она либо находит устройство автоматически через zeroconf в той же сети, либо принимает IP вручную и API-ключ шифрования из secrets.yaml.

Ручное добавление по IP работает даже без общей локальной сети — если между HA и ESP-устройством есть сетевой путь (тот же VPN-туннель), соединение по протоколу ESPHome API (порт 6053, Noise-шифрование) поднимется напрямую, без завязки на дашборд ESPHome как таковой. То есть дашборд нужен только для компиляции и заливки прошивок, а рабочая связь HA ↔ устройство идёт мимо него.

После добавления HA сам подхватывает все name: из YAML как объекты — температуру, влажность, состояния реле — без ручного создания сущностей.

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