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

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

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

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)

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

west build -t menuconfig

Search for a config option

west build -t guiconfig

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)

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.

./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

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](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)。

zephyr

Original

Translation

Zephyr RTOS

Zephyr RTOS

Purpose

用途

Triggers

触发场景

Workflow

工作流程

1. Workspace setup and first build

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

Install west

Install west

Initialize workspace from Zephyr manifest

Initialize workspace from Zephyr manifest

Install Python dependencies

Install Python dependencies

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

Build hello_world for a target board

Build hello_world for a target board

Flash to hardware

Flash to hardware

Open serial monitor

Open serial monitor

2. Application structure

2. 应用结构

CMakeLists.txt

CMakeLists.txt

3. Kconfig — feature configuration

3. Kconfig — 功能配置

prj.conf — Kconfig fragment (key=value)

prj.conf — Kconfig fragment (key=value)

Interactive Kconfig menu

Interactive Kconfig menu

Search for a config option

Search for a config option

Show all enabled options

Show all enabled options

4. Devicetree overlays

4. 设备树覆盖层

5. Logging subsystem

5. 日志子系统

6. native_sim — host testing

6. native_sim — 主机测试

Build for host (no hardware needed)

Build for host (no hardware needed)

Run directly on host

Run directly on host

Run with GDB

Run with GDB

Simulated UART appears on a PTY

Simulated UART appears on a PTY

native_sim extras

native_sim extras

7. Debugging on hardware

7. 硬件调试

West debug (launches OpenOCD + GDB automatically)

West debug (launches OpenOCD + GDB automatically)

Or manually with OpenOCD

Or manually with OpenOCD

Zephyr's thread-aware GDB (via OpenOCD RTOS plugin)

Zephyr's thread-aware GDB (via OpenOCD RTOS plugin)

Related skills

相关技能