> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/ask/flat/chapter-23-embedded-platforms-and-development-environments/di-23.6-jie-esp-idf-kai-fa-huan-jing.md). # 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](https://github.com/espressif/ESP8266_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: > > ```python > '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:** ```sh # pkg install py311-esptool xtensa-esp-elf ``` Or build using ports: ```sh # 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 ```sh $ 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](https://github.com/espressif/esp-idf) for the latest version. ### Install Required Tools Install using pkg: ```sh # pkg install rust cmake ninja pkgconf libffi openssl libxml2 unzip ``` Or build using ports: ```sh # 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: ```sh $ 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: ```sh ~/.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: ```sh 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**: ```sh $ 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: ```sh $ ./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: ```sh $ cd ~/Downloads/esp-idf-v5.5.3 $ ./export.sh ``` For fish users: ```sh $ 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. ```sh 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: ```sh $ 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`: ```sh $ 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]. . Or flash using `idf.py`: ```sh $ 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]. . Official partition table introduction. * Espressif Systems. Flashing Firmware — ESP32 esptool documentation\[EB/OL]. \[2026-04-19]. . Official firmware flashing method. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://book.bsdcn.org/ask/flat/chapter-23-embedded-platforms-and-development-environments/di-23.6-jie-esp-idf-kai-fa-huan-jing.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.