If you need urgent consulting help click here

Getting Started Guide

Follow this guide to:

  • Set up a command-line Zephyr development environment on Ubuntu, macOS, or Windows (instructions for other Linux distributions are discussed in Install Linux Host Dependencies)

  • Get the source code

  • Build, flash, and run a sample application

Select and Update OS

Click the operating system you are using.

Ubuntu

macOS

Windows

This guide covers Ubuntu version 18.04 LTS and later.

sudo apt update
sudo apt upgrade

On macOS Mojave or later, select System Preferences > Software Update. Click Update Now if necessary.

On other versions, see this Apple support topic.

Select Start > Settings > Update & Security > Windows Update. Click Check for updates and install any that are available.

Install dependencies

Next, you’ll install some host dependencies using your package manager.

The current minimum required version for the main dependencies are:

Tool

Min. Version

CMake

3.20.0

Python

3.6

Devicetree compiler

1.4.6

Ubuntu

macOS

Windows

  1. Download, inspect and execute the Kitware archive script to add the Kitware APT repository to your sources list. A detailed explanation of kitware-archive.sh can be found here kitware third-party apt repository:

    wget https://apt.kitware.com/kitware-archive.sh
sudo bash kitware-archive.sh

  2. Use apt to install the required dependencies:

    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

  3. Verify the versions of the main dependencies installed on your system by entering:

    cmake --version
python3 --version
dtc --version

    Check those against the versions in the table in the beginning of this section. Refer to the Install Linux Host Dependencies page for additional information on updating the dependencies manually.

  1. Install Homebrew:

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  2. Use brew to install the required dependencies:

    brew install cmake ninja gperf python3 ccache qemu dtc wget

Note

Due to issues finding executables, the Zephyr Project doesn’t currently support application flashing using the Windows Subsystem for Linux (WSL) (WSL).

Therefore, we don’t recommend using WSL when getting started.

These instructions must be run in a cmd.exe command prompt. The required commands differ on PowerShell.

These instructions rely on Chocolatey. If Chocolatey isn’t an option, you can install dependencies from their respective websites and ensure the command line tools are on your PATH environment variable.

  1. Install chocolatey.

  2. Open a cmd.exe window as Administrator. To do so, press the Windows key, type “cmd.exe”, right-click the result, and choose Run as Administrator.

  3. Disable global confirmation to avoid having to confirm the installation of individual programs:

    choco feature enable -n allowGlobalConfirmation

  4. Use choco to install the required dependencies:

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

  5. Close the window and open a new cmd.exe window as a regular user to continue.

Get Zephyr and install Python dependencies

Next, clone Zephyr and its modules into a new west workspace named zephyrproject. You’ll also install Zephyr’s additional Python dependencies.

Python is used by the west meta-tool as well as by many scripts invoked by the build system. It is easy to run into package incompatibilities when installing dependencies at a system or user level. This situation can happen, for example, if working on multiple Zephyr versions at the same time. For this reason it is suggested to use Python virtual environments.

Ubuntu

macOS

Windows

Install globally

Install within virtual environment

  1. Install west, and make sure ~/.local/bin is on your PATH environment variable:

    pip3 install --user -U west
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc

  2. Get the Zephyr source code:

    west init ~/zephyrproject
cd ~/zephyrproject
west update

  3. Export a Zephyr CMake package. This allows CMake to automatically load boilerplate code required for building Zephyr applications.

    west zephyr-export

  4. Zephyr’s scripts/requirements.txt file declares additional Python dependencies. Install them with pip3.

    pip3 install --user -r ~/zephyrproject/zephyr/scripts/requirements.txt

  1. Create a new virtual environment:

    python3 -m venv ~/zephyrproject/.venv

  2. Activate the virtual environment:

    source ~/zephyrproject/.venv/bin/activate

    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 every time you start working.

  3. Install west:

    pip install west

  4. Get the Zephyr source code:

    west init ~/zephyrproject
cd ~/zephyrproject
west update

  5. Export a Zephyr CMake package. This allows CMake to automatically load boilerplate code required for building Zephyr applications.

    west zephyr-export

  6. Zephyr’s scripts/requirements.txt file declares additional Python dependencies. Install them with pip.

    pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt

Install globally

Install within virtual environment

  1. Install west:

    pip3 install -U west

  2. Get the Zephyr source code:

    west init ~/zephyrproject
cd ~/zephyrproject
west update

  3. Export a Zephyr CMake package. This allows CMake to automatically load boilerplate code required for building Zephyr applications.

    west zephyr-export

  4. Zephyr’s scripts/requirements.txt file declares additional Python dependencies. Install them with pip3.

    pip3 install -r ~/zephyrproject/zephyr/scripts/requirements.txt

  1. Create a new virtual environment:

    python3 -m venv ~/zephyrproject/.venv

  2. Activate the virtual environment:

    source ~/zephyrproject/.venv/bin/activate

    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 every time you start working.

  3. Install west:

    pip install west

  4. Get the Zephyr source code:

    west init ~/zephyrproject
cd ~/zephyrproject
west update

  5. Export a Zephyr CMake package. This allows CMake to automatically load boilerplate code required for building Zephyr applications.

    west zephyr-export

  6. Zephyr’s scripts/requirements.txt file declares additional Python dependencies. Install them with pip.

    pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt

Install globally

Install within virtual environment

  1. Install west:

    pip3 install -U west

  2. Get the Zephyr source code:

    cd %HOMEPATH%
west init zephyrproject
cd zephyrproject
west update

  3. Export a Zephyr CMake package. This allows CMake to automatically load boilerplate code required for building Zephyr applications.

    west zephyr-export

  4. Zephyr’s scripts\requirements.txt file declares additional Python dependencies. Install them with pip3.

    pip3 install -r %HOMEPATH%\zephyrproject\zephyr\scripts\requirements.txt

  1. Create a new virtual environment:

    cd %HOMEPATH%
python3 -m venv zephyrproject\.venv

  2. Activate the virtual environment:

    :: cmd.exe
zephyrproject\.venv\Scripts\activate.bat
:: PowerShell
zephyrproject\.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 every time you start working.

  3. Install west:

    pip install west

  4. Get the Zephyr source code:

    west init zephyrproject
cd zephyrproject
west update

  5. Export a Zephyr CMake package. This allows CMake to automatically load boilerplate code required for building Zephyr applications.

    west zephyr-export

  6. Zephyr’s scripts\requirements.txt file declares additional Python dependencies. Install them with pip.

    pip install -r %HOMEPATH%\zephyrproject\zephyr\scripts\requirements.txt

Install Zephyr SDK

The Zephyr Software Development Kit (SDK) contains toolchains for each of Zephyr’s supported architectures, which include a compiler, assembler, linker and other programs required to build Zephyr applications.

It also contains additional host tools, such as custom QEMU and OpenOCD builds that are used to emulate, flash and debug Zephyr applications.

Ubuntu

macOS

Windows

  1. Download and verify the latest Zephyr SDK bundle:

    cd ~
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.14.2/zephyr-sdk-0.14.2_linux-x86_64.tar.gz
wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.14.2/sha256.sum | shasum --check --ignore-missing

    If your host architecture is 64-bit ARM (for example, Raspberry Pi), replace x86_64 with aarch64 in order to download the 64-bit ARM Linux SDK.

  2. Extract the Zephyr SDK bundle archive:

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

    Note

    It is recommended to extract the Zephyr SDK bundle at one of the following locations:

    • $HOME

    • $HOME/.local

    • $HOME/.local/opt

    • $HOME/bin

    • /opt

    • /usr/local

    The Zephyr SDK bundle archive contains the zephyr-sdk-0.14.2 directory and, when extracted under $HOME, the resulting installation path will be $HOME/zephyr-sdk-0.14.2.

  3. Run the Zephyr SDK bundle setup script:

    cd zephyr-sdk-0.14.2
./setup.sh

    Note

    You only need to run the setup script once after extracting the Zephyr SDK bundle.

    You must rerun the setup script if you relocate the Zephyr SDK bundle directory after the initial setup.

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

  1. Download and verify the latest Zephyr SDK bundle:

    cd ~
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.14.2/zephyr-sdk-0.14.2_macos-x86_64.tar.gz
wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.14.2/sha256.sum | shasum --check --ignore-missing

    If your host architecture is 64-bit ARM (Apple Silicon, also known as M1), replace x86_64 with aarch64 in order to download the 64-bit ARM macOS SDK.

  2. Extract the Zephyr SDK bundle archive:

    tar xvf zephyr-sdk-0.14.2_macos-x86_64.tar.gz

    Note

    It is recommended to extract the Zephyr SDK bundle at one of the following locations:

    • $HOME

    • $HOME/.local

    • $HOME/.local/opt

    • $HOME/bin

    • /opt

    • /usr/local

    The Zephyr SDK bundle archive contains the zephyr-sdk-0.14.2 directory and, when extracted under $HOME, the resulting installation path will be $HOME/zephyr-sdk-0.14.2.

  3. Run the Zephyr SDK bundle setup script:

    cd zephyr-sdk-0.14.2
./setup.sh

    Note

    You only need to run the setup script once after extracting the Zephyr SDK bundle.

    You must rerun the setup script if you relocate the Zephyr SDK bundle directory after the initial setup.

  1. Open a cmd.exe window by pressing the Windows key typing “cmd.exe”.

  2. Download the latest Zephyr SDK bundle:

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

  3. Extract the Zephyr SDK bundle archive:

    unzip zephyr-sdk-0.14.2_windows-x86_64.zip

    Note

    It is recommended to extract the Zephyr SDK bundle at one of the following locations:

    • %HOMEPATH%

    • %PROGRAMFILES%

    The Zephyr SDK bundle archive contains the zephyr-sdk-0.14.2 directory and, when extracted under %HOMEPATH%, the resulting installation path will be %HOMEPATH%\zephyr-sdk-0.14.2.

  4. Run the Zephyr SDK bundle setup script:

    cd zephyr-sdk-0.14.2
setup.cmd

    Note

    You only need to run the setup script once after extracting the Zephyr SDK bundle.

    You must rerun the setup script if you relocate the Zephyr SDK bundle directory after the initial setup.

Build the Blinky Sample

Note

Blinky is compatible with most, but not all, Supported Boards. If your board does not meet Blinky’s Requirements, then Hello World is a good alternative.

Build the Blinky with west build, changing <your-board-name> appropriately for your board:

Ubuntu

macOS

Windows

cd ~/zephyrproject/zephyr
west build -p auto -b <your-board-name> samples/basic/blinky

cd ~/zephyrproject/zephyr
west build -p auto -b <your-board-name> samples/basic/blinky

cd %HOMEPATH%\zephyrproject\zephyr
west build -p auto -b <your-board-name> samples\basic\blinky

The -p auto option automatically cleans byproducts from a previous build if necessary, which is useful if you try building another sample.

Flash the Sample

Connect your board, usually via USB, and turn it on if there’s a power switch. If in doubt about what to do, check your board’s page in Supported Boards.

Then flash the sample using west flash:

west flash

You may need to install additional host tools required by your board. The west flash command will print an error if any required dependencies are missing.

If you’re using blinky, the LED will start to blink as shown in this figure:

../../_images/ReelBoard-Blinky.png

Fig. 1 Phytec reel_board running blinky

Next Steps

Here are some next steps for exploring Zephyr:

Asking for Help

You can ask for help on a mailing list or on Discord. Please send bug reports and feature requests to GitHub.

How to Ask

Important

Please search this documentation and the mailing list archives first. Your question may have an answer there.

Don’t just say “this isn’t working” or ask “is this working?”. Include as much detail as you can about:

  1. What you want to do

  2. What you tried (commands you typed, etc.)

  3. What happened (output of each command, etc.)

Use Copy/Paste

Please copy/paste text instead of taking a picture or a screenshot of it. Text includes source code, terminal commands, and their output.

Doing this makes it easier for people to help you, and also helps other users search the archives.

When copy/pasting more than 5 lines of text into Discord, create a snippet using three backticks to delimit the snippet.