Install ESP32 core in Arduino IDE

In this tutorial you will learn how to install the ESP32 core in the Arduino IDE. The ESP32 is a powerful and versatile microcontroller widely used in IoT and maker projects. To program it using the Arduino IDE, you need to install the ESP32 core.

The ESP32 core acts as a bridge between the Arduino environment and the ESP32 hardware. It provides the necessary tools, libraries, and definitions to compile and upload your code to the ESP32 board.

You will learn what an Arduino core is, why it is essential, and how to install the ESP32 core step-by-step. We will also cover installing the required USB-to-Serial drivers, selecting the correct board and port, and configuring board settings. By the end, you will be ready to start building your ESP32 projects using the familiar Arduino IDE.

What is a Core in Arduino IDE?

In the Arduino ecosystem, a Core is a collection of software components that enable the Arduino IDE to compile and upload code to a specific family of microcontrollers or boards. It acts as the essential bridge between your Arduino sketches and the hardware you want to program. An Arduino Core typically includes several key parts:

Board Definitions

These are JSON or configuration files that describe the hardware specifics of each supported board. They define CPU architecture, clock speed, available pins, memory sizes, and other hardware parameters. For example, the ESP32 core includes definitions for popular boards like the ESP32 Dev Module, WROOM, and WROVER variants.

Compiler Toolchain

The core bundles the necessary compiler and linker tools tailored for the target architecture. For ESP32, this means the Xtensa GCC toolchain, which compiles your Arduino sketches into machine code that the ESP32’s CPU can execute.

Upload Tools

These tools handle the process of flashing your compiled code onto the board. For ESP32, the core uses esptool.py, a Python-based utility that communicates over the USB-to-Serial bridge to upload firmware.

Core Libraries

This includes the hardware abstraction layer (HAL), peripheral drivers, and core Arduino APIs adapted for the target platform. For ESP32, the core integrates FreeRTOS for multitasking, Wi-Fi and Bluetooth stacks, and other specialized libraries to leverage the chip’s advanced features.

Why is a Core Needed?

The Arduino IDE was originally designed for AVR-based boards like the Arduino Uno. When you want to program a different microcontroller, such as the ESP32, the IDE needs to understand how to:

• Compile code for the new CPU architecture
• Manage board-specific hardware features
• Upload code using the appropriate protocol and tools
• Provide libraries that support the board’s peripherals

Without a core, the IDE cannot communicate with the board and cannot compile code for it. The core let’s you use the same or very similar code for many different microcontroller and usually simplifies the code as well.

For instance, the following code example shows the classical Blink code for the Arduino IDE that blinks an LED connected to GPIO 2 every second:

#define LED_PIN 2

void setup() {
  pinMode(LED_PIN, OUTPUT);
}

void loop() {
  digitalWrite(LED_PIN, HIGH);
  delay(1000);
  digitalWrite(LED_PIN, LOW);
  delay(1000);
}

The same code using the ESP-IDF, which is an IDE specific for ESP32 programming, is a lot longer and more complex:

#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/gpio.h"

#define LED_PIN GPIO_NUM_2

void blink_task(void *pvParameter) {
    while (1) {
        gpio_set_level(LED_PIN, 1);
        vTaskDelay(pdMS_TO_TICKS(1000));

        gpio_set_level(LED_PIN, 0);
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

void app_main(void) {
    gpio_config_t io_conf = {
        .pin_bit_mask = (1ULL << LED_PIN),
        .mode = GPIO_MODE_OUTPUT,
        .pull_up_en = GPIO_PULLUP_DISABLE,
        .pull_down_en = GPIO_PULLDOWN_DISABLE,
        .intr_type = GPIO_INTR_DISABLE
    };
    gpio_config(&io_conf);

    xTaskCreate(blink_task, "blink_task",
                2048, NULL, 5, NULL);
}

Architecture of the ESP32 Core

The ESP32 Arduino Core is built on top of Espressif’s official ESP-IDF (IoT Development Framework). It wraps the complex ESP-IDF APIs into Arduino-friendly functions and classes. The core architecture includes:

• Hardware Abstraction Layer (HAL): Simplifies access to ESP32 peripherals like GPIO, ADC, SPI, I2C, and UART.
• FreeRTOS Kernel: Enables multitasking and real-time operations within Arduino sketches.
• Arduino API Layer: Offers familiar Arduino functions (setup(), loop(), digitalWrite(), analogRead(), Serial, etc.) adapted for ESP32 hardware.

This architecture allows developers to write Arduino sketches that run on ESP32 microcontrollers or any other microcontroller for which a core is available.

Installing or Updating the Arduino IDE

Before you install the ESP32 core, ensure you have the latest Arduino IDE version. The ESP32 core requires Arduino IDE 1.8.13 or newer. Using an outdated IDE can cause compatibility issues.

Visit the Arduino website. Choose your operating system: Windows, macOS, or Linux and download the latest stable release.

Installing the Arduino IDE

• Windows: Run the downloaded .exe file and follow the setup wizard.
• macOS: Open the .dmg file and drag the Arduino app to your Applications folder.
• Linux: Extract the downloaded archive and run the install.sh script.

Updating the Arduino IDE

If you already have the Arduino IDE installed, check your version by going to Help > About Arduino (Windows/Linux) or Arduino > About Arduino (macOS). Compare your version with the latest on the Arduino website.

Installing the USB-to-Serial Bridge Driver

To program your ESP32 board from the Arduino IDE, your computer must communicate with the board via a USB-to-Serial bridge. Most ESP32 development boards use either the CP210x or CH340 USB-to-Serial chips. Installing the correct driver ensures your computer recognizes the board properly.

Identify Your USB-to-Serial Chip

First, check which USB-to-Serial chip your ESP32 board uses. Look at the product description or the silkscreen on the board near the USB connector.

Common chips include the CP2102 / CP2104 by Silicon Labs and the CH340 / CH341 by WCH. Once you identify the chip, download the appropriate driver:

After downloading: run the installer, follow the on-screen instructions, restart your computer if prompted.

Verify Driver Installation

Connect your ESP32 board via USB. Then:

• On Windows, open Device Manager and look under Ports (COM & LPT). You should see a new COM port labeled with the USB-to-Serial chip name.
• On macOS or Linux, open a terminal and run:

ls /dev/tty.*

Look for a device like /dev/tty.SLAB_USBtoUART (CP210x) or /dev/tty.wchusbserialXXXX (CH340).

If you see the device, the driver installed successfully. Installing the correct USB-to-Serial driver is crucial. Without it, the Arduino IDE cannot upload code to your ESP32 board. Once this step is complete, you can proceed to add the ESP32 core to the Arduino IDE.

Adding ESP32 Core to Arduino IDE

Now that you have the Arduino IDE ready and the USB-to-Serial driver installed, it’s time to add the ESP32 core. This step allows the Arduino IDE to recognize and program ESP32 boards.

To install the ESP32 Core open your Arduino IDE and go to File > Preferences as shown below:

This opens the Preferences dialog. At the end of this dialog you find a section labelled “Additional boards manager URLs:

Click on the button to the right, which opens another dialog where you can enter the URL from which the ESP32 core can be downloaded:

There might be already other URLs (in my case for the ESP8266 and the Unihiker board). To this list add the following URL for the ESP32 core:

https://espressif.github.io/arduino-esp32/package_esp32_index.json

Alternatively, you can also use this one:

https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

The order of the URLs in the list does not matter. For other microcontroller architecture see this list of core URLs.

Installing ESP32 boards

Next, open the Boards Manager by navigating to Tools > Board > Boards Manager. In the search box type “esp32”, find the entry named “esp32 by Espressif Systems” and click the INSTALL button:

The installation might take a few minutes as it downloads all necessary files. Once installed, close the Boards Manager.

You have successfully added the ESP32 core. Now, the Arduino IDE can compile and upload code to ESP32 boards. In the next section, we will configure the board settings to match your specific ESP32 model and board.

Configuring ESP32 Board Settings

After installing the ESP32 core, you must configure the board settings. These options control how the Arduino IDE builds, uploads, and runs your sketch on the ESP32. Correct settings are critical for stable uploads, proper memory usage, and reliable debugging.

You can find all settings under Tools after selecting an ESP32 board. The screenshot below shows the settings for an “ESP32S3 Dev Module”:

Why Board Settings Matter

The ESP32 is highly configurable. It supports multiple upload methods, flash layouts, USB modes, and debug options. Therefore, incorrect settings often lead to upload failures, boot loops, or unexpected crashes.

However, only a few settings are essential for most projects. Others are advanced and can remain at their defaults. The most important settings are:

• Board: Must match your exact ESP32 variant.
• Upload Speed: Affects upload reliability.
• Flash Size: Must match the onboard flash memory.
• Partition Scheme: Controls how flash memory is divided.
• PSRAM: External RAM
• Port: Determines where the firmware is uploaded.

Once these are correct, most projects will compile and upload without issues. In the following a bit more information on these settings:

Flash Size

This setting must match the physical flash chip on your ESP32 module. If it is incorrect, uploads may succeed but sketches can crash at runtime.

Partition Scheme

The Partition Scheme defines how the ESP32’s flash memory is divided and allocated. It specifies where the application code, bootloader, file systems, and optional OTA (Over-The-Air) update slots are stored. This setting directly affects how large your sketch can be and which features are available.

• Choose Default for simple sketches.
• Use Minimal SPIFFS if your app is large.
• Select OTA if you plan to update firmware wirelessly.

Upload Speed

Higher speeds reduce upload time but may cause failures on unstable USB connections. If uploads fail, reduce the speed to 115200.

USB CDC and USB Mode

These settings are essential for ESP32-S2 and ESP32-S3 boards. They allow direct USB communication without an external USB-to-Serial converter.

PSRAM

Enable this only if your board physically includes PSRAM. Otherwise, your sketch may fail to boot. Typically, you will need PSRAM for applications with high demands on RAM such as video or audio.

Settings and their Function

List of the most common settings and their function:

Setting	Description	When to Change
USB CDC On Boot	Enables USB serial communication over native USB instead of UART	Enable for ESP32-S2/S3 USB-based boards
USB Mode	Selects USB functionality (CDC, HID, MSC, or disabled)	Use CDC for Serial Monitor support
USB DFU On Boot	Enables Device Firmware Update mode at boot	Required for DFU flashing workflows
Upload Mode	Defines how firmware is uploaded (UART0, USB, OTA)	Change only if using USB or OTA
Upload Speed	Baud rate used during upload	Lower speed if uploads fail
Flash Size	Size of onboard flash memory (e.g., 4MB, 8MB, 16MB)	Must match hardware
Flash Mode	Communication mode between ESP32 and flash (QIO, DIO, etc.)	Leave default unless datasheet says otherwise
Flash Frequency	Flash clock speed (40MHz or 80MHz)	Lower if flash instability occurs
Partition Scheme	Defines memory layout (app size, SPIFFS, OTA)	Change for OTA or file systems
Erase All Flash Before Sketch Upload	Clears entire flash before upload	Enable if facing boot or OTA issues
Core Debug Level	Controls verbosity of debug output	Increase during development
PSRAM	Enables external pseudo-static RAM	Enable if board includes PSRAM
JTAG Adapter	Selects JTAG interface for debugging	Only needed for hardware debugging
CPU Frequency	Sets CPU clock speed (e.g., 80MHz, 160MHz, 240MHz)	Lower for power savings
Arduino Runs On	Selects core (PRO or APP CPU)	Leave default for most use cases

Selecting the Board and Port

After configuring the ESP32 board settings, you must select the correct board and port. This step tells the Arduino IDE which ESP32 variant you are using and where the firmware should be uploaded. Incorrect selections are one of the most common causes of upload errors.

Selecting the ESP32 Board

First, open the Tools > Board menu. Then scroll to the ESP32 Arduino section. Here you will find a long list of supported boards.

Select the board that matches your hardware as closely as possible. For example:

• ESP32 Dev Module: Generic and widely compatible
• DOIT ESP32 DEVKIT V1: Common development board
• ESP32-WROOM-DA Module: Specific module variant
• ESP32-S3 Dev Module: For ESP32-S3-based boards
• ESP32-C3 Dev Module: For RISC-V–based ESP32-C3 boards

If you are unsure, start with ESP32 Dev Module. It works with most ESP32-WROOM boards and is a safe default.

Connecting the ESP32 to Your Computer

Now connect the ESP32 to your computer using a USB cable. Use a data-capable cable. Charging-only cables will not work and are a frequent source of confusion. Depending on the board, the connection uses either:

• An external USB-to-Serial converter (CP210x, CH340, FTDI)
• Native USB (ESP32-S2, ESP32-S3, ESP32-C3)

Selecting the Port

Next, open Tools > Port. You should see a new port appear after connecting the ESP32.

Typical port names include:

• COMx on Windows
• /dev/ttyUSBx or /dev/ttyACMx on Linux
• /dev/cu.usbserial-* or /dev/cu.usbmodem-* on macOS

Select the port that corresponds to your ESP32. If multiple ports are listed, unplug the board and observe which port disappears. Then reconnect it and select the newly appearing port.

Testing Core Installation

After selecting the board and port, you should verify that the ESP32 core is installed and working correctly. This step confirms that the toolchain, board definitions, and upload process are functioning as expected.

Opening a Test Sketch

Start with a known working example. Open the classic Blink sketch:

File > Examples > 01.Basics > Blink

void setup() {
  // initialize digital pin LED_BUILTIN as an output.
  pinMode(LED_BUILTIN, OUTPUT);
}

// the loop function runs over and over again forever
void loop() {
  digitalWrite(LED_BUILTIN, HIGH);  // turn the LED on (HIGH is the voltage level)
  delay(1000);                      // wait for a second
  digitalWrite(LED_BUILTIN, LOW);   // turn the LED off by making the voltage LOW
  delay(1000);                      // wait for a second
}

Most ESP32 boards include an onboard LED. However, the GPIO number varies by board. If the LED does not blink later, you may need to change the pin definition. For many ESP32 boards, the onboard LED is connected to GPIO 2:

#define LED_BUILTIN 2

Add the definition for LED_BUILTIN at the top of the sketch if it is missing and change the GPIO if needed:

#define LED_BUILTIN 2

void setup() {
  pinMode(LED_BUILTIN, OUTPUT);
}

void loop() {
  digitalWrite(LED_BUILTIN, HIGH); 
  delay(1000);                      
  digitalWrite(LED_BUILTIN, LOW);  
  delay(1000);                     
}

Compiling and Uploading the Sketch

Click the Upload button to flash the sketch to the ESP32.

During upload, watch the compile and status messages at the bottom of the IDE.

On some boards, you may need to press and hold the BOOT button until the upload starts. A successful upload ends with a message similar to:

Leaving...
Hard resetting via RTS pin...

This indicates that the ESP32 has been programmed and reset.

Verifying the Result

Once the ESP32 restarts, observe the onboard LED:

• If the LED blinks, the ESP32 core is installed and working correctly.
• If nothing happens, double-check the LED pin and board selection.

Testing Serial Communication

To further confirm the setup, open the Serial Monitor: Set the baud rate to 115200. Then run the following sketch that prints “test” to the Serial Monitor once every second:

void setup() {
  Serial.begin(115200);
}

void loop() {
  Serial.println("test");
  delay(1000);
}

If you see the messages in the Serial Monitor, USB communication and the ESP32 core are fully operational.

Common Installation Issues

Even with a correct installation, problems can occur when working with the ESP32 core. Most issues are related to drivers, board settings, or upload configuration. Below are the most common problems and how to resolve them.

ESP32 Does Not Appear Under Ports

If no port appears after connecting the ESP32, the computer is not detecting the board. Possible causes and solutions:

• Install the correct USB-to-Serial driver (CP210x, CH340, or FTDI).
• Use a known data-capable USB cable.
• Try a different USB port on your computer.
• For ESP32-S2 or ESP32-S3 boards, enable USB CDC On Boot and select the correct USB Mode.

Restart the Arduino IDE after installing drivers.

Upload Fails With “Timed out waiting for packet header”

This error indicates that the ESP32 did not enter flashing mode. Try to

• Press and hold the BOOT button when the upload starts.
• Lower the Upload Speed to 115200.
• Verify that the correct Port is selected.
• Disable other programs using the same serial port.

Upload Fails With “Wrong boot mode detected”

You may need to press the BOOT and the RESET button in a specific sequence, or you may need to 1µF Capacitor between RESET/ENABLE and GND. See the Wrong boot mode ESP32 tutorial.

Compilation Errors Related to ESP32 Headers

Errors mentioning missing files such as esp_system.h or WiFi.h usually point to a core installation issue. Try to:

• Reinstall the ESP32 core from the Boards Manager.
• Delete the ESP32 package folder and install again.
• Ensure only one ESP32 core version is installed.

Sketch Uploads but Does Not Run

If uploading succeeds but the ESP32 does not execute the sketch, configuration issues are likely. Check the following settings:

• Flash Size matches the actual hardware.
• Partition Scheme supports your sketch size.
• PSRAM is enabled only if the board includes it.
• Erase All Flash Before Sketch Upload is enabled for a clean test.

Serial Monitor Shows Garbled Output

Unreadable characters in the Serial Monitor usually mean a baud rate mismatch. To fix this set the Serial Monitor baud rate to match Serial.begin(). Common values are 115200 or 9600

For ESP32-S2 and ESP32-S3 boards, also verify that USB CDC is enabled.

Board Resets Continuously

Repeated resets can indicate power or configuration problems. Common causes are:

• Insufficient power from the USB port
• Incorrect flash frequency or flash mode
• Brownout detection triggering resets

Try a powered USB hub or reduce the CPU frequency.

Compilation Errors or Code does not work

Sometimes you need to downgrade the version of the ESP32 core, since some libraries don’t support newer version of the ESP32, specifically 3.x. Typically, you need to downgrade to version 2.0.17.

Open the BOARDS MANAGER, type “esp32” in the search bar and then select the version for the “esp32 by Espressif” core and click on “UPDATE” as shown below:

This will download and install the selected core version.

Conclusion

In this tutorial you learned how to install the ESP32 core for the Arduino IDE. The Arduino Core simplifies programming by providing an easy-to-use environment with familiar functions and libraries. It abstracts the complex hardware details, allowing you to focus on your project rather than low-level code. For additional information have a look at the Espressif Installation Guide.

The main advantage of using the Arduino Core is its accessibility. Beginners can quickly get started with ESP32 development without deep knowledge of embedded systems. The vast Arduino community and extensive library support make troubleshooting and expanding your projects easier.

Furthermore, there are other cores for many other microprocessors, for instance the ESP8266, STM32 and RP2350. This allows you to program a wide range of different microprocessors within the same IDE and with (nearly) identical code.

However, the Arduino Core also has some limitations. It may not expose all the advanced features of the ESP32 hardware. Performance tuning and real-time capabilities can be restricted compared to using the native ESP32-IDF (Espressif IoT Development Framework). The ESP32-IDF offers full control over the chip’s architecture, enabling optimized and complex applications, but it comes with a steeper learning curve.

In summary, choose the Arduino Core if you want rapid development, simplicity, and community support. Opt for the ESP32-IDF when you need maximum performance, fine-grained control, and access to the latest ESP32 features.

If you have any questions feel free to leave them in the comment section.

Happy Tinkering ; )