ESP-IDF Cheat Sheet

Espressif's official framework for ESP32 chips (C, FreeRTOS, CMake). Run the commands in an ESP-IDF terminal (Windows: the ESP-IDF CMD/PowerShell shortcut, or VS Code with the ESP-IDF extension). On Linux/macOS run . $HOME/esp/esp-idf/export.sh first.

36 entries
7 sections
Updated 1 Oct 2026
Click a command to see all its options

F

36 entries

On this page

idf.py Commands #

Command	Action
	New project
	Choose the chip (esp32, esp32s2, esp32s3, esp32c3, esp32c6…)
	Configuration menu (writes `sdkconfig`)
	Build
	Flash (`/dev/ttyUSB0`, `/dev/ttyACM0` or `/dev/cu.usbserial-*`)
	Serial monitor
	Flash, then monitor (the usual loop)
	Flash only the app (faster)
	Wipe the whole flash
	Delete the build folder
/ `size-components`	Memory usage
	Add a component from the registry
	Save minimal config to `sdkconfig.defaults`
	Installed IDF version

Monitor Keys #

Key	Action
`Ctrl + ]`	Exit the monitor
`Ctrl + T` then `Ctrl + H`	Help
`Ctrl + T` then `Ctrl + R`	Reset the chip
`Ctrl + T` then `Ctrl + F`	Build and flash the project
`Ctrl + T` then `Ctrl + A`	Build and flash only the app
`Ctrl + T` then `Ctrl + P`	Pause the app (hold in reset)

Project Layout #

my_app/
├── CMakeLists.txt          # project file
├── sdkconfig               # generated by menuconfig
├── partitions.csv          # optional custom partitions
└── main/
    ├── CMakeLists.txt      # idf_component_register(SRCS "main.c" INCLUDE_DIRS ".")
    ├── idf_component.yml   # registry dependencies
    └── main.c              # app_main()

Code Snippets #

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

static const char *TAG = "app";
#define LED GPIO_NUM_2

static void blink_task(void *arg) {
    gpio_reset_pin(LED);
    gpio_set_direction(LED, GPIO_MODE_OUTPUT);
    while (1) {
        gpio_set_level(LED, 1);
        vTaskDelay(pdMS_TO_TICKS(500));
        gpio_set_level(LED, 0);
        vTaskDelay(pdMS_TO_TICKS(500));
    }
}

void app_main(void) {
    ESP_ERROR_CHECK(nvs_flash_init());          // needed for Wi-Fi and storage
    ESP_LOGI(TAG, "Starting, free heap: %lu", esp_get_free_heap_size());
    xTaskCreate(blink_task, "blink", 2048, NULL, 5, NULL);
}

Logging #

Macro	Level
`ESP_LOGE(TAG, ...)`	Error
`ESP_LOGW(TAG, ...)`	Warning
`ESP_LOGI(TAG, ...)`	Info
`ESP_LOGD(TAG, ...)` / `ESP_LOGV`	Debug / verbose (enable in menuconfig)
`esp_log_level_set("wifi", ESP_LOG_WARN)`	Change the level per tag at runtime

FreeRTOS Basics #

Function	Use
`xTaskCreate(fn, "name", stack, arg, prio, &handle)`	Start a task
`xTaskCreatePinnedToCore(..., core)`	Start a task on core 0 / 1
`vTaskDelay(pdMS_TO_TICKS(ms))`	Sleep without blocking other tasks
`xQueueCreate` / `xQueueSend` / `xQueueReceive`	Pass data between tasks
`xSemaphoreCreateMutex`	Protect shared resources
`vTaskDelete(NULL)`	End the current task

Troubleshooting #

Problem	Fix
Port permission denied (Linux)	, then log out and back in
"Failed to connect"	Hold BOOT, tap EN/RST, release BOOT
Stack overflow / Guru Meditation	Increase the task stack size; read the decoded backtrace in the monitor
Wrong chip errors	(this resets the config)
Strange build errors after an update	and build again

Command / option	What it does
`create-project name`	New project (`-p folder` = where)
`set-target esp32s3`	Chip: `esp32`, `esp32s2`, `esp32s3`, `esp32c3`, `esp32c6`, `esp32h2`, `esp32p4`
`menuconfig`	Configuration menu → `sdkconfig`
`build`	Build the app
`flash`	Build and flash
`app-flash`	Flash only the app (faster)
`monitor`	Serial monitor (`Ctrl + ]` to exit)
`flash monitor`	The usual loop: flash, then watch the output
`erase-flash`	Wipe the whole flash
`clean` / `fullclean`	Remove build output / the whole build folder
`size` / `size-components` / `size-files`	Memory usage overview / per component / per file
`add-dependency "espressif/led_strip^2.5.0"`	Add a component from the registry
`update-dependencies`	Update managed components
`save-defconfig`	Write a minimal `sdkconfig.defaults`
`reconfigure`	Run CMake again
`-p COM5` / `-p /dev/ttyUSB0`	Serial port
`-b 921600`	Flash baud rate
`-C folder`	Project folder
`-B build-s3`	Other build folder
`-D SDKCONFIG=sdkconfig.prod`	Pass a CMake variable
`-v`	Verbose build output
`--version`	ESP-IDF version

Option	What it does
`-aG sudo`	Append to group(s) (log out/in to apply)
`-G a,b`	Set the groups (⚠ without `-a` removes all others)
`-s /bin/zsh`	Change the login shell
`-l newname`	Rename the account
`-d /new/home -m`	New home folder and move the files
`-L` / `-U`	Lock / unlock the account
`-e 2026-12-31`	Account expires on that date