Detailed introduction to the core part of ESP32-BOX component configuration

Preface

(1) In order to facilitate development, ESP32 provides a component library to facilitate users’ secondary development.
github repository ; gitee repository
(2) It is best to have a basic knowledge of CMake or Makefile before studying this chapter. If not, don’t panic. It would be best if you have some.
(3) CMake usage tutorial: CMake nanny-level tutorial (Part 1) ; CMake nanny-level tutorial (Part 2) ;

Component concept

what is component

(1) Before studying this article, we need to clarify a concept, what is a component.
(2) This is actually easy to understand. To put it bluntly, it is a module. If you are a student who has transferred from keil to learn ESP32, you will definitely know that if my MCU needs to mount some peripheral modules or use some communication protocols, such as OLED, ultrasonic, I2C, SPI, etc. Usually we will create a folder and write the code related to this module or protocol in this folder. As shown in the picture below
(3) If you have not played with other series of microcontrollers, don’t panic. You can understand the components as when learning C language, we will put some repeated codes in a designated C file, such as data structure For linked lists, create a list.c file specifically to store linked list related codes. This list.c is a component.

(3) After the above relatively simple explanation, I believe everyone already has a rough understanding of components. Now quoting the official documentation, the components are as follows:
<1>ESP-IDF basic library, including libc, ROM bindings, etc.
<2> Wi-Fi driver
<3> TCP/IP protocol stack
<4> FreeRTOS operating system
<5>Web server
<6>Humidity sensor driver
<7>The main program responsible for integrating the above components together

What are the benefits of component creation?

(1) It is convenient to read the source code. There will definitely be a lot of code in a project. If you do not create modules, it will easily be confusing. If you create a module, it will be easy for others to know what this large piece of content is for.
(2) Convenient for transplantation. When you are working on a project, it is certainly impossible to write all the code from beginning to end. Re-inventing the wheel is stupid and pointless.

How to add components to ESP32?

Add component path

concept

(1) There is a txt file in your project directory. CMakeLists.txtDouble-click to open this txt file. It will definitely contain the following three elements.
<1> cmake_minimum_required(): Used to specify the minimum version of cmake used. According to the syntax of CMake, this should not be written, but an error will occur. The standard way of writing is to add this paragraph on the first line.
<2> include(): Contains a CMake file written by Espressif Systems engineers, because we need to use the corresponding dependent libraries to develop ESP32. Therefore, when we select the corresponding chip in vscode, this CMake file will find the dependent library of the corresponding chip. Don't touch this, it must be there!
<3> project(): Specify the name of our project. You can write this name casually. According to CMake syntax, this specifies the project version, project description, web homepage address, and supported languages ​​(all languages ​​are supported by default). If you do not need these, you can ignore them. You only need to specify the project name.

# 指定CMake最小版本
cmake_minimum_required(VERSION 3.5)
# 引入芯片相关的依赖库
include($ENV{
    
    IDF_PATH}/tools/cmake/project.cmake)
# 项目名字
project(demo)

(2) If it is a file in the Demo project in the official GitHub CMakeLists.txt, this line of code may appear. The purpose of this sentence is to enable the compilation option for colored output during the compilation process. This colored output is usually used to improve the readability of the compilation process, because different types of messages can be displayed in different colors, making it easier for developers to identify and understanding compiler output. It can be deleted without affecting it, but it is recommended to add it.

# 编译时候设置彩色输出
add_compile_options(-fdiagnostics-color=always)

(3) So much has been introduced above. In fact, it has nothing to do with adding components, but I still briefly mention it to facilitate your understanding. Now this is the information that is actually related to component addition.
<1>To add a component, you only need to CMakeLists.txtadd the following paragraph to the file in the top directory of the project to specify the path of the component.
<2> For EXTRA_COMPONENT_DIRSsetting the third-party component path (the components we add ourselves are called third-party components), the compiler will find the third-party component path. When the compiler finds this path, it will check if there is CMakeLists.txta file in this path. If there is, it means that this is a valid component.
<3>But what if the compiler finds this third-party component path but does not find CMakeLists.txtthe file? The compiler will start to look for any subdirectories in the path that requires this third-party component. If there is a subdirectory, check whether there are files in the subdirectory CMakeLists.txt. If there are CMakeLists.txtfiles in the subdirectory, it means that the third-party component path is a collection of components. It is also feasible.

set(EXTRA_COMPONENT_DIRS
	//要添加的组件路径
    )

Practice 1

(1) Example After reading the above description, I believe that most of you are still confused. It doesn't matter, let me give you an example. The following is my project directory (because there are too many files, I only removed part of it)
<1> Everyone must be confused when they see this directory, because why is there no CMakeLists in the esp-box, the top directory of my files. txt. This is obviously not grammatical.
<2>At this time, everyone must understand the truth. The project path is not necessarily the project path. The project path we call is actually the path where the main folder is located.

- esp-box/
	  - components/   - bsp/          - include/
	                                  - src/
	                                  - CMakeLists.txt
	                                  - Kconfig.projbuild
	                  - light/        - include/
	                                  - test/
	                                  - CMakeLists.txt
	                                  - light.c
	  - applications/ - factory_demo/ - main/   - main.c
	                                            - CMakeLists.txt
	                                  - build/
	                                  - CMakeLists.txt
	                  - image_viewer/ - main/   - main.c
	                                            - CMakeLists.txt
	                                  - build/
	                                  - CMakeLists.txt
	  - docs/
	  - hardware/
	  - README_cn.md

(5) Now that I know the structure of my project, we start parsing it in the factory_demo project.
<1>From the directory structure above, we can know that the component folder is in the upper-level directory of the project directory, so we need to set it EXTRA_COMPONENT_DIRSto " ../../components"
<2> After adding some of the elements I mentioned above, we can write Out a file containing third-party components CMakeLists.txt.

# 指定CMake最小版本
cmake_minimum_required(VERSION 3.5)
# 引入芯片相关的依赖库
include($ENV{
    
    IDF_PATH}/tools/cmake/project.cmake)
# 配置组件路径
set(EXTRA_COMPONENT_DIRS
    ../../components
    )
# 编译时候设置彩色输出
add_compile_options(-fdiagnostics-color=always)
# 项目名字
project(factory_demo)

Practice 2

(1) As mentioned earlier, if EXTRA_COMPONENT_DIRSthere is a file in the set path CMakeLists.txt, then this path is the valid component path. Otherwise, it will search EXTRA_COMPONENT_DIRSfor files in subdirectories in the path CMakeLists.txt. If there is a subdirectory with CMakeLists.txtfiles, this subdirectory is a valid component. Therefore, when there are two components " and " componentsin the folder , and we specify a file without a file, it will automatically help us find the two components " and " under the path . (2) So, what if we assume there is a file under the path ?bsplightCMakeLists.txtEXTRA_COMPONENT_DIRSbsplight
EXTRA_COMPONENT_DIRSCMakeLists.txt
Note: I personally do not recommend following me to do the experiment of Practical Operation 2, because there will be a strange bug in this experiment - Configuring incomplete, errors occurred!. This bug sometimes appears and sometimes disappears. If you insist on following me, I suggest you back up the project first. I haven’t found a solution yet.
(3) We can then EXTRA_COMPONENT_DIRScreate one under the path CMakeLists.txt. When compiling, we will find that the component cannot be found. Why is this? The reason is very simple. As mentioned earlier, EXTRA_COMPONENT_DIRSif there is no component directory in the path, CMakeLists.txtit is not a valid component directory, then it will go to the subdirectory to find the component. If EXTRA_COMPONENT_DIRSthere is one in the path CMakeLists.txtthen it will be considered a valid component directory. Because components in subdirectories cannot be searched.

Practice 3

(1) Directly specify the specific component directory. Note that if I specify a specific component directory and there are two components in my project, the paths of both components need to be written out.
(2) Therefore, we can see that the writing method of Practical Operation 1 is the most appropriate.

# 指定CMake最小版本
cmake_minimum_required(VERSION 3.5)
# 引入芯片相关的依赖库
include($ENV{
    
    IDF_PATH}/tools/cmake/project.cmake)
# 配置组件路径
set(EXTRA_COMPONENT_DIRS
    ../../components/bsp
    ../../components/light
    )
# 编译时候设置彩色输出
add_compile_options(-fdiagnostics-color=always)
# 项目名字
project(factory_demo)

Set component CMakeLists.txt

(1) After specifying the component path, we need to create a CMakeLists.txt file in the component path, which must contain the following two contents.
<1>SRCS: It contains all the source files ( *.c, *.cpp, *.cc, *.S) used by the current component. All source files inside will be compiled into the component library.
<2>INCLUDE_DIRS: This is the header file path of the specified component. Because our header file is placed in the includefolder, it is followed by addition "./include". If the header file is in the current directory, then it is ".".

- esp-box/
	  - components/   - bsp/     - include/
	                             - src/
	                             - CMakeLists.txt
	                             - Kconfig.projbuild
	                  - light/   - include/         - iot_light.h
	                             - test/
	                             - CMakeLists.txt
	                             - light.c

idf_component_register(SRCS "light.c"
                        INCLUDE_DIRS "./include"
                        )

Introduction to other non-essential parts

Components section

(1) REQUIRESSpecify dependencies between components. For example, OLED components depend on I2C or SPI components, then we can use to REQUIRESspecify their dependencies.

Kconfig

(1) The component addition part we introduced only describes the configuration of the CMake file. In fact, you also need to add the Kconfig configuration, so that the added components will appear in the menuconfig. This will be very convenient if we need to make some adjustments to the components later.
(2) For example, we now have an LED program, which is active at high level at the beginning, then we configure the LED to be active at high level in menuconfig. For some reasons, the LED program becomes low-level active, then we can also directly configure low-level active in menuconfig, so there is no need to change the code, which is very convenient for transplantation and use.