ESP-IDF for Programming ESP32 Development Board

Introduction

Express if provides the necessary tools for the development of esp32 series hardware. ESP-IDF is the IOT Development Framework from Express if for ESP32 chip. The software development framework by Espressif is intended for rapidly developing Internet-of-Things (IoT) applications, with Wi-Fi, Bluetooth, power management and several other system features.

ESP32 integrates Wi-Fi (2.4 GHz band) and Bluetooth 4.2 solutions on a single chip, along with dual high-performance cores, Ultra-Low Power co-processor and several peripherals. Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform to meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability.

To develop applications for ESP32 you need:

  • PC loaded with either Windows, Linux or Mac operating system
  • Toolchain to build the Application for ESP32
  • ESP-IDF that essentially contains API for ESP32 and scripts to operate the Toolchain
  • A text editor to write programs (Projects) in C, e.g. Eclipse
  • The ESP32 board itself and a USB cable to connect it to the PC

Preparation of development environment consists of three steps:

  • Setup of Toolchain
  • Getting of ESP-IDF from GitHub
  • Installation and configuration of Eclipse

Set up of Toolchain for Windows

The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Windows don’t have a built-in “make” environment, so as well as installing the toolchain you will need a GNU-compatible environment. We use the MSYS2 environment.

The quick setup is to download the Windows all-in-one toolchain & MSYS zip file from:

https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20170111.zip

Unzip the zip file to C: and it will create a “msys32” directory with a pre-prepared environment.

Note: Usage of toolchain

Use cd to change to the project directory (not the ESP-IDF directory.) Type make menuconfig to configure your project, then make to build it, make clean to remove built files, and make flash to flash (use the menuconfig to set the serial port for flashing.)

Get ESP-IDF

Besides the toolchain (that contains programs to compile and build the application), you also need ESP32 specific API / libraries. They are provided by Espressif in ESP-IDF repository. To get it, open an MSYS2 terminal window with administrative permissions by running C:\msys32\msys2_shell.cmd. The environment in this window is a bash shell., navigate to the directory you want to put ESP-IDF, and clone it using git clone command:

cd *$IDF_PATH *(This path can be user specific)
git clone --recursive https://github.com/espressif/esp-idf.git

ESP-IDF will be downloaded into $IDF_PATH/esp-idf

NOTE:

  • Do not miss the –recursive If you have already cloned ESP-IDF without this option, run another command to get all the submodules:
cd $IDF_PATH/esp-idf
git submodule update --init
  • While cloning submodules, the git clone command may print some output starting ‘:notavalididentifier….’ This is a known issue but the git clone still succeeds without any problems.

Setup Path to ESP-IDF

The user profile scripts are contained in C:/msys32/etc/profile.d/directory. They are executed every time you open an MSYS2 window.

  • Create a new script file in C:/msys32/etc/profile.d/ directory. Name it export_idf_path.sh
  • Identify the path to ESP-IDF directory. It is specific to your system configuration and may look something like C:\msys32\home\user-name\esp\esp-idf
  • Add the export command to the script file, e.g.:
export IDF_PATH*=*"C:/msys32/home/user-name/esp/esp-idf"

Remember to replace back-slashes with forward-slashes in the original Windows path.

  • Save the script file.
  • Close MSYS2 window and open it again. Check if IDF_PATH is set, by typing:
printenv IDF_PATH

The path previously entered in the script file should be printed out.

Start a Project

Now you are ready to prepare your application for ESP32. To start off quickly, we will use get-started/hello_world project from examples directory in the downloaded esp-idf file.

cd* $IDF_PATH*/examples/get-started/hello_world .

You can also find a range of example projects under the examples directory in ESP-IDF.

Configure

Being in the terminal window, go to the directory of hello_world application by typing cd $IDF_PATH/examples/get-started/hello_world. Then start project configuration utility menuconfig:

cd *$IDF_PATH*/examples/get-started/hello_world
make menuconfig

If previous steps have been done correctly, the following menu will be displayed:

esp-idf-configuraton

In the menu, navigate to Serial flasher config > Default serial port to configure the serial port, where the project will be loaded to. Confirm the selection by pressing enter, save the configuration by selecting < Save >and then exit the application by selecting < Exit >.

Note: On Windows, serial ports have names like COM1. On MacOS, they start with /dev/cu.. On Linux, they start with /dev/tty.

Build and Flash

Now you can build and flash the application. Run:

make flash

This will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries, and flash these binaries to your ESP32 board. If there are no issues, at the end of the build process, you should see messages describing the progress of the loading process. Finally, the end module will be reset and “hello_world” application will start.

Monitor

To see if “hello_world” application is indeed running, type make monitor. This command is launching IDF Monitor application:

$ make monitor
MONITOR
--- idf_monitor on COM12 115200 ---
--- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---

ets Dec  18 2017 03:22:57

rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
ets Dec  18 2017 03:22:57

Several lines below, after start-up and diagnostic log, you should see “Hello world!” printed out by the application.

...
Hello world!
Restarting in 10 seconds...
I (211) cpu_start: Starting scheduler on APP CPU.
Restarting in 9 seconds...
Restarting in 8 seconds...
Restarting in 7 seconds...

To exit the monitor use shortcut Ctrl+].

Note: If instead of the messages above, you see a random garbage similar to:

e���)(Xn@�y.!��(�PW+)��Hn9a؅/9�!�t5��P�~�k��e�ea�5�jA
~zY��Y(1�,1�� e���)(Xn@�y.!Dr�zY(�jpi�|�+z5Ymvp

or monitor fails shortly after upload, your board is likely using 26MHz crystal, while the ESP-IDF assumes a default of 40MHz. Exit the monitor, go back to the menuconfig, change ESP32_XTAL_FREQ_SEL to 26MHz, then build and flash the application again.

To execute make flash and make monitor in one go, type make flash monitor.

Issues Observed on Windows

  • If you are using the supported Windows environment and receive the error “winpty: command not found” then run pacman -S winpty to fix.
  • Arrow keys and some other special keys in gdb don’t work, due to Windows Console limitations.
  • Occasionally when “make” exits, it may stall for up to 30 seconds before idf_monitor resumes.
  • Occasionally when “gdb” is run, it may stall for a short time before it begins communicating with the gdbstub.

Eclipse IDE on Windows

Configuring Eclipse on Windows requires some different steps. The full configuration steps for Windows are shown below.

(For OS X and Linux instructions, see the Eclipse IDE page.)

Installing Eclipse IDE

  • Download the Eclipse Installer for your platform from eclipse.org.
  • When running the Eclipse Installer, choose “Eclipse for C/C++ Development” (in other places you’ll see this referred to as CDT.)

Setting up Eclipse on Windows

Once your new Eclipse installation launches, follow these steps:

Import New Project

  • Eclipse makes use of the Makefile support in ESP-IDF. This means you need to start by creating an ESP-IDF project. You can use the idf-template project from GitHub, or open one of the examples in the esp-idf examples subdirectory.
  • Once Eclipse is running, choose File -> Import…
  • In the dialog that pops up, choose “C/C++” -> “Existing Code as Makefile Project” and click Next.
  • On the next page, enter “Existing Code Location” to be the directory of your IDF project. Don’t specify the path to the ESP-IDF directory itself (that comes later). The directory you specify should contain a file named “Makefile” (the project Makefile).
  • On the same page, under “Toolchain for Indexer Settings” uncheck “Show only available toolchains that support this platform”.
  • On the extended list that appears, choose “Cygwin GCC”. Then click Finish.

Note: you may see warnings in the UI that Cygwin GCC Toolchain could not be found. This is OK, we’re going to reconfigure Eclipse to find our toolchain.

Project Properties

  • The new project will appear under Project Explorer. Right-click the project and choose Properties from the context menu.
  • Click on the “C/C++ Build” properties page (top-level):
    • Uncheck “Use default build command” and enter this for the custom build command: python ${IDF_PATH}/tools/windows/eclipse_make.py.
  • Click on the “Environment” properties page under “C/C++ Build”:
    • Click “Add…” and enter the name BATCH_BUILDand value 1.
    • Click “Add…” again, and enter the name IDF_PATH. The value should be the full path where ESP-IDF is installed. The IDF_PATH directory should be specified using forward slashes not backslashes, ie C:/Users/MyUser/Development/esp-idf.
    • Edit the PATH environment variable. Delete the existing value and replace it with C:\msys32\usr\bin;C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin (If you installed msys32 to a different directory then you’ll need to change these paths to match).
  • Click on “C/C++ General” -> “Preprocessor Include Paths, Macros,etc.” property page:
    • Click the “Providers” tab
      • In the list of providers, click “CDT GCC Built-in Compiler Settings Cygwin”. Under “Command to get compiler specs”, replace the text ${COMMAND} at the beginning of the line with xtensa-esp32-elf-gcc. This means the full “Command to get compiler specs” should be xtensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD “${INPUTS}”.
      • In the list of providers, click “CDT GCC Build Output Parser” and type xtensa-esp32-elf- at the beginning of the Compiler command pattern. This means the full Compiler command pattern should be xtensa-esp32-elf-(g?cc)|([gc]\+\+)|(clang)

Building in Eclipse

Before your project is first built, Eclipse may show a lot of errors and warnings about undefined values. This is because some source files are automatically generated as part of the esp-idf build process. These errors and warnings will go away after you build the project.

  • Click OK to close the Properties dialog in Eclipse.
  • Outside Eclipse, open a command-line prompt. Navigate to your project directory, and run make menuconfig to configure your project’s esp-idf settings. This step currently has to be run outside Eclipse.

If you try to build without running a configuration step first, esp-idf will prompt for configuration on the command line – but Eclipse is not able to deal with this, so the build will hang or fail.

  • Back in Eclipse, choose Project -> Build to build your project.

TIP: If your project had already been built outside Eclipse, you may need to do a Project -> Clean before choosing Project -> Build. This is so Eclipse can see the compiler arguments for all source files. It uses these to determine the header include paths.

Flash from Eclipse

You can integrate the “make flash” target into your Eclipse project to flash using esptool.py from the Eclipse UI:

  • Right-click your project in Project Explorer (important to make sure you select the project, not a directory in the project, or Eclipse may find the wrong Makefile.)
  • Select Build Targets -> Create… from the context menu.
  • Type “flash” as the target name. Leave the other options as their defaults.
  • Now you can use Project -> Build Target -> Build (Shift+F9) to build the custom flash target, which will compile and flash the project.

Note that you will need to use “make menuconfig” to set the serial port and other config options for flashing. “make menuconfig” still requires a command line terminal (see the instructions for your platform.)

 

 

.