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:

Board	Target name
nRF52840 DK	nrf52840dk/nrf52840
STM32 Nucleo-F446RE	nucleo_f446re
Raspberry Pi Pico	rpi_pico/rp2040
ESP32	esp32_devkitc_wroom/esp32/procpu
QEMU Cortex-M3	qemu_cortex_m3
Native POSIX	native_sim

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