esptool: как прошить ESP32 и ESP8266

Установка

Для esptool 5 нужен Python 3.10 или новее; на Python 3.7–3.9 работает esptool 4, на Python 2.7 и 3.4–3.6 — версия 3.3. Установка из PyPI:

pip install esptool

Если команда pip не находится, подойдут python -m pip install esptool или pip3 install esptool. После установки утилита запускается как esptool или python -m esptool; у Python из Microsoft Store работает, скорее всего, только второй вариант. Разработчики советуют ставить esptool в отдельное виртуальное окружение (python -m venv), чтобы не задеть версии, которые используют ESP-IDF или PlatformIO.

Без Python можно обойтись готовыми сборками со страницы релизов на GitHub: для Windows (x86-64), Linux (x86-64, ARMv7, AArch64) и macOS (x86-64 и ARM). У них есть ограничения: они дольше запускаются, весят больше, а антивирус иногда принимает их за вредоносные.

esptool, установленный в составе ESP-IDF, Arduino или PlatformIO, лучше обновлять средствами самой среды: обновление до другой основной версии (с 4.x на 5.x) может сломать её команды.

Что изменилось в esptool 5

В версии 5 команды и ключи пишутся через дефис, а не через подчёркивание, а утилита вызывается без .py. Старые имена пока работают с предупреждением, но будут удалены в следующей основной версии — в инструкциях из интернета они встречаются постоянно.

Ключ --verify у write-flash больше не нужен: после записи esptool проверяет данные сам, если это технически возможно.

Основные ключи

Общие ключи пишутся сразу после esptool, до команды:

Соединение esptool всегда устанавливает на 115 200 бит/с, а большую скорость включает только для передачи данных. По документации, с 230 400 бит/с работает почти любое оборудование, со скоростями 460 800, 921 600 и 1 500 000 бит/с — многие платы; при сбоях скорость снижают, вплоть до 9600 бит/с. Порт, скорость и чип можно задать и переменными окружения ESPTOOL_PORT, ESPTOOL_BAUD и ESPTOOL_CHIP.

Готовые команды

Записать прошивку

# один файл приложения
esptool --port COM5 write-flash 0x10000 firmware.bin

# загрузчик, таблица разделов и приложение проекта ESP-IDF для ESP32
esptool --chip esp32 -b 460800 write-flash 0x1000 bootloader.bin 0x8000 partition-table.bin 0x10000 app.bin

После write-flash идут пары «адрес — файл»; адрес пишут в шестнадцатеричном (0x10000) или десятичном виде. Перед записью esptool стирает затронутые секторы по 4096 байт; ключ -e (--erase-all) стирает всю память, а -s (--skip-flashed) пропускает запись, если в памяти уже лежит тот же файл.

Адрес загрузчика зависит от чипа:

Адреса таблицы разделов и приложения — из стандартной таблицы ESP-IDF; в проекте со своей таблицей разделов они другие. Точную команду со всеми адресами печатает сама среда: ESP-IDF — после сборки, Arduino IDE — при загрузке, если в настройках включён подробный вывод при загрузке.

Полный образ одним файлом

# собрать загрузчик, таблицу разделов и приложение в один образ
esptool --chip esp32 merge-bin -o merged.bin --flash-mode dio --flash-size 4MB 0x1000 bootloader.bin 0x8000 partition-table.bin 0x10000 app.bin

# записать его
esptool write-flash 0x0 merged.bin

В двоичном образе промежутки между файлами заполнены байтами 0xFF, поэтому запись медленнее и стирает память между частями. С ключом --format hex получается файл Intel HEX без заполнения, который пишется быстрее.

Сохранить прошивку с платы

# прочитать всю флеш-память, размер определить автоматически
esptool -p COM5 -b 460800 read-flash 0 ALL backup.bin

Размер можно задать числом байтов или с суффиксом: 0x400000 или 4M. Записать сохранённый образ обратно — esptool write-flash 0x0 backup.bin.

Стереть память и узнать параметры

esptool erase-flash                 # стереть всю флеш-память
esptool erase-region 0x9000 0x6000  # стереть область: адрес и длина кратны 4096
esptool read-mac                    # MAC-адрес
esptool flash-id                    # производитель, модель и размер флеш-памяти

Команда erase-flash стирает всё, включая сохранённые настройки Wi-Fi и файловую систему. Если на чипе включены Secure Boot или шифрование флеш-памяти, esptool по умолчанию отказывается стирать память, чтобы не сделать чип непригодным.

Режим флеш-памяти, частота и объём

У загрузочного образа в заголовке записаны режим работы флеш-памяти (qio, qout, dio, dout), её частота и объём. По умолчанию esptool оставляет их такими, как в файле (keep), и учитывает только при записи образа по адресу загрузчика. Ключ --flash-size detect определяет объём по идентификатору флеш-микросхемы. Если плата прошивается без ошибок, но программа не запускается, документация советует первым делом попробовать режим --flash-mode dio: некоторые модули работают только в нём.

Как чип входит в загрузчик

Загрузчик в ПЗУ запускается, если в момент сброса вывод выбора режима притянут к нулю: у ESP32, S2 и S3 это GPIO0, у других чипов — свои выводы, их список — в справочнике «Выводы обвязки ESP32». На большинстве отладочных плат esptool делает это сам: линии DTR и RTS преобразователя USB-UART (CP210x, CH340, FTDI) подключены к выводу выбора режима и выводу EN, и перед прошивкой esptool переключает их в нужном порядке.

Если автоматический вход не срабатывает, плату переводят в загрузчик вручную: зажать кнопку BOOT, нажать и отпустить EN (RESET), отпустить BOOT и запустить esptool. Можно и держать BOOT нажатой всё время, пока esptool подключается.

Загрузчик работает по UART с уровнями 3,3 В: 115 200 бит/с (у ESP8266 сообщения при загрузке выводятся на 74 880 бит/с), 8 бит данных, 1 стоповый бит, без чётности и управления потоком. Вывод TX микроконтроллера соединяется с RX адаптера и наоборот. Адаптеры с уровнями 5 В и порт RS-232 подключать нельзя.

Частые ошибки

• Failed to connect to ESP32: No serial data received. — esptool не получила от чипа ни одного байта: чип не вошёл в загрузчик, не соединены RX и TX, неверный порт или порт занят другой программой (часто — забытым монитором порта). Проверьте питание 3,3 В, отключите устройства от выводов GPIO, попробуйте ручной вход в загрузчик и скорость -b 9600.
• Wrong boot mode detected (0xXX)! The chip needs to be in download mode — связь с чипом есть, но он запустился в обычном режиме: не сработала схема автоматического входа, нужен ручной вход кнопкой BOOT.
• Download mode successfully detected, but getting no sync reply — чип в загрузчике и передаёт данные, но не получает ответы компьютера: проблема на линии от адаптера к RX чипа.
• Invalid head of packet (0xXX): Possible serial noise or corruption — помехи или искажения на линии: плохой кабель USB, замыкание выводов флеш-памяти на макетной плате, просадка питания. Помогают меньшая скорость и указание типа чипа ключом --chip.
• Запись обрывается на середине — снизить скорость и проверить питание.
• Прошивка записалась, но не запускается — неверный режим флеш-памяти (попробовать dio), недостаточное питание или нет загрузчика по нужному адресу.
• Permission denied в Linux — у пользователя нет прав на порт: его добавляют в группу dialout командой sudo usermod -a -G dialout $USER.

Питание. Документация esptool указывает, что ESP потребляет до 70 мА постоянно и 200–300 мА в пиках, поэтому выхода 3,3 В микросхемы FT232R или платы Arduino для питания ESP недостаточно: иногда это работает, но ненадёжно. Голым модулям вроде ESP-WROOM-32 нужен внешний конденсатор на питании — его ёмкость указана в даташите модуля.