С тех пор как прямые способы прошивки ESP-устройств стали недоступны из-за внешних ограничений, многие столкнулись с проблемой. Но решение есть — используем облачную сборку на GitHub.
Пошаговая инструкция
Шаг 1: Создайте репозиторий на GitHub
- Нажмите зелёную кнопку New (новый репозиторий)
- Введите название, например esphome-devices
- Выберите Public или Private (на ваше усмотрение)
- Нажмите Create repository
Шаг 2: Создайте конфигурацию устройства ESPHome
- В репозитории нажмите Add file → Create new file
- Назовите файл device.yaml
- Вставьте конфигурацию например из HA
- Нажмите Commit changes
Шаг 3: Настройте секреты
Секреты — это безопасный способ хранить пароли. Они шифруются и недоступны другим пользователям.
- Перейдите в Settings → Secrets and variables → Actions
- Нажмите New repository secret
- Добавьте два секрета:
WIFI_SSID
Ваша_WiFi_Сеть
WIFI_PASSWORD
ваш_wifi_пароль
Шаг 4: Добавьте GitHub Actions workflow
- Создайте файл build.yml. Для этого копируем .github/workflows/build.yml и вставляем в окно как на скриншоте ниже
- Нажмите Commit changes
Шаг 5: Запустите сборку
Прошивка соберётся автоматически при создании workflow. Также можно запустить вручную:
- Перейдите во вкладку Actions
- Выберите workflow 🏭 Сборка прошивки ESPHome
- Нажмите Run workflow → Run workflow
- Дождитесь завершения (2-5 минут)
Шаг 6: Скачайте прошивку
- Откройте завершённую сборку
- Прокрутите вниз до раздела Artifacts
- Скачайте firmware-package.zip
Распакуйте архив — внутри будут:firmware.bin — для OTA-обновлений factory.bin — для первичной прошивки README.txt — инструкция по использованию
Прошивка устройства
Первичная прошивка (через USB)
- Подключите ESP8266/ESP32 к компьютеру через USB
- Скачайте ESPHome Flasher
- Выберите COM-порт
- Загрузите factory.bin
- Нажмите Flash ESP
OTA-обновление (через Wi-Fi)
После первой прошивки все последующие обновления можно делать по воздуху:
- Найдите IP-адрес устройства (в роутере или через mDNS)
- Откройте в браузере http://IP-адрес-устройства
- Перейдите в раздел OTA Update
- Загрузите firmware.bin
- Дождитесь перезагрузки
Редактирование конфигурации
Все изменения делаются прямо на GitHub:
- Откройте файл device.yaml
- Нажмите иконку карандаша (Edit)
- Внесите изменения
- Нажмите Commit changes
Через 2-5 минут новая прошивка будет готова в разделе Actions.
Устранение проблем
Сборка не запускается
- Проверьте, что файл называется именно device.yaml
- Убедитесь, что workflow-файл находится в .github/workflows/
- Проверьте вкладку Actions — там будут ошибки
Ошибка компиляции
- Проверьте синтаксис YAML (отступы должны быть пробелами, не табами)
- Убедитесь, что платформа и плата указаны правильно
- ESP8266: platform: ESP8266, board: nodemcuv2
- ESP32: platform: ESP32, board: esp32dev
Устройство не подключается к Wi-Fi
- Проверьте секреты WIFI_SSID и WIFI_PASSWORD
- Убедитесь, что сеть работает на частоте 2.4 ГГц (5 ГГц не поддерживается)
- Попробуйте подключиться к резервной точке доступа устройства
Не могу найти IP-адрес устройства
- Откройте интерфейс роутера и найдите новое устройство
- Или подключитесь к резервной точке доступа (см. конфигурацию)
- Используйте mDNS: http://my-device.local (работает не всегда)
Интеграция с Home Assistant
После прошивки устройство автоматически обнаружится в Home Assistant
Заключение
GitHub Actions превращает сборку прошивок ESPHome в простой и надёжный процесс. Этот метод особенно полезен при блокировках, для командной работы или когда нужно собирать прошивки на разных компьютерах без установки зависимостей.
Вся работа происходит в браузере, секреты защищены, а прошивки собираются автоматически. Попробуйте — это действительно удобно!
Дополнение: Облачная подготовка + Локальная прошивка
Проблема: ESPHome зависает на скачивании библиотек из-за блокировок.
Решение: Собираем зависимости на GitHub, прошиваем локально — без интернета!
🔄 Как это работает:
- GitHub собирает все библиотеки
- Вы скачиваете готовую папку .esphome с зависимостями
- Локально прошиваете без скачивания дополнительных файлов
Краткая инструкция:
Шаг 1: Подготовка на GitHub
- Создайте репозиторий с device.yaml (используйте !secret для паролей)
- Запустите сборку вручную через Actions → Run workflow
Шаг 2: Локальная настройка
- Скачайте архив из раздела Artifacts (папка .esphome)
- Установите ESPHome на ПК: pip install esphome
- Создайте локальный device.yaml с реальными Wi-Fi данными
Шаг 3: Прошивка
- Скопируйте папку .esphome из архива в каталог с вашим device.yaml
- Подключите устройство к ПК (или включите для OTA)
- Запустите в командной строке:
cd /путь/к/папке
esphome run device.yaml
Результат:
ESPHome использует уже скачанные библиотеки и сразу начинает компиляцию и прошивку без дополнительных загрузок.