Ultimate Guide to ESP32 Development with ESP-IDF, Docker, and Docker Compose

ESP32 Updated on May 5, 2025

Table of Contents

  1. Introduction
  2. Why Use Docker and Docker Compose for ESP-IDF?
  3. Prerequisites
  4. Part 1: Setting Up ESP-IDF with Docker
  5. Part 2: Enhancing the Setup with Docker Compose
  6. Advanced Tips and Troubleshooting
  7. Conclusion

Introduction

The ESP32, developed by Espressif Systems, is a versatile microcontroller widely used in IoT applications due to its dual-core processor, Wi-Fi, and Bluetooth capabilities. The Espressif IoT Development Framework (ESP-IDF) is the official toolkit for programming the ESP32, offering robust libraries and tools. However, setting up ESP-IDF can be challenging due to dependency management, toolchain installation, and cross-platform compatibility issues.

Docker simplifies this by encapsulating the ESP-IDF environment in a portable container, ensuring consistency across operating systems. Docker Compose takes it further by defining the container configuration, including USB passthrough for flashing and monitoring, in a single YAML file, making the setup reusable and manageable. This guide combines both approaches, providing a step-by-step process to set up an ESP32 development environment using ESP-IDF with Docker and Docker Compose, complete with USB passthrough for hardware interaction.

Why Use Docker and Docker Compose for ESP-IDF?

Using Docker and Docker Compose for ESP-IDF development offers numerous benefits:

  • Consistency: Ensures the same environment across Windows, macOS, and Linux, eliminating setup discrepancies.
  • Simplified Setup: Encapsulates toolchains, libraries, and dependencies, reducing manual installation.
  • Portability: Share the environment with teams or use it in CI/CD pipelines.
  • Version Control: Easily switch between ESP-IDF versions by changing Docker images or tags.
  • USB Passthrough: Enables flashing and monitoring the ESP32 directly from the container.
  • Reusability with Docker Compose: Define complex configurations in a single file, replacing cumbersome docker run commands.
  • Isolation: Prevents conflicts with other tools on the host system.

While Docker adds slight overhead and requires USB configuration, these are manageable with proper setup, as detailed below.

Prerequisites

Before starting, ensure you have:

  • Hardware:
    • An ESP32 development board (e.g., ESP32-DevKitC).
    • A USB cable (data-capable, not power-only) for connecting the ESP32.
  • Software:
    • Docker installed (Docker Desktop for Windows/macOS or Docker for Linux).
    • Docker Compose (included with Docker Desktop or installed separately on Linux).
    • A code editor (e.g., VS Code) for editing project files and YAML configurations.
  • System Requirements:
    • A computer running Windows, macOS, or Linux.
    • Internet access to pull Docker images and dependencies.
    • Administrative privileges for USB device access and Docker setup.
  • Knowledge:
    • Basic familiarity with Docker, Docker Compose, ESP-IDF, and command-line interfaces.

If you lack an ESP32 board, you can follow along to set up the environment and build projects, but flashing and monitoring require hardware.

Part 1: Setting Up ESP-IDF with Docker

Step 1: Install Docker

Docker is the foundation for running the ESP-IDF environment.

  • Download and Install:
    • Windows/macOS: Install Docker Desktop from docker.com.
    • Linux: Use your package manager (e.g., sudo apt install docker.io on Ubuntu).
  • Verify Installation:
docker --version

Expect output like Docker version 24.0.7, build afdd53b.

Step 2: Pull the ESP-IDF Docker Image

Espressif provides an official espressif/idf Docker image with preconfigured ESP-IDF versions.

  • Choose a Version: Check available tags on Docker Hub (e.g., release-v5.2).

  • Pull the Image:

docker pull espressif/idf:release-v5.2

This downloads the image (several GB). Ensure a stable internet connection.

  • Verify:
docker images

Confirm espressif/idf:release-v5.2 is listed.

Step 3: Set Up Your Project Directory

Create a directory to store ESP-IDF projects, which will be mounted into the container.

mkdir ~/esp32-projects
cd ~/esp32-projects

This directory persists project files on the host, even if the container is removed.

Step 4: Run the Docker Container

Launch the container with the project directory and USB device mounted.

  • Identify USB Device Path:
    • Linux: ls /dev/tty* (look for /dev/ttyUSB0 or /dev/ttyACM0).
    • Windows: Check Device Manager for COM ports (e.g., COM3 maps to /dev/ttyS3 in WSL).
    • macOS: ls /dev/cu.* (e.g., /dev/cu.usbserial-XXXX).
  • Run the Container:
docker run -it -v ~/esp32-projects:/project --device=/dev/ttyUSB0 espressif/idf:release-v5.2

Explanation:

 - `-it`: Interactive terminal.
 - `-v`: Mounts `~/esp32-projects` to `/project`.
 - `--device`: Passes the USB device for flashing.

Step 5: Configure the ESP-IDF Environment

Inside the container, set up ESP-IDF:

. /opt/esp/idf/export.sh

Verify:

idf.py --version

This initializes the toolchain and paths, required for each session.

Step 6: Create and Build an ESP-IDF Project

Test the setup with a sample project:

  • Copy Example:
cd /project
cp -r /opt/esp/idf/examples/get-started/hello_world .
cd hello_world
  • Set Target:
idf.py set-target esp32
  • Build:
idf.py build

This compiles the hello_world project, generating firmware in build.

Step 7: Flash the Firmware to ESP32

Deploy the firmware:

  • Connect ESP32: Plug in the board via USB.
  • Flash:
idf.py -p /dev/ttyUSB0 flash

Press the “Boot” button if prompted.

Step 8: Monitor the Output

View the ESP32’s output:

idf.py -p /dev/ttyUSB0 monitor

See “Hello, World!” in the serial monitor. Exit with Ctrl+].

Part 2: Enhancing the Setup with Docker Compose

Docker Compose simplifies the configuration by defining it in a YAML file, making it reusable and ideal for teams or automation.

Step 9: Create the Docker Compose Configuration

In a new or existing project directory:

mkdir ~/esp32-docker
cd ~/esp32-docker
mkdir esp32-projects
touch docker-compose.yml

Edit docker-compose.yml:

services:
  esp-idf:
    image: espressif/idf:release-v5.2
    container_name: esp-idf-container
    volumes:
       - ./esp32-projects:/project
    devices:
       - /dev/ttyUSB0:/dev/ttyUSB0
    tty: true
    stdin_open: true
    working_dir: /project
    command: /bin/bash

Key Fields:

  • image: ESP-IDF v5.2.
  • volumes: Mounts esp32-projects to /project.
  • devices: Maps /dev/ttyUSB0 for USB passthrough.
  • tty/stdin_open: Interactive shell.
  • command: Starts Bash.

For Windows/macOS, adjust the devices path (e.g., /dev/ttyS3 or /dev/cu.usbserial-XXXX).

Step 10: Handle USB Permissions (Linux)

Ensure USB access:

  • Add to dialout Group:
sudo usermod -aG dialout $USER

Log out and back in.

  • Check Permissions:
ls -l /dev/ttyUSB0

Adjust if needed:

sudo chmod 666 /dev/ttyUSB0

Step 11: Start the Docker Compose Service

Launch the service:

docker-compose up

This starts the container, mounts the project directory, and provides an interactive shell at /project.

Step 12: Test the Setup with a Sample Project

Inside the container:

  • Set Up Environment:
. /opt/esp/idf/export.sh
  • Copy Example:
cp -r /opt/esp/idf/examples/get-started/hello_world .
cd hello_world
  • Set Target and Build:
idf.py set-target esp32
idf.py build

Step 13: Flash and Monitor Using Docker Compose

With USB passthrough:

  • Flash:
idf.py -p /dev/ttyUSB0 flash
  • Monitor:
idf.py -p /dev/ttyUSB0 monitor

Combine:

idf.py -p /dev/ttyUSB0 flash monitor

Step 14: Stop the Docker Compose Service

Stop the service:

docker-compose down

This removes the container but preserves esp32-projects.

Advanced Tips and Troubleshooting

  • Flexible Docker Compose: Use environment variables:
image: espressif/idf:${IDF_VERSION:-release-v5.2}
devices:
    - ${USB_DEVICE:-/dev/ttyUSB0}:${USB_DEVICE:-/dev/ttyUSB0}

Set variables:

export IDF_VERSION=release-v5.1
export USB_DEVICE=/dev/ttyACM0
docker-compose up
  • Persistent Environment: Auto-source export.sh:
command: /bin/bash -c ". /opt/esp/idf/export.sh && /bin/bash"
  • Custom Dockerfile: For additional tools or permissions:
FROM espressif/idf:release-v5.2
RUN usermod -aG dialout idf
WORKDIR /project
CMD ["/bin/bash"]
  • Troubleshooting USB:
    • Device Not Found: Verify path and cable. Check WSL mappings on Windows.
    • Permissions: Ensure dialout group access or adjust device permissions.
    • macOS: USB passthrough is limited; consider native ESP-IDF if issues persist.
  • CI/CD: Run non-interactive builds:
docker-compose run esp-idf bash -c ". /opt/esp/idf/export.sh && cd /project/hello_world && idf.py build"
  • VS Code: Use “Dev Containers” to open the project in the container.

Conclusion

This guide provides a complete roadmap for setting up an ESP32 development environment using ESP-IDF with Docker and Docker Compose. The Docker approach ensures a consistent, isolated environment, while Docker Compose simplifies configuration with USB passthrough, making it ideal for individual developers, teams, or CI/CD pipelines. By following these steps, you’ve built, flashed, and monitored a sample project, laying the foundation for advanced IoT applications. Experiment with different ESP-IDF versions, integrate with IDEs, or extend the setup to suit your needs. With this robust setup, you’re ready to unlock the full potential of the ESP32!