How to use the Arduino-ESP32 Library as an ESP-IDF Component

Related Documentation

• arduino-esp32 SDK
• ESP-IDF SDK
• ESP-IDF Environment Setup Guide
• Arduino Environment Setup Guide
• Arduino as an ESP-IDF component

---

Prepare Environment

Currently, the latest Master version of the arduino-esp32 SDK requires the usage of ESP-IDF SDK environment version v4.4.

• For the different versions of the arduino-esp32 SDK and their corresponding ESP-IDF SDK versions, please refer to the “ESP32 Arduino Release” documentation.
• You can find the released versions of the arduino-esp32 SDK under the arduino-esp32 SDK management directory as follows:
  

• ESP-IDF Compilation Environment

  • If you are using the Windows environment, setting up the ESP-IDF SDK compilation environment is straightforward. You only need to use the offline version of the “ESP-IDF Windows Installer” to install the required ESP-IDF SDK version.

    For detailed instructions, you can refer to the guide titled “Set up the ESP-IDF SDK compilation environment + Visual Studio Code software programming environment” Additionally, you may find a video tutorial “Setting Up ESP-IDF Development Environment (Windows) Using One-Click Installation Tool” helpful.

  • If you are using the Ubuntu environment, please refer to the “Standard Setup of Toolchain for Linux” documentation for instructions. You can also refer to the “How to set up the software development environment ESP-IDF for ESP32-S3” guide.

---

Next, we will demonstrate how to use the arduino-esp32 library as an ESP-IDF SDK component on a Windows environment. This includes:

• Using the arduino-esp32 library as a component in the project
• Using the arduino-esp32 library as a component in the ESP-IDF SDK libraries

---

1、 Using the arduino-esp32 library as a component in the project:

• Create a custom project
• Create a component folder for the current project
• Clone the arduino-esp32 library as a component for the current project
• Make modifications to the project file names
• Make modifications to the project configuration options
• Compile and flash the current project for testing

1.1 Creating a custom project:

You can based on the ESP-IDF SDK to copy a project for testing. For example, copy the hello-world project. and rename the project name as hello-world_Arduino.

1.2 Create a component folder for the current project

You can use the following command to create a component folder for the current project:

cd hello-world_Arduino
mkdir components

1.3 Clone the arduino-esp32 library as a component for the current project

• Goto the components directory, running the following commands to clone the arduino-esp32 library into the components directory

cd components

git clone https://github.com/espressif/arduino-esp32.git

• After completing the cloning of the arduino-esp32 SDK, goto the “arduino-esp32” directory, and running the following command to clone the submodules of the arduino-esp32 library.

cd arduino-esp32

git submodule update --init --recursive

After completing the above steps, the project structure will be as follows:

---

1.4 Make modifications to the project file names

We will use Arduino’s setup() and loop() functions within the hello-world_Arduino project to demonstrate.

• In the “hello-world_Arduino” project directory, rename the file “main.c” to “main.cpp” . As follows:

  

• In the main folder within the project directory, open the file CMakeLists.txt and change the name of the file main.c to main.cpp . As follows:
  

• In the hello-world_Arduino project, you can write test code based on the Arduino library in the hello_world_main.cpp file as follows:

#include "Arduino.h"

#define RGB_BUILTIN 26

void setup() {
  // No need to initialize the RGB LED
  Serial.begin(115200);
  pinMode(RGB_BUILTIN, OUTPUT);
  Serial.printf("GPIO is %d \r\n", RGB_BUILTIN);
}

// the loop function runs over and over again forever
void loop() {
#ifdef RGB_BUILTIN
  digitalWrite(RGB_BUILTIN, HIGH);
   Serial.printf("Light on \r\n ");
  delay(1000);
  
  digitalWrite(RGB_BUILTIN, LOW);   // Turn the RGB LED off
  Serial.printf("Light off \r\n");
  delay(1000);

#endif
}

---

1.5 Make modifications to the project configuration options

• Modify the CONFIG_FREERTOS_HZ configuration in the sdkconfig file to 1000. The default value is 100.

  

• In the project directory, run the command idf.py menuconfig to enter the project configuration options interface. Enable the Autostart Arduino setup and loop on boot configuration option.

  

  idf.py menuconfig → Arduino Configuration [*] Autostart Arduino setup and loop on boot

  

1.6 Compile and flash the current project for testing

• In the current project directory, run the following command to compile the project:

  idf.py build
  

  

  After the firmware compilation is completed, the following log will be printed, indicating the compiled firmware and its corresponding download address.

• In the current project directory, run the following command to download the firmware and print the firmware running logs.

  idf.py -p COM4 flash monitor
  

  

---

2、Using the Arduino-ESP32 Library as an ESP-IDF Component

• Create the components-Arduino folder in the esp-idf SDK directory
• Clone the arduino-esp32 SDK into the components-Arduino folder
• In the CMakeLists.txt file located in the project directory, add the path to the arduino-esp32 component

2.1 Open the esp-idf CMD environment and create the components-Arduino folder in the esp-idf SDK directory

mkdir components-Arduino

2.2 Clone the arduino-esp32 SDK into the components-Arduino folder

cd components-Arduino

git clone https://github.com/espressif/arduino-esp32.git

cd arduino-esp32

git submodule update --init --recursive

2.3 In the CMakeLists.txt file located in the project directory, add the path to the arduino-esp32 component

To include the arduino-esp32 library as a component based on the esp-idf SDK directory, add the path to the arduino-esp32 component in the CMakeLists.txt file of the project directory, as follows:

set(EXTRA_COMPONENT_DIRS $ENV{IDF_PATH}/components-Arduino/arduino-esp32)

Other steps are exactly the same as Step 1.

---

【Note】

• If you need to switch the chip environment, please running the following command in the project directory:

 idf.py set-target esp32s3

• If you need to use app_main() from ESP-IDF to run the code and call Arduino library API functions, the project file must be named main.cpp. In addition, you need to disable the Autostart Arduino setup and loop on boot configuration option and define app_main() using extern "C" void app_main(), as shown in the example test code below:

#include "Arduino.h"
#include 
#include 
#include "sdkconfig.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_chip_info.h"
#include "esp_flash.h"

#define RGB_BUILTIN 21

extern "C" void app_main()
{

      // ESP-IDF API Usage
 printf("Hello world!\n");

    /* Print chip information */
    esp_chip_info_t chip_info;
    uint32_t flash_size;
    esp_chip_info(&chip_info);
    printf("This is %s chip with %d CPU core(s), %s%s%s%s, ",
           CONFIG_IDF_TARGET,
           chip_info.cores,
           (chip_info.features & CHIP_FEATURE_WIFI_BGN) ? "WiFi/" : "",
           (chip_info.features & CHIP_FEATURE_BT) ? "BT" : "",
           (chip_info.features & CHIP_FEATURE_BLE) ? "BLE" : "",
           (chip_info.features & CHIP_FEATURE_IEEE802154) ? ", 802.15.4 (Zigbee/Thread)" : "");

    unsigned major_rev = chip_info.revision / 100;
    unsigned minor_rev = chip_info.revision % 100;
    printf("silicon revision v%d.%d, ", major_rev, minor_rev);
    if(esp_flash_get_size(NULL, &flash_size) != ESP_OK) {
        printf("Get flash size failed");
        return;
    }

    printf("%" PRIu32 "MB %s flash\n", flash_size / (uint32_t)(1024 * 1024),
           (chip_info.features & CHIP_FEATURE_EMB_FLASH) ? "embedded" : "external");

    printf("Minimum free heap size: %" PRIu32 " bytes\n", esp_get_minimum_free_heap_size());

    for (int i = 5; i >= 0; i--) {
        printf("Restarting in %d seconds...\n", i);
        vTaskDelay(1000 / portTICK_PERIOD_MS);
    }

    // Arduino-like setup()
  Serial.begin(115200);
   pinMode(RGB_BUILTIN, OUTPUT);
  Serial.printf("GPIO is %d \r\n", RGB_BUILTIN);
 
  // Arduino-like loop()
  while(true){
    #ifdef RGB_BUILTIN
  digitalWrite(RGB_BUILTIN, HIGH);
   Serial.printf("Light on \r\n ");
  delay(1000);
  
  digitalWrite(RGB_BUILTIN, LOW);   // Turn the RGB LED off
  Serial.printf("Light off \r\n");
  delay(1000);

#endif
    
    }

}

• The setup() function in Arduino is called only once within app_main() and does not require the while(!Serial){} loop.
• The loop() function in Arduino, when used within app_main(), must be implemented with while(true){} or while(1){} to create an infinite loop.

• 固件运行日志：