There are three steps to creating a Zephyr RTOS project on your chosen microcontroller:

  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 Mac OSX, this is as simple as navigating to System Preferences from the Apple menu and selecting Software Update. This guide was created using Catalina 10.15.2, 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 Homebrew to install and manage all the command line software you'll use. If you don’t have Homebrew, you can get it by opening your Terminal in your Applications folder and running the following: 

Download: file
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Once you have Homebrew, you can install software by using the brew command. Install the following Zephyr prerequisites by running:

Download: file
brew install cmake ninja gperf ccache dfu-util qemu dtc python3

When installing like this, it’s possible you may run into some things you’ve installed already, which is usually ok. If you need to double check the version of a program, you can often do it by running the --version option after it, such as python3 --version. You can also see all the programs you have installed by running brew list

Python Virtual Environments and West

Zephyr also has a lot of Python3 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 ~/.bash_profile on MacOSX. If it doesn’t exist already, create it with sudo nano ~/.bash_profile and paste in the following after any existing contents:

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

Then, run:

Download: file
source ~/.bash_profile

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. If it’s different from /usr/local/bin/python3, change that section to whatever which python3 showed you. It's also possible that virtualenvwrapper might need it's location changed as well if the python3 location is different - it'll usually be in the same *bin/ location as python3. 

Note that the location of your python3 installation can be VERY different than what's listed here. This isn't a big deal! There are a lot of ways python3 can get installed, including Homebrew, pre-included mac OSX versions, and versions installed by IDEs and other applications, and they can all put the link in different spots. Your personal bash settings, if you have any, may also impact the location of programs. But as long as you correctly change the environment variables, the specific location shouldn't matter.

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! Anytime you log on or restart your computer, you can return to it by running workon zephyenv again. It only has Python3  installed, so you don’t even have to worry about that pesky default 2.7 install on MacOSX anymore, 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
One of the python prerequisites, hidapi, requires XCode to be installed on Mac OSX. Sadly, it’s not optional. You can install Xcode on the Apple Store for free - note that it also can take quite a while to download.

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, but that isn’t available on Mac yet, so there’s some extra steps. First, get the latest version of the ARM Toolchain, which allows you to compile and link applications like those made in Zephyr. You can download it with Brew by using the following (note the cask):

Download: file
brew cask install gcc-arm-embedded

You’ll now have a host of ARM Toolchain tools installed, which all start with the prefix arm-none-eabi-*. Before Zephyr can use them, however, you need to add a few more lines to the end of our ~/.bash_profile file:

Download: file
#zephyr build vars
export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
export GNUARMEMB_TOOLCHAIN_PATH=/usr/local/

Similarly to the virtual environment setup, you can double check that the GNUARMEMB_TOOLCHAIN_PATH is correct by running which arm-none-eabi-gdb. Just like python3, the location of this can vary based on your system settings - if it shows somewhere other than /usr/local/, make sure to use the new location. When you’re done, run:

Download: file
source ~/.bash_profile

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 (OSX)) was last updated on Sep 20, 2020.