ESP-IDF Project Setup Guide
When to Use This Skill
Apply this skill when the user:
-
Wants to set up ESP-IDF for the first time
-
Needs to create a new ESP32 project
-
Wants to configure CMakeLists.txt or component dependencies
-
Needs help with sdkconfig or menuconfig
-
Wants to add a project to the monorepo
ESP-IDF Installation
Automated Installation
Use the Makefile targets:
Install ESP-IDF v5.3.2
make setup-idf
Custom version
make setup-idf IDF_VERSION=v5.4
Full environment setup
make setup-all
Shell Configuration
After installation, add alias to shell profile (~/.bashrc or ~/.zshrc):
alias get_idf='. $HOME/repos/esp-idf/export.sh'
Important: Do NOT add export.sh directly to profile - use an alias instead.
Creating New Projects
Minimal Project Structure
new-project/ ├── CMakeLists.txt ├── main/ │ ├── CMakeLists.txt │ └── main.c └── sdkconfig.defaults
Root CMakeLists.txt
cmake_minimum_required(VERSION 3.16)
For monorepo: use shared components
set(EXTRA_COMPONENT_DIRS "${CMAKE_CURRENT_SOURCE_DIR}/../../shared-libs")
include($ENV{IDF_PATH}/tools/cmake/project.cmake) project(new-project)
Main Component CMakeLists.txt
idf_component_register( SRCS "main.c" INCLUDE_DIRS "." REQUIRES driver nvs_flash esp_wifi )
sdkconfig.defaults
Target chip
CONFIG_IDF_TARGET="esp32"
Flash size
CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
Partition table
CONFIG_PARTITION_TABLE_SINGLE_APP=y
Log level
CONFIG_LOG_DEFAULT_LEVEL_INFO=y
Adding to the Monorepo
Directory Location
Place new ESP32 projects in:
packages/esp32-projects/new-project-name/
Create Makefile Target
Add to root Makefile:
New project variables
NEW_PROJECT_DIR = $(ESP32_PACKAGES_DIR)/new-project-name
Build target
new-project-build: check-idf @echo "$(BLUE)Building new-project...$(NC)" @cd $(NEW_PROJECT_DIR) && $(IDF_ENV_CMD) && idf.py build
Flash target
new-project-flash: check-idf @echo "$(BLUE)Flashing new-project...$(NC)" @cd $(NEW_PROJECT_DIR) && $(IDF_ENV_CMD) && idf.py flash -p $(PORT)
Add to .PHONY
.PHONY: new-project-build new-project-flash
Component Management
Using IDF Component Manager
Create idf_component.yml in component directory:
dependencies:
From ESP Component Registry
espressif/led_strip: "^2.0.0"
From GitHub
my_component: git: https://github.com/user/component.git version: "v1.0.0"
Local Components
Place in project's components/ directory:
project/ ├── components/ │ └── my_component/ │ ├── CMakeLists.txt │ ├── include/ │ │ └── my_component.h │ └── my_component.c └── main/
Common Configuration Tasks
Setting Target Chip
Set target (creates fresh sdkconfig)
idf.py set-target esp32s3
Or via Makefile
make robocar-set-target TARGET=esp32s3
Menuconfig Options
idf.py menuconfig
Common sections:
-
Serial flasher config (port, baud rate)
-
Partition table
-
Component config (WiFi, Bluetooth, etc.)
-
FreeRTOS (tick rate, stack sizes)
Flash Size Configuration
In sdkconfig.defaults:
4MB flash
CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
16MB flash (for ESP32-S3)
CONFIG_ESPTOOLPY_FLASHSIZE_16MB=y
Best Practices
-
Use sdkconfig.defaults - Don't commit sdkconfig, use defaults
-
Pin ESP-IDF version - Document which version the project requires
-
Minimal dependencies - Only include REQUIRES you actually use
-
Target-specific configs - Use sdkconfig.defaults.esp32s3 for variants
-
Document GPIO usage - Create a pinout table in README