Getting Started Guide
Follow this guide to get a quick start with Zephyr development where
Set up a command-line development environment for Linux* (Ubuntu),
macOS, or Windows, with required package manager, compiler, and
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:
This guide covers Ubuntu version 18.04 LTS and later. See
Install Linux Host Dependencies for information about other Linux
distributions and older versions of Ubuntu.
Use these commands to bring your Ubuntu system up to date:
sudo apt update
sudo apt upgrade
On macOS Mojave or later, 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.
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
We’ll also install Zephyr’s multi-purpose west tool.
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 g++-multilib libsdl2-dev
Verify the version of cmake installed on your system using:
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.
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 -
Add the kitware repo corresponding to the Ubuntu 18.04 LTS release:
sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ bionic main'
Then install the updated cmake using the usual apt commands:
sudo apt update
sudo apt install cmake
pip3 install --user -U west
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
--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 install cmake ninja gperf ccache dfu-util qemu dtc python3
These instructions assume you are using the Windows
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
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..
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
directory using west:
west init zephyrproject
west init zephyrproject
west init zephyrproject
Install needed Python packages
The Zephyr source folders we downloaded contain a
that we’ll use to install additional Python tools used by the Zephyr
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
Build the Blinky Application
The sample Blinky sample 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.
This sample is compatible with most boards supported by
Zephyr, but not all of them. See the blinky sample requirements for more information. If this sample is not
compatible with your board, a good alternative to try is the
Hello World sample.
Set build environment variables:
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:
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.
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
Now that you’ve got the blinky sample running, here are some next steps
for exploring Zephyr: