zephyr-integration

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

1. Reproduce the build.

Capture the exact west build command, board, app path, and pristine status.

1. Inspect generated artifacts.

Check build/zephyr/zephyr.dts, .config, and generated headers before editing source code.

1. Prove devicetree binding.

Confirm status = "okay", compatible, pinctrl, clocks, interrupts, aliases, and chosen nodes.

1. Prove Kconfig selection.

Verify symbols in .config, dependency chains, and whether another config file overrides the intended value.

1. Check device readiness.

Use device_is_ready(), init priority, logging, and driver return codes.

1. 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:

1. Checks board, overlay, generated devicetree, and Kconfig dependencies.
2. Verifies the bus, sensor node, pinctrl, clocks, and init priority.
3. Only then inspects the sensor driver and read path.