Get Started


This document is intended to help you set up the development environment for ESP-IoT-Solution (Espressif IoT Solution). After that, a simple example will show you how to use ESP-IoT-Solution to set up environment, create a project, build and flash firmware onto an ESP series board, etc.

ESP-IoT-Solution Introduction

ESP-IoT-Solution contains peripheral drivers and code frameworks commonly used in IoT system development, which provide complementary components to ESP-IDF to facilitate simpler development, mainly including the following contents:

  • Device drivers such as sensors, screens, audio devices, input devices, actuators, and etc.

  • Code framework and related documents of low power management, security encryption, storage and etc.

  • Entrance guideline for Espressif’s open-source solutions from the perspective of practical application.

ESP-IoT-Solution Versions

Specifications of different ESP-IoT-Solution versions are listed in the following table:

ESP-IoT-Solution version

Corresponding ESP-IDF version

Main changes




support component manager and new chips

New features development branch



IDF version updated, deleted codes that have been moved to other repos

Stop maintenance



Legacy version

Stop maintenance

Since the master branch uses the ESP Component Manager to manager components, each of them is a separate package, and each package may support a different version of the ESP-IDF, which will be declared in the component’s idf_component.yml file.

ESP-IDF Introduction

ESP-IDF is the IoT development framework for ESP series SoCs provided by Espressif, including:

  • A series of libraries and header files, providing core components required for building software projects based on ESP SoC;

  • Common tools and functions used during the development and manufacturing processes, e.g., build, flashing, debugging, measurement and etc.


For detailed information, please go to ESP-IDF Programming Guide.

ESP Series SoC Introduction

You can select any development board from ESP series to get started with ESP-IoT-Solution, or select a supported board from the Boards Component directly for a quick start.

ESP series SoC support the following features:

  • 2.4 GHz Wi-Fi

  • Bluetooth

  • High-performance single core, dual-core processor, capable of running at 240 MHz

  • Ultra-low-power co-processor

  • Various peripherals including GPIO, I2C, I2S, SPI ,UART, SDIO, RMT, LEDC PWM, Ethernet, TWAI®, Touch, USB OTG and etc.

  • Rich memory resources, including up to 520 KB internal RAM and can support external PSRAM

  • Support security functions, e.g., hardware encryption

ESP series of SoC are designed with the 40nm technology, showing the best power and RF performance, versatility and reliability in a wide variety of application and power scenarios.


The configuration varies by SoC series, please refer to ESP Product Selector for details.

Setting up Development Environment

1. Get ESP-IDF

As ESP-IoT-Solution relies on ESP-IDF basic functions and build tools, please set up ESP-IDF development environment first following ESP-IDF Installation Step by Step. Please note that different versions of ESP-IoT-Solution may rely on different ESP-IDF versions, please refer to ESP-IoT-Solution Versions for specifications.

2. Get ESP-IoT-Solution

For master version, please use the following command:

git clone --recursive

For release/v1.1 version, please use the following command:

git clone -b release/v1.1 --recursive

For other versions, please also use this command with release/v1.1 replaced by your target branch name.

Use ESP-IoT-Solution Components

If you just want to use the components in ESP-IoT-Solution, we recommend you use it from the ESP Component Registry.

The registered components in ESP-IoT-Solution are listed in , You can directly add the components from the Component Registry to your project by using the add-dependency command under your project’s root directory. eg run add-dependency "espressif/usb_stream" to add the usb_stream, the component will be downloaded automatically during the CMake step.

Please refer to IDF Component Manager for details.

Build and Download

1. Set up the environment variables

The tools installed in above steps are not yet added to the PATH environment variables. To make the tools usable from the command line, please follow the following steps to add environment variables:

  • Add ESP-IDF environment variables:

    For Windows system, please open the Command Prompt and run:


    For Linux and macOS, please run:

    . $HOME/esp/esp-idf/

    Please remember to replace the paths in above commands as your actual paths.

  • Add IOT_SOLUTION_PATH environment variables:

    For Windows system, please open the Command Prompt and run:

    set IOT_SOLUTION_PATH=C:\esp\esp-iot-solution

    For Linux and macOS, please run:

    export IOT_SOLUTION_PATH=~/esp/esp-iot-solution


The environment variables set by the above method are only valid in the current terminal. Please repeat above steps if you open a new terminal.

2. Set build target

ESP-IDF supports multiple chips as esp32, esp32s2 and others, please set your target chip before building (the default target is esp32). For example, you can set the build target as esp32s2. set-target esp32s2

For examples in ESP-IoT-Solution developed based on Boards Component, you can go to Board Options -> Choose Target Board in menuconfig to choose a target board: menuconfig

3. Build and download the program

Use the tool to build and download the program with: -p PORT build flash

Please replace PORT with your board’s port name. Serial ports have the following patterns in their names: Windows is like COMx; Linux starting with /dev/ttyUSBx; macOS usually is /dev/cu..

4. Serial print log

Use the tool to see logs: -p PORT monitor

Do not forget to replace PORT with your serial port name (COMx for Windows; /dev/ttyUSBx for Linux; /dev/cu. for macOS).