Как прошить ESP32-контроллер, если в панели управления ESPHome это сделать не получается

Если при попытке установки вашего проекта на контроллер зависает панель управления ESPHome (она же ESPHome Device Builder или ESPHome dashboard) на скачивании или установке библиотек или других компонентов, то поздравляю с новой реальностью. Либо нас заблокировали оттуда, либо их заблокировали отсюда, либо всё вместе.

Выход есть и он состоит из трёх букв, которые нельзя рекламировать. Причём нужно сделать так, чтобы доступ в западный интернет был именно у вашего устройства с установленным ESPHome, либо у роутера, через который устройство выходит в интернет.

Альтернативой может быть установка ESPHome CLI (версия для работы через командную строку) на компьютер с Windows. Такое решение предлагают сами разработчики Open Home Foundation на своём сайте, но они рассказывают как должно быть, когда всё работает, а не по той причине, по которой вы читаете эти строки.

Установка Python

Скачайте Python с официального сайта. Необходима версия не ниже 3.11. Версию 3.14 и выше ставить не рекомендуется.

Убедитесь, что вы отметили пункт «Add pyton.exe to PATH»

Нажмите на Install Now и пройдите весь процесс установки:

После чего выйдите из системы и войдите снова или перезагрузите компьютер. Как вам удобнее.

Откройте меню «Пуск», введите в строке поиска cmd и нажмите Enter. Можно правой кнопкой нажать на «Пуск», вызвать контекстное меню и выбрать Терминал.

В открывшемся окне терминала проверьте, установлен ли Python. Для этого введите команду:

python --version

Ответом должен быть номер версии. В моём случае — это 3.13.11.

Возможные проблемы

Если команда возвращает Python без указания версии:

то некоторые советуют проверить версию с помощью другой команды:

py --version

а потом бегать по форумам и спрашивать, почему всё равно ничего не работает, даже если ответом стал номер версии.

О разнице между python и py есть целая статья в документации по использованию Python в Windows. В дебри лезть не буду и предлагаю просто удалить все установленные на компьютере версии Python и воспользоваться магазином приложений Microsoft Store. Откройте его и введите в строку поиска python:

Устанавливайте версию 3.13, которая должна работать как ей положено:

По крайней мере с ней у меня никогда проблем не возникало.

После установки и перезагрузки компьютера (хотя должно работать и без неё), снова проверяем версию в Терминале.

Установка дополнительных пакетов

На следующем шаге установите пакет Wheel командой:

pip3 install wheel

После установки может появиться сообщение, что скрипт wheel.exe установлен по такому-то пути, который не прописан в «PATH»:

WARNING: The script wheel. exe is installed in ‘C:\Users…\Scripts’ which is not on PATH.
Consider adding this directory to PATH or, if you prefer to suppress this warning, use — no-warn-script-location.

Чтобы это исправить, откройте меню «Пуск», введите в строке поиска SystemPropertiesAdvanced и нажмите Enter. Откроется окно «Свойства системы». Нажмите на кнопку «Переменные среды…»:

В новом окне найдите строку с переменной «Path» и дважды кликните по ней. Либо выделите её и нажмите на кнопку «Изменить…»:

Откроется новое окно «Изменить переменную среды», куда нам нужно будет записать наш путь к скриптам.

Перейдите в терминал, выделите путь без кавычек скопируйте его в буфер обмена:

У вас этот путь будет точно другой, но конкретно в моём случае это C:\Users\admin\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.13_qbz5n2kfra8p0\LocalCache\local-packages\Python313\Scripts.

Если имя пользователя содержит кириллицу, то рекомендую его заменить на %USERPROFILE%. Например:

вместо C:\Users\Имя_пользователя\AppData\…

должно быть %USERPROFILE%\AppData\…

Вернитесь в предыдущее окно «Изменить переменную среды», нажмите кнопку «Создать»:

и вставьте из буфера ваш путь из терминала в конец списка:

нажимайте на всех открытых ранее окнах «ОК» и возвращайтесь в окно терминала:

В самом конце нам предлагают обновить менеджер пакетов PIP до последней версии:

[notice] A new release of pip is available: 25.2 -> 25.3
[notice] To update, run: C:\Users\….\python.exe -m pip install —upgrade pip

Для обновления можно скопировать предложенную команду целиком (она в терминале выделена зеленым цветом), а можно обойтись короткой командой:

python -m pip install --upgrade pip

Затем устанавите саму ESPHome с помощью команды:

pip3 install esphome

После успешной установки проверьте версию ESPHome с помощью команды:

esphome version

Если версия отобразилась, значит всё получилось. Почти.

Проверить наличие обновлений и обновить ESPHome CLI на новую версию, используйте команду:

pip3 install esphome --upgrade

или:

pip3 install esphome -U

Разработчики ещё рекомендуют установить Git. Загрузите его с официального сайта. Подойдёт любая из ссылок, обозначенных стрелками:

Установка проста и состоит из нескольких шагов: после кнопки «Install» везде нажимаем на «Next», пока не появится «Finish»:

Теперь можно переходить к компиляции и прошивке ESP32-контроллера.

Подготовка к прошивке

Для прошивки контроллера с помощью ESPHome CLI нужен файл конфигурации в формате YAML. Его можно скачать из панели управления ESPHome или составить самостоятельно. Первый способ проще. Откройте панель ESPHome, нажмите на кнопку «NEW DEVICE», а затем в появившемся окне выберите «CONTINUE»:

В новом окне выберите «New Device Setup»:

Придумайте название конфигурации и нажмите на «NEXT»:

Выберите тип микроконтроллера, для которого будет создан файл конфигурации:

В моём случае это ESP32-C3 — наиболее доступный бюджетный вариант.

Конфигурация готова. Поскольку установка у нас не работает, нажмите «SKIP»:

Encryption key сейчас никуда сохранять не нужно, он будет записан в файл конфигурации, и вы сможете просмотреть его в любое время там или через контекстное меню готовой конфигурации.

Нажмите на три точки и выберите в меню «Download YAML»:

В итоге получается файл примерно такого содержания:

В нём найдите строку wifi, и измените !secret wifi_ssid и !secret wifi_password на название и пароль от вашей Wi-Fi сети. Они обязательно должны быть заключены в кавычки.

Значительно упрощает работу с устройством веб-сервер. Рекомендую всегда его использовать, если не критична автономность и достаточно памяти. Он помогает проверить работоспособность и напрямую обновить прошивку микроконтроллера по воздуху. Для этого в наш файл нужно добавить всего две строки:

web_server:
  port: 80

В результате получится что-то вроде этого:

Файл с итоговым примером конфигурации

Создайте каталог (папку) с коротким названием и перенесите туда готовый файл. Чем проще и короче до неё будет путь, тем меньше вероятность ошибок.

В моём случае это будет каталог esp в корне диска c. Путь до неё соответственно будет c:\esp. В нём находится файл конфигурации с именем test.yaml.

Прошивка контроллера

Ввернитесь к терминалу и с помощью команды cd перейдите в созданный каталог. В моём примере команда будет выглядеть так:

cd c:\esp

Теперь подключите своё устройство к компьютеру через USB и введите следующую команду:

esphome run test.yaml

Вы увидите, как ESPHome проверит конфигурацию, а затем приступит к компиляции прошивки:

Первый раз весь процесс у меня занял приблизительно 1,5 минуты. По окончании ESPHome предложит выбрать порт для устройства:

Выберите COM-порт, к которому подключён ваш ESP32-контроллер (в моём случае это COM8). После этого ESPHome выполнит прошивку устройства:

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

OTA-обновление через веб-сервер

Если в конфигурацию был добавлен веб-сервер, то через некоторое время по адресу имя_устройства.local (в примере — это test.local) или по IP-адресу (мой роутер назначил устройству 192.168.1.41) появится страница устройства с данными от сенсоров, если они были подключены, и возможность обновить прошивку «по воздуху»:

Для этого способа обновления прошивки потребуется файл firmware.ota.bin, который создается ESPHome при каждой компиляции прошивки и находится внутри каталога с вашим файлом конфигурации.

Для примера, предлагаю добавить для доступа к веб-серверу устройства HTTP-аутентификацию. Для этого в файле test.yaml измените параметры конфигурации веб-сервера следующим образом:

web_server:
  port: 80
  auth:
    username: "логин"
    password: "пароль"

Кавычки нужно оставить. YAML к ним чувствителен, как и к количеству пробелов.

Сохраните изменения в файле. В терминале вместо esphome run test.yaml выполните команду:

esphome compile test.yaml

После компиляции прошивки ESPHome покажет точный путь к месту расположения файла firmware.ota.bin:

Кроме firmware.ota.bin в этом каталоге будут находиться файлы с похожими названиями firmware.bin и firmware.factory.bin.

firmware.ota.bin и firmware.bin внутри одинаковые и при прошивке через OTA можно выбирать любую из них.

Возвращайтесь на страницу устройства, выбирайте файл с обновлённой прошивкой и нажимайте «Update». Начнётся процесс обновления:

После успешного обновления откроется пустая страница с надписью «Update Successful!».

Теперь для доступа к test.local потребуется ввести логин и пароль: