zephyr

Zephyr RTOS

用途

指导 Agent 进行 Zephyr 应用开发：west 构建工作流、开发板配置、Kconfig 和 devicetree、Zephyr shell 和日志、用于主机测试的 native_sim 目标，以及使用 GDB 进行调试。

触发条件

• “如何使用 west 构建 Zephyr 应用？”
• “如何使用 Kconfig 配置 Zephyr？”
• “如何在 Zephyr 中使用 devicetree 覆盖文件？”
• “如何为 Zephyr 应用添加日志？”
• “如何在主机上运行 Zephyr 进行测试？”
• “如何调试 Zephyr 应用？”

工作流

1. 工作区设置和首次构建

# 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

常见的开发板目标：

开发板	目标名称
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. 应用结构

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 — 功能配置

# 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 覆盖文件

/* 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. 日志子系统

#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");
}

在 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 — 主机测试

# 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 会将 Zephyr 作为 Linux 进程运行。它支持大多数 Zephyr API，是单元测试和 CI 的理想选择。

7. 在硬件上调试

# 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

有关 west 清单的详细信息，请参阅 references/west-manifest.md。

相关技能

• 使用 skills/embedded/openocd-jtag 了解硬件调试详情
• 使用 skills/embedded/freertos 了解 FreeRTOS 这一替代 RTOS
• 使用 skills/embedded/linker-scripts 配置内存区域
• 使用 skills/debuggers/gdb 管理 GDB 会话