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
- 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
- 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)
- 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_"
- 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);
- 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
- 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.
- 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