Espressif IoT Development Framework¶

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

[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.

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

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.

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)

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 Espressif IoT Development Framework.

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:

• https://github.com/platformio/platform-espressif32/tree/develop/examples/espidf-ulp-adc

• https://github.com/platformio/platform-espressif32/tree/develop/examples/espidf-ulp-pulse

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. This limitation is imposed by the native ESP-IDF build system. This affects users that have a whitespace in their username or added a whitespace to the project name. As a workaround, it’s recommended to move core_dir to a folder without spaces. For example:

  [platformio]
  core_dir = C:/.platformio
  
  [env:esp32dev]
  platform = espressif32
  framework = espidf
  board = esp32dev
  

• The src_filter option cannot be used. It’s done to preserve compatibility with existing ESP-IDF projects. List of source files is specified in the project CMakeLists.txt file.

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 Espressif IoT Development Framework 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:

• https://github.com/platformio/platform-espressif32/tree/v1.10.0/examples/espidf-ulp-adc

• https://github.com/platformio/platform-espressif32/tree/v1.10.0/examples/espidf-ulp-pulse

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.

External Debug Tools¶

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