Arduino as an ESP-IDF component

About

You can use the Arduino framework as an ESP-IDF component. This allows you to use the Arduino framework in your ESP-IDF projects with the full flexibility of the ESP-IDF.

This method is recommended for advanced users. To use this method, you will need to have the ESP-IDF toolchain installed.

For a simplified method, seeInstalling using Boards Manager.

If you plan to use these modified settings multiple times, for different projects and targets, you can recompile the Arduino core with the new settings using the Arduino Static Library Builder.For more information, see theLib Builder documentation.

Note

Latest Arduino Core ESP32 version (3.3.4) is now compatible with ESP-IDF v5.5. Please consider this compatibility when using Arduino as a component in ESP-IDF.

For easiest use of Arduino framework as a ESP-IDF component, you can use theIDF Component Manager to add the Arduino component to your project.This will automatically clone the repository and its submodules. You can find the Arduino component in theESP Registry together with dependencies list and examples.

Installation

  1. Download and installESP-IDF.

Installing using IDF Component Manager

To add the Arduino component to your project using the IDF Component Manager, run the following command in your project directory:

idf.pyadd-dependency"espressif/arduino-esp32^3.3.4"

Or you can start a new project from a template with the Arduino component:

idf.pycreate-project-from-example"espressif/arduino-esp32^3.3.4:hello_world"

Manual installation of Arduino framework

  1. Create a blank ESP-IDF project (use sample_project from /examples/get-started) or choose one of the examples.

  2. In the project folder, create a new folder calledcomponents and clone this repository inside the newly created folder.

mkdir-pcomponents&&\cdcomponents&&\gitclonehttps://github.com/espressif/arduino-esp32.gitarduino&&\cdarduino&&\gitsubmoduleupdate--init--recursive&&\cd../..&&\idf.pymenuconfig

Note

If you use Arduino with ESP-IDF often, you can place the arduino folder into global components folder.

If you’re targeting the ESP32-S2 or ESP32-S3 and you want to use USBHID classes such asUSBHID,USBHIDConsumerControl,USBHIDGamepad,USBHIDKeyboard,USBHIDMouse,USBHIDSystemControl, orUSBHIDVendor:

  1. Clone these nested repos somewhere:

gitclonehttps://github.com/espressif/esp32-arduino-lib-builder.gitesp32-arduino-lib-builder&&\gitclonehttps://github.com/hathach/tinyusb.gitesp32-arduino-lib-builder/components/arduino_tinyusb/tinyusb

  1. In the project folder, editCMakeLists.txt and add the following before theproject() line:

set(EXTRA_COMPONENT_DIRS<pathtoesp32-arduino-lib-builder/components/arduino_tinyusb>)

Configuration

Depending on one of the two following options, in the menuconfig set the appropriate settings.

Go to the sectionArduinoConfiguration--->

  1. For usage ofapp_main() function - Turn offAutostartArduinosetupandlooponboot

  2. For usage ofsetup() andloop() functions - Turn onAutostartArduinosetupandlooponboot

Experienced users can explore other options in the Arduino section.

After the setup you can save and exit:

  • Save [S]

  • Confirm default filename [Enter]

  • Close confirmation window [Enter] or [Space] or [Esc]

  • Quit [Q]

As the Arduino libraries use C++ features, you will need to swap some file extensions from.c to.cpp:

  • In main folder rename filemain.c tomain.cpp.

  • In main folder open fileCMakeLists.txt and changemain.c tomain.cpp as described below.

Option 1. Using Arduino setup() and loop()

Your main.cpp should be formatted like any other sketch. Don’t forget to includeArduino.h.

//file: main.cpp#include"Arduino.h"voidsetup(){Serial.begin(115200);while(!Serial){;// wait for serial port to connect}}voidloop(){Serial.println("loop");delay(1000);}

Option 2. Using ESP-IDF appmain()

In main.cpp you need to implementapp_main() and callinitArduino(); in it.

Keep in mind that setup() and loop() will not be called in this case.Furthermore theapp_main() is single execution as a normal function so if you need an infinite loop as in Arduino place it there.

//file: main.cpp#include"Arduino.h"extern"C"voidapp_main(){initArduino();// Arduino-like setup()Serial.begin(115200);while(!Serial){;// wait for serial port to connect}// Arduino-like loop()while(true){Serial.println("loop");}// WARNING: if program reaches end of function app_main() the MCU will restart.}

Build, flash and monitor

  • For both options use commandidf.py-p<your-board-serial-port>flashmonitor

  • The project will build, upload and open the serial monitor to your board

    • Some boards require button combo press on the board: press-and-hold Boot button + press-and-release RST button, release Boot button

    • After a successful flash, you may need to press the RST button again

    • To terminate the serial monitor pressCtrl +]

Logging To Serial

If you are writing code that does not require Arduino to compile and you want yourESP_LOGx macros to work in Arduino IDE, you can enable the compatibility by adding the following lines:

#ifdef ARDUINO_ARCH_ESP32#include"esp32-hal-log.h"#endif

FreeRTOS Tick Rate (Hz)

The Arduino component requires the FreeRTOS tick rateCONFIG_FREERTOS_HZ set to 1000 Hz inmake menuconfig ->Component config ->FreeRTOS ->Tick rate.

Compilation Errors

As commits are made to ESP-IDF and submodules, the codebases can develop incompatibilities that cause compilation errors.If you have problems compiling, follow the instructions inIssue #1142to roll ESP-IDF back to a different version.

Adding arduino library

There are few approaches:

  1. Add global library tocomponents/arduino-esp32/libraries/new_library

  2. Add local project library toexamples/your_project/main/libraries/new_library

1 Adding global library

Download the library:

cd~/esp/esp-idf/components/arduino/gitclone--recursivegit@github.com:Author/new_library.gitlibraries/new_library

Edit filecomponents/arduino-esp32/CMakeLists.txt

Get the source file list with shell command:

findlibraries/new_library/src/-name'*.c'-o-name'*.cpp'libraries/new_library/src/new_library.cpplibraries/new_library/src/new_library_extra_file.c

Locate block which starts withset(LIBRARY_SRCS and copy the list there. Now it should look something like this:

set(LIBRARY_SRCSlibraries/ArduinoOTA/src/ArduinoOTA.cpplibraries/AsyncUDP/src/AsyncUDP.cpplibraries/new_library/src/new_library.cpplibraries/new_library/src/new_library_extra_file.c

After this add the library path to block which starts withset(includedirs. It should look like this:

set(includedirsvariants/${CONFIG_ARDUINO_VARIANT}/cores/esp32/libraries/ArduinoOTA/srclibraries/AsyncUDP/srclibraries/new_library/src

2 Adding local library

Download the library:

cd~/esp/esp-idf/examples/your_projectmkdircomponentsgitclone--recursivegit@github.com:Author/new_library.gitcomponents/new_library

Create new CMakeists.txt in the library folder:components/new_library/CMakeLists.txt

idf_component_register(SRCS"new_library.cpp""another_source.c"INCLUDE_DIRS"."REQUIRESarduino-esp32)

You can read more about CMakeLists in the IDF documentation regarding theBuild System

Tip

If you want to use arduino-esp32 both as an ESP-IDF component and with Arduino IDE you can simply create a symlink:

ln-s~/Arduino/hardware/espressif/esp32~/esp/esp-idf/components/arduino-esp32

This will allow you to install new libraries as usual with Arduino IDE. To use them with IDF component, useadd_lib.sh-e~/Arduino/libraries/New_lib