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:
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.
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
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 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'
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 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:
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: