ESP-IDF

Configuration

framework = espidf

Espressif IoT Development Framework. Official development framework for ESP32.

For more detailed information please visit vendor site.

Configuration

Note

Starting with ESP-IDF v4.0, a CMake-based build system is used. Different configuration steps are required for ESP-IDF v3.x due to a legacy build system based on GNU Make.

Each release of Espressif 32 platform uses a specific version of ESP-IDF. The latest version of the platform only supports the latest stable version of the framework.

Warning

ESP-IDF v4.0 projects are not backwards-compatible with ESP-IDF v3.x projects in terms of project configuration process.

Configuration for 4.0

The general project configuration (default optimization level, bootloader configuration partition tables, etc) is set in a single file called sdkconfig in the root folder of the project. This configuration file can be modified via a special target called menuconfig (PlatformIO v4.3.0 greater is required):

platformio run -t menuconfig

Warning

ESP-IDF requires some extra tools to be installed in your system in order to build firmware for supported chips. Most of these tools are available in PlatformIO ecosystem as standalone packages, but in order to use configuration tool called menuconfig several additional packages need to be installed on Linux-based systems:

libncurses5-dev flex bison

More details about required packages can be found in the official ESP-IDF documentation - Standard Setup of Toolchain for Linux.

Project Structure

The ESP-IDF framework requires an unusual project structure because most of the framework configuration is performed by the native for the ESP-IDF build system called CMake.

A typical PlatformIO project for the ESP-IDF framework must have the following structure:

project_dir
├── include
├── src
│    ├── CMakeLists.txt
│    └── main.c
├── CMakeLists.txt
└── platformio.ini

Tip

It’s also possible to use the default ESP-IDF project structure with main folder. To specify main as the folder with source files use src_dir option, for example:

[platformio]
src_dir = main

[env:esp32dev]
platform = espressif32
framework = espidf
board = esp32dev

Besides the files related to PlatformIO project, there are several additional ESP-IDF-specific files: the main CMakeLists.txt, project-specific CMakeLists.txt in src_dir and optional default configuration file sdkconfig.defaults. CMakeLists.txt files enable features supported by the ESP-IDF’s build system, e.g. ULP configuration, adding extra components, etc. A typical CMakeLists.txt file in the root folder has the following content:

# The following lines of boilerplate have to be in your project's CMakeLists
# in this exact order for cmake to work correctly
cmake_minimum_required(VERSION 3.16.0)

include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(project-name)

The second CMakeLists.txt in src_dir is responsible for controlling the build process of the component and its integration into the overall project. The minimal component CMakeLists.txt file simply registers the component to the build system using idf_component_register:

idf_component_register(SRCS "foo.c" "bar.c")

The files specified using idf_component_register are used ONLY for generating build configurations, but it’s highly recommended to specify all application source files in order to keep the project compatible with the usual ESP-IDF workflow.

Warning

By default PlatformIO expects source files to be located in the src folder. At the same time, the default location for source files within the ESP-IDF build system is a special folder with the name main. Renaming the main component may require users to manually specify additional dependencies:

idf_component_register(SRCS "main.c" REQUIRES idf::mbedtls)

More details in the official ESP-IDF documentation - Renaming main component.

Due to the current limitations of CMake file-based API, there is no way of generating build configuration for source files written in various programming languages if they are not specified in idf_component_register command. If your project contains libraries written in languages that differ from the language used for the main application you need to create an empty file with the desired extension (e.g. *.cpp for C++) in order to force CMake generate build configuration for this language.

Note

Build configuration generated for source files specified in idf_component_register is also used as the base build environment for project sources (including libraries).

ESP-IDF components

ESP-IDF modules as modular pieces of standalone code might be useful for structuring reusable code or including third party components that aren’t part of ESP-IDF.

These components contain either a single CMakeLists.txt file which controls the build process of the component and its integration into the overall project. An optional Kconfig file defines the component configuration options that can be set via menuconfig. Some components may also include Kconfig.projbuild and project_include.cmake files, which are special files for overriding parts of the project. All valid components will be compiled as static libraries and linked to the final firmware. There are two possible ways of adding extra components to PlatformIO project:

  • By adding a new component to an optional folder called components in the root of your project. This folder will be automatically scanned for valid components.

  • Using EXTRA_COMPONENT_DIRS option in the root CMakeLists.txt file. This option represents a list of extra directories to search for components.

An example of specifying esp-aws-iot as an extra component:

# The following lines of boilerplate have to be in your project's CMakeLists
# in this exact order for cmake to work correctly
cmake_minimum_required(VERSION 3.16)

include($ENV{IDF_PATH}/tools/cmake/project.cmake)
list(APPEND EXTRA_COMPONENT_DIRS esp-aws-iot)
project(subscribe_publish)

Warning

Since src_dir is also passed to CMake as an extra component, you should only append to EXTRA_COMPONENT_DIRS variable in order not to override the default package.

Since the build may not work correctly if the full path to sources is greater than 250 characters (see CMAKE_OBJECT_PATH_MAX) it might be a good idea to keep modules close to the project files.

ULP coprocessor programming

If you want to take measurements using ADC, internal temperature sensor or external I2C sensors, while the main processors are in deep sleep mode you need to use ULP coprocessor. At the moment ULP can be used only with the ESP-IDF.

All ULP code, usually written in assembly in files with .S extension, must be placed into a separate directory with the name ulp in the root folder of your project. So your project structure should look like this:

project_dir
├── include
├── src
│    ├── CMakeLists.txt
│    └── main.c
├── ulp
│    └── ulp_code.S
├── CMakeLists.txt
└── platformio.ini

Since PlatformIO uses the code model generated by CMake it’s mandatory to specify ULP source files in CMakeLists.txt as well. An example of typical CMakeLists.txt for ULP:

idf_component_register(SRCS "ulp_adc_example_main.c")
#
# ULP support additions to component CMakeLists.txt.
#
# 1. The ULP app name must be "ulp_main"
set(ulp_app_name ulp_main)
#
# 2. Specify all assembly source files.
#    Paths are relative because ULP files are placed into a special directory "ulp"
#    in the root of the project
set(ulp_s_sources "../ulp/adc.S")
#
# 3. List all the component source files which include automatically
#    generated ULP export file, ${ulp_app_name}.h:
set(ulp_exp_dep_srcs "ulp_adc_example_main.c")
#
# 4. Call function to build ULP binary and embed in project using the argument
#    values above.
ulp_embed_binary(${ulp_app_name} ${ulp_s_sources} ${ulp_exp_dep_srcs})

See full examples with ULP coprocessor programming:

More details are located in the official ESP-IDF documentation - ULP coprocessor programming.

Limitations

At the moment several limitations are present:

  • No whitespace characters allowed in project paths.

  • The src_filter option cannot be used.

Configuration for 3.0, 3.1, 3.2, 3.3

Support for ESP-IDF v3.x is considered obsolete and is not available in the latest platform releases. Please check the platform release notes to figure out what version of the platform should be installed to use required ESP-IDF version, for example:

[env:esp32dev]
; v1.10.0 is the last version that supports ESP-IDF v3.3
platform = espressif32@1.10.0
framework = espidf
board = esp32dev

Project Structure

Due to limited support of GNU Make build system used in ESP-IDF v3.x, the project configuration depends on a pregenerated file sdkconfig.h which contains a list of macro definitions CONFIG_*. These definitions describe project settings that will be used for preparing a proper build environment. You can use the default sdkconfig.h shipped with the platform or generate a custom one using native ESP-IDF build environment.

A typical PlatformIO project for ESP-IDF v3.x must have the following structure:

project_dir
├── include
├── lib
│   └── README
├── test
├── src
│    ├── sdkconfig.h
│    └── main.c
└── platformio.ini

Enable C++ exceptions

to enable C++ exceptions for ESP-IDF add -D PIO_FRAMEWORK_ESP_IDF_ENABLE_EXCEPTIONS to build_flags of “platformio.ini” (Project Configuration File).

See project example with enabled exceptions.

ULP coprocessor programming

To use ULP in your project you need to make sure that it’s enabled in the sdkconfig.h configuration file. The following two lines must be added:

#define CONFIG_ULP_COPROC_ENABLED 1
#define CONFIG_ULP_COPROC_RESERVE_MEM 1024

Usually CONFIG_ULP_COPROC_RESERVE_MEM is already defined in the default sdkconfig.h with value 0. You can modify this value to meet your requirements.

All ULP code, usually written in assembly in files with .S extension, must be placed into a separate directory with the name ulp in the root folder of your project. So your project structure should look like this:

project_dir
├── include
├── lib
│   └── README
├── test
├── src
│    ├── main.c
│    └── sdkconfig.h
├── ulp
│    └── ulp_code.S
└── platformio.ini

See full examples with ULP coprocessor programming for ESP-IDF v3.x:

Debugging

PIO Unified Debugger - “1-click” solution for debugging with a zero configuration.

Tools & Debug Probes

Supported debugging tools are listed in “Debug” column. For more detailed information, please scroll table by horizontal. You can switch between debugging Tools & Debug Probes using debug_tool option in “platformio.ini” (Project Configuration File).

Warning

You will need to install debug tool drivers depending on your system. Please click on compatible debug tool below for the further instructions.

On-Board Debug Tools

Boards listed below have on-board debug probe and ARE READY for debugging! You do not need to use/buy external debug probe.

Name

Platform

MCU

Frequency

Flash

RAM

Espressif ESP-WROVER-KIT

Espressif 32

ESP32

240MHz

4MB

320KB

External Debug Tools

Boards listed below are compatible with PIO Unified Debugger but DEPEND ON external debug probe. They ARE NOT READY for debugging. Please click on board name for the further details.

Name

Platform

MCU

Frequency

Flash

RAM

AI Thinker ESP32-CAM

Espressif 32

ESP32

240MHz

4MB

320KB

AZ-Delivery ESP-32 Dev Kit C V4

Espressif 32

ESP32

240MHz

16MB

520KB

Adafruit ESP32 Feather

Espressif 32

ESP32

240MHz

4MB

320KB

D-duino-32

Espressif 32

ESP32

240MHz

4MB

320KB

DOIT ESP32 DEVKIT V1

Espressif 32

ESP32

240MHz

4MB

320KB

Dongsen Tech Pocket 32

Espressif 32

ESP32

240MHz

4MB

320KB

ESP32 FM DevKit

Espressif 32

ESP32

240MHz

4MB

320KB

ESP32vn IoT Uno

Espressif 32

ESP32

240MHz

4MB

320KB

ESPectro32

Espressif 32

ESP32

240MHz

4MB

320KB

ESPino32

Espressif 32

ESP32

240MHz

4MB

320KB

Espressif ESP32 Dev Module

Espressif 32

ESP32

240MHz

4MB

320KB

FireBeetle-ESP32

Espressif 32

ESP32

240MHz

4MB

320KB

Frog Board ESP32

Espressif 32

ESP32

240MHz

4MB

320KB

Heltec WiFi LoRa 32

Espressif 32

ESP32

240MHz

4MB

320KB

Heltec WiFi LoRa 32 (V2)

Espressif 32

ESP32

240MHz

8MB

320KB

Heltec Wireless Stick

Espressif 32

ESP32

240MHz

8MB

320KB

Hornbill ESP32 Dev

Espressif 32

ESP32

240MHz

4MB

320KB

Hornbill ESP32 Minima

Espressif 32

ESP32

240MHz

4MB

320KB

MH ET LIVE ESP32DevKIT

Espressif 32

ESP32

240MHz

4MB

320KB

MH ET LIVE ESP32MiniKit

Espressif 32

ESP32

240MHz

4MB

320KB

Node32s

Espressif 32

ESP32

240MHz

4MB

320KB

NodeMCU-32S

Espressif 32

ESP32

240MHz

4MB

320KB

OLIMEX ESP32-DevKit-LiPo

Espressif 32

ESP32

240MHz

4MB

320KB

OLIMEX ESP32-EVB

Espressif 32

ESP32

240MHz

4MB

320KB

OLIMEX ESP32-GATEWAY

Espressif 32

ESP32

240MHz

4MB

320KB

Pycom LoPy

Espressif 32

ESP32

240MHz

4MB

320KB

Pycom LoPy4

Espressif 32

ESP32

240MHz

4MB

1.25MB

SG-O AirMon

Espressif 32

ESP32

240MHz

4MB

320KB

Silicognition wESP32

Espressif 32

ESP32

240MHz

4MB

320KB

SparkFun ESP32 Thing

Espressif 32

ESP32

240MHz

4MB

320KB

SparkFun LoRa Gateway 1-Channel

Espressif 32

ESP32

240MHz

4MB

320KB

TTGO LoRa32-OLED V1

Espressif 32

ESP32

240MHz

4MB

320KB

TTGO LoRa32-OLED V2

Espressif 32

ESP32

240MHz

4MB

320KB

TTGO T-Beam

Espressif 32

ESP32

240MHz

4MB

1.25MB

TTGO T1

Espressif 32

ESP32

240MHz

4MB

320KB

VintLabs ESP32 Devkit

Espressif 32

ESP32

240MHz

4MB

320KB

WEMOS LOLIN D32

Espressif 32

ESP32

240MHz

4MB

320KB

WEMOS LOLIN D32 PRO

Espressif 32

ESP32

240MHz

4MB

320KB

WEMOS LOLIN32

Espressif 32

ESP32

240MHz

4MB

320KB

WeMos D1 MINI ESP32

Espressif 32

ESP32

240MHz

4MB

320KB

WeMos WiFi and Bluetooth Battery

Espressif 32

ESP32

240MHz

4MB

320KB

XinaBox CW02

Espressif 32

ESP32

240MHz

4MB

320KB

oddWires IoT-Bus Io

Espressif 32

ESP32

240MHz

4MB

320KB

oddWires IoT-Bus Proteus

Espressif 32

ESP32

240MHz

4MB

320KB

Platforms

Name

Description

Espressif 32

Espressif Systems is a privately held fabless semiconductor company. They provide wireless communications and Wi-Fi chips which are widely used in mobile devices and the Internet of Things applications.

Boards

Note

AI Thinker

Name

Platform

Debug

MCU

Frequency

Flash

RAM

AI Thinker ESP32-CAM

Espressif 32

External

ESP32

240MHz

4MB

320KB

AZ-Delivery

Name

Platform

Debug

MCU

Frequency

Flash

RAM

AZ-Delivery ESP-32 Dev Kit C V4

Espressif 32

External

ESP32

240MHz

16MB

520KB

Adafruit

Name

Platform

Debug

MCU

Frequency

Flash

RAM

Adafruit ESP32 Feather

Espressif 32

External

ESP32

240MHz

4MB

320KB

Aiyarafun

Name

Platform

Debug

MCU

Frequency

Flash

RAM

Node32s

Espressif 32

External

ESP32

240MHz

4MB

320KB

April Brother

Name

Platform

Debug

MCU

Frequency

Flash

RAM

April Brother ESPea32

Espressif 32

No

ESP32

240MHz

4MB

320KB

BPI Tech

Name

Platform

Debug

MCU

Frequency

Flash

RAM

BPI-Bit

Espressif 32

No

ESP32

160MHz

4MB

320KB

DFRobot

Name

Platform

Debug

MCU

Frequency

Flash

RAM

FireBeetle-ESP32

Espressif 32

External

ESP32

240MHz

4MB

320KB

DOIT

Name

Platform

Debug

MCU

Frequency

Flash

RAM

DOIT ESP32 DEVKIT V1

Espressif 32

External

ESP32

240MHz

4MB

320KB

DSTIKE

Name

Platform

Debug

MCU

Frequency

Flash

RAM

D-duino-32

Espressif 32

External

ESP32

240MHz

4MB

320KB

Dongsen Technology

Name

Platform

Debug

MCU

Frequency

Flash

RAM

Dongsen Tech Pocket 32

Espressif 32

External

ESP32

240MHz

4MB

320KB

DycodeX

Name

Platform

Debug

MCU

Frequency

Flash

RAM

ESPectro32

Espressif 32

External

ESP32

240MHz

4MB

320KB

ESP32vn

Name

Platform

Debug

MCU

Frequency

Flash

RAM

ESP32vn IoT Uno

Espressif 32

External

ESP32

240MHz

4MB

320KB

Electronic SweetPeas

Name

Platform

Debug

MCU

Frequency

Flash

RAM

Electronic SweetPeas ESP320

Espressif 32

No

ESP32

240MHz

4MB

320KB

Espressif

Name

Platform

Debug

MCU

Frequency

Flash

RAM

ESP32 Pico Kit

Espressif 32

No

ESP32

240MHz

4MB

320KB

Espressif ESP-WROVER-KIT

Espressif 32

On-board

ESP32

240MHz

4MB

320KB

Espressif ESP32 Dev Module

Espressif 32

External

ESP32

240MHz

4MB

320KB

Fred

Name

Platform

Debug

MCU

Frequency

Flash

RAM

Frog Board ESP32

Espressif 32

External

ESP32

240MHz

4MB

320KB

Hardkernel

Name

Platform

Debug

MCU

Frequency

Flash

RAM

ODROID-GO

Espressif 32

No

ESP32

240MHz

16MB

320KB

Heltec Automation

Name

Platform

Debug

MCU

Frequency

Flash

RAM

Heltec WiFi Kit 32

Espressif 32

No

ESP32

240MHz

4MB

320KB

Heltec WiFi LoRa 32

Espressif 32

External

ESP32

240MHz

4MB

320KB

Heltec WiFi LoRa 32 (V2)

Espressif 32

External

ESP32

240MHz

8MB

320KB

Heltec Wireless Stick

Espressif 32

External

ESP32

240MHz

8MB

320KB

Hornbill

Name

Platform

Debug

MCU

Frequency

Flash

RAM

Hornbill ESP32 Dev

Espressif 32

External

ESP32

240MHz

4MB

320KB

Hornbill ESP32 Minima

Espressif 32

External

ESP32

240MHz

4MB

320KB

IntoRobot

Name

Platform

Debug

MCU

Frequency

Flash

RAM

IntoRobot Fig

Espressif 32

No

ESP32

240MHz

4MB

320KB

M5Stack

Name

Platform

Debug

MCU

Frequency

Flash

RAM

M5Stack Core ESP32

Espressif 32

No

ESP32

240MHz

4MB

320KB

M5Stack FIRE

Espressif 32

No

ESP32

240MHz

16MB

6.25MB

M5Stack GREY ESP32

Espressif 32

No

ESP32

240MHz

16MB

520KB

M5Stick-C

Espressif 32

No

ESP32

240MHz

4MB

320KB

MH-ET Live

Name

Platform

Debug

MCU

Frequency

Flash

RAM

MH ET LIVE ESP32DevKIT

Espressif 32

External

ESP32

240MHz

4MB

320KB

MH ET LIVE ESP32MiniKit

Espressif 32

External

ESP32

240MHz

4MB

320KB

Magicblocks.io

Name

Platform

Debug

MCU

Frequency

Flash

RAM

MagicBit

Espressif 32

No

ESP32

240MHz

4MB

320KB

MakerAsia

Name

Platform

Debug

MCU

Frequency

Flash

RAM

MakerAsia Nano32

Espressif 32

No

ESP32

240MHz

4MB

320KB

Microduino

Name

Platform

Debug

MCU

Frequency

Flash

RAM

Microduino Core ESP32

Espressif 32

No

ESP32

240MHz

4MB

320KB

NodeMCU

Name

Platform

Debug

MCU

Frequency

Flash

RAM

NodeMCU-32S

Espressif 32

External

ESP32

240MHz

4MB

320KB

Noduino

Name

Platform

Debug

MCU

Frequency

Flash

RAM

Noduino Quantum

Espressif 32

No

ESP32

240MHz

16MB

320KB

OLIMEX

Name

Platform

Debug

MCU

Frequency

Flash

RAM

OLIMEX ESP32-DevKit-LiPo

Espressif 32

External

ESP32

240MHz

4MB

320KB

OLIMEX ESP32-EVB

Espressif 32

External

ESP32

240MHz

4MB

320KB

OLIMEX ESP32-GATEWAY

Espressif 32

External

ESP32

240MHz

4MB

320KB

OLIMEX ESP32-PRO

Espressif 32

No

ESP32

240MHz

4MB

320KB

OLIMEX ESP32-PoE

Espressif 32

No

ESP32

240MHz

4MB

320KB

OLIMEX ESP32-PoE-ISO

Espressif 32

No

ESP32

240MHz

4MB

320KB

OROCA

Name

Platform

Debug

MCU

Frequency

Flash

RAM

OROCA EduBot

Espressif 32

No

ESP32

240MHz

4MB

320KB

Onehorse

Name

Platform

Debug

MCU

Frequency

Flash

RAM

Onehorse ESP32 Dev Module

Espressif 32

No

ESP32

240MHz

4MB

320KB

Pycom Ltd.

Name

Platform

Debug

MCU

Frequency

Flash

RAM

Pycom GPy

Espressif 32

No

ESP32

240MHz

4MB

320KB

Pycom LoPy

Espressif 32

External

ESP32

240MHz

4MB

320KB

Pycom LoPy4

Espressif 32

External

ESP32

240MHz

4MB

1.25MB

Qmobot LLP

Name

Platform

Debug

MCU

Frequency

Flash

RAM

Qchip

Espressif 32

No

ESP32

240MHz

4MB

320KB

SG-O

Name

Platform

Debug

MCU

Frequency

Flash

RAM

SG-O AirMon

Espressif 32

External

ESP32

240MHz

4MB

320KB

Silicognition

Name

Platform

Debug

MCU

Frequency

Flash

RAM

Silicognition wESP32

Espressif 32

External

ESP32

240MHz

4MB

320KB

SparkFun

Name

Platform

Debug

MCU

Frequency

Flash

RAM

SparkFun LoRa Gateway 1-Channel

Espressif 32

External

ESP32

240MHz

4MB

320KB

SparkFun Electronics

Name

Platform

Debug

MCU

Frequency

Flash

RAM

SparkFun ESP32 Thing

Espressif 32

External

ESP32

240MHz

4MB

320KB

TTGO

Name

Platform

Debug

MCU

Frequency

Flash

RAM

TTGO LoRa32-OLED V1

Espressif 32

External

ESP32

240MHz

4MB

320KB

TTGO LoRa32-OLED V2

Espressif 32

External

ESP32

240MHz

4MB

320KB

TTGO T-Beam

Espressif 32

External

ESP32

240MHz

4MB

1.25MB

TTGO T-Watch

Espressif 32

No

ESP32

240MHz

16MB

320KB

TTGO T1

Espressif 32

External

ESP32

240MHz

4MB

320KB

ThaiEasyElec

Name

Platform

Debug

MCU

Frequency

Flash

RAM

ESPino32

Espressif 32

External

ESP32

240MHz

4MB

320KB

TinyPICO

Name

Platform

Debug

MCU

Frequency

Flash

RAM

TinyPICO

Espressif 32

No

ESP32

240MHz

4MB

320KB

Turta

Name

Platform

Debug

MCU

Frequency

Flash

RAM

Turta IoT Node

Espressif 32

No

ESP32

240MHz

4MB

320KB

Unknown

Name

Platform

Debug

MCU

Frequency

Flash

RAM

ESP32 FM DevKit

Espressif 32

External

ESP32

240MHz

4MB

320KB

VintLabs

Name

Platform

Debug

MCU

Frequency

Flash

RAM

VintLabs ESP32 Devkit

Espressif 32

External

ESP32

240MHz

4MB

320KB

WEMOS

Name

Platform

Debug

MCU

Frequency

Flash

RAM

WEMOS LOLIN D32

Espressif 32

External

ESP32

240MHz

4MB

320KB

WEMOS LOLIN D32 PRO

Espressif 32

External

ESP32

240MHz

4MB

320KB

WEMOS LOLIN32

Espressif 32

External

ESP32

240MHz

4MB

320KB

WeMos D1 MINI ESP32

Espressif 32

External

ESP32

240MHz

4MB

320KB

WeMos WiFi and Bluetooth Battery

Espressif 32

External

ESP32

240MHz

4MB

320KB

Widora

Name

Platform

Debug

MCU

Frequency

Flash

RAM

Widora AIR

Espressif 32

No

ESP32

240MHz

16MB

320KB

XinaBox

Name

Platform

Debug

MCU

Frequency

Flash

RAM

XinaBox CW02

Espressif 32

External

ESP32

240MHz

4MB

320KB

oddWires

Name

Platform

Debug

MCU

Frequency

Flash

RAM

oddWires IoT-Bus Io

Espressif 32

External

ESP32

240MHz

4MB

320KB

oddWires IoT-Bus Proteus

Espressif 32

External

ESP32

240MHz

4MB

320KB

u-blox

Name

Platform

Debug

MCU

Frequency

Flash

RAM

u-blox NINA-W10 series

Espressif 32

No

ESP32

240MHz

2MB

320KB