There are three steps to creating a Zephyr RTOS project on a Linux computer:

  1. Setting up your development environment (installing prerequisite programs, obtaining python scripts, setting environment variables, etc)
  2. Cloning the Zephyr RTOS source code with the Zephyr multi-purpose tool, West. 
  3. Creating your own application linked to the Zephyr source, which you can compile and upload to your board. 

This page will focus on installing all of the scripts and prerequisites you need, along with some other setup tasks that are usually specific to your host computer. This section is broadly similar (with some added suggestions) to the official Zephyr startup guide, which you can also check out for more information. 

Installing Dependencies

The first thing you’ll want to do, before installing anything, is to ensure your system is up to date: for Linux, this is handled with the standard terminal commands sudo apt update and sudo apt upgrade. This guide was created using Ubuntu 18.04 LTS, though most version differences should hopefully be handled by the package managers you’ll be using. 

Once you’re up to date, you can use the apt manager to download the prerequisites you need:

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

This may skip over some installations if you already have them. Once it is complete, double check that you have the correct version of cmake installed: 

Download: file
cmake --version

If it is not 3.13.1 or above, you'll need to take extra steps to add the Kitware apt repository, so that you can obtain the correct version of cmake. Run the following commands to add the kitware key and repository to apt, and then download the correct cmake version. 

Download: file
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/ bionic main'
sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ bionic main'
sudo apt update
sudo apt install cmake

Python Virtual Environments and West

Zephyr also has a lot of Python 3 dependencies you will need to install using the pip3 package manager. However, I’m going to diverge from the official guide here and strongly suggest you use a python virtual environment before doing any installations with pip. Often, when doing the installations for different projects, you’ll find that one project has a conflicting version requirement with another - a virtual environment system allows you to set up a fresh “virtual” Python installation any time you want, letting you install the right versions of all your prerequisites specifically for that project. It’s a good idea for any developer, and is particularly useful for projects with a huge list of python requirements like Zephyr. 

There are a number of virtual environment managers, but I recommend virtualenv and virtualenvwrapper for simplicity. Install them now by running: 

Download: file
sudo pip3 install virtualenv virtualenvwrapper

You then need to add the following text to your ~/.bashrc on Ubuntu. If it doesn’t exist already, create it with sudo nano ~/.bashrc and paste in the following after any existing contents:

Download: file
# virtualenv and virtualenvwrapper
export WORKON_HOME=$HOME/.virtualenvs
export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3
source /usr/local/bin/virtualenvwrapper.sh

Then, run:

Download: file
source ~/.bashrc

This should display some setup information. If you run into any errors, make sure the location of your python executable is correct by using which python3, which will show you the path to your default Python version. If it’s different from /usr/bin/python3, change that section to whatever which python3 showed you. 

Now, you should have virtualenv installed! Some of the commands available to you are:

  • Create with mkvirtualenv
  • Activate with workon
  • Deactivate with deactivate
  • Remove with rmvirtualenv

For now, make a new virtual environment for your Zephyr installs and move to it by using:

Download: file
mkvirtualenv zephyenv
workon zephyenv

You’re now in a pristine new virtual environment for Python! Any time you log on or restart your computer, you can return to it by running workon zephyenv again. It only has Python 3 installed, so you don’t have to worry about any other versions of Python you may have, you can use python and pip directly and it’ll use the Python 3 versions automatically.

Now that that’s over with, you can install the Zepyhr multi-purpose tool, West, which will help you download the Zephyr RTOS code and wrap up all your other Python requirements. Get it by running:

Download: file
pip install west

Getting the source code and adding packages

Now that you have West installed, you’ll be using it to download the Zephyr RTOS source code into a new directory in your home folder called zephyrproject/:

Download: file
cd ~
west init zephyrproject
cd zephyrproject
west update
Note that the zephyrproject/ folder is NOT your application folder - it isn’t where you’re going to put main.c or any of the specific libraries for your application. It’s the Zephyr source code, which we’ll be linking into new, totally separate application folders that we make later. ZephyrProject refers to the The Zephyr Project™, not your project!

Make sure you give yourself some time to do this. west update clones all of the various software libraries and repositories for a big collection of chips - depending on your internet speed, it could take up to an hour. 

Once that’s done, you’ll install the latest python requirements for Zephyr (make sure you’re working on the virtualenv you set up before!). From inside the zephyrproject/ directory, run:

Download: file
pip install -r zephyr/scripts/requirements.txt

This should show a new, long list of Python modules being installed on your virtual environment.

Installing the Development Toolchain

Now we need the proper build tools! On Linux this is handled automatically via the Zephyr SDK, which has a number of features not available on other operating systems. Download it as a self-extracting binary:

Download: file
cd ~
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.11.1/zephyr-sdk-0.11.1-setup.run

Enter the following commands to run the installation binary, add the SDK to your home folder, and set some udev rules required for flashing hardware:

Download: file
chmod +x zephyr-sdk-0.11.1-setup.run
./zephyr-sdk-0.11.1-setup.run -- -d ~/zephyr-sdk-0.11.1
sudo cp ${ZEPHYR_SDK_INSTALL_DIR}/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d
sudo udevadm control --reload

You'll also want to add some environmental variables to your ~/.bashrc file to tell West where to find the SDK, so you don't need to remember to set them every time you turn on your computer. Add the following lines to your ~/.bashrc file, after the lines we added earlier for the virtualenv:

Download: file
#zephyr build vars
export ZEPHYR_TOOLCHAIN_VARIANT=zephyr
export ZEPHYR_SDK_INSTALL_DIR=~/zephyr-sdk-0.11.1

Add the variables to this session by running:

Download: file
source ~/.bashrc

You can now double check that the environmental variables were set properly by running:

Download: file
echo $ZEPHYR_TOOLCHAIN_VARIANT

Once those variables match up, you’re all done with the installation process! It’s always a lot of work getting a multi-stage development environment like this running, but thankfully you usually only have to do it once. To test your new Zephyr setup, you can use the next section: building a sample program directly out of the Zephyr Project directory using West.

This guide was first published on Feb 25, 2020. It was last updated on Feb 25, 2020.
This page (Installing Zephyr (Linux)) was last updated on Sep 20, 2020.