ESP-IDF is a powerful development framework for Espressif SoCs, supporting Windows, Linux, and macOS platforms. Whether you're an experienced developer or just starting out, this comprehensive guide will walk you through setting up and working with ESP-IDF projects.

Setting Up ESP-IDF

Before diving into the world of IoT development, it's essential to understand the different versions and releases of ESP-IDF. Please refer to the support policy and documentation for more information on ESP-IDF versions. Additionally, check out the End-of-Life Advisories for details about discontinued support for specific releases.

Compatibility and Support

Espressif SoCs released before 2016 (ESP8266 and ESP8285) are supported by RTOS SDK instead of ESP-IDF. For detailed instructions on setting up the ESP-IDF, depending on the chip you use, visit https://idf.espressif.com/.

Each SoC series and each ESP-IDF release has its own documentation. To find the right documentation and check out a specific release of ESP-IDF, refer to Section Versions.

Using ESP-IDF Submodules

ESP-IDF uses relative locations as its submodules URLs (.gitmodules), linking to GitHub. If you're forking ESP-IDF to a Git repository not on GitHub, you'll need to run the script tools/set-submodules-to-github.sh after git clone. This script sets absolute URLs for all submodules, allowing git submodule update --init --recursive to complete.

Example Projects and Templates

ESP-IDF comes with some example projects in the examples directory. Once you've found the project you want to work with, change to its directory and configure and build it. To start your own project based on an example, copy the example project directory outside of the ESP-IDF directory.

Common Commands for ESP-IDF Projects

Here are some common commands when working with ESP-IDF projects:

  • Install host build dependencies mentioned in the Getting Started guide.
  • Run the install script to set up the build environment. The options include:

+ install.bat or install.ps1 for Windows, and install.sh or install.fish for Unix shells.

  • Run the export script on Windows (export.bat) or source it on Unix (source export.sh) in every shell environment before using ESP-IDF.

Configuring and Building Projects

To set the target of your project to a specific chip, run idf.py set-target . To open a text-based configuration menu where you can configure the project, use idf.py menuconfig.

Flashing and Monitoring

To flash the entire project (app, bootloader, and partition table) to a new chip, use idf.py -p PORT flash, replacing PORT with the name of your serial port. You can also do this automatically by running idf.py flash, which will try to flash the first available serial port.

Monitoring Serial Output

The idf.py monitor target uses the esp-idf-monitor tool to display serial output from Espressif SoCs. This tool has a range of features to decode crash output and interact with the device. Check the documentation page for details.

Exit and Rebuild Options

To exit the monitor, type Ctrl-]. To build and flash just your app, not the bootloader and partition table, use idf.py app. You can also run idf.py app-flash to automatically rebuild the app if any source files have changed.

Erasing Flash Contents

The idf.py erase-flash target erases the entire flash contents. This can be combined with other targets, such as idf.py -p PORT erase-flash flash, which will erase everything and then re-flash the new app, bootloader, and partition table.

Community Resources and Support

For documentation on the latest version of ESP-IDF, visit https://docs.espressif.com/projects/esp-idf/. The esp32.com forum is a place to ask questions and find community resources. If you're interested in contributing to ESP-IDF, please check out the Contributions Guide.

Remember to check the Issues section on GitHub if you find a bug or have a feature request. Please also check existing Issues before opening a new one.