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.
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.
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
Verify the version of cmake that is installed on your system by entering:
cmake --version
The version must be 3.13.1 or later. If your version is older, complete the following steps to add the Kitware third-party apt repository, which contains an updated version of cmake.
Add the Kitware signing key:
wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | sudo apt-key add -
Add the Kitware apt repository for your OS release. For Ubuntu 18.04 LTS:
sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ bionic main'
Then install the updated version of cmake with
apt
:sudo apt update sudo apt install cmake
Install Homebrew:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Use
brew
to install the required dependencies:brew install cmake ninja gperf python3 ccache qemu dtc
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.
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.Disable global confirmation to avoid having to confirm the installation of individual programs:
choco feature enable -n allowGlobalConfirmation
Use
choco
to install the required dependencies:choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System' choco install ninja gperf python git
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.
Install west, and make sure
~/.local/bin
is on yourPATH
environment variable:pip3 install --user -U west echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc source ~/.bashrc
Get the Zephyr source code:
west init ~/zephyrproject cd ~/zephyrproject west update
Export a Zephyr CMake package. This allows CMake to automatically load boilerplate code required for building Zephyr applications.
west zephyr-export
Zephyr’s
scripts/requirements.txt
file declares additional Python dependencies. Install them withpip3
.pip3 install --user -r ~/zephyrproject/zephyr/scripts/requirements.txt
Install west:
pip3 install west
Get the Zephyr source code:
west init ~/zephyrproject cd ~/zephyrproject west update
Export a Zephyr CMake package. This allows CMake to automatically load boilerplate code required for building Zephyr applications.
west zephyr-export
Zephyr’s
scripts/requirements.txt
file declares additional Python dependencies. Install them withpip3
.pip3 install -r ~/zephyrproject/zephyr/scripts/requirements.txt
Install west:
pip3 install west
Get the Zephyr source code:
cd %HOMEPATH% west init zephyrproject cd zephyrproject west update
Export a Zephyr CMake package. This allows CMake to automatically load boilerplate code required for building Zephyr applications.
west zephyr-export
Zephyr’s
scripts/requirements.txt
file declares additional Python dependencies. Install them withpip3
.pip3 install -r %HOMEPATH%\zephyrproject\zephyr\scripts\requirements.txt
Install a Toolchain¶
A toolchain provides a compiler, assembler, linker, and other programs required to build Zephyr applications.
The Zephyr Software Development Kit (SDK) contains toolchains for each of Zephyr’s supported architectures. It also includes additional host tools, such as custom QEMU binaries and a host compiler.
Download the latest SDK installer:
cd ~ wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.12.4/zephyr-sdk-0.12.4-x86_64-linux-setup.run
Run the installer, installing the SDK in
~/zephyr-sdk-0.12.4
:chmod +x zephyr-sdk-0.12.4-x86_64-linux-setup.run ./zephyr-sdk-0.12.4-x86_64-linux-setup.run -- -d ~/zephyr-sdk-0.12.4
Note
It is recommended to install the Zephyr SDK at one of the following locations:
$HOME/zephyr-sdk[-x.y.z]
$HOME/.local/zephyr-sdk[-x.y.z]
$HOME/.local/opt/zephyr-sdk[-x.y.z]
$HOME/bin/zephyr-sdk[-x.y.z]
/opt/zephyr-sdk[-x.y.z]
/usr/zephyr-sdk[-x.y.z]
/usr/local/zephyr-sdk[-x.y.z]
where
[-x.y.z]
is optional text, and can be any text, for example-0.12.4
.If installing the Zephyr SDK outside any of those locations, please read: Install the Zephyr Software Development Kit (SDK)
You cannot move the SDK directory after you have installed it.
Install udev rules, which allow you to flash most Zephyr boards as a regular user:
sudo cp ~/zephyr-sdk-0.12.4/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d sudo udevadm control --reload
Follow the instructions in Set Up a Toolchain. Note that the Zephyr SDK is not available on macOS.
Do not forget to set the required environment variables
(ZEPHYR_TOOLCHAIN_VARIANT
and toolchain specific ones).
Follow the instructions in Set Up a Toolchain. Note that the Zephyr SDK is not available on Windows.
Do not forget to set the required environment variables
(ZEPHYR_TOOLCHAIN_VARIANT
and toolchain specific ones).
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:
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.gif](../_images/ReelBoard-Blinky.gif)
Phytec reel_board running blinky¶
Next Steps¶
Here are some next steps for exploring Zephyr:
Try other Samples and Demos
Learn about Application Development and the west tool
Find out about west’s flashing and debugging features, or more about Flashing and Debugging in general
Check out Beyond the Getting Started Guide for additional setup alternatives and ideas
Discover Resources for getting help from the Zephyr community