Блог
esptool: команды, флаги, починки
esptool — инструмент, который каждому владельцу ESP32 рано или поздно приходится запускать руками: Arduino IDE его прячет, PlatformIO прячет, а потом в один день прошивка падает, и вы печатаете Python в терминале. Команды, флаги и ошибки, которые не имеют смысла, пока не увидишь их однажды.
Что такое esptool?
esptool — официальный инструмент Espressif для общения с чипами ESP32 через serial: прошивка, стирание, чтение памяти, определение чипа. Через него проходят все пути прошивки: Arduino IDE тащит его в комплекте, PlatformIO тоже, веб-установщики его запускают. Знание esptool — это час отладки, который вы не повторите никогда.
Как проверить, что esptool установлен?
Выполните esptool.py version. Номер версии (5.x, 4.7 — что актуально) означает, что всё готово. «Command not found» — значит pip install esptool; единственное требование — Python 3.7+.
Какие команды esptool самые полезные?
Ядро esptool — пять команд: chip_id определяет чип, flash_id читает флеш, read_mac печатает заводской MAC, erase_flash стирает всё, а write_flash пишет бинарник по адресу — это 90% повседневного использования. merge_bin объединяет несколько бинарников в один образ, который можно отдать другому человеку.
Как прошить прошивку через esptool?
Одна строка: esptool.py write_flash 0x0 firmware.bin, на большинстве машин с --port COM3. Адрес важен сильнее, чем думают: 0x0 — это начало заводского образа, а приложения ESP-IDF идут по адресу 0x10000. Прошьёте не туда — плата загрузится в пустоту, так многие «убитые» платы на деле оказываются просто неверно прошитыми. FAQ по прошивке разбирает адреса и схемы разделов.
Как стереть флеш ESP32?
esptool.py erase_flash за секунды стирает весь чип. Предупреждение, которое все пропускают: стирается и загрузчик, так что плата, работавшая на заводской прошивке, не загрузится, пока вы не прошьёте что-нибудь обратно. Стирание чинит повреждённую таблицу разделов и циклы перезагрузки — относитесь к нему как к сбросу, а не ремонту.
Можно ли сделать бэкап флеша перед экспериментами?
esptool.py read_flash 0x0 0x400000 backup.bin дампнет первые 4 МБ в файл — стандартный приём «бэкап перед обновлением»; восстановление — это write_flash по тому же адресу. Один нюанс: простой бэкап не восстановится на плату с включённым шифрованием флеша — я узнал это на собственной шкуре прошлой весной.
Что делают флаги –port, –baud и остальные?
--port выбирает последовательный порт (COM3 на Windows, /dev/ttyUSB0 на Linux, /dev/cu.usbserial-XXXX на macOS); --baud задаёт скорость — 460800 безопасный быстрый выбор, а некоторые USB-чипы начинают заикаться выше 921600, так что всё зависит от мостового чипа вашей платы; --chip принудительно задаёт цель, если автодетект не сработал. Остальное можно игнорировать, пока какая-нибудь ошибка не назовёт флаг по имени.
Почему появляется «Failed to Connect to ESP32: Timed Out Waiting for Packet Header»?
Чип не в режиме загрузки. esptool нужен слушающий ROM-загрузчик, а классические причины: не подключённая цепь автоперезагрузки (голые модули), неверный порт или кто-то держит serial-линию — я однажды час гонялся за этой ошибкой, потому что был открыт Serial Monitor. Зажмите BOOT, нажмите EN, отпустите BOOT, повторите. На голых модулях замкните GPIO0 на землю при включении. Больше — в FAQ по отладке.
Почему прошивка зависает на 100%?
Данные записаны, и плата перезагружается в новую прошивку, оставаясь молчаливой — это нормально, если у прошивки нет вывода в serial. А вот цикл перезагрузки означает, что образ рассчитан на другой размер флеша или другой чип. Проверьте esptool.py chip_id, гляньте flash_id, прошейте заново.
Работает ли esptool одинаково на Windows, Linux и Mac?
Да — команды, флаги и адреса одинаковы, потому что это Python-скрипт на всех платформах. Различаются только имена портов и драйверы; в нашей базе знаний есть заметки о драйверах для каждой ОС.
Проекты по этой теме запускаются прямо в бесплатном симуляторе sensbench: схема уже собрана, прошивка включена — без аккаунта и установки.