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: 

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

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: 

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:

Then, run:

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. 

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:

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:

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

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:

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

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:

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:

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

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.