SDK – ESP32 – Xtensa architecture toolchain

Xtensa chip
Website

Informatie (ENG)

The Xtensa processor architecture is a configurable, extensible, and synthesizable 32-bit RISC processor core. Processor and SOC vendors can select from various processor options and even create customized instructions in addition to a base ISA to tailor the processor for a particular application.

Set up of Toolchain for Windows

Step 1: Quick Steps

Windows doesn’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 to provide.
You don’t need to use this environment all the time (you can use Eclipse or some other front-end), but it runs behind the scenes.

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

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

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

Alternative Step 1: Configure toolchain & environment from scratch

As an alternative to getting a pre-prepared environment, you can set up the environment from scratch:

  • Navigate to the MSYS2 installer page and download the msys2-i686-xxxxxxx.exe installer executable (we only support a 32-bit MSYS environment, it works on both 32-bit and 64-bit Windows.)
  • Run through the installer steps, and accept the “Run MSYS2 now” option at the end. A window will open with a MSYS2 terminal.
  • The ESP-IDF repository on github contains a script in the tools directory titled windows_install_prerequisites.sh. If you haven’t downloaded the ESP-IDF yet, that’s OK – you can just download that one file in Raw format from here. Save it somewhere on your computer.
  • Type the path to the shell script into the MSYS2 terminal window. You can type it as a normal Windows path, but use forward-slashes instead of back-slashes. ie: C:/Users/myuser/Downloads/windows_install_prerequisites.sh. You can read the script beforehand to check what it does.
  • If you use the 201602 MSYS2 installer, the first time you run windows_install_prerequisites.sh it will update the MSYS2 core system. At the end of this update, you will be prompted to close the MSYS2 terminal and re-open. When you re-open after the update, re-run windows_install_prerequisites.sh. The next version of MSYS2 (after 201602) will not need this interim step.
  • The windows_install_prerequisites.sh script will download and install packages for ESP-IDF support, and the ESP32 toolchain.

Note: You may encounter a bug where svchost.exe uses 100% CPU in Windows after setup is finished, resulting in the ESP-IDF building very slowly. Terminating svchost.exe or restarting Windows will solve this problem.

Another Alternative Step 1: Just download a toolchain

If you already have an MSYS2 install or want to do things differently, you can download just the toolchain here:

https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-59.zip

If you followed one of the above options for Step 1, you won’t need this download.

Important: Just having this toolchain is not enough to use ESP-IDF on Windows. You will need GNU make, bash, and sed at minimum. The above environments provide all this, plus a host compiler (required for menuconfig support).

Step 2: Getting the esp-idf repository from github

Open an MSYS2 terminal window by running C:\msys32\msys2_shell.cmd. The environment in this window is a bash shell.

Change to the directory you want to clone the SDK into by typing a command like this one: cd "C:/path/to/dir" (note the forward-slashes in the path). Then type git clone --recursive https://github.com/espressif/esp-idf.git

If you’d rather use a Windows UI tool to manage your git repositories, this is also possible. A wide range are available.

NOTE: While cloning submodules, the git clone command may print some output starting ': not a valid identifier.... This is a known issue but the git clone still succeeds without any problems.

Step 3: Starting a project

ESP-IDF by itself does not build a binary to run on the ESP32. The binary “app” comes from a project in a different directory. Multiple projects can share the same ESP-IDF directory on your computer.

The easiest way to start a project is to download the Getting Started project from github.

The process is the same as for checking out the ESP-IDF from github. Change to the parent directory and run git clone https://github.com/espressif/esp-idf-template.git.

IMPORTANT: The esp-idf build system does not support spaces in paths to esp-idf or to projects.

Step 4: Configuring the project

Open an MSYS2 terminal window by running C:\msys32\msys2_shell.cmd. The environment in this window is a bash shell.

Type a command like this to set the path to ESP-IDF directory: export IDF_PATH="C:/path/to/esp-idf" (note the forward-slashes not back-slashes for the path). If you don’t want to run this command every time you open an MSYS2 window, create a new file in C:/msys32/etc/profile.d/ and paste this line in – then it will be run each time you open an MYS2 terminal.

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

If you’d like to use the Eclipse IDE instead of running make, check out the Eclipse setup guide in this directory.

Set up of Toolchain for Linux

Step 0: Prerequisites

Install some packages

To compile with ESP-IDF you need to get the following packages:

  • Ubuntu and Debian:
  • Arch:

Step 1: Download binary toolchain for the ESP32

ESP32 toolchain for Linux is available for download from Espressif website:

  • for 64-bit Linux:
  • for 32-bit Linux:

Download this file, then extract it to the location you prefer, for example:

The toolchain will be extracted into ~/esp/xtensa-esp32-elf/ directory.

To use it, you will need to update your PATH environment variable in ~/.bash_profile file. To make xtensa-esp32-elfavailable for all terminal sessions, add the following line to your ~/.bash_profile file:

Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ~/.bash_profile file:

Then when you need the toolchain you can type get_esp32 on the command line and the toolchain will be added to your PATH.

Alternative Step 1: Compile the toolchain from source using crosstool-NG

Instead of downloading binary toolchain from Espressif website (Step 1 above) you may build the toolchain yourself.

If you can’t think of a reason why you need to build it yourself, then probably it’s better to stick with the binary version. However, here are some of the reasons why you might want to compile it from source:

  • if you want to customize toolchain build configuration
  • if you want to hack gcc or newlib or libstdc++
  • if you are curious and/or have time to spare
  • if you don’t trust binaries downloaded from the Internet

In any case, here are the steps to compile the toolchain yourself.

  • Install dependencies:
    • Ubuntu:
    • Debian:
    • Arch:

Download crosstool-NG and build it:

Build the toolchain:

Toolchain will be built in ~/esp/crosstool-NG/builds/xtensa-esp32-elf. Follow instructions given in the previous section to add the toolchain to your PATH.

Step 2: Getting ESP-IDF from github

Open terminal, navigate to the directory you want to clone ESP-IDF and clone it using git clone command:

ESP-IDF will be downloaded into ~/esp/esp-idf.

Note the --recursive option! If you have already cloned ESP-IDF without this option, run another command to get all the submodules:

IMPORTANT: The esp-idf build system does not support spaces in paths to esp-idf or to projects.

Step 3: Starting a project

ESP-IDF by itself does not build a binary to run on the ESP32. The binary “app” comes from a project in a different directory. Multiple projects can share the same ESP-IDF directory.

The easiest way to start a project is to download the template project from GitHub:

This will download esp-idf-template project into ~/esp/myapp directory.

Step 4: Building and flashing the application

In terminal, go to the application directory which was obtained on the previous step:

Type a command like this to set the path to ESP-IDF directory:

At this point you may configure the serial port to be used for uploading. Run:

Then navigate to “Serial flasher config” submenu and change value of “Default serial port” to match the serial port you will use. Also take a moment to explore other options which are configurable in menuconfig.

Special note for Arch Linux users: navigate to “SDK tool configuration” and change the name of “Python 2 interpreter” from python to python2.

Now you can build and flash the application. Run:

This will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries, and flash these binaries to your development board.

Further reading

If you’d like to use the Eclipse IDE instead of running make, check out the Eclipse setup guide in this directory.

Set up of Toolchain for Mac OS

Step 0: Prerequisites

Getting MacPorts or homebrew

Whether you compile the toolchain from source or download binary toolchain, there are some dependencies which need to be installed on macOS first. These dependencies are installed with one of the package managers: homebrew or MacPorts. If you have these already, you can skip the following instructions.

  • Install XCode from Mac App Store
  • Open Terminal.app and run xcode-select --install
  • Run sudo xcodebuild -license and agree to XCode license
  • Install MacPorts or homebrew

Step 1: Download binary toolchain for the ESP32

ESP32 toolchain for macOS is available for download from Espressif website:

https://dl.espressif.com/dl/xtensa-esp32-elf-osx-1.22.0-59.tar.gz

Download this file, then extract it to the location you prefer, for example:

The toolchain will be extracted into ~/esp/xtensa-esp32-elf/ directory.

To use it, you will need to update your PATH environment variable in ~/.profile file. To make xtensa-esp32-elf available for all terminal sessions, add the following line to your ~/.profile file:

Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ~/.profile file:

Then when you need the toolchain you can type get_esp32 on the command line and the toolchain will be added to your PATH.

Alternative Step 1: Compile the toolchain from source using crosstool-NG

Instead of downloading binary toolchain from Espressif website (Step 1 above) you may build the toolchain yourself.

If you can’t think of a reason why you need to build it yourself, then probably it’s better to stick with the binary version. However, here are some of the reasons why you might want to compile it from source:

  • if you want to customize toolchain build configuration
  • if you want to hack gcc or newlib or libstdc++
  • if you are curious and/or have time to spare
  • if you don’t trust binaries downloaded from the Internet

In any case, here are the steps to compile the toolchain yourself.

  • Install dependencies:
    • with MacPorts:
    • with homebrew (TODO: provide list of packages for homebrew)

Create a case-sensitive filesystem image:

Mount it:

Create a symlink to your work directory:

Download crosstool-NG and build it:

Build the toolchain:

Toolchain will be built in ~/esp/crosstool-NG/builds/xtensa-esp32-elf. Follow instructions given in the previous section to add the toolchain to your PATH.

Step 2: Getting ESP-IDF from github

Open Terminal.app, navigate to the directory you want to clone ESP-IDF and clone it using git clone command:

ESP-IDF will be downloaded into ~/esp/esp-idf.

Note the --recursive option! If you have already cloned ESP-IDF without this option, run another command to get all the submodules:

Step 3: Starting a project

ESP-IDF by itself does not build a binary to run on the ESP32. The binary “app” comes from a project in a different directory. Multiple projects can share the same ESP-IDF directory.

The easiest way to start a project is to download the template project from GitHub:

This will download esp-idf-template project into ~/esp/myapp directory.

IMPORTANT: The esp-idf build system does not support spaces in paths to esp-idf or to projects.

Step 4: Building and flashing the application

In Terminal.app, go to the application directory which was obtained on the previous step:

Type a command like this to set the path to ESP-IDF directory:

At this point you may configure the serial port to be used for uploading. Run:

Then navigate to “Serial flasher config” submenu and change value of “Default serial port” to match the serial port you will use. Also take a moment to explore other options which are configurable in menuconfig.

If you don’t know device name for the serial port of your development board, run this command two times, first with the board unplugged, then with the board plugged in. The port which appears the second time is the one you need:

Now you can build and flash the application. Run:

This will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries, and flash these binaries to your development board.

Further reading

If you’d like to use the Eclipse IDE instead of running make, check out the Eclipse setup guide in this directory.

Download ESP32 toolchain voor Windows @ GitHub
Download ESP32 toolchain voor Linux @ GitHub
Download ESP32 toolchain voor MACOS @ GitHub

[#/esp/software/toolchain/xtensa-esp32″ ]