23.6 ESP-IDF Development Environment

ESP Series Chip Overview

In addition to the STM32 platform, Espressif's ESP series chips are also a mainstream choice in the Internet of Things (IoT) development field. These chips feature high integration, low power consumption, and Wi-Fi and Bluetooth connectivity capabilities.

ESP-IDF is the official development framework provided by Espressif for ESP32, ESP32-S, ESP32-C, ESP32-H, ESP32-P and other SoC series. ESP8266 and ESP8285 use a separate RTOS SDK, which is not within the scope of ESP-IDF support. The ESP-IDF framework includes a complete Wi-Fi/Bluetooth protocol stack, FreeRTOS real-time operating system kernel, various peripheral drivers, functional component libraries, and rich example code.

Warning

ESP-IDF does not yet officially support the FreeBSD platform. Its official documentation only lists support for Windows, Linux, and macOS.

The following configuration exists in the tools/idf_tools.py file in the ESP-IDF repository:

'FreeBSD-amd64': PLATFORM_LINUX64,
'FreeBSD-i386': PLATFORM_LINUX32,

However, this is merely a compatibility mapping that maps the FreeBSD platform to the Linux platform, not official direct support in the true sense.

Although ESP-IDF can be successfully compiled on FreeBSD through certain technical means, its stability is still inferior to officially supported platforms, and unexpected errors may occur. Therefore, this configuration is not recommended for production environments.

Installing esptool and the Build Toolchain

Before starting with ESP-IDF, you need to install the firmware flashing tool and the cross-compilation toolchain.

Install using the pkg binary package manager:

# pkg install py311-esptool xtensa-esp-elf

Or build using ports:

# cd /usr/ports/comms/py-esptool && make install clean          # ESP flashing tool
# cd /usr/ports/devel/xtensa-esp-elf && make install clean     # ESP32/ESP-IDF build toolchain

Installing ESP-IDF

Download the Latest ESP-IDF RELEASE Archive

$ fetch https://github.com/espressif/esp-idf/releases/download/v5.5.3/esp-idf-v5.5.3.zip

Note

The file names and paths such as esp-idf-v5.5.3 and espidf.constraints.v5.5.txt that appear in this section are bound to a specific version. Please replace them with your actual installed ESP-IDF version number.

Tip

ESP-IDF versions may be updated. Please check the ESP-IDF GitHub repository for the latest version.

Install Required Tools

Install using pkg:

# pkg install rust cmake ninja pkgconf libffi openssl libxml2 unzip

Or build using ports:

# cd /usr/ports/lang/rust && make install clean      # Project build requires Cargo
# cd /usr/ports/devel/cmake && make install clean      # Project build system core
# cd /usr/ports/devel/ninja && make install clean      # Efficient build tool
# cd /usr/ports/devel/pkgconf && make install clean      # Provides pkg-config functionality
# cd /usr/ports/devel/libffi && make install clean      # Underlying dependency for Python cffi module
# cd /usr/ports/security/openssl && make install clean      # Provides cryptographic algorithm support
# cd /usr/ports/textproc/libxml2 && make install clean      # XML parsing library
# cd /usr/ports/archivers/unzip && make install clean      # Terminal decompression tool

Running the ESP-IDF Installer for the First Time

After downloading ESP-IDF, run the installation script to configure the environment:

$ unzip /path/to/esp-idf-v5.5.3.zip          # Extract ESP-IDF
$ cd esp-idf-v5.5.3
$ ./install.sh                               # Run the ESP-IDF installation script (to generate the espidf.constraints.v5.5.txt file)

At this point, the script will automatically download these tools:

~/.espressif/
└── dist/
    ├── esp-rom-elfs-20241011.tar.gz
    ├── esp32ulp-elf-2.38_20240113-linux-amd64.tar.gz
    ├── openocd-esp32-linux-amd64-0.12.0-esp32-20251215.tar.gz
    ├── openocd-esp32-linux-amd64-0.12.0-esp32-20251215.tar.gz.tmp
    ├── riscv32-esp-elf-14.2.0_20251107-x86_64-linux-gnu.tar.xz
    ├── riscv32-esp-elf-14.2.0_20251107-x86_64-linux-gnu.tar.xz.tmp
    ├── riscv32-esp-elf-gdb-16.3_20250913-x86_64-linux-gnu.tar.gz
    ├── xtensa-esp-elf-14.2.0_20251107-x86_64-linux-gnu.tar.xz
    └── xtensa-esp-elf-gdb-16.3_20250913-x86_64-linux-gnu.tar.gz

Tip

If the download speed is slow, you can copy the download link from the terminal and use a tool to accelerate the download.

Note

Running ./install.sh for the first time will stall during the Python package installation phase and produce an error:

ERROR: Cannot install cryptography because these package versions have conflicting dependencies.
...(some non-essential information omitted)
ERROR: ResolutionImpossible

Cause:

Neither PyPI nor Espressif's extra-index contains precompiled wheels for FreeBSD-amd64 (officially only linux-amd64, win-amd64, macosx, etc. are provided). Additionally, the espidf.constraints.v5.5.txt file enforces --only-binary cryptography and --only-binary tree-sitter-c, causing pip to refuse compilation from source.

Solution: Modify the constraints file:

$ sed -i '' 's/^--only-binary /#--only-binary /' ~/.espressif/espidf.constraints.v5.5.txt

This command removes the source compilation restrictions by commenting out all --only-binary entries in the file, allowing pip to compile cryptography, tree-sitter-c, and other packages from source.

After modifying, re-execute:

$ ./install.sh

After re-execution, the installation script can successfully complete the Python environment phase.

After installation is complete, you can activate the ESP-IDF environment:

For sh / Bash / Zsh users:

$ cd ~/Downloads/esp-idf-v5.5.3
$ ./export.sh

For fish users:

$ cd ~/Downloads/esp-idf-v5.5.3
$ ./export.fish

Building and Flashing Examples

After configuring the development environment, you can start building and flashing example programs.

Erasing the Entire Flash

Warning

erase_flash will erase all Flash content on the chip, including existing firmware, partition tables, and all stored data. After erasing, the device will not be able to boot until new firmware is flashed.

Before flashing new firmware, you typically need to erase the chip's Flash storage space first to ensure the new firmware can run properly.

esptool.py --chip esp32 --port /dev/cuaU0 erase_flash

Parameter description:

Parameter	Description
--chip	Change to the actual chip model, e.g., esp32s3, esp32c3
--port	The port can be found using dmesg | grep usb or usbconfig; typically /dev/cuaU0 or /dev/ttyU0

For more subcommand help, use: esptool.py {subcommand} --help, e.g., esptool.py write_flash --help.

Building the Project

After erasing Flash, create and build an ESP-IDF project:

$ mkdir -p /path/to/new/project      # Create a folder to store the example project
$ cd /path/to/new/project    # Enter the directory
$ idf.py create-project hello_world      # Create an ESP-IDF project named hello_world
$ idf.py set-target esp32          # Set the target chip model; can be changed to esp32s3, etc.
$ idf.py build                     # Build using xtensa-esp-elf-gcc

Flashing Firmware

Flash using esptool.py:

$ esptool.py --chip esp32 --port /dev/cuaU0 --baud 921600 write_flash -z 0x1000 bootloader.bin

Parameter description:

Parameter	Description
-z	Compression mode, can improve transfer speed
0x1000	Application start address
bootloader.bin	The application firmware to flash

Additional notes:

Component	Address
bootloader	0x1000
partition table	0x8000
app (factory)	0x10000

Warning

Flashing addresses may differ across different models. Be sure to verify against the official documentation. See: Espressif Systems. Getting firmware flashing information for different software development platforms (development stage)[EB/OL]. (n.d.)[2026-04-19]. https://docs.espressif.com/projects/esp-techpedia/en/latest/esp-friends/get-started/try-firmware/get-firmware-address.html.

Or flash using idf.py:

$ idf.py -p /dev/cuaU0 flash       # Automatically calls esptool.py to flash

References

• Espressif Systems. ESP-IDF Programming Guide: Partition Tables[EB/OL]. [2026-04-19]. https://docs.espressif.com/projects/esp-idf/en/v6.0/esp32/api-guides/partition-tables.html. Official partition table introduction.
• Espressif Systems. Flashing Firmware — ESP32 esptool documentation[EB/OL]. [2026-04-19]. https://docs.espressif.com/projects/esptool/en/latest/esp32/esptool/flashing-firmware.html. Official firmware flashing method.