How can I create a new component using the ESP-IDF framework in PlatformIO?

I am new to the ESP32 board and I am trying to get my development environment setup using PlatformIO using VScode. I have been reading over the docs to understand the project structure. There are “components” in the build structure which essentially act like configurations specifically related to the ESP32 firmware. Right now, I am trying to build and run the blink example code from the espressif32 github but I cannot get my PlatformIO project to recognize a required component for it.

The example component specifies which pin the LED is on and there is a typedef in the main.c script directly references it. I need this component included in the project structure correctly to be able to compile it successfully.

In the platformIO documentation there is information on how to add 3rd party components to a project. I am supposed to add it to the optional ‘components’ directory of my project. No “components” folder was automatically generated in my case. If I create one myself and insert the Kconfig.projbuild file into this directory, the compiler will still tell me that the typedef macro is not valid when trying to build the project so it still not recognizing it.

The PlatformIO docs additionally do not specify how you can create your own components instead of using already written ones. Within the ESP-IDF documentation, there is a mention that can create a new component using the create-component command. However when entering this into the project’s terminal, it throws an error saying that it cannot find

From what I understand, PlatformIO uses a different build structure than ESP-IDF-- sort of like a wrapper. I noticed that when you go to the PlatformIO project tasks menus and select the “Run Menuconfig” option, this is what gets entered into the terminal:

> Executing task: C:\Users\Aspen\.platformio\penv\Scripts\pio.exe run --target menuconfig --environment esp32-s2-saola-1 <

When I try and run pio.exe with the same create-component argument, it throws an error saying that it is an invalid argument. pio.exe is not a python script, it’s an executable. So I can’t look at the possible arguments related to this particular framework in the source code or anything like that. But I can probably safely assume that it is not compatible with the same arguments except for menuconfig which seems to be supported.

What do I have to do in order to get components included into my project?

How can I create a brand new component with a newly generated cmakelists.txt that is included into the project?

How can I check what version of the framework PlatformIO is using for the project?

Note: I had issues updating PlatformIO on windows 7. It does not seem to like version 2.3 so I am still on version 2.2.1. PlatformIO core is 5.1.0 and Home is 3.3.3, which still seems to be the latest.

You’re referring to the master-tree version of it. Per Espressif32 release page, PlatformIO is currently using ESP-IDF v4.2, so if you want to use any example code from the official ESP-IDF repos, it must be from e.g. esp-idf/examples/get-started/blink at release/v4.2 · espressif/esp-idf · GitHub.

But the real starting point should be offical PlatformIO + ESP-IDF examples located at platform-espressif32/examples at develop · platformio/platform-espressif32 · GitHub. In the VSCode IDE, when you create a new project and select e.g. ESP32Dev + ESP-IDF, you get a working base project with correct file structure etc.

Per docs there must be a component folder in your project with at least a CMakeListst.txt and optionally a Kconfig file inside.

See official example project at platform-espressif32/examples/espidf-aws-iot at develop · platformio/platform-espressif32 · GitHub – it includes esp-aws-iot as a component. Maybe building that project will clear up some confusions you have.

Well there is where the confusion is stemmed from.

The ESP32 board I am specifically using is the ESP32-S2-Saola-R2. When I go to create a new project, the best board definition that correlates with this hardware is the Esp32-S2-Saola-1. When creating a new project, the project file structure does not automatically generate a components folder.

If I were to select the Espressif32 esp32 dev module and then select the ESP32-IDF framework, the same behavior occurs. No components folder is generated.

It is my understanding that this folder is considered optional. So I may have to manually create the “components” directory within the project structure. PlatformIO should be able to look in that directory automatically when building. After this is done, I try and insert a component manually from the example project into this directory for testing.

I directly download the 3 files: Kconfig.projbuild, Kconfig, and Cmakelists.txt, from the Espressif32 blink example on github, then moved them to the components directory. Then I try and build the project. It fails to build. Looking at the console output, this is what is printed:

Compiling .pio\build\esp32dev\app_trace\app_trace.o
Compiling .pio\build\esp32dev\app_trace\app_trace_util.o
Compiling .pio\build\esp32dev\app_trace\host_file_io.o
src/main.c:14:10: fatal error: led_strip.h: No such file or directory

* Looking for led_strip.h dependency? Check our library registry!
* CLI  > platformio lib search "header:led_strip.h"
* Web  >

 #include "led_strip.h"
compilation terminated.
Compiling .pio\build\esp32dev\app_trace\gcov\gcov_rtio.o
Compiling .pio\build\esp32dev\app_update\esp_ota_ops.o
*** [.pio\build\esp32dev\src\main.o] Error 1
============================================================================================= [FAILED] Took 4.66 seconds =============================================================================================
The terminal process "C:\Users\Aspen\.platformio\penv\Scripts\pio.exe 'run'" terminated with exit code: 1.

Terminal will be reused by tasks, press any key to close it.

In this test (which seems to be behaving differently than my last attempt), seems to not be finding the appropriate header file led_strip.h from the espressif32 framework. I am not exactly sure what error I was encountering before when I tested this a few days ago, but this was not the case back then. If I were to take out all related code in the example blink.c to this header then it actually successfully compiles, including the components folder…!

What is strange about retesting this now is two things:

  1. Before when I tested this I was getting some sort of error stating that the components did not exist from the compiler. Maybe I had the projbuild file and not the actual component or I had created the file, copy/pasted it’s code or messed something else up. It seems the components are actually correctly linking to the project now.
  2. Using the different board definition “Espressif32 esp32 dev module” finds the header file fine and compiles successfully.

So what could be the issue with not finding the header file? The frameworks are exactly the same between the two board definitions. The only thing that could possibly be different are the hardware’s GPIO configurations or something along those lines, which should be configured automatically by stating the board definition in platformio.ini. I’m not really sure why this is happening…

Can you upload the excact project files of the project where it doesn’t find the header files?

Yes, so after some further investigation the issue seems to be related to the ESP32-S2 board currently not supporting the Arduino framework. I understand that you probably are not having the same issue and are just trying to help troubleshoot so I will be leaving some information below for anyone else who visits this thread.

Also, forgive me if I am not uploading my project files here. I have a bunch of dummy project files in my project’s directory now from just trying to troubleshoot this thing and I do not want to go back and find the specific one with which we were discussing :smile:

Using the Esp32Dev board definition will not work with the ESP32-S2-Saola (and as far as I know, any other ESP-S2 board). It will fail to build/flash. Instead, you must use the ESP32-Saola-1 board definition and either use the espidf framework or a workaround that I found to get the arduino framework working.

The following platformio configuration snippit will get the Arduino framework working for this board. However, I encourage you to briefly read this thread where it originated from.


platform =
board = esp32-s2-saola-1
framework = arduino

It is not bug-free from what I understand. I haven’t played around with it enough to find anything wrong yet though. Just make sure that your source file is in .ino format. Once you have the Arduino.h header, main.ino and your normal setup() and loop() functions implemented, it will build just fine. I can even include libraries now and their own dependencies on the Arduino core framework seem to be linking and building just fine now.

This is a relief since I needed this framework for most of the features in my project. However considering the esp32-s2 board is almost 1.5 years old now, I’d expect something like this to be integrated into the PlatformIO pluggin or at least offer a ‘beta’ of the framework when initializing the project. It creates a lot of difficulties for the end user which takes more time researching, slows down development, and creates a lot of confusion. The point of platformIO is to make things easier for these microcontrollers, not more difficult. Although I suppose I can’t criticize too much-- since at least there is a workaround and overall the pluggin is pretty great. :wink: