idf-ci

1.1.0 verified Sat May 09 auth: no python

Python library for CI/CD of ESP-IDF projects. Currently at version 1.1.0, released with a monthly cadence. Provides tools to automate building, testing, and deployment for ESP-IDF firmware.

pip install idf-ci

Common errors

error ImportError: cannot import name 'IDFBuild' from 'idf_ci' ↓

cause Using an older version (<1.0.0) where the class was named Builder.

fix

Upgrade idf-ci: pip install --upgrade idf-ci, or use from idf_ci import Builder for old versions.

error FileNotFoundError: [Errno 2] No such file or directory: 'idf.py' ↓

cause ESP-IDF environment not sourced.

fix

Source the environment: . $HOME/esp/esp-idf/export.sh

error PermissionError: [Errno 13] Permission denied: '/dev/ttyUSB0' ↓

cause Insufficient permissions to access the serial port.

fix

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

Warnings

gotcha The library requires the ESP-IDF environment to be sourced prior to use. Running commands without sourcing will result in missing toolchain errors. ↓

fix Run `. $HOME/esp/esp-idf/export.sh` before executing scripts.

breaking In version 1.0.0, the `IDFBuild` class was renamed from `Builder`. Existing code using `Builder` will break. ↓

fix Replace imports from `idf_ci.Builder` to `idf_ci.IDFBuild`.

gotcha The `Flash` class only supports serial ports; it does not support JTAG or other interfaces. ↓

fix Ensure you are using a UART serial connection. For JTAG, use esptool.py directly.

Imports

IDFBuild

wrong

from idf_ci import IDFBuilder

correct

from idf_ci import IDFBuild

Class is named IDFBuild, not IDFBuilder.

Flash
wrong
```
from idf_ci.flash import Flash
```
correct
```
from idf_ci import Flash
```
Flash is directly importable from idf_ci, not from a submodule.

Quickstart

Build an ESP-IDF project and flash it to a device.

from idf_ci import IDFBuild, Flash
import os

# Build the project
builder = IDFBuild(project_dir='./my_project', build_dir='./build')
builder.run()

# Flash the firmware
flash = Flash(port=os.environ.get('ESP_PORT', '/dev/ttyUSB0'))
flash.run(binary='./build/app.bin')