llms.txt: machine-readable documentation index. Markdown version of this page is also available.

CLion 2026.3 Help

ESP-IDF

ESP-IDF is the official development framework for Espressif SoCs, such as ESP32 and ESP32-S3. ESP-IDF projects use CMake, so you can open, build, flash, and debug them in CLion.

This article uses the led_strip_simple_encoder example from the ESP-IDF repository and an ESP32-S3-DevKitC-1 v1.1 board. The examples are given for macOS. On Windows, the steps are the same except for the differences noted below. On Linux, the steps are similar to those on macOS.

Before you start

Make sure that you have the following:

  • An ESP32 development board and a USB data cable that fits its connectors.

  • The ESP-IDF toolchain installed on your machine. To install it, follow the ESP-IDF Get Started guide for your OS. The examples below assume that ESP-IDF is installed in ~/esp/esp-idf.

Configure, build, and debug an ESP-IDF project

Set up a toolchain for the sample project

  1. Launch CLion and click Open on the Welcome screen.

  2. Go to ~/esp/esp-idf/examples/peripherals/rmt/led_strip_simple_encoder and open this directory. The example lights the LED strip with a rainbow chase effect. On a board with a single LED, the LED cycles through colors.

  3. Click Trust Project. For more information, refer to Project security.

    CLion opens the Open Project Wizard dialog.

    Open Project Wizard showing the Debug CMake profile with the Default toolchain selected and the Manage toolchains link next to it.

  4. Click Manage toolchains next to the Toolchain field.

  5. Click the Add button and select System. On Windows, select MinGW.

    Toolchains dialog in CLion with the Add menu open, listing System, Remote Host, and Docker, and System highlighted to add a local toolchain.

    Specify a name for the toolchain, for example, ESP-IDF.

  6. Click Add environment, select From file, and then click Browse.

    Toolchains settings for the ESP-IDF toolchain with the Add environment menu expanded and the From file option highlighted under Environment.

    Select the export.sh file in the ESP-IDF directory, for example, ~/esp/esp-idf/export.sh. On Windows, select export.bat.

  7. Click OK.

  8. In the Open Project Wizard dialog, select your new toolchain. In our example, it is ESP-IDF.

  9. Click OK. CLion loads the CMake project. When the project is loaded, the CMake tool window shows [Finished].

    CMake tool window with the Debug-ESP-IDF profile showing the ESP-IDF project loaded successfully, ending with the [Finished] message.

    If loading fails, select Tools | CMake | Reset Cache and Reload Project from the main menu.

Build and flash the project

  1. Connect the board to your computer through its UART connector.

  2. Open main/led_strip_example_main.c and set RMT_LED_STRIP_GPIO_NUM to the GPIO of the LED on your board. On ESP32-S3-DevKitC-1, it is 38 for board revision v1.1 and 48 for v1.0:

  3. In the run/debug configuration switcher, select flash and click the Build button (Ctrl+F9).

    Run/debug configuration list of ESP-IDF targets with the flash configuration highlighted, used to build the project and flash the board.

    CLion builds the project and flashes the firmware to the board. You can track the progress in the Messages tool window.

    Messages tool window with the flash write complete, the written data hash verified, the board reset, and Build finished.

  4. Optionally, change the effect: EXAMPLE_ANGLE_INC_FRAME controls the speed of the chase, and EXAMPLE_ANGLE_INC_LED controls the color density. Then build the flash configuration again.

Debug the project

  1. Connect the board through its USB connector instead of the UART one. ESP32-S3 has a built-in JTAG interface available on this connector. For other chips, check the JTAG setup in the ESP-IDF JTAG debugging guide.

  2. Go to Settings | Build, Execution, Deployment | Debugger | Debug Profiles.

  3. Under Debuggers for embedded development, click ESP-IDF. If you already have a debug profile, click the Add button and select ESP-IDF.

    Debug Profiles settings with an existing LLDB profile and the Add Profile list open, ESP-IDF selected at the top of the debugger types.

  4. For this sample project, the default values work fine. You can enter your own or configure your debug profile in JSON.

    ESP-IDF debug profile with default settings: UART set to Auto, 500 ms startup delay, monitor after upload, and a button to configure it in JSON.

  5. Click OK.

  6. In the main toolbar, select the ESP-IDF debug profile and the led_strip_simple_encoder.elf run/debug configuration.

    Main toolbar run widget set to Debug-ESP-IDF | ESP-IDF, with led_strip_simple_encoder.elf selected under Recent Configurations.

  7. Set a breakpoint in the code and click the Debug button (Shift+F9).

    CLion starts the session, flashes the firmware, and stops at the breakpoint.

    ESP-IDF debug session stopped at a breakpoint in encoder_callback, with the call stack and local variable values in the Debug tool window.

    For more information about the debugger features, refer to Start/pause/stop debug session.

Run idf.py commands

ESP-IDF tools that work in the terminal, such as the IDF monitor and the project configuration menu, run through idf.py. To run them from CLion, create a Shell Script run/debug configuration that sources the ESP-IDF environment and then calls idf.py.

Run the IDF monitor

  1. Connect the board through its UART connector.

  2. Select Run | Edit Configurations… from the main menu.

  3. Click the Add New Configuration button and select Shell Script.

  4. Specify a name for the configuration, for example, ESP-monitor. Next to Execute, select Script text and enter a command like this:

    . ~/esp/esp-idf/export.sh && idf.py -C "$HOME/esp/esp-idf/examples/peripherals/rmt/led_strip_simple_encoder" -p /dev/cu.usbserial-110 flash monitor

    Replace the following:

    • ~/esp/esp-idf/export.sh: the path to export.sh that you specified in the toolchain settings.

    • The path after -C: the path to your project folder.

    • The value after -p: your board's serial port.

  5. Click OK, then click the Run button (Shift+F10).

    CLion flashes the board and shows the monitor output in the terminal.

    ESP-monitor tab in the Terminal tool window showing the board boot log, ending with the LED example starting its rainbow chase.

The project configuration menu is a terminal-based interface for the Kconfig settings of the project. For the list of options, refer to the Configuration Options Reference.

  1. In the Run | Edit Configurations… dialog, select the monitor configuration and click Copy Configuration.

  2. Rename the copy, for example, to ESP-menuconfig, and replace flash monitor with menuconfig in the script text.

  3. Click OK, then click the Run button.

    ESP-menuconfig tab in the Terminal tool window showing the ESP-IDF configuration menu, with Serial flasher config among the top-level sections.

    Use the keyboard to navigate the menu and change the settings, for example, the flash size in Serial flasher config | Flash size.

Run other commands

You can also run idf.py commands in the CLion terminal. For example, the following command shows the firmware size: idf.py size

Terminal tool window with idf.py size output: a memory type usage summary table and a total image size of 187193 bytes.

If you use a command frequently, save it as a shell script configuration, as described above.

Known issues

In CLion 2026.3 with ESP-IDF 6.1, clangd computes type sizes for the target correctly. If you see false _Static_assert errors about sizeof (CPP-23731), add --target=riscv32 on a separate line to diagnostig flags in Settings | Languages & Frameworks | C/C++ | Clangd.

09 September 2026
STM32CubeMX projectsOpenOCD support