Back to Details

zephyr

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Zephyr RTOS

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.
指导开发人员完成Zephyr应用开发流程：west构建工作流、开发板配置、Kconfig与设备树使用、Zephyr Shell与日志系统操作、用于主机测试的native_sim目标平台，以及使用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?"
  • "如何使用west构建Zephyr应用？"
  • "如何使用Kconfig配置Zephyr？"
  • "如何在Zephyr中使用设备树覆盖层？"
  • "如何为我的Zephyr应用添加日志功能？"
  • "如何在主机上运行Zephyr进行测试？"
  • "如何调试Zephyr应用？"

Workflow

工作流程

1. Workspace setup and first build

1. 工作区搭建与首次构建

bash
undefined
bash
undefined

Install west

Install west

pip install west
pip install west

Initialize workspace from Zephyr manifest

Initialize workspace from Zephyr manifest

west init ~/zephyrproject cd ~/zephyrproject west update # fetches Zephyr + all modules
west init ~/zephyrproject cd ~/zephyrproject west update # fetches Zephyr + all modules

Install Python dependencies

Install Python dependencies

pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt
pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt

Install Zephyr SDK (toolchains for all targets)

Install Zephyr SDK (toolchains for all targets)

Download from: https://github.com/zephyrproject-rtos/sdk-ng/releases

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
export ZEPHYR_SDK_INSTALL_DIR=/zephyr-sdk-0.17.0 export ZEPHYR_BASE=/zephyrproject/zephyr

Build hello_world for a target board

Build hello_world for a target board

west build -b nrf52840dk/nrf52840 samples/hello_world
west build -b nrf52840dk/nrf52840 samples/hello_world

Flash to hardware

Flash to hardware

west flash
west flash

Open serial monitor

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` |
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` |
| 原生POSIX | `native_sim` |

2. Application structure

2. 应用结构

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

CMakeLists.txt

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)
undefined
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)
undefined

3. Kconfig — feature configuration

3. Kconfig — 功能配置

undefined
undefined

prj.conf — Kconfig fragment (key=value)

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

```bash
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

```bash

Interactive Kconfig menu

Interactive Kconfig menu

west build -t menuconfig
west build -t menuconfig

Search for a config option

Search for a config option

west build -t guiconfig
west build -t guiconfig

Show all enabled options

Show all enabled options

west build -t config -- -n | grep "^CONFIG_"
undefined
west build -t config -- -n | grep "^CONFIG_"
undefined

4. Devicetree overlays

4. 设备树覆盖层

dts
/* 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";
};
c
// 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);
dts
/* 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";
};
c
// 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

5. 日志子系统

c
#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
c
#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 — host testing

6. native_sim — 主机测试

bash
undefined
bash
undefined

Build for host (no hardware needed)

Build for host (no hardware needed)

west build -b native_sim samples/hello_world
west build -b native_sim samples/hello_world

Run directly on host

Run directly on host

./build/zephyr/zephyr.exe
./build/zephyr/zephyr.exe

Run with GDB

Run with GDB

gdb ./build/zephyr/zephyr.exe (gdb) run
gdb ./build/zephyr/zephyr.exe (gdb) run

Simulated UART appears on a PTY

Simulated UART appears on a PTY

./build/zephyr/zephyr.exe & screen $(ls /tmp/zephyr-uart-*)
./build/zephyr/zephyr.exe & screen $(ls /tmp/zephyr-uart-*)

native_sim extras

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.
./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. Debugging on hardware

7. 硬件调试

bash
undefined
bash
undefined

West debug (launches OpenOCD + GDB automatically)

West debug (launches OpenOCD + GDB automatically)

west debug
west debug

Or manually with OpenOCD

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
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)

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](references/west-manifest.md).
(gdb) info threads # lists Zephyr threads (gdb) thread 2 # switch to thread

如需west清单的详细信息，请参阅[references/west-manifest.md](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
  • 如需硬件调试的详细内容，请使用
    skills/embedded/openocd-jtag
    技能
  • 如需替代RTOS的相关内容，请使用
    skills/embedded/freertos
    技能
  • 如需内存区域配置的相关内容，请使用
    skills/embedded/linker-scripts
    技能
  • 如需GDB会话管理的相关内容，请使用
    skills/debuggers/gdb
    技能