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

1. Use sdkconfig.defaults - Don't commit sdkconfig, use defaults
2. Pin ESP-IDF version - Document which version the project requires
3. Minimal dependencies - Only include REQUIRES you actually use
4. Target-specific configs - Use sdkconfig.defaults.esp32s3 for variants
5. Document GPIO usage - Create a pinout table in README