A project is a folder that contains an entry program
user-defined components, and files required to build executable
applications, such as compilation scripts, configuration files,
partition tables, etc. Projects can be copied and passed on, and the
same executable file can be compiled and generated in machines with the
same version of ESP-IDF development environment. A typical ESP-IDF
project file structure is shown in Figure 4.14.
Since ESP-IDF supports multiple IoT chips from Espressif, including ESP32, ESP32-S series, ESP32-C series, ESP32-H series, etc., a target needs to be determined before compiling the code. The target is both the hardware device that runs the application program and the build target of the compilation system.
Depending on your needs, you can specify one or more targets for your
project. For example, through command
idf.py set-target esp32c3, you
can set the compilation target to ESP32-C3, during which the default
parameters and compilation tool chain path for ESP32-C3 will be loaded.
After compilation, an executable program can be generated for ESP32-C3.
You can also run the command
set-target again to set a different
target, and the compilation system will automatically clean up and
Components in ESP-IDF are modular and independent code units managed within the compilation system. They are organised as folders, with the folder name representing the component name by default. Each component has its own compilation script that specifies its compilation parameters and dependencies. During the compilation process, components are compiled into separate static libraries (.a files) and eventually combined with other components to form the application program.
ESP-IDF provides essential functions, such as the operating system,
peripheral drivers, and network protocol stack, in the form of
components. These components are stored in the
located within the ESP-IDF root directory. Developers do not need to
copy these components to the
components directory of
Instead, they only need to specify the dependency relationships of these
components in the project's
CMakeLists.txt file using the
PRIV_REQUIRES directives. The compilation system will automatically
locate and compile the required components.
components directory under
myProject is not
necessary. It is only used to include some custom components of the
project, which can be third-party libraries or user-defined code.
Additionally, components can be sourced from any directory other than
ESP-IDF or the current project, such as from an open-source project
saved in another directory. In this case, you only need to add the path
of the component by setting the
EXTRA_COMPONENT_DIRS variable in the
CMakeLists.txt under the root directory. This directory will override
any ESP-IDF component with the same name, ensuring the correct component
main directory within the project follows the same file structure as other components (e.g.,
component1). However, it holds a special significance as it is a
mandatory component that must exist in every project. The main directory
contains the project's source code and the user program's entry point,
app_main. By default, the execution of the user
program starts from this entry point. The
main component also differs
in that it automatically depends on all components within the search
path. Therefore, there is no need to explicitly indicate dependencies
PRIV_REQUIRES directives in the
The root directory of the project contains a configuration file called
sdkconfig, which contains the configuration parameters for all the components within the project.
sdkconfig file is automatically generated by the compilation
system and can be modified and regenerated by the command
idf.py menuconfig. The menuconfig options mainly originate from the
Kconfig.projbuild of the project and the
Kconfig of the components.
Component developers generally add configuration items in
make the component flexible and configurable.
By default, the
build directory within the project stores intermediate
files and the final executable programs generated by the
command. In general, it is not necessary to directly access the contents
build directory. ESP-IDF provides predefined commands to
interact with the directory, such as using the
idf.py flash command to
automatically locate the compiled binary file and flash it to the
specified flash address, or using the
idf.py fullclean command to
clean the entire
Each project requires a partition table to divide the space of flash and
specify the size and starting address of the executable program and user
data space. Command
idf.py flash or OTA upgrade program will flash the firmware to the corresponding address according to this table. ESP-IDF provides several
default partition tables in
components/partition_table, such as
partitions_two_ota.csv, which can be
If the default partition table of the system cannot meet the
requirements of the project, a custom
partitions.csv can be added to
the project directory and be selected in