esptool (Espressif flashing tool)

What it is

esptool.py — Espressif's official tool for ESP32/ESP8266: flash firmware, read flash, chip info, baud-tuned serial boot control. The standard last-mile tool for ESP32 firmware.

Install

Via pipx (isolated, current stable):

sudo apt install pipx python3-venv
pipx install esptool
pipx ensurepath      # re-login so ~/.local/bin is on PATH

(pip install esptool in a venv works too. Needs Python 3.8+.)

USB serial access:

sudo usermod -aG dialout $USER     # re-login to apply

Authenticate

None — talks to the chip over USB/UART. No tokens involved.

Configure for this environment

Devices appear as /dev/ttyUSB0 (or /dev/ttyACM0 for native-USB chips like ESP32-S3). Convenience alias for the common fast-flash settings:

alias espflash='esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 460800'

For firmware destined at AWS IoT Core, keep device certificates in Vaultwarden (https://vault.portugalfuturista.org) — never bake shared certs into images.

Self-hosted equivalent

Fully local by design — flashing happens over USB on the laptop. Firmware artifacts can be archived to MinIO (http://192.168.0.40:9000) for reproducibility. For OTA at scale the self-hosted route is an update server behind the LAN; cloud OTA (AWS IoT Jobs) only when devices are off-LAN.

Aurélio integration

The embedded-linux skill uses esptool for ESP32 flash/verify cycles. Flashed firmware typically targets the mqtt-local broker or aws-iot connector endpoints.

Verify

esptool.py version
# esptool.py v4.x / v5.x ...
esptool.py --port /dev/ttyUSB0 chip_id
# Chip is ESP32-D0WDQ6 (revision ...)
# MAC: xx:xx:xx:xx:xx:xx

Troubleshooting

Permission denied: /dev/ttyUSB0 — not in dialout group, or a lingering serial monitor (minicom/IDE) holds the port.
Failed to connect — hold BOOT while plugging in (or press BOOT during connect) to force download mode; also try a lower --baud.
Device not enumerated — bad USB cable (charge-only) or missing driver for the CP210x/CH340 bridge; check dmesg | tail.
Flash write errors at high baud — drop to --baud 115200; some bridges and cables can't sustain 460800+.

2.2 KiB Raw Permalink Blame History