How to set up ESP32 SDK/ toolchain

I’m trying to start building for the ESP32 with platformIO (Atom on OSX)

I’m confused as to how to get platformIO to install, or locate the SDK + toolchain.

Following these instructions:

  • It seems that all that is required is to start an ESP32 project and hit ‘build’

I get this error:
src/app_bt.c:13:20: fatal error: esp_bt.h: No such file or directory

and the suggestion:

  • Looking for esp_bt.h dependency? Check our library registry!
  • CLI > platformio lib search “header:esp_bt.h”
  • Web > PlatformIO Registry

Trying the search I get:
Nothing has been found by your request

esp_bt.h is nowhere on my filing system, so I tried downloading the SDK+toolchain myself, and adding to platformio.ini

build_flags = -I/Users/tim/esp/esp-idf/components/bt/include/

(it seems to require the full path?)

…this seemed to locate the header, and I got a new error:

.pioenvs/nodemcu-32s/src/app_bt.o:(.literal.app_main+0x34): undefined referenc
e to `esp_bt_controller_mem_release’

my question is, what’t the correct way to connect the IDE with the SDK+ toolchain? Do I have to locate and include every header and library manually?

You are trying to compile the most recent version of app_bt.c against PIO’s esp-idf version, which is from at most Nov 27, 2017 where some functions simply don’t exist and header files were renamed.

You are getting that “undefined refrence” error because even though you have include the function’s definition via the header file, the function code itself is not compiled and linked it. You need to make PIO compile the esp_bt.c file.

Also it seems that you’re including the header file from a seperate esp-idf directory, not PIO’s folder. PIO’s version of esp-idf (in your home folder at .platformio/packages/framework-espidf) does contain the bt component folder, but it has a header file called “bt.h”. However, PIO’s version of esp-idf is a little bit older. If you look at the current version of the “bt.h” on Espressif’s github repository, you’ll see

#pragma once
#warning "This header is deprecated, please use functions defined in esp_bt.h instead."
#include "esp_bt.h"

That change was made 2 months ago (8th December 2017). PIO’s version comes from Nov 27, 2017 (here)

PIO’s esp-idf version simply doesn’t have that function because it’s not recent enough. You can successfully compile an older version of the app_bt.c example from this commit. I have personally verified this.

There’s a few things you can do:

  • Work with the older version of PIO’s esp-idf framework and older example versions (which apparently leaves out some fixes for BLE stuff in newer versions?)
  • Use esp-idf directly on the bleeding-edge github version according to their setup
  • Upgrade your PIO’s esp-idf files to the newest version manually by replacing the necessary files
  • (Wait for a update on PIO’s framework-espidf to be released sometime)

Hi Max,

This is Michael whom you helped before. I am trying to run ibeacon_demo.c.

My platform IO is using Framework IDF 3.4. But, the compiler could not find esp_bt.h file.

PLATFORM: Espressif 32 1.12.4 > Espressif ESP32 Dev Module
HARDWARE: ESP32 240MHz, 320KB RAM, 4MB Flash
DEBUG: Current (esp-prog) External (esp-prog, iot-bus-jtag, jlink, minimodule, olimex-arm-usb-ocd, olimex-arm-usb-ocd-h, olimex-arm-usb-tiny-h, olimex-jtag-tiny, tumpa)
 - framework-espidf 3.40001.200521 (4.0.1) 
 - tool-cmake 3.16.4
 - tool-esptoolpy 1.20600.0 (2.6.0)
 - tool-idf 1.0.1
 - tool-mconf 1.4060000.20190628 (406.0.0)
 - tool-ninja 1.9.0 
 - toolchain-esp32ulp 1.22851.190618 (2.28.51)
 - toolchain-xtensa32 2.80200.200226 (8.2.0)
Reading CMake configuration...
LDF: Library Dependency Finder ->
LDF Modes: Finder ~ chain, Compatibility ~ soft
Found 0 compatible libraries
Scanning dependencies...
No dependencies
Building in release mode
Compiling .pio\build\esp32dev\esp-idf\src\main.c.o
Compiling .pio\build\esp32dev\esp-idf\spi_flash\flash_ops.c.o
Compiling .pio\build\esp32dev\esp-idf\spi_flash\esp_flash_api.c.o
Compiling .pio\build\esp32dev\esp-idf\spi_flash\esp_flash_spi_init.c.o
src\main.c:27:10: fatal error: esp_bt.h: No such file or directory

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

 #include "esp_bt.h"
compilation terminated.
*** [.pio\build\esp32dev\esp-idf\src\main.c.o] Error 1
=================================================================================================== [FAILED] Took 4.40 seconds 

Today the PIO package has that header file.

(the header file)

(the example file)

Why is the error occurs? Thank you.


The PlatformIO package version is 3.40001.200521, which it tells you corresponds to ESP-IDF 4.0.1. But nonetheless, the esp_bt.h is still there.

THe component is only enabled once you activate bluetooth support though.

# Component Makefile

So just like the original project does with its

You’ll have to configure ESP-IDF according to the docs to enable bluetooth (and WiFi coexistence if needed).

I alsoe needed to make the project ESP-IDF v4.0.1 compatible by:

  • removing #include "controller.h" in two files
  • add #include "esp_log.h in main.c
  • patching up definitions in esp_ibeacon_api.h
typedef bool BOOLEAN;
#define FALSE false
#define TRUE true
#define BD_ADDR_LEN     (6)                     /* Device address length */

then it compiles for me.

Advanced Memory Usage is available via "PlatformIO Home > Project Inspect"
RAM:   [=         ]  14.2% (used 46424 bytes from 327680 bytes)
Flash: [======    ]  64.9% (used 680753 bytes from 1048576 bytes) v2.6
=============================================================================================== [SUCCESS] Took 139.82 seconds ===============================================================================================
1 Like

Thank you for your quick reply!!! I see how the version number works. Thank you so much for a lot of information and suggestions especially for BLE (not so simple to set up right).

I am going to read the document and work on it. Yes I found sdkconfig.defaults in the original repos. Look forward to seeing it work.

Best regards,

Hi Max,

Thank you for your help. I am able to compile and run successfully.

I did something differently b/c this menu config looks new and complicated to me. So, I just copied the sdkconfig.defaults file. I see how “pio run -t menuconfig” work.

  1. Copy the ble_ibeacon example from C:\Users\mikel.platformio\packages\framework-espidf\examples\bluetooth\bluedroid\ble\ble_ibeacon.

sdkconfig.defaults (for the example) is different.

# Override some defaults so BT stack is enabled
# and WiFi disabled by default in this example
  1. pio run (Clean build. Now I can see esp_bt.h file)
  2. pio run --target upload
  3. open the serial monitor.
  4. My smartphone detected the beacon.

It seems that I don’t need to make the 3 changes to make the project ESP-IDF v4.0.1 compatible. Please correct me if I am wrong.

Now I want to enable both BLE and WiFi co-existence for my real project. Is this the only option I need to enable? Would you know if there is an example of BLE and WiFi combo example made by Expressif? I can’t find an example. Hope you can help me on this.

ESP-IDF shows a Bluetooth-Mesh + WiFi example with code walkthrough:

1 Like

Thank you. I am glad that you found two examples. sdkconfig.defaults have a lot more settings!!! I am glad that the setting is given by the author.

I will try both examples. Thank you so much for sharing them with me.

I have another question for you. My firmware uses some libraries in Arduino framework. Can I enable these Wifi/BLE coexistence configuration features for the Arduino framework within Platform IO? So, I can avoid writing a lot of codes for IDF framework.

Thank you again.

Arduino-ESP32 uses a precompiled ESP-IDF base in the form of .a archive files, see If you need a different ESP-IDF base with different objects you will have to recompile ESP-IDF and substitute the compiled libraries. Performance drop on Wifi (30%) and BT (60%) with latest build? · Issue #2125 · espressif/arduino-esp32 · GitHub is a pointer on how to do that (I’ve never done it myself).

So that also means that Arduino-ESP32 is based on ESP-IDF so you will have their code in there too.

1 Like

Great. I am excited to try it. Thank you for your help!

Hi Max,

I need your help. I have a problem with using sdkconfig.defaults.

This is what I have been using. This method works fine to compile ibeacon example. The project runs successfully.

pio run -t menuconfig (Select Y to include Bluetooth)

I open sdkconfig and realize that it is not same as sdkconfig.default.

Now, I want to use sdkconfig.defaults. I copy it to my project directory and then build (pio -run).
It won’t compile because it cannot locate the esp_bt.h file.

sdkconfig.defaults File Content

# Override some defaults so BT stack is enabled
# and WiFi disabled by default in this example

sdkconfig File Content

# CONFIG_BT_ENABLED is not set

According to this doc, it seems that I need to delete sdkconfig file and allow the tool to rebuild sdkconfig with sdkconfig.defaults. It did not happen.

Can you help me? I think that this is very important as the wifi/ble coex example has a very complex sdkconfig.defaults. I can’t just configure all the settings correctly with >pio run -t menuconfig. I need to use sdkconfig.defaults.

Thank you again.