Skip to main content

Set up Zephyr for ESP32

Golioth can be added to a device with Device SDKs which are based on different embedded Operating Systems. Currently Golioth targets the Zephyr Project and builds upon the APIs & tools of Zephyr. As such, prior experience with Zephyr will be helpful when working with Golioth's Zephyr Device SDK. Refer to Zephyr's detailed documentation when running into issues.

Install West

west is the Zephyr "meta tool" that will allow you to build firmware, install packages, and flash firmware. There are various dependencies required, depending upon your operating system (OS), because west is Python based.

Choose your OS from the tabs below

Install dependencies with apt:

sudo apt update
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

West requires CMake version 3.20.0 or higher. Check the version that your package manager installed:

$ cmake --version
cmake version 3.16.3

If you have an older version, Ubuntu 20.04 systems can add the Kitware repository which maintains the newest release:

wget -O - 2>/dev/null | sudo apt-key add -
sudo apt-add-repository 'deb focal main'
sudo apt update
sudo apt install cmake
cmake --version

If the Kitware repository doesn't work for you (ie: your system is not running Ubuntu 20.04), you can build the stable version of CMake from source.

While the official documentation for Zephyr suggests jumping right into installing west, we suggest creating a python3 virtual environment first, to avoid running into tooling incompatibilities.

Use pip3 to install west (beginning with the wheel dependency):

pip3 install wheel
pip3 install west

Install Golioth Zephyr SDK

With west installed, grab the Zephyr SDK:


Depending on your internet and I/O speed, west update can take upwards of 5 or 10 minutes.

cd ~
west init -m --mf west-zephyr.yml ~/golioth-zephyr-workspace
cd golioth-zephyr-workspace
west update

Tell west to automatically configure CMake:

west zephyr-export

Install the remaining dependencies:

pip install -r ~/golioth-zephyr-workspace/zephyr/scripts/requirements.txt

Installing the Zephyr SDK Toolchain

Download the latest SDK installer:

cd ~

Unpack the archive and run the installer. The SDK will be placed in the ~/zephyr-sdk-0.14.2 directory:

tar -xvf zephyr-sdk-0.14.2_linux-x86_64.tar.gz
cd zephyr-sdk-0.14.2

Answer y to both of the questions asked during the setup process.

Install udev rules, which allow you to flash most Zephyr boards as a regular user:

sudo cp ~/zephyr-sdk-0.14.2/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d/
sudo udevadm control --reload

Install the Espressif (ESP32) submodules

west makes it easy to install Espressif submodules and OpenOCD configurations:

west espressif update
west espressif install

Older versions of the Zephyr SDK Toolchain (prior to 0.14.2) installed the compiler tools using west espressif install and required manually setting environmental variables as follows:

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

Now, compiler tools are included in the Zephyr SDK. Manually setting these environmental variables is deprecated and this step is no longer needed. We included this message to help inform users about the changes.

Sample build

Your system is all set up and ready to start building & flashing with Zephyr. Verify by building a minimal sample:

cd ~/golioth-zephyr-workspace/zephyr
west build -b esp32 samples/basic/minimal -p