Перейти к содержимому
ESPHome Flasher

GitHub OTA — быстрый старт

GitHub OTA за несколько шагов

Предполагается, что манифест и бинарник отдаются с HTTPS (свой сервер или артефакт после CI), а в прошивке настроен http_request + разбор JSON.

1. Поднять версию в шаблоне

В .yaml.j2 (или в рендере) строка esphome.project.version должна совпадать с логикой сравнения на устройстве:

esphome:
  project:
    name: "vendor.project"
    version: "0.2.0-alpha.5"

При сборке через flasher можно задать без правки файла:

Окно терминала
# Windows PowerShell
$env:FIRMWARE_VERSION_OVERRIDE='0.2.0-alpha.5'
py -3.13 scripts/flasher.py -f path/to/device.yaml.j2 -a compile --local --board-profile esp32c6-supermini -y

2. Секреты для сборки на GitHub (OTA Pipeline)

Прошивка с сервера вшивает api_encryption_key и Wi‑Fi из secrets.yaml на момент esphome compile. Один секрет в GitHub — весь файл, без отдельного secret на каждый ключ.

  1. Локально: firmwares/secrets.yaml (копия с secrets.yaml.example), тот же api_encryption_key, что указан в Home Assistant при добавлении устройства.
  2. Репозиторий esphomeFlasher → Settings → Secrets and variables → Actions → New repository secret:
    • имя: ESPHOME_CI_SECRETS_YAML
    • значение: полное содержимое вашего firmwares/secrets.yaml
  3. Уже должен быть FIRMWARE_REPOS_TOKEN (клон внешних репо). В YAML можно оставить github_token: "ghp_ci_placeholder_token" — при сборке подставится этот PAT.

Альтернатива: секрет ESPHOME_CI_SECRETS_B64 = base64 -w0 firmwares/secrets.yaml (Linux).

Workflow OTA Pipeline вызывает scripts/prepare_ci_secrets.sh и копирует файл во все firmwares-external/*/. После OTA с сервера HA подключается с вашим ключом, а не с публичной заглушкой AAAA… из старого CI.

3. Собрать артефакт OTA

Локально из корня репозитория:

Окно терминала
py -3.13 scripts/flasher.py -f firmwares-external/mihazzzold.espHome_HumidifierSystem/espHome_HumidifierSystem.yaml.j2 -a ota --local --board-profile esp32c6-supermini -y

Итог — firmware.ota.bin (путь покажет ESPHome / flasher в логе).

4. Опубликовать манифест

Формат latest.json, который пишет scripts/generate_metadata.py (поля могут дополняться вашим клиентом на устройстве):

{
  "version": "0.2.0-alpha.5",
  "url": "https://firmware.vendor.com/pub/mihazzzold.mydevice/latest.bin",
  "changelog": "краткий текст…",
  "release_date": "2026-05-04",
  "min_version": "1.0.0"
}

Генерация из корня репозитория (--url — реальный HTTPS; плейсхолдеры вроде example.com скрипт отклонит):

Окно терминала
python scripts/generate_metadata.py 0.2.0-alpha.5 CHANGELOG.md --project mihazzzold.mydevice --url https://ota.yourdomain.com/firmware

Файлы появятся под firmwares/ota-server/<project>/.

Важно: тело ответа должно целиком помещаться в буфер чтения на устройстве (длинный changelog быстро превышает 1–2 KiB).

5. Проверить с устройства

В Home Assistant: сущности вроде Check for updates / статус OTA (если есть в конфиге). Либо лог UART после ручного вызова скрипта проверки.

Мини-чеклист

  • Версия в прошивке строго согласована с полем version в JSON.
  • URL и MD5 открываются с устройства (HTTPS, сертификат).
  • Размер JSON не обрезается при чтении в прошивке.
  • Устройство в сети и уже на совместимой базовой прошивке.

Дальше