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

Linux

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 - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | sudo apt-key add -
sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ 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.

Install within a virtualenv

Create a new version environment:

Even though we haven't pulled down Zephyr yet, we can create the virtual environment in the place where we will pull down Zephyr.

python3 -m venv ~/golioth-zephyr-workspace/.venv

Activate the virtual environment:

source ~/golioth-zephyr-workspace/.venv/bin/activate
# OR, if you're using the fish shell, run
source ~/golioth-zephyr-workspace/.venv/bin/activate.fish

Whenever the virtual environment is active, your shell's prompt will be prefixed with (.venv).

Deactivate the virtual environment when you're done by running deactivate.

note

Anytime you need to use west or Zephyr, remember to re-activate the virtual environment.

Now, use pip to install west (beginning with the wheel dependency):

Because we're in a python3 virtualenv, we don't need to specify pip3 and can just use pip (because virtual env knows the best version to use)

pip install wheel
pip install west

Install globally

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

pip3 install wheel
pip3 install west

MacOS

Start by installing dependencies with brew:

brew install cmake ninja gperf python3 ccache qemu dtc

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.

Install within a virtualenv

Create a new version environment:

Even though we haven't pulled down Zephyr yet, we can create the virtual environment in the place where we will pull down Zephyr.

python3 -m venv ~/golioth-zephyr-workspace/.venv

Activate the virtual environment:

source ~/golioth-zephyr-workspace/.venv/bin/activate
# OR, if you're using the fish shell, run
source ~/golioth-zephyr-workspace/.venv/bin/activate.fish

Whenever the virtual environment is active, your shell's prompt will be prefixed with (.venv).

Deactivate the virtual environment when you're done by running deactivate.

note

Anytime you need to use west or Zephyr, remember to re-activate the virtual environment.

Now, use pip to install west (beginning with the wheel dependency):

Because we're in a python3 virtualenv, we don't need to specify pip3 and can just use pip (because virtual env knows the best version to use)

pip install wheel
pip install west

Install globally

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

pip3 install wheel
pip3 install west

Windows

Install Dependencies

Python3

1. Open the command line by hitting the Windows key, typing cmd.exe and pressing enter.
2. Type python3
3. If python3 is installed, the interpreter will open and display the version. Type exit() to exit.
4. If python3 is not installed, the Windows Store will automatically open and offer to install it.
   • Test it: Go back to to the command line, type python3 to launch then interpreter, exit() to exit.
   • Alternatively you can download Python3 directly and install it manually.

Package Manager: Chocolatey

The chocolatey package manager needs to be installed to fetch software packages required by Zephyr.

1. Open the command line as an Administrator:

   1. Press the windows key and type cmd.exe (do not press enter)
   2. Use the mouse to click on "Run as administrator"

2. Run Powershell and install Chocolately:

   powershell.exe

   > Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
   > exit

   This command may take a few minutes to complete.

3. Disable global confirmation and use choco to install remaining dependencies:

   choco feature enable -n allowGlobalConfirmation
   choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'
   choco install ninja gperf python git dtc-msys2 wget unzip

4. Type exit to close the console window, we no longer need administrator privileges.

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.

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.

Install within a virtualenv

1. Create a new virtual environment:

   cd c:\
   python3 -m venv golioth-zephyr-workspace\.venv

2. Activate the virtual environment:

   :: cmd.exe
   golioth-zephyr-workspace\.venv\Scripts\activate.bat
   :: PowerShell
   golioth-zephyr-workspace\.venv\Scripts\Activate.ps1

   Once activated your shell will be prefixed with (.venv). The virtual environment can be deactivated at any time by running deactivate.

   note

   Remember to activate the virtual environment whenever you need to use the west command.

3. Install west:

   Now, use pip to install west. Because we're in a python3 virtualenv, we don't need to specify pip3 and can just use pip (because virtual env knows the best version to use)

   pip install west

Install globally

1. Use pip3 to install west:

   pip3 install -U west

Install Golioth Zephyr SDK

Linux

With west installed, grab the Zephyr SDK:

info

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

cd ~
west init -m https://github.com/golioth/golioth-zephyr-sdk.git --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:

Install within a virtualenv

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

Install globally

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

MacOS

With west installed, grab the Zephyr SDK:

info

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

cd ~
west init -m https://github.com/golioth/golioth-zephyr-sdk.git --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:

Install within a virtualenv

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

Install globally

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

Windows

1. With west installed, download the Zephyr SDK:

   cd c:\
   west init -m https://github.com/golioth/golioth-zephyr-sdk.git --mf west-zephyr.yml golioth-zephyr-workspace
   cd golioth-zephyr-workspace
   west update

   info

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

2. Tell west to automatically configure CMake:

   west zephyr-export

3. Install the remaining dependencies:

   Install within a virtualenv

   pip install -r C:\golioth-zephyr-workspace\zephyr\scripts\requirements.txt

   Install globally

   pip3 install -r C:\golioth-zephyr-workspace\zephyr\scripts\requirements.txt

Installing the Zephyr SDK Toolchain

Download the latest SDK installer:

Linux

cd ~
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.14.2/zephyr-sdk-0.14.2_linux-x86_64.tar.gz

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
./setup.sh

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

MacOS

cd ~
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.14.2/zephyr-sdk-0.14.2_macos-x86_64.tar.gz

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_macos-x86_64.tar.gz
cd zephyr-sdk-0.14.2
./setup.sh

Windows

Unpack the archive and run the installer. The SDK will be placed in the %HOMEPATH%\zephyr-sdk-0.14.2 directory:

cd %HOMEPATH%
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.14.2/zephyr-sdk-0.14.2_windows-x86_64.zip
unzip zephyr-sdk-0.14.2_windows-x86_64.zip
cd zephyr-sdk-0.14.2
setup.cmd

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

:::

Install the Espressif (ESP32) submodules

Linux

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

west espressif update
west espressif install

caution

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

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.

MacOS

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

west espressif update
west espressif install

caution

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

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.

Windows

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

west espressif update
west espressif install

caution

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:

set ESPRESSIF_TOOLCHAIN_PATH=C:\Users\Mike\.espressif\tools\zephyr
set ZEPHYR_TOOLCHAIN_VARIANT=espressif

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:

Linux

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

MacOS

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

Windows

1. Verify by building a minimal sample:

   cd C:\golioth-zephyr-workspace\zephyr
   west build -b esp32 samples\basic\minimal -p