PlatformIO Community

ESP-MDF support


What is the status of ESP-MDF support in Platformio? I have a very complex project based on Arduino with ESP32 and I would like to add MESH network to it. That is the reason I’m asking this.

Thank you in advance.

See ESP32 Mesh - Platform in Platform IO includes ESP-MDF.

2 years ago I ported the current version of ESP-MDF to be PlatformIO compilable. It wasn’t very hard though – I just put all the folders in compontens from MDF into the lib/ folder of the project and added a basic library.json to it. Then added configuration macros in the platformio.ini.

Today, this should be much easier, since PlatformIO natively understands the CMake configuration system of ESP-IDF. It should be as easy as taking the current compontent folder, copying that into the project’s component folder (example) and configuring it with menuconfig. Might additionally need the partition table again from the current example, but not much more.

Hello, I have tried very hard to create the project setup you describe, but it has issues. can menuconfig and start the build process, but pio.exe cannot do either. It starts an endless cmake rebuild, through ninja I think. I have tried every combination I can think of IDF_PATH and MDF_PATH from the github repos and the installer, nesting the project folder inside the MDF repo, etc. to no avail. Is there anything else I can try to get this working? PIO and MDF would be perfect for my project.

I don’t have these problems when I try the suggested procedure above.

I created a blank ESP-IDF project, put all the components into my components folder, copied the sdkconfig.defaults, partitions.csv, main\get_started.c and main\Kconfig.projbuild files, adapted the src\CMakeLists.txt file from the main\CMakeLists.txt file, referenced the partition file in the platformio.ini and pio run -t menuconfig comes up nicely


and it lets me configure all the mesh stuff


and all the MDF component configs are there


And when initially built it, it complains about

components\mcommon\include/mdf_common.h:98:30: error: 'MDF_VER' undeclared (first use in this function); did you mean 'IDF_VER'?

Which is set through this file

but instead of including that CMake file in the build, I just add to platformio.ini

build_flags = 
   -D MDF_VER=\"v1.0-121-gf77e318\"

(same effect, it would also do git describe)

And then rebuilding it…


Is a success :slight_smile:

And it also creates some output (I’ve configured the firmware for to be “Root” of the mesh)


And there it’s running whatever the firmware is supposed to do…

See my reference project at GitHub - maxgerhardt/pio-esp-mdf-example: Examplatory use of the ESP-MDF framework with PlatformIO if you have further troubles.

Edit: There’s a Arduino-ESP32 compatible version in the arduino branch (GitHub - maxgerhardt/pio-esp-mdf-example at arduino).

@maxgerhardt From your answers, I can see that ESPIDF framework is used, but as I mentioned I would like to use Arduino because my project is based on the Arduino framework. I tried your instructions in Arduino framework but without success. This is the platformio.ini from the project in which I would like to add MDF.

platform = espressif32
board = esp32doit-devkit-v1
framework = arduino

Using ESP-IDF components (which is what ESP-MDF is, basically) in a pure Arduino project is not so straight-forward (refer Using esp-idf library within the Arduino Framework (ESP32)). The configuration of the components is supposed to happen via menuconfig but you can’t do that in an Arduino project – so all the config macros have to go into the build_flags as per old example, which can be quite cumbersome. Also, it might be actually incompatible since the current Arduino core uses an older ESP-IDF version, but ESP-MDF might need a newer version.

The easiest path is to use framework = espidf, arduino per e.g. this example and adapting the code. I’ll give it a quick shot.

If you want to stay with only framework = arduino you’ll need to move all folders in components into lib and add a library.json to them for build instructions and component and example config per remarks above. I can also give that a quick shot.

Thanks a lot. I tried arudino+esp-idf framework but got some issue with importing process of MDF header files. I really appreciate your help, if you end up with some working example that would be great also so I can test it.

The idea with framework = espidf, arduino didn’t work out for me because

  • the ESP-MDF library doesn’t compile with ESP-IDF v4.0, needs v4.2
  • the PlatformIO example uses Arduino-ESP32 in the v4.0 version, but switching over to the v4.2 branch (with framework-espidf also set to v4.2) doesn’t compile – weird CMake errors about not finding target “main” and then not finding Arduino.h. --> gave up, but will probably raise an issue about this

The pure Arduino path compiles (see branch arduino) but doesn’t run. Crashes with a stack error. This is because ESP-MDF projects modify some ESP-IDF configuration paramters (e.g. regarding stacksize), but when using Arduino-ESP32 it uses it’s preconfigured, statically compiled ESP-IDF files. So, I have to use their tool to rebuild those .a library files in the configuration that ESP-IDF needs, and link those in, and then it should in theory work with just framework = arduino.

The ESP-IDF path of that is unaffected by these problems ofc.

PS: The build process seems to take ages since it downloads the compiler toolchains from the chinese Espresif website which has horrible download speeds.

After some excruciating pain when attempting to rebuild the Arduino-ESP32 SDK libraries with the ESP-IDF settings changes needed for ESP-MDF so that it doesn’t crash after 5 seconds, I managed to recompile the libraries and upload the changes.

You can test the project (zip). The platformio.ini already contains the 2 environments, esp32dev_root and esp32dev_node, preconfigured for a network.

I was only able to verify that it doesn’t crash immediately, didn’t try both root + node.

The root outputs

I (1081) [mwifi, 223]: MESH is started
I (1081) [get_started, 32]: Root is running
I (1081) [get_started, 188]: event_loop_cb, event: 0
I (1087) [get_started, 192]: MESH is started
W (11081) wifi:Haven't to connect to a suitable AP now!
I (11081) [get_started, 135]: System information, channel: 13, layer: 1, self mac: 24:0a:c4:04:26:38, parent bssid: 00:00:00:00:00:00, parent rssi: -120, node num: 1, free heap: 98668

which I guess means it’s waiting for a connection / node to join.

You can give it a try.

The ESP-IDF branch is still unmodified and should work out of the box and without much hassle.

@maxgerhardt I did a test and node and root are communicating, I even connected the root to the WiFi AP successfully. Thank you for that.

Now, I’m adding the MQTT connection to it so I can send the data to my MQTT broker. The issue I have is that I got the errors when I include “mlink.h”. I’ve created library.json file and put it in mlink folder. Can you try to add mlink.h? Below are the errors I’m getting:

lib/mlink/mlink_espnow.c:18:10: fatal error: mespnow.h: No such file or directory

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

 #include "mespnow.h"
compilation terminated.
*** [.pio\build\esp32dev_root\lib35c\mlink\mlink_espnow.c.o] 
Error 1
lib/mlink/mlink_handle.c:17:10: fatal error: mconfig_chain.h: No such file or directory

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

 #include "mconfig_chain.h"
compilation terminated.
lib/mlink/mlink_httpd.c:20:10: fatal error: mupgrade.h: No such file or directory

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

 #include "mupgrade.h"
compilation terminated.
*** [.pio\build\esp32dev_root\lib35c\mlink\mlink_handle.c.o] 
Error 1
*** [.pio\build\esp32dev_root\lib35c\mlink\mlink_httpd.c.o] Error 1

Solved the issue by updating the platformio.ini. @maxgerhardt if you need the file let me know so I can send you.

1 Like

Using the other libraries requires expansion of the

line with whatever other libs from here you’re using – mconfig and mespnow probably for you.

When you’re using these additional libraries, take care to configure them properly. For example, the mespnow KConfig file shows that you can define the config flags (CONFIG_ prefixed with the “config xyz” option from the file)

  • CONFIG_MESPNOW_DEFAULT_PMK (default \"pmk1234567890123"\)
  • …etc…

the configs for that shoul then be added to the platformio.ini.

same method goes for mconfig

But I’m glad to hear it’s working fine at this moment :slight_smile:

@maxgerhardt Is there any plan to have the latest Arduino ESP32 framework compatible with ESP-MDF?

It is very hard for me to use only one specific version of Arduino ESP32 like from your example ( because it is not compatible with some other libraries.

Once Arduino-ESP32 2.0.0 is released properly and not in beta anymore I’ll port it to the new version.

Is there any timeline for that?

In the future do you need to do a porting for each new version of Arduino-ESP32?

What is current status of compatibility between ESP-MDF and Arduino-ESP32?

I don’t know the timeline of the Arduino-ESP32 regarding a new release.

As long as they don’t enable the needed configuration options in ESP-IDF, the precompiled ESP-IDF version contained in Arduino-ESP32 is not able to run ESP-MDF code correctly. So a base library recompile is needed for each version.

The current stable (1.0.6) version is based on the old ESP-IDF v3.3, I don’t think ESP-MDF can run with that. The newer 2.0.0 will be based on a much more recent ESP-IDF and should have no problems.

So, basically, your ported version is upgraded to support and work with a newer version of ESP-IDF which allows the usage of ESP-MDF? Just asking to clarify the whole process.

Thank you so much for your answers. Can you tell me what I need to follow or subscribe to be notified when you release that new version?

@maxgerhardt just want to inform you that Arduino ESP32 2.0.0 is officially released. Please let me know when you complete porting.

First of all, thanks to anyone working on this project. I just wonder if it’s possible to use esp-mdf in the PlatformIO and add Arduino as a component to it?

Oh they really did. I’m taking a look at it.

EDIT: Once the PlatformIO devs release Arduino core 2.0.0 support into platform-espressif32, the work can start (

1 Like