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 ESP32/ESP32-S series board, etc.

ESP-IoT-Solution Introduction

ESP-IoT-Solution contains peripheral drivers and code frameworks commonly used in IoT system development, which can be used as a complementary component 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

Status

master

release/v4.3

Code structure changed, added ESP32-S2 support

New features development branch

release/v1.1

v4.0.1

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

Limited maintenance

release/v1.0

v3.2.2

Legacy version

Stop maintenance

ESP-IDF Introduction

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

  • A series of libraries and header files, providing core components required for building software projects based on ESP32/ESP32-S2;

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

Note

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

ESP32/ESP32-S Introduction

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

ESP32/ESP32-S series SoCs 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

ESP32/ESP32-S series of SoCs are designed with the 40 nm technology, showing the best power and RF performance, versatility and reliability in a wide variety of application and power scenarios.

Note

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 https://github.com/espressif/esp-iot-solution

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

git clone -b release/v1.1 --recursive https://github.com/espressif/esp-iot-solution

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

Use ESP-IoT-Solution Components

The following ways can be used to add ESP-IoT-Solution components:

  1. Add all components from ESP-IoT-Solution to the project directory by inserting the following code to CMakeLists.txt under the project:

    cmake_minimum_required(VERSION 3.5)
    
    include($ENV{IOT_SOLUTION_PATH}/component.cmake)
    include($ENV{IDF_PATH}/tools/cmake/project.cmake)
    
    project(empty-project)
    
  2. Add specific components from ESP-IoT-Solution to the project directory by inserting the following code to CMakeLists.txt under the project:

    set(EXTRA_COMPONENT_DIRS "${EXTRA_COMPONENT_DIRS} $ENV{IOT_SOLUTION_PATH}/components/{component_you_choose}")
    #Please replace {component_you_choose} with the component name you choose. This command can be repeated if you need to add multiple components.
    
  3. Copy specific components from ESP-IoT-Solution to the project directory by directly copying and pasting the components and their dependencies into the components folder under the project.

Note

It is recommended to use the build system based on CMake (the default build system for ESP-IDF v4.0 and later versions) for ESP-IoT-Solution. If you need to use the GNU Make system, please refer to Build System (Legacy GNU Make).

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:

    %userprofile%\esp\esp-idf\export.bat
    

    For Linux and macOS, please run:

    . $HOME/esp/esp-idf/export.sh
    

    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
    

Note

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.

idf.py 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:

idf.py menuconfig

3. Build and download the program

Use the idf.py tool to build and download the program with:

idf.py -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 idf.py tool to see logs:

idf.py -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).