ESP-IDF Development Guide

Complete Setup and Workflow for ESP32-S3 on Linux

📋 Overview

ESP-IDF (Espressif IoT Development Framework) is the official development framework for ESP32 series chips. This comprehensive guide walks you through the complete setup process for ESP32-S3 development on Linux systems, from initial installation to building and flashing your first project.

🎯 What You'll Learn:
  • One-time ESP-IDF installation and configuration
  • Environment setup for each terminal session
  • Creating, building, and flashing ESP32 projects
  • System maintenance and cleanup procedures

🔧 Step 1: First Time Setup (Once Ever)

This initial setup process only needs to be performed once on your system. It downloads the ESP-IDF framework, installs all necessary tools for ESP32-S3 development, and configures your shell environment for easy access.

Navigate to your projects directory:
cd ~/esp32-projects
Clone the ESP-IDF repository with all submodules:
git clone --recursive https://github.com/espressif/esp-idf.git
Enter the ESP-IDF directory:
cd esp-idf
Install ESP32-S3 specific tools and dependencies:
./install.sh esp32s3
Open your shell configuration file (for zsh users):
nano ~/.zshrc
📝 Shell Configuration:

Add the following alias to your ~/.zshrc file:

alias get_idf='. ~/esp32-projects/esp-idf/export.sh'

If you're using bash instead of zsh, edit ~/.bashrc instead.

Reload your shell configuration to apply changes:
source ~/.zshrc
💡 Pro Tip:

The --recursive flag is crucial as it ensures all git submodules are downloaded. Without it, you'll be missing important components!

🔄 Step 2: Every New Terminal Session (Once Per Window)

Each time you open a new terminal window and want to work with ESP-IDF, you need to set up the environment variables. This is done quickly with the alias you created earlier.

Activate ESP-IDF environment:
get_idf
ℹ️ Why is this needed?

The get_idf command sets up environment variables that point to ESP-IDF tools and libraries. These variables are session-specific and don't persist when you close the terminal. Running this command ensures all ESP-IDF commands (idf.py) work correctly.

🚀 Step 3: Every New Project

This workflow is used whenever you start a new ESP32 project. We'll use the "hello_world" example as a starting point, which demonstrates basic ESP-IDF project structure and functionality.

Copy the hello_world example to create your new project:
cp -r $IDF_PATH/examples/get-started/hello_world ~/esp32-projects/my_project
Navigate to your new project directory:
cd ~/esp32-projects/my_project
Configure the project for ESP32-S3 target:
idf.py set-target esp32s3
Build the project (compile and link):
idf.py build
Flash the compiled binary to ESP32 and open serial monitor:
idf.py -p /dev/tty.usbserial-* flash monitor
🔌 Port Selection:

The /dev/tty.usbserial-* is a wildcard that matches your USB serial port. On Linux, it might be /dev/ttyUSB0 or /dev/ttyACM0. To find your exact port:

ls /dev/tty*

Look for devices that appear when you connect your ESP32 board.

📱 Example: Creating a Custom Project

Let's say you want to create a WiFi-enabled temperature sensor project:

cp -r $IDF_PATH/examples/wifi/getting_started/station ~/esp32-projects/temp_sensor cd ~/esp32-projects/temp_sensor idf.py set-target esp32s3 idf.py menuconfig

The menuconfig command opens a configuration menu where you can set WiFi credentials, partition tables, and other project-specific settings.

📊 Complete Development Workflow

Development Cycle Overview

1. Open Terminal
Launch your terminal application
2. Activate Environment
Run: get_idf
3. Navigate to Project
Use: cd ~/esp32-projects/my_project
4. Edit Code
Modify source files in your preferred editor
5. Build Project
Execute: idf.py build
6. Flash & Monitor
Run: idf.py -p PORT flash monitor
7. Test & Debug
Observe serial output and test functionality

🧹 Step 4: Optional Cleanup (Free Up Disk Space)

During installation, ESP-IDF downloads compressed archives of tools and libraries. After installation, these archives are no longer needed and can be safely removed to free up disk space (typically several hundred megabytes).

Remove installation archives to save disk space:
python $IDF_PATH/tools/idf_tools.py uninstall --remove-archives
💾 Disk Space Savings:

This command can free up 500MB-1GB of disk space depending on which toolchains were installed. The actual tools remain functional; only the compressed archive files are removed.

🛠️ Common Commands Reference

Configuration & Building

Open configuration menu:
idf.py menuconfig
Clean build artifacts:
idf.py fullclean
Build project (incremental):
idf.py build

Flashing & Monitoring

Flash only (without monitor):
idf.py -p /dev/ttyUSB0 flash
Monitor only (view serial output):
idf.py -p /dev/ttyUSB0 monitor
Erase flash memory completely:
idf.py -p /dev/ttyUSB0 erase-flash

Project Information

Show project size information:
idf.py size
Display partition table:
idf.py partition-table

❗ Troubleshooting Common Issues

Permission Denied on Serial Port

Problem: Cannot access /dev/ttyUSB0 due to permission errors.

Solution: Add your user to the dialout group:

sudo usermod -a -G dialout $USER

Log out and log back in for changes to take effect.

Command 'idf.py' Not Found

Problem: ESP-IDF commands are not recognized.

Solution: Make sure you've run get_idf in your current terminal session.

Build Errors After Git Pull

Problem: Project won't build after updating ESP-IDF.

Solution: Clean the project and rebuild:

idf.py fullclean idf.py build

Flash Fails or Device Not Detected

Problem: Cannot connect to ESP32 board.

Solutions:

  • Check USB cable (use a data cable, not charge-only)
  • Try holding BOOT button while flashing
  • Verify correct port: ls /dev/tty*
  • Try a different USB port

📚 Project Structure Example

A typical ESP-IDF project has the following structure:

my_project/
├── CMakeLists.txt          (Project build configuration)
├── main/
│   ├── CMakeLists.txt      (Main component build config)
│   └── main.c              (Your application code)
├── components/             (Optional: custom components)
├── sdkconfig               (Project configuration file)
└── build/                  (Generated build files)
📝 Key Files:
  • CMakeLists.txt: Defines project name and components
  • main/main.c: Entry point of your application (contains app_main())
  • sdkconfig: Generated by menuconfig, stores all configuration
  • build/: Contains compiled binaries (can be deleted and rebuilt)

🎓 Best Practices

✅ Recommended Practices:
  • Always run get_idf when opening a new terminal
  • Use idf.py fullclean if you encounter strange build errors
  • Keep ESP-IDF updated: cd ~/esp32-projects/esp-idf && git pull
  • Use version control (git) for your projects
  • Create a separate project directory for each new application
  • Test on hardware frequently during development
  • Use menuconfig to configure WiFi, logging, and other settings
  • Monitor serial output for debugging with ESP_LOGI() macros

🔗 Additional Resources