ESP32 is one of the most powerful microcontrollers for IoT and embedded development. While most
beginners use the Arduino framework, professionals and companies use ESP-IDF — the official development
framework from Espressif.
Why ESP-IDF?
- Official SDK used by Espressif themselves
- RTOS-based (FreeRTOS built-in)
- Low-level hardware control
- Professional-grade features: WiFi, BLE, OTA, ESP-NOW, Drivers, NVS, Tasks
1. Installing ESP-IDF
The installation process differs slightly for Windows, macOS, and Linux. Below are the correct steps for each.
Windows Installation
Windows users should install ESP-IDF using the ESP-IDF Installer:
Download: https://dl.espressif.com/dl/esp-idf/
- Installs ESP-IDF, Python, Git, Tools
- Sets all environment variables automatically
macOS Installation
Through Homebrew:
brew install cmake ninja dfu-util ccache python@3 git python3 -m pip install --upgrade pip
Clone ESP-IDF:
git clone --recursive https://github.com/espressif/esp-idf.git cd esp-idf ./install.sh
Linux (Ubuntu/Debian)
sudo apt-get update sudo apt-get install git wget flex bison gperf python3 python3-pip cmake ninja-build ccache
Clone and install:
git clone --recursive https://github.com/espressif/esp-idf.git cd esp-idf ./install.sh
2. Setting Up the Environment
Before using ESP-IDF, activate the environment:
Windows
Use the provided ESP-IDF PowerShell shortcut.
macOS / Linux
. $HOME/esp/esp-idf/export.sh
3. Creating Your First ESP-IDF Project
Step 1 — Create a New Project
cd ~/esp idf.py create-project hello_world cd hello_world
Step 2 — Build the Project
idf.py build
Step 3 — Flash to ESP32
idf.py -p /dev/ttyUSB0 flash
Windows example: COM3
Step 4 — Monitor Output
idf.py monitor
4. Recommended Tools (VS Code)
Installing the official ESP-IDF extension makes development easier.
Benefits:
- GUI menuconfig
- Device selection
- Integrated flashing & monitoring
- Project templates
5. ESP-IDF Project Structure Explained
- main/ → your code
- CMakeLists.txt → project configuration
- sdkconfig → all ESP32 feature settings
6. Your First ESP-IDF Application
Inside main/main.c:
#include <stdio.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_system.h"
#include "esp_log.h"
void app_main(void)
{
while (1) {
ESP_LOGI("MAIN", "Hello from ESP32!");
vTaskDelay(pdMS_TO_TICKS(1000));
}
}
7. Useful ESP-IDF Commands
idf.py build # Build idf.py flash # Flash idf.py monitor # Serial output idf.py menuconfig # Configure project idf.py clean # Clean build
8. Troubleshooting
- Permission issues (Linux/macOS): sudo usermod -a -G dialout $USER
- Port not found: check cable or driver (CP2102/CH340).
- Build errors: run
git submodule update --init --recursive