Zephyr RTOS Setup Guide

Zephyr is a scalable real-time operating system designed for resource-constrained embedded devices. It supports a wide range of ARM Cortex-M targets — including STM32 and Nordic nRF series — which are commonly used in avionics hardware.

These scripts automate the full installation of the Zephyr SDK, the west meta-tool, and all required dependencies.

Note:

• Summary written by AI
• Any time zephyrproject is mentioned, it can be replaced with the top level directory of your project.

Quick Start

Platform-Specific Instructions

Linux

Prerequisites: sudo access is required to install system packages.

chmod +x install_zephyr_linux.sh
./install_zephyr_linux.sh

Supported distributions: Ubuntu, Debian, Linux Mint, Pop!_OS, Fedora, Arch, Manjaro.

macOS

Prerequisites: The script will install Homebrew automatically if it is not present. Accept the Xcode Command Line Tools prompt when asked.

chmod +x install_zephyr_mac.sh
./install_zephyr_mac.sh

Works on both Intel (x86_64) and Apple Silicon (arm64) Macs.

Windows

Windows support is native PowerShell — no Git Bash, WSL2, or Chocolatey required. Dependencies are installed via winget, which ships with Windows 10 21H2+ and Windows 11.

Run the script from PowerShell:

powershell -ExecutionPolicy Bypass -File install_zephyr_windows.ps1

WSL2 alternative: If you have WSL2 installed, running install_zephyr_linux.sh inside a WSL2 Ubuntu shell also works. See Microsoft's WSL2 guide for setup instructions.

What the Scripts Do

Each script performs the following steps in order:

1. Install system packages — cmake, ninja, gperf, device tree compiler, Python 3, and other build tools via the platform's package manager (winget on Windows).
2. Create a Python virtual environment at ~/zephyrproject/.venv to isolate Zephyr's Python dependencies from the system.
3. Install West — Zephyr's meta-build tool, used to manage the workspace and build firmware.
4. Initialize the Zephyr workspace at ~/zephyrproject/ by cloning the Zephyr repository and all required modules.
5. Install Zephyr Python requirements.
6. Install the Zephyr SDK — the cross-compilation toolchain for your target architecture (west sdk install on Windows; manual download on Linux/macOS).
7. Persist the venv activation in your shell profile (.bashrc, .zshrc, or PowerShell $PROFILE) so the environment is available in future terminal sessions.

Configuration

All scripts respect the following environment variables, which you can set before running to override defaults:

Example — install a specific SDK version and all toolchains:

ZEPHYR_SDK_VERSION=0.16.8 ZEPHYR_TOOLCHAIN=all ./install_zephyr_linux.sh

Common toolchain values:

• arm-zephyr-eabi — ARM Cortex-M/R (STM32, nRF, most avionics MCUs)
• riscv64-zephyr-elf — RISC-V targets
• xtensa-espressif_esp32_zephyr-elf — ESP32
• all — every supported toolchain (~7 GB download)

For most avionics work targeting STM32 or Nordic nRF MCUs, the default arm-zephyr-eabi toolchain is sufficient.

Verifying the Installation

After the script completes, open a new terminal and run:

source ~/zephyrproject/.venv/bin/activate   # Linux/macOS

& "$HOME\zephyrproject\.venv\Scripts\Activate.ps1"   # Windows PowerShell

west --version
cmake --version

You should see version output for both tools with no errors.

Building Your First Project

The standard Zephyr workflow uses west build to compile firmware for a specific board target.

# Activate the Zephyr environment
source ~/zephyrproject/.venv/bin/activate

# Navigate into the Zephyr source tree
cd ~/zephyrproject/zephyr

# Build the hello_world sample for your board
west build -b <board_name> samples/hello_world

# Flash the firmware (requires a connected programmer)
west flash

Common board targets:

Run west boards to list all supported targets, or search at docs.zephyrproject.org.

Pinning a Specific Zephyr Version

To use a specific Zephyr release instead of the latest, pass --mr to west init:

west init --mr v3.7.0 ~/zephyrproject

Zephyr releases follow the pattern v<major>.<minor>.<patch>. Check GitHub releases for available versions.

Troubleshooting

west: command not found after installation The virtual environment is not active. Run:

source ~/zephyrproject/.venv/bin/activate

west update fails mid-way Network interruptions can leave the workspace in a partial state. Re-run west update — it is idempotent and will resume where it left off.

SDK setup fails with permission errors (Linux) Ensure ~/zephyr-sdk-<version>/ is owned by your user, not root. Re-run the SDK setup step manually:

cd ~/zephyr-sdk-0.16.8
./setup.sh -t arm-zephyr-eabi -h -c

Homebrew not on PATH after install (macOS Apple Silicon) Add this to your ~/.zshrc:

eval "$(/opt/homebrew/bin/brew shellenv)"

CMake can't find the Zephyr package Run west zephyr-export from inside the workspace directory:

cd ~/zephyrproject
west zephyr-export

Windows: venv activation blocked by execution policy Allow locally-created scripts to run for your user account:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Windows: winget not found Update the "App Installer" package from the Microsoft Store, or install it manually from the winget-cli releases page.

Further Reading

• Zephyr Getting Started Guide
• West Workspace Basics
• Zephyr Board Support
• Zephyr SDK Releases