Zephyr RTOS on ESP32

Written by Glauber Ferreira, Embedded Software Engineer

The blog originally ran on The ESP Journal Medium site. For more content like this, click here.

Zephyr is a very low footprint RTOS maintained by the Linux Foundation and ported to several architectures. This RTOS has been gaining massive support from many silicon manufacturers and an ever-growing list of contributors on its mainline.

Espressif has been expanding support for Zephyr RTOS on ESP32, an extremely popular SoC among hobbyists but also widely used in commercial applications. Since its release, this SoC became famous for integrating both Wifi and Bluetooth stacks on a single chip and for being very cost-competitive. In this post, all the required steps to prepare your host’s environment to use Zephyr on ESP32 will be explained. In the end, we will run a hello world application to validate our setup. In this step-by-step guide, the ESP32 DevKitC board will be used.

The first thing to do is to prepare Zephyr’s development environment. I briefly list the steps required for Linux (Ubuntu 20.04.1 LTS), for the most up-to-date documentation, and for support for other Operating Systems you can see Zephyr’s official Getting Started guide and, specifically, you can see most of the original instructions included in this post in the ESP32 SoC section of the Zephyr Project documentation.

Updating Linux

Before we start, update your repositories list.

sudo apt update
sudo apt upgrade

Installing dependencies

Run apt to install dependencies:

sudo apt install --no-install-recommends git cmake \
ninja-build gperf ccache dfu-util device-tree-compiler wget \
python3-dev python3-pip python3-setuptools python3-tk \
python3-wheel xz-utils file make gcc gcc-multilib \
g++-multilib libsdl2-dev

Check the CMake version on your host.

cmake --version

If the version displayed is 3.13.1 or above then skip to the next section. Otherwise, follow these three steps to update CMake:

Add the Kitware signing key:

wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | sudo apt-key add -

Add the Kitware apt repository for your OS release. For Ubuntu 20.04 LTS:

sudo apt-add-repository \
'deb https://apt.kitware.com/ubuntu/ focal main'

Reinstall CMake

sudo apt update
sudo apt install cmake

Getting Zephyr and installing Python dependencies

Install west and ensure that ~/.local/bin is part of your PATH environment variable:

pip3 install -- user -U west
echo ‘export PATH=~/.local/bin:”$PATH”’ >> ~/.bashrc
source ~/.bashrc

Here is a worthy observation: west is the tool that manages the entire life-cycle of a Zephyr-based project. This is made clearer below. Now, get Zephyr’s source code:

west init ~/zephyrproject
cd ~/zephyrproject
west update
west espressif update

Be patient, these last commands will fetch Zephyr’s repository and all the HALs (including ESP32’s) already ported to this RTOS. Note that we do not explicitly call a git command to clone the repositories, west takes care of everything. Now, export a Zephyr CMake package. This causes CMake to automatically load some boilerplate code.

west zephyr-export

Zephyr’s requirements.txt file declares additional Python dependencies. Install them through pip3.

pip3 install --user -r \
~/zephyrproject/zephyr/scripts/requirements.txt

Installing Zephyr’s toolchain

Zephyr’s SDK adds several additional tools for the host. Download the SDK installer:

cd ~
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.12.2/zephyr-sdk-0.12.2-x86_64-linux-setup.run

Run the installer, this will install the SDK under the ~/zephyr-sdk-0.12.2 folder.

chmod +x zephyr-sdk-0.12.2-x86_64-linux-setup.run
./zephyr-sdk-0.12.2-x86_64-linux-setup.run -- -d ~/zephyr-sdk-0.12.2

This is one of the default locations recommended for SDK installation, for other locations check Zephyr’s official documentation.

Adding ESP32 toolchain to the project

Before building, we need to tell Zephyr where to find the toolchain for ESP32’s Xtensa architecture. Open your terminal, and type the following commands:

export ZEPHYR_TOOLCHAIN_VARIANT="espressif"
export ESPRESSIF_TOOLCHAIN_PATH="${HOME}/.espressif/tools/xtensa-esp32-elf/esp-2020r3-8.4.0/xtensa-esp32-elf"
export PATH=$PATH:$ESPRESSIF_TOOLCHAIN_PATH/bin

Alternatively, you can add the above commands to your ~/.bashrc configuration file, making those variables available at any time on your current working session. Finally, install the toolchain:

cd ~/zephyrproject
west espressif install

Building the application

Remember I mentioned west takes part in all stages of a Zephyr’s project life-cycle? Well, we’ll see it in action here again. Build the hello_world project for the ESP32 board from the sample code folder.

cd ~/zephyrproject/zephyr/samples/hello_world
west build -p auto -b esp32

If the previous build fails with a message indicating missing Python packages, your OS likely uses python2.x by default. If so, make python3 its preferred choice by running the following:

sudo update-alternatives --install \
/usr/bin/python python /usr/bin/python3 10 && alias pip=pip3

Then, run the build command again.

We will need a serial program utility to see the logs, use the one of your preference. Here I use minicom.

sudo apt install minicom

To open minicom’s serial settings, type this command:

sudo minicom -s

After minicom is opened, chose the serial port setup option and set it to 115200 8N1.

Flashing the binary

Flashing the binary is quite simple, just do the following:

west flash; minicom

In older ESP32 DevKitC boards, the chip may run to standby mode until the BOOT button is pressed, which triggers the flashing action. Newer boards start flashing immediately.

If you have been following everything up to this point, after some ESP32’s boot messages, you should see the expected hello message.

There you have it! Your development environment was properly configured and you have run your first application using Zephyr on ESP32!

Supported Features

ESP32 support for Zephyr is growing. By the time I am writing this post, it includes basic peripherals such as:

• UART
• I2C
• GPIO
• SPI Master
• Timers

WiFi native driver support for ESP32 is also coming to Zephyr’s upstream, you can check it by clicking on its PR link. Additionally, please follow here for overall future road-map for ESP32 support.

Summary

In this post, we saw how to set the environment for Zephyr RTOS and how to build a sample project for an ESP32 based board. The whole process has been greatly simplified since Xtensa’s toolchain installation has been incorporated into the west tool commands.

Stay tuned to Zephyr’s documentation and repository for the most recent supported peripherals. Espressif Team keeps actively working on porting and supporting its SoCs on Zephyr.