ESPHome - esp-idf Integration Guide?

Having difficulty getting my .h .cpp esp-idf modules to build using the ESPHome Development Environment.

Yes, I looked. There seem to be a plethora of examples of how to include C++ files, or set these up as external or custom components.

These examples for the most part won’t work for me. In every case, my included esp-idf Bluetooth headers can’t be found.

I’m needing to source a definitive, up-to-date guide for integrating esp-idf modules into ESPHome 2025.10.0.

Can anyone point me in the right direction, please?

TIA. :alien:

Outstanding, Chris.

Thank you very much.

M.

Would it be fair to say that in the current ESPHome build system, there is no way to access Bluetooth APIs, from a custom component?

If you mean an external component, then it can access anything that any other component can access so Bluetooth shouldn’t be a problem. Custom components (which were basically a way to inline C++ code in the yaml file) are no longer supported.

Thank you, Clyde.

When I try to include the same headers that the native esp32_ble_beacon: component does to get Bluetooth, with the same dependencies listed in it’s init.py, yet I get file not found errors.

I’ve battled to create an external component that implemented a custom beacon for a couple of weeks. Each attempt has ended at ‘file not found’ involving my included headers.

You would need to show the code you’re using, and how you are building it, for any further help. I would suggest starting by copying the esp32_ble_beacon into an external component and compile that. Once that is working, rename it and modify it as required.

I did exactly as you have suggested, Clyde. I copied the esp32_ble_beacon source to a renamed external components folder, and to my very great pleasure, it compiled! It boot loops on my esp32c3, as it always has, when compiled from the inbuilt esp32_ble_beacon component. Still, it finds all requisite includes, and compiles!!!

This is great news, as stupid AI kept saying I was trying to do the impossible. Now that I empirically understand that not to be the case, I’ll soon work out what I’m doing wrong from the (nearly) working external component example.

Thanks muchly for the very helpful diagnostic approach, Clyde.

:alien:

Good to hear. The AIs are good at building a basic structure from scratch, but pretty hopeless at problem-solving - they tend to go around in circles when something is not working, trying random changes. Going back to a known working state then making incremental changes is always a good strategy.