ESP-IDF Monitor

1.9.0 verified Mon Apr 27 auth: no python

Serial monitor for Espressif ESP-IDF, providing output decoding, binary log support, and interactive CLI commands. Current version: 1.9.0. Release cadence: irregular, approximately 3-4 releases per year.

pip install esp-idf-monitor

Common errors

error ModuleNotFoundError: No module named 'monitor' ↓

cause Old import path for esp-idf-monitor.

fix

Use from esp_idf_monitor import ... instead.

error SerialException: could not open port /dev/ttyUSB0: [Errno 13] Permission denied: '/dev/ttyUSB0' ↓

cause User lacks read/write permission on the serial port.

fix

Add user to dialout group: sudo usermod -aG dialout $USER and log out/in.

error ValueError: No ELF files found. Provide ELF file using --elf option. ↓

cause Monitor cannot find the ELF binary.

fix

Specify the ELF file with --elf path/to/your_app.elf.

Warnings

breaking In v1.9.0, the 'idf-monitor' script is added; standalone usage requires Python 3.7+. Prior use via `idf.py monitor` is unchanged. ↓

fix Use 'idf-monitor' command or install via pip.

deprecated The old module path `from monitor import ...` is deprecated; use `from esp_idf_monitor import ...`. ↓

fix Replace `from monitor` with `from esp_idf_monitor`.

gotcha On Linux, if no ELF files are found, monitor may exit with an error. Ensure the ELF path is correct. ↓

fix Specify a valid ELF file via the `--elf` argument or `elf_file` parameter.

breaking The environment variable `ESP_IDF_MONITOR_NO_RESET` changed behavior in v1.4.0; it now disables reset on connect. ↓

fix Set `ESP_IDF_MONITOR_NO_RESET=1` to prevent resetting the chip on open.

Imports

make_monitor

wrong

from monitor import make_monitor

correct

from esp_idf_monitor import make_monitor

Wrong import path from old module name.

MONITOR_DIR

from esp_idf_monitor.constants import MONITOR_DIR

Correct import for constants.

Quickstart

Start the monitor with a serial port and ELF file.

from esp_idf_monitor import make_monitor

# Basic usage (requires a serial port, e.g., /dev/ttyUSB0)
monitor = make_monitor(
    serial_port='/dev/ttyUSB0',
    elf_file='build/myapp.elf',
    print_filter='tag:myapp'
)
monitor.run_forever()