Zephyr RTOS skill for Codex

Done well means: hardware is described in devicetree and features in Kconfig, never hard-coded in C; the app builds for every board it claims to support from a pinned west manifest; and logic is tested on native_sim before it touches hardware.

Inspect first

1. Read AGENTS.md, then west.yml (or the workspace manifest) for the Zephyr or nRF Connect SDK revision. APIs and board names change between releases; match the pinned one.
2. App layout: CMakeLists.txt, prj.conf, boards/*.overlay, boards/*.conf, src/, optional sysbuild.conf, Kconfig, sample.yaml or testcase.yaml.
3. Build once unchanged and keep the log; generated files are the ground truth.

west build -b nrf52840dk/nrf52840 app -p auto
west build -t menuconfig                 # interactive Kconfig for the current build dir
west build -t rom_report                 # also ram_report
west flash                               # user runs this with the board attached

Setting up a workspace (west init, west update, Python requirements, the Zephyr SDK) needs network and a large download; ask before doing it in the sandbox. If the user’s workspace exists, point Codex at it instead of creating another.

Board names

Zephyr 3.7+ uses hardware model v2: board/soc[/cpucluster][/variant], for example nrf5340dk/nrf5340/cpuapp, nrf52840dk/nrf52840, nucleo_f401re, rpi_pico/rp2040, esp32s3_devkitc/esp32s3/procpu, native_sim. Board overlay and conf files replace / with _: boards/nrf5340dk_nrf5340_cpuapp.overlay. west boards | grep nucleo lists them.

Where a change belongs

You want to	Put it in
Enable a subsystem or driver (I2C, logging, BLE, shell)	prj.conf (CONFIG_I2C=y)
Board-specific Kconfig	boards/<board>.conf
Pin, bus, address, interrupt line, sensor instance	Devicetree overlay
An app option users can tune	App Kconfig with source "Kconfig.zephyr" at the end
Build-variant config (debug vs release)	-DEXTRA_CONF_FILE=debug.conf
A second overlay for a shield or variant	-DEXTRA_DTC_OVERLAY_FILE=sensor.overlay or --shield

Devicetree

Overlay that enables I2C and adds a sensor, plus an alias the code can use:

/* boards/nrf52840dk_nrf52840.overlay */
&i2c0 {
    status = "okay";
    bme280: bme280@76 {
        compatible = "bosch,bme280";
        reg = <0x76>;
    };
};

/ {
    aliases {
        status-led = &led1;
    };
};

#include <zephyr/kernel.h>
#include <zephyr/device.h>
#include <zephyr/drivers/gpio.h>
#include <zephyr/drivers/sensor.h>
#include <zephyr/logging/log.h>

LOG_MODULE_REGISTER(app, LOG_LEVEL_INF);

static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(DT_ALIAS(status_led), gpios);
static const struct device *const bme = DEVICE_DT_GET(DT_NODELABEL(bme280));

int main(void)
{
    if (!gpio_is_ready_dt(&led) || !device_is_ready(bme)) {
        LOG_ERR("hardware not ready");
        return -ENODEV;
    }
    gpio_pin_configure_dt(&led, GPIO_OUTPUT_INACTIVE);

    while (1) {
        struct sensor_value t;
        if (sensor_sample_fetch(bme) == 0 &&
            sensor_channel_get(bme, SENSOR_CHAN_AMBIENT_TEMP, &t) == 0) {
            LOG_INF("temp %d.%06d C", t.val1, t.val2);
        }
        gpio_pin_toggle_dt(&led);
        k_sleep(K_SECONDS(1));
    }
}

• In C, devicetree names use underscores: alias status-led becomes DT_ALIAS(status_led).
• device_is_ready() false means the driver did not initialise: check the node has status = "okay", the matching CONFIG_ for the driver is set (most sensor drivers default on when CONFIG_SENSOR=y and an enabled node exists), and the bus came up.
• After a build, read build/zephyr/zephyr.dts (the merged tree) and build/zephyr/.config (final Kconfig) before guessing. With sysbuild the app lives in build/<app-name>/zephyr/.
• Bindings live in zephyr/dts/bindings; the binding defines which properties are required. Read it when DTC errors mention missing properties.

Kconfig traps

• A symbol set in prj.conf with unmet dependencies is silently dropped, with only a warning in the build log. Grep the final .config to confirm the value.
• Disable with CONFIG_FOO=n in prj.conf. Never edit build/zephyr/.config by hand; it is regenerated, and menuconfig changes vanish on a pristine build unless copied back.
• Symbols without a prompt cannot be set from prj.conf at all; they follow their default and select statements. menuconfig shows why a symbol has its value.
• Stack sizes are Kconfig (CONFIG_MAIN_STACK_SIZE, CONFIG_SYSTEM_WORKQUEUE_STACK_SIZE). Turn on CONFIG_THREAD_ANALYZER=y during development to see real usage.

Concurrency

Need	Primitive
Fixed thread at boot	K_THREAD_DEFINE(name, stack, fn, p1, p2, p3, prio, 0, 0)
Pass fixed-size messages	K_MSGQ_DEFINE with k_msgq_put/k_msgq_get
Defer work from an ISR	k_work_submit on the system work queue; own queue if it blocks
Periodic work	k_work_delayable or k_timer handing off to work
Protect shared data between threads	k_mutex (priority inheritance); k_spinlock for ISR-shared

Cooperative threads (negative priority) are never preempted by other threads; use them only for short, deliberate sections. Never call blocking APIs or k_sleep from an ISR.

Tests with Twister

west build -b native_sim tests/unit -p auto && ./build/zephyr/zephyr.exe
west twister -T tests -p native_sim --inline-logs

Write tests with the ztest API (ZTEST_SUITE, ZTEST, zassert_equal) and declare platforms and tags in testcase.yaml. Use emulated devices (zephyr,i2c-emul-controller and sensor emulators) for driver-facing code. native_sim builds need a Linux host; on macOS run them in the project’s container or CI.

Bootloader and updates

west build -b nrf52840dk/nrf52840 app --sysbuild -p auto -- -DSB_CONFIG_BOOTLOADER_MCUBOOT=y

MCUboot signs images with a development key by default; that key is public. Production signing, slot layout and confirming images belong to firmware-ota.

Verification

• Clean pristine build (-p always) for every board in sample.yaml or the README
• No Kconfig warnings about unmet dependencies in the log
• zephyr.dts shows the intended pins and status = "okay" on used nodes
• Twister passes on native_sim; hardware log (west flash then RTT or UART output) pasted by the user shows the expected boot sequence
• rom_report/ram_report compared against the previous build

Report

**Workspace:** Zephyr v4.1.0 via west.yml; boards nrf52840dk/nrf52840, native_sim
**Change:** BME280 moved to devicetree overlay; LED via alias; sensor thread -> k_work_delayable
**Checks:** pristine builds pass; twister 12/12 on native_sim; .config shows CONFIG_BME280=y
**Size:** flash 61.2 -> 63.0 KB, RAM 18.4 -> 18.9 KB
**Open:** production MCUboot key not configured (dev key in use)