Zephyr

Zephyr RTOS

Purpose

Guide agents through Zephyr application development: west build workflow, board configuration, Kconfig and devicetree, Zephyr shell and logging, native_sim target for host testing, and debugging with GDB.

Triggers

• "How do I build a Zephyr application with west?"
• "How do I configure Zephyr with Kconfig?"
• "How do I use devicetree overlays in Zephyr?"
• "How do I add logging to my Zephyr application?"
• "How do I run Zephyr on my host machine for testing?"
• "How do I debug a Zephyr application?"

Workflow

1. Workspace setup and first build

# Install west
pip install west

# Initialize workspace from Zephyr manifest
west init ~/zephyrproject
cd ~/zephyrproject
west update                          # fetches Zephyr + all modules

# Install Python dependencies
pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt

# Install Zephyr SDK (toolchains for all targets)
# Download from: https://github.com/zephyrproject-rtos/sdk-ng/releases
export ZEPHYR_SDK_INSTALL_DIR=~/zephyr-sdk-0.17.0
export ZEPHYR_BASE=~/zephyrproject/zephyr

# Build hello_world for a target board
west build -b nrf52840dk/nrf52840 samples/hello_world

# Flash to hardware
west flash

# Open serial monitor
west espressif monitor  # or: screen /dev/ttyACM0 115200

Common board targets:

2. Application structure

my_app/
├── CMakeLists.txt
├── prj.conf              # Kconfig fragment
├── app.overlay           # devicetree overlay (optional)
└── src/
    └── main.c

# CMakeLists.txt
cmake_minimum_required(VERSION 3.20.0)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(my_app)
target_sources(app PRIVATE src/main.c)

3. Kconfig — feature configuration

# prj.conf — Kconfig fragment (key=value)
CONFIG_GPIO=y
CONFIG_UART_CONSOLE=y
CONFIG_LOG=y
CONFIG_LOG_DEFAULT_LEVEL=3     # 0=off 1=err 2=warn 3=info 4=debug
CONFIG_PRINTK=y
CONFIG_HEAP_MEM_POOL_SIZE=4096
CONFIG_MAIN_STACK_SIZE=2048

# Interactive Kconfig menu
west build -t menuconfig

# Search for a config option
west build -t guiconfig

# Show all enabled options
west build -t config -- -n | grep "^CONFIG_"

4. Devicetree overlays

/* app.overlay — board-specific hardware additions */
/ {
    leds {
        compatible = "gpio-leds";
        my_led: led_0 {
            gpios = <&gpio0 13 GPIO_ACTIVE_LOW>;
            label = "My LED";
        };
    };
};

/* Override a node property */
&uart0 {
    current-speed = <115200>;
};

/* Disable an existing node */
&spi1 {
    status = "disabled";
};

// Access devicetree nodes in C
#include <zephyr/devicetree.h>
#include <zephyr/drivers/gpio.h>

#define LED_NODE DT_ALIAS(led0)
static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(LED_NODE, gpios);

// Initialize and toggle
gpio_pin_configure_dt(&led, GPIO_OUTPUT_ACTIVE);
gpio_pin_toggle_dt(&led);

5. Logging subsystem

#include <zephyr/logging/log.h>

LOG_MODULE_REGISTER(my_module, LOG_LEVEL_DBG);

void my_function(void) {
    LOG_INF("Sensor value: %d", 42);
    LOG_WRN("Low battery: %d%%", battery_pct);
    LOG_ERR("SPI transfer failed: %d", ret);
    LOG_DBG("Debug detail: ptr=%p", ptr);
    LOG_HEXDUMP_DBG(buf, len, "raw buffer");
}

Backend configuration in prj.conf:

CONFIG_LOG=y
CONFIG_LOG_BACKEND_UART=y        # UART output
CONFIG_LOG_BACKEND_RTT=y         # Segger RTT output
CONFIG_LOG_TIMESTAMP_DEFAULT=y   # add timestamps
CONFIG_LOG_PROCESS_THREAD_STACK_SIZE=512

6. native_sim — host testing

# Build for host (no hardware needed)
west build -b native_sim samples/hello_world

# Run directly on host
./build/zephyr/zephyr.exe

# Run with GDB
gdb ./build/zephyr/zephyr.exe
(gdb) run

# Simulated UART appears on a PTY
./build/zephyr/zephyr.exe &
screen $(ls /tmp/zephyr-uart-*)

# native_sim extras
./build/zephyr/zephyr.exe --help
./build/zephyr/zephyr.exe --stop-at=5  # stop after 5 simulated seconds

native_sim runs Zephyr as a Linux process. Supports most Zephyr APIs, ideal for unit testing and CI.

7. Debugging on hardware

# West debug (launches OpenOCD + GDB automatically)
west debug

# Or manually with OpenOCD
west build -t run &
arm-zephyr-eabi-gdb build/zephyr/zephyr.elf
(gdb) target remote :3333
(gdb) monitor reset halt
(gdb) load
(gdb) continue

# Zephyr's thread-aware GDB (via OpenOCD RTOS plugin)
(gdb) info threads     # lists Zephyr threads
(gdb) thread 2         # switch to thread

For west manifest details, see references/west-manifest.md.

Related skills

• Use skills/embedded/openocd-jtag for hardware debugging details
• Use skills/embedded/freertos for FreeRTOS as an alternative RTOS
• Use skills/embedded/linker-scripts for memory region configuration
• Use skills/debuggers/gdb for GDB session management

West Manifest Reference

Source: https://docs.zephyrproject.org/latest/develop/west/manifest.html

Table of Contents

1. west.yml Structure 2. Common Commands 3. Custom Module

west.yml Structure

# west.yml — placed at workspace root (T2 topology)
manifest:
  version: "0.13"

  remotes:
    - name: zephyrproject-rtos
      url-base: https://github.com/zephyrproject-rtos

  defaults:
    remote: zephyrproject-rtos

  projects:
    - name: zephyr
      revision: v3.7.0          # pin to a release tag
      import: true              # import Zephyr's own west.yml

    # Add a custom driver module
    - name: my-drivers
      url: https://github.com/myorg/my-drivers
      revision: main
      path: modules/my-drivers

  self:
    path: app                   # this repo's path in the workspace

Common Commands

# Initialize workspace from manifest
west init -m https://github.com/myorg/my-manifest workspace/
cd workspace && west update

# Update all projects to manifest revisions
west update

# Show workspace state
west list
west status

# Run a command across all projects
west forall -c "git log --oneline -5"

# Fetch without updating
west update --narrow

# Create a snapshot manifest (freeze all revisions)
west manifest --resolve > west-snapshot.yml

Custom Module

To add a custom HAL or driver as a Zephyr module:

# modules/my-hal/zephyr/module.yml
build:
  cmake: CMakeLists.txt
  kconfig: Kconfig

  settings:
    dts_root: .         # if module has devicetree bindings
    board_root: .       # if module defines custom boards

# modules/my-hal/CMakeLists.txt
zephyr_include_directories(include)
zephyr_library_sources(src/my_hal.c)

# modules/my-hal/Kconfig
config MY_HAL
    bool "My HAL driver"
    depends on I2C
    help
      Enable My HAL I2C driver.