ESP-IDF examples - header file conflict

Development Platforms
, ,
1

Hi there,

I am trying to get up and running with PlatformIO on VScode and ESP-IDF framework, using ESP32 device. I thought I’d try with one of espressif’s examples, although I know they are not written for use with PlatformIO. Whenever I put the example header files in the project “include” folder I get compile errors “error: ‘TAG’ undeclared (first use in this function)”. If I put the header files in the project “src” folder it compiles ok. I really need to understand what is going on but don’t!

Some details:

I’m trying to use the Nimble_GATT_server example (\users\\.platformio\packages\framework-espidf\examples\bluetooth\ble_get_started\nimble\NimBLE_GATT_Server)

Steps:

  1. Create new project from PIO home, selecting esp-idf framework and esp32-dev board

  2. Delete the sdkconfig.esp32dev file that is created.

  3. Copy sdkconfig.default and sdkconfig.default.esp32 and CMakeLists.txt from root of example folder to the root of project folder.

  4. Copy main.c & CMakeLists.txt files from example “main\” folder into project “src\” folder.

  5. Copy all other .c files from example “main\src\” folder into project “src\” folder (Note I’ve put main.c and all other .c files in “src\”, unlike in example where main.c is in “main\”, and others in “main\src\”. I am not using a “main\” folder.)

  6. Copy all .h files from example “main\include\” folder into project “include\” folder.

  7. Modify sdkconfig.default to use 4MB flash size (reqd. for the device I’m using)

  8. In CMakeLists.txt (in project root folder), comment out “idf_build_set_property(MINIMAL_BUILD ON)” line, as if I leave this in I get “Error: Couldn’t find the main target of the project!” when opening the folder.

  9. Modify src\CMakeLists.txt so that

    1. GLOB_RECURSE srcs points to “*.c” rather than “src/*.c”

    2. “INCLUDE_DIRS” key in “idf_component_register” statement points to correct include folder (“../include” instead of “./include”)

When I try and compile, and I get the “error: ‘TAG’ undeclared (first use in this function)” messaages. Despite the fact that in VScode TAG seems to be defined correctly (I can ctrl-click on any instance of TAG in the code and it jumps to the definition in “include\common.h”.

If in step 6 I copy the .h files into “src\” folder instead, then everything compiles ok.

Does anyone have any ideas – I have been hunting on forums all day for the answer!

Thank you.

2

To add to my own question, I think this may be an issue with the compiler finding a duplicate header file called “common.h” in the framework folders. If I rename the project “common.h” to something else (e.g. “myHeader.h”) and update all references in src files, the code compiles fine. But I’m not sure why it is picking up the wrong header - should it not pick up headers from project “include” folder before any framework ones?

I thought perhaps it was related to this post: PIO library doesn't see header files in project's include folder but it makes no difference if I add “build_flags = -I include” to the platformio.ini.

My project folder structure looks like this:

Screenshot 2025-10-20 171124
Screenshot 2025-10-20 171124297×713 15.3 KB

I’m sure I’m missing something really obvious - any input gratefully received!