The latest development version of this page may be more current than this released 2.1.0 version.

Getting Started Guide¶

Follow this guide to get a quick start with Zephyr development where you’ll:

Set up a command-line development environment for Linux* (Ubuntu), macOS, or Windows, with required package manager, compiler, and build-system tools,
Get the sources,
Build, flash, and run a sample application on your target board.

*Instructions for other Linux distributions are discussed in the advanced Linux setup document.

Select and Update OS¶

Zephyr development depends on an up-to-date host system and common build system tools. First, make sure your development system OS is updated:

Use these commands to bring your Linux (Ubuntu) system up to date. If you’re using a different Linux distribution, use the appropriate package manager for your OS. (See Install Linux Host Dependencies for more information about other Linux distributions.)

sudo apt update
sudo apt upgrade

On macOS Mojave, you can manually check for updates by choosing System Preferences from the Apple menu, then clicking Software Update (and click Update Now if there are). For other macOS versions, see the Update macOS topic in Apple support.

On Windows, you can manually check for updates by selecting Start > Settings > Update & Security > Windows Update, and then select Check for updates. If updates are available, install them.

Install dependencies¶

Next, use a package manager to install required support tools. Python 3 and its package manager, pip, are used extensively by Zephyr for installing and running scripts used to compile, build, and run Zephyr applications.

We’ll also install Zephyr’s multi-purpose west tool.

Use the apt package manager to install these tools:

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

Verify the version of cmake installed on your system using:
```
cmake --version
```
If it’s not version 3.13.1 or higher, follow these steps to add the kitware third-party apt repository to get an updated version of cmake.
1. Add the kitware signing key to apt:
```
wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | sudo apt-key add -
```
2. Add the kitware repo corresponding to your Ubuntu LTS release (use cat /etc/os-release to check):
  
  For Ubuntu Bionic Beaver (18.04) use:
```
sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ bionic main'
```
  For Ubuntu Xenial Xerus (16.04) use:
```
sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ xenial main'
```
3. Then install the updated cmake using the usual apt commands:
```
sudo apt update
sudo apt install cmake
```
Install west:
```
pip3 install --user -U west
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc
```
The pip3 --user option puts installed Python packages into your ~/.local/bin folder so we’ll need to add this to the PATH so these packages will be found. Adding the PATH specification to your .bashrc file ensures this setting is permanent.

On macOS, install Homebrew by following instructions on the Homebrew site, and as shown here. Homebrew is a free and open-source package management system that simplifies installing software on macOS. While installing Homebrew, you may be prompted to install additional missing dependencies; please follow any such instructions as well.
```
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
```

Then, install these host dependencies with the brew command:

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

Install west:
```
pip3 install west
```

Note

Currently, the built-in Windows Subsystem for Linux (WSL) doesn’t support flashing your application to the board. As such, we don’t recommend using WSL yet.

These instructions assume you are using the Windows cmd.exe command prompt. Some of the details, such as setting environment variables, may differ if you are using PowerShell.

An easy way to install native Windows dependencies is to first install Chocolatey, a package manager for Windows. If you prefer to install dependencies manually, you can also download the required programs from their respective websites and verify they can be found on your PATH.

Install Chocolatey by following the instructions on the Chocolatey install page.
Open a command prompt (cmd.exe) as an Administrator (press the Windows key, type “cmd.exe” in the prompt, then right-click the result and choose “Run as Administrator”).
Disable global confirmation to avoid having to confirm installation of individual programs:
```
choco feature enable -n allowGlobalConfirmation
```

Install CMake:

choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'

Install the rest of the tools:

choco install git python ninja dtc-msys2 gperf

Close the Administrator command prompt window and open a regular command prompt window to continue..
Install west:
```
pip3 install west
```

Get the source code¶

Zephyr’s multi-purpose west tool simplifies getting the Zephyr project git repositories and external modules used by Zephyr. Clone all of Zephyr’s git repositories in a new zephyrproject directory using west:

cd ~
west init zephyrproject
cd zephyrproject
west update

cd ~
west init zephyrproject
cd zephyrproject
west update

cd %HOMEPATH%
west init zephyrproject
cd zephyrproject
west update

Install needed Python packages¶

The Zephyr source folders we downloaded contain a requirements.txt file that we’ll use to install additional Python tools used by the Zephyr project:

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

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

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

Install Software Development Toolchain¶

A toolchain includes necessary tools used to build Zephyr applications including: compiler, assembler, linker, and their dependencies.

Zephyr’s Software Development Kit (SDK) contains necessary Linux development tools to build Zephyr on all supported architectures. Additionally, it includes host tools such as custom QEMU binaries and a host compiler.

Download the latest SDK as a self-extracting installation binary:

cd ~
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.10.3/zephyr-sdk-0.10.3-setup.run

Run the installation binary, installing the SDK in your home folder ~/zephyr-sdk-0.10.3:

chmod +x zephyr-sdk-0.10.3-setup.run
./zephyr-sdk-0.10.3-setup.run -- -d ~/zephyr-sdk-0.10.3

Set environment variables to let the build system know where to find the toolchain programs:

export ZEPHYR_TOOLCHAIN_VARIANT=zephyr
export ZEPHYR_SDK_INSTALL_DIR=~/zephyr-sdk-0.10.3

The SDK contains a udev rules file that provides information needed to identify boards and grant hardware access permission to flash tools. Install these udev rules with these commands:

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

#. The Zephyr SDK is not supported on macOS. See instructions for installing 3rd-party toolchains.

Do not forget to set environment variables (ZEPHYR_TOOLCHAIN_VARIANT and toolchain specific ones) to let the build system know where to find the toolchain programs.

#. The Zephyr SDK is not supported on Windows. See instructions for installing 3rd-party toolchains.

Do not forget to set environment variables (ZEPHYR_TOOLCHAIN_VARIANT and toolchain specific ones) to let the build system know where to find the toolchain programs.

Build the Blinky Application¶

The sample Blinky Application blinks an LED on the target board. By building and running it, we can verify that the environment and tools are properly set up for Zephyr development.

Set build environment variables:

cd ~/zephyrproject/zephyr
source zephyr-env.sh

cd ~/zephyrproject/zephyr
source zephyr-env.sh

cd %HOMEPATH%/zephyrproject/zephyr
zephyr-env.cmd

Build the blinky sample. Specify your board name (see Supported Boards) in the command below:
```
west build -p auto -b <your-board-name> samples/basic/blinky
```
This west command uses the -p auto parameter to automatically clean out any byproducts from a previous build if needed, useful if you try building another sample.

Flash and Run the Application¶

Connect a USB cable between the board and your development computer. (Refer to the specific Supported Boards documentation if you’re not sure which connector to use on the board.)
If there’s a switch, turn the board on.
Flash the blinky application you just built using the command:
Ubuntu

macOS

Windows
west flash
If the flash command fails, and you’ve checked your board is powered on and connected to the right on-board USB connector, verify you’ve granted needed access permission by Setting udev rules.
west flash
west flash

The application will start running and you’ll see blinky in action. The actual blinking LED location is board specific.

Phytec reel_board running blinky¶

Next Steps¶

Now that you’ve got the blinky sample running, here are some next steps for exploring Zephyr:

Try some other Samples and Demos that demonstrate Zephyr capabilities.
Learn about Application Development and more details about West (Zephyr’s meta-tool).
Check out Beyond the Getting Started Guide for information about advanced setup alternatives and issues.
Discover Resources for getting help from the Zephyr community.