Building ESP32 Projects with CMake and ESP-IDF

1. ESP-IDF Project Structure

Before we create a project, let's understand its anatomy. An ESP-IDF project is not just a collection of source files; it's a well-defined directory structure that the build system relies on.

As you read, the key takeaway is that an ESP-IDF project is a collection of components. The main directory is simply a special component that holds your primary application logic. This modular approach is powerful for organizing large projects, which we will leverage later in the course.

2. Creating a New Project

The ESP-IDF provides a command-line tool, idf.py, to handle project management. Let's use it to generate the skeleton of our new project.

To do this yourself:

1. Open VS Code.
2. Open the command palette (Ctrl+Shift+P) and select ESP-IDF: Open ESP-IDF Terminal.
3. Navigate to a directory where you store your projects (e.g., cd ~/esp).
4. Run the command: idf.py create-project cpp_project
5. Open this new cpp_project folder in VS Code (File > Open Folder...).

You now have a standard, C-based ESP-IDF project.

3. The Build System: Understanding CMake

You'll notice your new project contains two CMakeLists.txt files. These are the blueprints for our build system, CMake. CMake is a tool that reads these files to understand how to compile and link all the necessary code—your source files and the ESP-IDF's libraries—into a final executable firmware.

Let's examine the purpose of these two critical files.

The Root CMakeLists.txt

This file configures the entire project.

In essence, this file:

1. Sets the minimum required CMake version.
2. Includes the main ESP-IDF build system logic (project.cmake).
3. Declares your project and gives it a name.

The main Component's CMakeLists.txt

This file defines the contents of the main component.

4. Configuring the Project for C++

Our goal is to use C++, but the default project is C. Let's fix that. This involves three simple changes.

To summarize the steps from the article:

1. Rename main.c: In the main directory, rename main.c to main.cpp.

2. Modify the root CMakeLists.txt: Add the line set(CMAKE_CXX_STANDARD 17) before the include(...) line. This tells CMake to use the C++17 standard. Your file should look like this:

   cmake_minimum_required(VERSION 3.16)
   set(CMAKE_CXX_STANDARD 17)
   include($ENV{IDF_PATH}/tools/cmake/project.cmake)
   project(cpp_project)
   

3. Modify main/CMakeLists.txt: Update the SRCS argument in idf_component_register to point to main.cpp.

   idf_component_register(SRCS "main.cpp"
                       INCLUDE_DIRS ".")
   

4. Update main.cpp: Replace the contents of main.cpp with a simple C++ "Hello World". Note the extern "C" block.

   #include <iostream>
   #include "freertos/FreeRTOS.h"
   #include "freertos/task.h"
   
   extern "C" void app_main(void)
   {
       int i = 0;
       while (true)
       {
           std::cout << "Hello from C++! Count: " << i++ << std::endl;
           vTaskDelay(1000 / portTICK_PERIOD_MS);
       }
   }
   

Why extern "C"?
The ESP-IDF startup code is written in C and expects to find a C-style function named app_main. C++ compilers perform "name mangling" to support function overloading, which changes the function's name in the compiled object file. extern "C" tells the C++ compiler to give this specific function C-style linkage, ensuring its name is not mangled and the startup code can find it.

idf_component_register(SRCS "main.cpp" "my_helper_functions.cpp"
                    INCLUDE_DIRS ".")

5. Customizing Configuration with menuconfig

The ESP-IDF is highly configurable. You can enable or disable entire features (like Bluetooth), change driver settings, or adjust system-level parameters. This is done through a menu-based tool called menuconfig.

menuconfig works by modifying the sdkconfig file in your project's root directory. This file tracks every configuration choice you make.

A common and useful configuration is setting the default log level. The ESP-IDF has a powerful logging framework, and you can control how much detail it outputs.

6. Building the Project

Now that we have created a project, configured it for C++, and know how to customize its settings, the final step is to build it. This is the same build command you used in the last lesson.

In the ESP-IDF terminal, simply run:
idf.py build

This command will:

1. Read your sdkconfig file.
2. Parse your root CMakeLists.txt and all component CMakeLists.txt files.
3. Invoke the compiler for all necessary source files.
4. Link the resulting object files into a final firmware binary.

The video you watched earlier also demonstrates the build process and explains the key files that are generated in the build directory.

Conclusion

You've now successfully journeyed from a blank slate to a fully configured, custom C++ project for the ESP32. This is a foundational skill for all the advanced topics we'll cover.

Let's recap the key takeaways:

• An ESP-IDF project is structured into components, with main being the primary one for your application code.
• CMake is the build system that uses CMakeLists.txt files as blueprints to compile and link your project.
• The root CMakeLists.txt configures the project as a whole, while component CMakeLists.txt files register source files for that specific component.
• Enabling C++ requires adding set(CMAKE_CXX_STANDARD) and renaming your source files to .cpp.
• The idf.py menuconfig tool is used to customize project features, and it saves these settings in the sdkconfig file.

In the next lesson, we will focus on flashing and monitoring your newly built program. We'll take the cpp_project.bin you just created, upload it to your ESP32 board, and learn how to view its output and interact with it over the serial connection.