| name | zephyr-integration |
| description | Use when integrating, porting, configuring, or debugging Zephyr RTOS, west builds, devicetree overlays, Kconfig, drivers, threads, logging, networking, or board support |
Zephyr Integration
Overview
Use this skill to debug Zephyr by separating board selection, devicetree, Kconfig,
driver binding, and runtime behavior. Zephyr issues usually come from build-time
configuration mismatches before they appear as firmware bugs.
When To Use
Use this skill when:
- The user is working with Zephyr RTOS,
west, boards, shields, samples, or
custom board ports.
- The issue involves devicetree overlays, Kconfig symbols, drivers, threads,
logging, flash partitions, networking, Bluetooth, or power management.
- A build succeeds but the device tree binding, generated config, or runtime
device readiness is suspicious.
Do not use this skill for generic RTOS scheduling bugs with no Zephyr-specific
surface. Use rtos-debug or freertos-kernel-debug instead.
First Questions
Ask for:
- Zephyr version, SDK/toolchain,
west workspace layout, board, and sample/app.
- Full
west build command, prj.conf, overlays, and board revision.
- Relevant devicetree node, binding, compatible string, alias, and chosen node.
- Generated
zephyr.dts, .config, and the failing log or build error.
- Whether the issue is build-time, boot-time, driver probing, or runtime.
Debug Workflow
-
Reproduce the build.
Capture the exact west build command, board, app path, and pristine status.
-
Inspect generated artifacts.
Check build/zephyr/zephyr.dts, .config, and generated headers before
editing source code.
-
Prove devicetree binding.
Confirm status = "okay", compatible, pinctrl, clocks, interrupts,
aliases, and chosen nodes.
-
Prove Kconfig selection.
Verify symbols in .config, dependency chains, and whether another config
file overrides the intended value.
-
Check device readiness.
Use device_is_ready(), init priority, logging, and driver return codes.
-
Debug runtime behavior.
Only after configuration is proven, inspect threads, stacks, work queues,
interrupts, buffers, and subsystem-specific APIs.
Common Failures
- Overlay targets the wrong board revision or node path.
- Kconfig symbol is set in
prj.conf but silently unmet due to dependencies.
- Driver instance exists in devicetree but is disabled or lacks pinctrl/clocks.
- Code uses a device before its init priority has run.
- Stack sizes are too small for logging, networking, Bluetooth, or filesystem.
- A stale build directory hides changed devicetree or Kconfig input.
Verification
Before claiming a Zephyr fix works:
- State Zephyr version, board, build command, overlay, and key Kconfig symbols.
- Confirm generated
zephyr.dts and .config contain the intended values.
- Confirm driver readiness or subsystem initialization in logs.
- Confirm runtime behavior on hardware or in the selected emulator/simulator.
Example
User:
Zephyr 里 I2C sensor 一直 device not ready。
Agent:
- Checks board, overlay, generated devicetree, and Kconfig dependencies.
- Verifies the bus, sensor node, pinctrl, clocks, and init priority.
- Only then inspects the sensor driver and read path.
