Esptool

https://docs.espressif.com/projects/esptool/en/latest/
Admin
Esptool is an open-source, Python-based utility for flashing firmware, provisioning eFuses, and...
Tokens:90,256
Snippets:607
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install esptool with pip

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/index.html

Install esptool using pip. This is the first step in the quick start guide.

```bash
$ pip install esptool
```

--------------------------------

### Install and enable pre-commit hooks

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/contributing.html

Commands to install the pre-commit framework and enable the required git hooks for automated code checks.

```bash
$ python -m pip install pre-commit
$ pre-commit install -t pre-commit -t commit-msg
```

--------------------------------

### Install development dependencies for esptool

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/contributing.html

Installs esptool plus additional packages useful for development using setuptools extras. This is needed for actually developing and testing esptool.

```bash
$ pip install --user -e ".[dev]"

```

--------------------------------

### pip install esptool==5.1.0 error output

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/troubleshooting.html

Shows the error output when installing esptool 5.1.0 with an outdated setuptools version. The error indicates that the package metadata reports an unknown project name, causing pip to reject the installation. To resolve, upgrade setuptools to at least 64.0.0 using `pip install setuptools>=64`.

```text
$ pip install esptool==5.1.0
Collecting esptool==5.1.0
....
WARNING: Generating metadata for package esptool produced metadata for project name unknown. Fix your #egg=esptool fragments.
Discarding https://files.pythonhosted.org/packages/.../esptool-5.1.0.tar.gz (from https://pypi.org/simple/esptool/) (requires-python:>=3.10): Requested unknown from https://files.pythonhosted.org/packages/.../esptool-5.1.0.tar.gz has inconsistent name: filename has 'esptool', but metadata has 'unknown'
ERROR: Could not find a version that satisfies the requirement esptool==5.1.0 (from versions: 4.0, 4.0.1, 4.1, 4.2, 4.2.1, 4.3, 4.4, 4.5, 4.5.1, 4.6, 4.6.1, 4.6.2, 4.7.0, 4.8.0, 4.8.1, 4.9.0, 4.10.0, 4.11.0, 5.0.0, 5.0.1, 5.0.2, 5.1.0)
ERROR: No matching distribution found for esptool==5.1.0

```

--------------------------------

### ESP32 ROM Boot Mode Message Example

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/advanced-topics/boot-mode-selection.html

Example output printed by the ESP32 ROM at 115200bps after reset. The second line shows the reset reason (rst:0x1 POWERON_RESET) and boot mode (boot:0x3 DOWNLOAD_BOOT(UART0/UART1/SDIO_REI_REO_V2)).

```text
ets Jun  8 2016 00:22:57
rst:0x1 (POWERON_RESET),boot:0x3 (DOWNLOAD_BOOT(UART0/UART1/SDIO_REI_REO_V2))

```

--------------------------------

### Install esptool in a virtual environment

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/installation.html

Commands for installing esptool in a virtual environment. Create a venv named 'esptoolenv', activate it (Windows vs Linux/macOS), install esptool, use it, and deactivate when done. The environment can be reused by activating it again.

```bash
python -m venv esptoolenv

```

```bash
esptoolenv\Scripts\activate

```

```bash
source esptoolenv/bin/activate

```

```bash
pip install esptool

```

```bash
esptool <command>

```

```bash
deactivate

```

--------------------------------

### Install esptool with pip

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/installation.html

Installs the latest stable esptool release from PyPI. Requires Python 3.10 or newer. If this command fails, try `python -m pip install esptool` or `pip3 install esptool`.

```bash
$ pip install esptool

```

--------------------------------

### Override flash settings with write-flash

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/esptool/flash-modes.html

Example of using --flash-mode and --flash-size arguments when writing a bootloader image.

```bash
esptool --port /dev/ttyUSB1 write-flash --flash-mode dio --flash-size 4MB 0x0 bootloader.bin
```

--------------------------------

### Clone and install esptool in development mode

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/contributing.html

Clones the esptool repository and installs it in development mode with pip. This creates executable script wrappers that run directly from the working directory, so changes are picked up automatically.

```bash
$ git clone https://github.com/espressif/esptool.git
$ cd esptool
$ pip install --user -e .

```

--------------------------------

### Using esptool.main() to pass CLI arguments

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/esptool/scripting.html

Passes the same arguments as the CLI to esptool.main() for basic integration. The example reads flash memory and saves it to a file.

```python
import esptool

command = ['--baud', '460800', 'read-flash', '0', '0x200000', 'flash_contents.bin']
print("Using command ", " ".join(command))
esptool.main(command)
```

--------------------------------

### Run all esptool integration tests on real hardware

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/contributing.html

Command format for running test_esptool.py against real Espressif hardware. Requires a serial port, chip name, and baud rate. Example runs all tests on an ESP32 board at /dev/ttyUSB0 with 230400 baud.

```bash
pytest test_esptool.py --port <serial port> --chip <name of chip> --baud <baud rate>
```

```bash
pytest test_esptool.py --port /dev/ttyUSB0 --chip esp32 --baud 230400
```

--------------------------------

### Convert ELF to Binary with custom output filename

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/esptool/basic-commands.html

Example of converting an ELF file where the output binary defaults to the same name with a .bin extension.

```bash
esptool --chip ESP32 elf2image my_esp_app.elf
```

--------------------------------

### Sample trace output for initial synchronization sequence

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/advanced-topics/serial-protocol.html

Example trace output showing part of the initial synchronization sequence with many 0x55 bytes (ASCII 'U'). The split display shows hexadecimal bytes on the left and ASCII on the right, with non-printable characters as '.'. Note the multiple 'Received full packet' lines.

```plaintext
TRACE +0.000   Write 46 bytes:
  c000082400000000 0007071220555555 | ...$........ UUU
  5555555555555555 5555555555555555 | UUUUUUUUUUUUUUUU
  5555555555555555 5555555555c0     | UUUUUUUUUUUUU.
TRACE +0.012   Read 1 bytes:         c0
TRACE +0.000   Read 63 bytes:
  0108040007071220 00000000c0c00108 | ....... ........
  0400070712200000 0000c0c001080400 | ..... ..........
  0707122000000000 c0c0010804000707 | ... ............
  122000000000c0c0 01080400070712   | . .............
TRACE +0.000   Received full packet: 010804000707122000000000
TRACE +0.000   Received full packet: 010804000707122000000000

```

--------------------------------

### Run RFC2217 Server and Client

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/remote-serial-ports.html

Commands to start the modified RFC2217 server on the host machine and connect to it from the client using the ign_set_control flag to handle network latency.

```bash
esp_rfc2217_server -p 4000 /dev/ttyUSB1
```

```bash
esptool --port rfc2217://ADDRESS_OF_SERVER:4000?ign_set_control flash-id
```

--------------------------------

### run

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/esptool/scripting.html

Execute the firmware loaded on the ESP device.

```APIDOC
## run

### Description
Execute the firmware loaded on the ESP device.

### Parameters
- **esp** (ESPLoader) - Required - Initiated esp object connected to a real device.

### Returns
None

### Example
```python
from esptool.cmds import connect_esp, run

with connect_esp() as esp:
    run(esp)
```
```

--------------------------------

### Using Batch Mode for eFuse Operations

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/scripting.html

Demonstrates enabling batch mode via init_commands, queuing operations like burning keys and setting eFuses, and executing them with burn_all. Includes verification steps to ensure eFuses were set correctly.

```python
from espefuse import init_commands

PORT = "/dev/ttyACM0"

# Connect to chip and enable batch mode
with init_commands(port=PORT, batch_mode=True) as espefuse:
    # Queue multiple eFuse operations
    with open("flash_encryption_key.bin", "rb") as f:
        espefuse.burn_key(["flash_encryption"], [f], no_protect_key=True)
    espefuse.burn_efuse({"FLASH_CRYPT_CNT": 0x7})
    espefuse.burn_efuse({"DISABLE_DL_ENCRYPT": 1})
    espefuse.burn_efuse({"JTAG_DISABLE": 1})

    # Execute all queued eFuse operations
    espefuse.burn_all()

    # Check that all eFuses are set properly
    espefuse.summary()

    # Checks written eFuses
    if espefuse.efuses["FLASH_CRYPT_CNT"].get() != 0x7:
        raise esptool.FatalError("FLASH_CRYPT_CNT was not set")
    if espefuse.efuses["DISABLE_DL_ENCRYPT"].get() != 1:
        raise esptool.FatalError("DISABLE_DL_ENCRYPT was not set")
    if espefuse.efuses["JTAG_DISABLE"].is_readable() or espefuse.efuses["JTAG_DISABLE"].is_writeable():
        raise esptool.FatalError("JTAG_DISABLE should be read and write protected")
```

--------------------------------

### Example of eFuse summary error output

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/check-error-cmd.html

This log shows an example of an error detected in BLOCK0 during a summary check.

```text
> espefuse summary
...
WDT_DELAY_SEL (BLOCK0)[FAIL:1]                     Selects RTC WDT timeout threshold at startup       = False R/W (0b0)
...
Error(s) in BLOCK0 [ERRORS:1 FAIL:1]

BLOCK0          (                ) [0 ] err__regs: 00000400 00000000 00000000 00000000 00000000 00000000
EFUSE_RD_RS_ERR0_REG        0x00000000
EFUSE_RD_RS_ERR1_REG        0x00000000
WARNING: Coding scheme has encoding bit error warnings
```

--------------------------------

### Run host test suite

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/contributing.html

Runs the whole test suite without tests needing actual hardware or additional prerequisites. Execute from the esptool root folder.

```bash
pytest -m host_test
```

--------------------------------

### esp_efuse_custom_table.csv example

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/index.html

Example of an esp_efuse_custom_table.csv file. It defines single eFuse fields, structured eFuse fields, and non-sequential bit fields. Non-sequential fields are split into sub-fields with _0 and _1 postfixes for safer handling.

```csv
MODULE_VERSION,                EFUSE_BLK3,       56,           8,          Module version
DEVICE_ROLE,                   EFUSE_BLK3,       64,           3,          Device role
SETTING_1,                     EFUSE_BLK3,       67,           6,          [SETTING_1_ALT_NAME] Setting 1
SETTING_2,                     EFUSE_BLK3,       73,           5,          Setting 2
ID_NUM,                        EFUSE_BLK3,      140,           8,          [MY_ID_NUM] comment
,                              EFUSE_BLK3,      132,           8,          [MY_ID_NUM] comment
,                              EFUSE_BLK3,      122,           8,          [MY_ID_NUM] comment
CUSTOM_SECURE_VERSION,         EFUSE_BLK3,       78,          16,          Custom secure version
ID_NUMK,                       EFUSE_BLK3,      150,           8,          [MY_ID_NUMK] comment
,                              EFUSE_BLK3,      182,           8,          [MY_ID_NUMK] comment
MY_DATA,                       EFUSE_BLK3,      190,          10,          My data
MY_DATA.FIELD1,                EFUSE_BLK3,      190,           7,          Field1

```

--------------------------------

### Connect, run stub, change baud, and attach flash with esptool.cmds

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/esptool/scripting.html

Shows the recommended high-level workflow: auto-discover the port, auto-detect the chip, optionally upload the stub flasher, raise the baud rate to 921600, and attach flash. Raises FatalError if no Espressif device can be reached on any candidate serial port.

```python
from esptool.cmds import connect_esp, attach_flash, run_stub

# Auto-discover the port and auto-detect the chip
with connect_esp() as esp:
    esp = run_stub(esp)  # Optional: upload the stub flasher
    esp.change_baud(921600)  # Upgrade to a faster operational rate
    attach_flash(esp)
    ...

```

--------------------------------

### Run esptool SDM integration tests

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/contributing.html

Command format for test_esptool_sdm.py, which tests esptool with chips in secure download mode. Requires real hardware with active SDM. The format is the same as for test_esptool.py.

```bash
pytest test_esptool.py --port <serial port> --chip <name of chip> --baud <baud rate>
```

--------------------------------

### pySerial error example: read failed: [Errno 6] Device not configured

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/troubleshooting.html

Example of a pySerial error message that esptool may print when the serial port cannot be accessed. This error is typically caused by hardware or driver issues, such as the port being in use, the device being disconnected, or missing permissions.

```text
A serial exception error occurred: read failed: [Errno 6] Device not configured

```

--------------------------------

### espefuse.get_esp

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/scripting.html

Gets the ESPLoader object for the given chip, using the esptool.cmds.detect_chip() function.

```APIDOC
## espefuse.get_esp

### Description
Get the ESPLoader object for the given chip. Uses `esptool.cmds.detect_chip()` function.

### Method
Function call

### Endpoint
`espefuse.get_esp(port: str | None = None, baud: int = 115200, before: str = 'default-reset', chip: str = 'auto', skip_connect: bool = False, virt: bool = False, debug: bool = False, virt_efuse_file: str | None = None, token: str | None = None) -> ESPLoader | EmulateEfuseControllerBase`

### Parameters
- **port** (str | None) - Optional - The port to connect to the chip
- **baud** (int) - Optional - The baud rate to connect to the chip
- **before** (str) - Optional - The reset mode to use before connecting to the chip. Supported values are: "default-reset", "usb-reset", "no-reset", "no-reset-no-sync"
- **chip** (str) - Optional - The chip to use
- **skip_connect** (bool) - Optional - Whether to skip connecting to the chip
- **virt** (bool) - Optional - Whether to use virtual mode
- **debug** (bool) - Optional - Whether to enable debug mode
- **virt_efuse_file** (str | None) - Optional - The file to save the eFuse values to
- **token** (str | None) - Optional - eFuse token dump (format string: EFSR:esp32:000:…)

### Returns
- **ESPLoader | EmulateEfuseControllerBase** - The ESPLoader object or EmulateEfuseController object
```

--------------------------------

### Flash encryption key file content

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/burn-key-cmd.html

Example content of a 256-bit flash encryption key file.

```text
0001 0203 0405 0607 0809 0a0b 0c0d 0e0f  1011 1213 1415 1617 1819 1a1b 1c1d 1e1f
```

--------------------------------

### Initialize Zsh autocompletion

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/installation.html

Required initialization steps for Zsh before enabling tool-specific completions.

```bash
autoload -U compinit
compinit
```

--------------------------------

### espefuse.main()

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/scripting.html

Passes command-line arguments to espefuse, allowing the same operations as the CLI.

```APIDOC
## espefuse.main()

### Description
Passes command-line arguments to espefuse, allowing the same operations as the CLI.

### Method
main

### Parameters
- **command** (list of str) - Required - List of command-line arguments, same as CLI.

### Request Example
```python
import espefuse

command = ["--port", "/dev/ttyACM0", "summary"]
print("Using command ", " ".join(command))
espefuse.main(command)
```

### Response
No return value documented.
```

--------------------------------

### EfuseFieldBase.get_meaning

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/scripting.html

Gets the meaning of the eFuse from a dictionary if possible, suitable for display. Optionally reads from the device or uses cached value.

```APIDOC
## EfuseFieldBase.get_meaning(from_read: bool = True) -> str | int | float | bool

### Description
Get the meaning of eFuse from dict if possible, suitable for display.

### Method
Function call

### Signature
`get_meaning(from_read: bool = True) -> str | int | float | bool`

### Parameters
- **from_read** (bool) - Optional - If True, read the eFuse value from the device. If False, use the cached value.

### Returns
- **str | int | bool** - The meaning of the eFuse.

```

--------------------------------

### load_ram

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/esptool/scripting.html

Load a firmware image into RAM and execute it on the ESP device.

```APIDOC
## load_ram

### Description
Load a firmware image into RAM and execute it on the ESP device.

### Parameters
- **esp** (ESPLoader) - Required - Initiated esp object connected to a real device.
- **input** (str | bytes | IO[bytes]) - Required - Path to the firmware image file, opened file-like object, or the image data as bytes.

### Returns
None

### Example
```python
from esptool.cmds import connect_esp, load_ram

with connect_esp() as esp:
    load_ram(esp, 'firmware.bin')
```
```

--------------------------------

### Update esptool standalone

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/installation.html

Use this command to update esptool to the latest version available on PyPI when installed globally or in a virtual environment.

```bash
$ pip install --upgrade esptool
```

--------------------------------

### Display eFuse protection status

Source: https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/read-write-protections-cmd.html

Example output showing the R/W protection status of a block, where -/W indicates read protection is set.

```text
BLOCK1 (BLOCK1):
= ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? -/W
```
Tokens:
Raw