ESP-IDF Setup

ESP-IDF (Espressif IoT Development Framework) is Espressif’s official development framework, providing full access to all ESP32-S3 features.

Prerequisites

4GB+ free disk space
Python 3.8+
Git
Build essentials (gcc, make)

sudo apt-get install git wget flex bison gperf python3 python3-pip \
  python3-venv cmake ninja-build ccache libffi-dev libssl-dev \
  dfu-util libusb-1.0-0

sudo pacman -S git wget flex bison gperf python python-pip cmake \
  ninja ccache dfu-util libusb

xcode-select --install
brew install cmake ninja dfu-util python3

Installation

Clone ESP-IDF
Terminal window
```
mkdir -p ~/esp
cd ~/esp
git clone -b v5.2 --recursive https://github.com/espressif/esp-idf.git
```
Use v5.2 or the latest stable version. Check releases at github.com/espressif/esp-idf.
Install tools for ESP32-S3
Terminal window
```
cd ~/esp/esp-idf
./install.sh esp32s3
```
This installs the Xtensa toolchain, OpenOCD, and Python dependencies.
Set up environment (required each session)
Terminal window
```
source ~/esp/esp-idf/export.sh
```
Add this to your shell profile for convenience:
Terminal window
```
echo 'alias get_idf=". ~/esp/esp-idf/export.sh"' >> ~/.bashrc
```
Then use get_idf to activate the environment.

Create Your First Project

Copy the blink example

cd ~/esp
cp -r $IDF_PATH/examples/get-started/blink .
cd blink

Set the target chip
Terminal window
```
idf.py set-target esp32s3
```
Configure for N16R8 memory
Terminal window
```
idf.py menuconfig
```
Navigate to:
- Serial flasher config → Flash size → 16 MB
- Component config → ESP PSRAM → Support for external, SPI-connected RAM → Enable
- Component config → ESP PSRAM → SPI RAM config → Mode (QUAD/OCT) → Octal Mode
- Example Configuration → Blink GPIO number → 38 (V1.1) or 48 (V1.0)
Build the project
Terminal window
```
idf.py build
```
Flash to board
Terminal window
```
idf.py -p /dev/ttyUSB0 flash
```
Monitor output
Terminal window
```
idf.py -p /dev/ttyUSB0 monitor
```
Press Ctrl+] to exit.

Project Configuration (sdkconfig)

Key settings for ESP32-S3-DevKitC-1-N16R8:

# Target and memory
CONFIG_IDF_TARGET="esp32s3"
CONFIG_ESPTOOLPY_FLASHSIZE_16MB=y
CONFIG_SPIRAM=y
CONFIG_SPIRAM_MODE_OCT=y
CONFIG_SPIRAM_SPEED_80M=y

# USB console (if using native USB)
CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=y

# Wi-Fi
CONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM=10
CONFIG_ESP_WIFI_DYNAMIC_RX_BUFFER_NUM=32

Useful Commands

Command	Description
`idf.py set-target esp32s3`	Set chip target
`idf.py menuconfig`	Interactive configuration
`idf.py build`	Compile project
`idf.py flash`	Flash to board
`idf.py monitor`	Serial monitor
`idf.py flash monitor`	Flash and monitor
`idf.py fullclean`	Clean all build artifacts
`idf.py size`	Show firmware size
`idf.py size-components`	Size per component

Example Projects

ESP-IDF includes many examples:

ls $IDF_PATH/examples/

Notable examples for DevKitC-1:

Example	Path	Description
Blink	`get-started/blink`	GPIO LED control
Wi-Fi Station	`wifi/getting_started/station`	Connect to AP
Wi-Fi SoftAP	`wifi/getting_started/softAP`	Create AP
USB Serial/JTAG	`peripherals/usb/device/tusb_serial_device`	USB CDC
PSRAM Test	`system/himem`	High memory allocation
Camera	`peripherals/camera`	Camera interface

Troubleshooting

Cannot find ttyUSB0

# Check device connection
dmesg | grep -i cp210
# Add user to dialout group
sudo usermod -aG dialout $USER
# Log out and back in

Build fails with memory errors

# Increase swap space or use
idf.py build -j 2  # Limit parallel jobs

Flash fails

Hold BOOT while pressing RST
Release both buttons
Run flash command

PSRAM not detected

Verify in menuconfig:

Component config → ESP PSRAM → Support for external RAM is enabled
SPI RAM config → Mode matches your module (OCT for N8R8/N16R8)

Next Steps

PlatformIO Setup - Alternative IDE-based workflow
First Blink Tutorial - RGB LED details
USB Serial Guide - USB vs UART options