ESP-IDF v5.4.1 integration experience on ESP32 and possible compatibility improvements

[fayyaz-27]

ESP-IDF Integration of Arduino LibHelix on ESP32

Hi everyone,

My name is Fayyaz. I am an embedded systems developer and a final-year Electronics & Telecommunication Engineering student from Mumbai, India.

Recently, I integrated Arduino LibHelix into an ESP32 project developed using ESP-IDF v5.4.1 rather than the Arduino framework.

During the integration process, I encountered a few compatibility issues that prevented the library from building and running correctly in a pure ESP-IDF environment. The main challenges were related to:

• Platform detection and build configuration for the ESP-IDF/Xtensa toolchain
• Utility-layer dependencies that assume an Arduino environment
• Memory-management integration when building as a native ESP-IDF component

After investigating these issues and making a small set of modifications in the library, I was able to successfully compile, link, and run the decoder under ESP-IDF.

I validated the implementation on real hardware using:

• ESP32
• MAX98357 I2S audio amplifier
• Speaker output
• MP3 files stored in SPIFFS

The decoder successfully decoded and played MP3 audio, and playback was verified on hardware.

One outcome of this work is that ESP-IDF users can integrate the library directly as an ESP-IDF component while the existing Arduino workflow remains unchanged.

I have also prepared a complete ESP-IDF example project demonstrating the integration and MP3 playback process. If possible, I can also add a link for that example project tutorial in the Readme file of arduino-libhelix library so that it becomes easy for ESP IDF users on how they can utilize this library for mp3 decoding and playback via i2s protocol.

If the new changes aligns with the project's goals, I would be happy to prepare a pull request and contribute for review.

I have attached below:

• Hardware test setup
• Playback verification logs
• Build logs from the ESP-IDF integration process

Thanks for maintaining this library.

Hardware Setup:

Before Changes:

After Changes:

[pschatzmann]

In your mail you mentined:
a) Platform/toolchain compatibility issues related to the Xtensa ESP-IDF environment
b) Utility-layer dependencies that assume an Arduino environment
c) Memory-management integration issues when building as a native ESP-IDF component

for a) You must be doing something wrong: the CMakeLists.txt has a compile definition: add_compile_definitions(ESP32) so you can't hit this error in assembly.h !

I will have a look at b and c

ps.
The example project contains submodules, so you need to do a recursive clone...

[pschatzmann]

I could reproduce the issue with the logger. I committed some corrections and took the opportunity to clean up the target_compile_options

[fayyaz-27]

The latest library is working without errors with the below folder format:

If the components folder format for testing the library isnt like above, the build will fail

After adding the line of "add_compile_definitions(ESP32)" inside components/libhelix-mp3/CMakeLists.txt.. I am able to solve the assembly.h platform compatibility error

Also after the changes which you made for idf logging, helix_memory.cpp issue has also been solved

As you have solved this issue, I would also like to let you know the solution which I found to make the library work in the previous version of this library

[fayyaz-27]

Okay so in total I made three changes in the previous library to make it work

1. Because of helix_memory.cpp format, the arduino's serial api was getting called, to solve this issue, I added an equivalent helix_memory.c in the same utils folder without deleting the previous .cpp version( so that the library doesnt break for arduino ide). Then I added utils/helix_memory.c inside CMakeLists.txt of libhelix-mp3 component

2. To solve the ConfigHelix.h path issue, as the header file is originally outside libhelix-mp3 in the repository, in project folder locally, by keeping it inside libhelix-mp3 folder and the same copy inside utils, solves the issue of various mentions of (#include "../ConfigHelix.h") & (#include "ConfigHelix.h") in utils folder

3. Then atlast to solve the platform error of assembly.h compilation, I didnt know to add "add_compile_definitions(ESP32)" inside cmake file, So after some digging, I found a working solution for ESP IDF
   In assembly.h, near line 420:
   #elif defined(ARDUINO) || defined(ESP32) || defined(APPLE) || defined(unix)

I just added another check for XTENSA

Many beginners wouldnt know to add the "add_compile_definitions" inside cmake and might get stuck into it. You can also let me know if you would like to see my esp idf example project file

I would be happy to prepare and submit a pull request for the above changes if you feel they would be valuable to the project.

Thanks

[pschatzmann]

1. I prefer my impementation which uses PSRAM if enabled: the current impementation convers both IDF and Arduino API. The current logic relys on ESP32 to be defined and covers really all possible architectures.
2. I prefer my current correction whch uses include "ConfigHelix.h"
3. XTENSA is not good enough since this only convers the old ESP32 architectures but not the new ones

Potentially we coud extend all existing ESP32 checks by also checking using the ESP_PLATFORM define provided by the IDF.

[fayyaz-27]

1. Yes that's a valid point which even I thought of

2. Noted

3. Yeah! I missed that detail!

As you mentioned, I tried the ESP_PLATFORM and did a few changes and got the code working

I defined ESP_PLATFORM in the assembly.h

Then I commented out the add_compile_definitions() from component cmake file

then I added the ESP_PLATFORM check instead of ESP32 in ConfigHelix.h file

This is how we can add the ESP_PLATFORM and support all types of ESP32 altogether

Please guide me on the next steps

[pschatzmann]

I commite a change to also support ESP_PLATFORM

[fayyaz-27]

Great