Dev Environment
Set up ESP-IDF v5 before writing any firmware. This takes 15–30 minutes the first time.
Install ESP-IDF v5
Recommended method: VSCode + ESP-IDF Extension
- Install Visual Studio Code
- Open the Extensions panel, search for ESP-IDF, install the Espressif extension
- Open the Command Palette (
Ctrl+Shift+P) and runESP-IDF: Configure ESP-IDF Extension - Select Express setup, choose ESP-IDF v5.3 (or latest v5.x), pick an install directory
- Wait for the download (~1 GB including the toolchain)
The extension downloads ESP-IDF, the Xtensa GCC toolchain, and OpenOCD for debugging.
Alternative: command-line install
mkdir -p ~/esp && cd ~/esp
git clone --recursive https://github.com/espressif/esp-idf.git --branch v5.3
cd esp-idf
./install.sh esp32s3
. ./export.sh # adds idf.py to PATH (run this in each new shell)
Add . $HOME/esp/esp-idf/export.sh to your shell profile (~/.bashrc or ~/.zshrc) to
avoid running it manually.
Create the Project
idf.py create-project alarm-clock
cd alarm-clock
idf.py set-target esp32s3
idf.py set-target creates sdkconfig and sets the target chip. Always run this before
idf.py build on a new project.
Build and Flash
idf.py build # compile everything
idf.py flash # flash to connected ESP32-S3
idf.py monitor # open serial console (Ctrl+] to exit)
idf.py flash monitor # flash and immediately open monitor
The ESP-IDF build system is based on CMake. idf.py is a wrapper that calls CMake,
Ninja, and esptool.py under the hood.
Configuring sdkconfig
sdkconfig is ESP-IDF's equivalent of environment variables for the build. It controls
which peripherals are enabled, stack sizes, log levels, and more.
Open it with:
idf.py menuconfig
Key settings for this project:
| Path | Setting | Value |
|---|---|---|
| Component config → ESP System Settings → Brownout detector level | 2.44V | Lower threshold reduces spurious resets from audio current spikes |
| Component config → FreeRTOS → Tick rate (Hz) | 1000 | Better timer resolution for debounce timers |
| Component config → Log output → Default log verbosity | Info | Reduce noise in production |
| Component config → PSRAM | Enable PSRAM | Required for e-ink frame buffer |
After changing menuconfig, run idf.py build to rebuild with the new settings.
Serial Port Permissions (Linux)
On Linux, you may get a "Permission denied" error when accessing the serial port:
sudo usermod -aG dialout $USER
# Log out and log back in for the change to take effect
Verifying the Setup
cd $IDF_PATH/examples/get-started/hello_world
idf.py set-target esp32s3
idf.py flash monitor
Expected output:
Hello world!
This is esp32s3 chip with 2 CPU core(s), WiFi/BLE, silicon revision v0.2, 16MB external-flash
Restarting in 10 seconds...
If this works, your environment is ready.