Esptool.py Documentation - ESP32-S3 - — esptool.py latest documentation (original) (raw)
This is the documentation for esptool.py - a Python-based, open-source, platform-independent utility for flashing, provisioning, and interacting with Espressif SoCs. Esptool communicates with the ROM bootloader (or the flasher stub) in Espressif SoCs.
The flasher stub is a small program included with esptool that replaces the original ROM bootloader in the chip to fix some of its limitations and bugs. See Flasher Stub for more details.
esptool.py, espefuse.py and espsecure.py are a complete toolset for working with Espressif chips. They can do a number of things, for example:
- Read, write, erase, and verify binary data stored in flash.
- Read chip features and other related data such as MAC address or flash chip ID.
- Read and write the one-time-programmable eFuses.
- Prepare binary executable images ready for flashing.
- Analyze, assemble, and merge binary images.
esptool.py can be used both as a command-line tool and as a Python library. The command-line is the most common way to use the tool, and is the primary focus of this documentation. To use it as a library, see the scripting section.
This document describes using esptool.py with the ESP32-S3 SoC. To switch to a different SoC target, choose target from the dropdown in the upper left.
Quick Start
Getting started is easy:
- Install
esptool.py: - Connect an Espressif chip to your computer.
Note
Please note that serial communication has to work and chip has to be in the download mode. This is usually done automatically or can be done manually. Esptool cannot function until this is resolved. For more information, see Troubleshooting.
- Run
esptool.pycommands. For example, to read information about your chip’s SPI flash, run:$ esptool.py -p PORT flash-id
Replace
PORTwith the name of used serial port. If connection fails, see Troubleshooting.
After successfully executing the command, esptool will hard reset the chip, causing it to run the user code. This behavior can be adjusted, see Advanced Options.
Alternatives
esptool.py is not the only tool for working with Espressif chips. Some notable options include:
- esptool.js is a JavaScript port of esptool.py that can be used in a web browser or in a Node.js environment.
- espflash is a Rust port of esptool.py. It relies on the support in esp-hal, which may delay support for new chips.
- OpenOCD is a general-purpose tool for debugging and flashing chips.
Among these, esptool.py is the most feature-rich, and support for the newest chips and features usually appears here first.