Как установить esptool для ESP32 на Windows, macOS и Linux

Как установить esptool для ESP32 на Windows, macOS и Linux

Устанавливаем esptool для ESP32 через Python: Windows, macOS и Linux. Проверяем порт, читаем информацию о чипе, стираем flash и разбираем частые ошибки.

esptool — официальная утилита Espressif для работы с микросхемами ESP8266 и ESP32 через последовательный порт. Ей можно стереть flash-память, записать прошивку, прочитать сведения о чипе и проверить соединение с платой.

Эта инструкция пригодится перед установкой MicroPython, CircuitPython, ESP-IDF, Arduino-образа или заводской firmware. В основной статье  esptool используется для записи .bin-файлов.

Что понадобится

  • Python 3. Убедитесь, что команды python --version или python3 --version работают.
  • ESP32 и USB-кабель с передачей данных.
  • Драйвер USB-UART, если на плате CP210x, CH340/CH341 или CH9102.
  • Терминал: PowerShell/Windows Terminal, Terminal в macOS или любой shell в Linux.

Установка через pip

Самый простой способ:

python -m pip install --upgrade esptool

На macOS/Linux, если Python вызывается как python3:

python3 -m pip install --upgrade esptool

Проверьте результат:

python -m esptool version

Если команда вывела версию, всё готово. В этой серии статей используем форму python -m esptool, а не просто esptool: она надёжнее работает в системах, где папка с исполняемыми скриптами Python не добавлена в PATH.

Рекомендуемый вариант: виртуальное окружение

Если не хотите устанавливать пакеты Python глобально, создайте отдельное окружение:

python -m venv esptoolenv

Активируйте его.

Windows PowerShell

.\esptoolenv\Scripts\Activate.ps1

Windows cmd.exe

esptoolenv\Scripts\activate.bat

macOS и Linux

source esptoolenv/bin/activate

Теперь установите пакет:

python -m pip install --upgrade esptool

После завершения работы окружение можно отключить:

deactivate

Находим последовательный порт

Windows

Подключите ESP32, откройте «Диспетчер устройств» и найдите раздел «Порты (COM и LPT)». Запомните номер, например COM5.

macOS

ls /dev/cu.*

Часто будут видны /dev/cu.usbserial-*, /dev/cu.SLAB_USBtoUART или /dev/cu.wchusbserial*.

Linux

ls /dev/ttyUSB* /dev/ttyACM* 2>/dev/null

Обычно это /dev/ttyUSB0 или /dev/ttyACM0.

Если подключаете плату в Linux и не видите порт, посмотрите последние сообщения ядра:

dmesg | tail -n 30

Проверяем связь с ESP32

Замените значение порта на своё.

macOS/Linux:

python -m esptool --port /dev/cu.usbserial-0001 chip_id

Windows:

python -m esptool --port COM5 chip_id

Для явного выбора семейства можно добавить --chip esp32:

python -m esptool --chip esp32 --port /dev/cu.usbserial-0001 chip_id

При успехе esptool покажет информацию о кристалле, MAC-адрес и другие параметры. Если команда не может подключиться, переведите плату в режим загрузчика: удерживайте BOOT, кратко нажмите EN/RESET, отпустите BOOT и запустите команду ещё раз.

Основные команды esptool

Стереть всю flash-память

python -m esptool --port <PORT> erase_flash

Пример:

python -m esptool --port COM5 erase_flash

Команда удалит программу, файловую систему и все данные из flash. Делайте это, если устанавливаете прошивку впервые, переходите между сильно разными firmware или устраняете проблемы с остаточными разделами памяти.

Записать один файл прошивки

Шаблон:

python -m esptool --chip <CHIP> --port <PORT> --baud 460800 write_flash -z <OFFSET> <FIRMWARE.bin>

Пример для распространённой generic-прошивки обычного ESP32:

python -m esptool --chip esp32 --port COM5 --baud 460800 write_flash -z 0x1000 firmware.bin

Но адрес нельзя считать универсальным. Для классического ESP32 MicroPython часто используется 0x1000; для ESP32-S3 MicroPython на странице загрузки может быть указан 0x0; CircuitPython для конкретной платы также требует свои параметры. Всегда берите CHIP, OFFSET и имя файла из инструкции к вашему firmware.

Снизить скорость передачи

Если прошивка срывается, замените 460800 на 115200:

python -m esptool --chip esp32 --port COM5 --baud 115200 write_flash -z 0x1000 firmware.bin

Это медленнее, но иногда стабильнее для плохого кабеля, USB-хаба или нестандартного USB-UART преобразователя.

Проблемы и решения

python не является внутренней или внешней командой

Установите Python 3 с официального сайта или через пакетный менеджер и перезапустите терминал. В Windows при установке Python включите опцию добавления Python в PATH. Иногда помогает команда py:

py -m pip install esptool
py -m esptool version
No module named esptool

Пакет установлен для другого интерпретатора Python. Ставьте и запускайте его через один и тот же путь:

python -m pip install --upgrade esptool
python -m esptool version
Failed to connect / Connecting...
  • Проверьте правильность COM-порта или /dev/tty....
  • Закройте Arduino IDE, Thonny, serial monitor и другие программы, удерживающие порт.
  • Войдите в bootloader комбинацией BOOT + RESET.
  • Используйте другой USB-кабель и прямое подключение без хаба.
  • Установите драйвер CP210x/CH340, если порт вообще не появляется.
Permission denied в Linux

Добавьте пользователя в группу dialout:

sudo usermod -aG dialout $USER

Затем завершите сеанс пользователя и войдите снова. Временно можно запускать через sudo, но постоянное использование sudo для esptool лучше не делать.

Порт исчезает после прошивки

У некоторых ESP32-S2/S3/C3 плат порт в bootloader и порт работающей прошивки — это разные USB-устройства. Отключите и подключите плату заново, затем снова проверьте список портов.