XIAO Zephyr RTOS Development

Overview

Complete Zephyr RTOS development guide for SeeedStudio XIAO series. This skill works with the /xiao skill - use /xiao for pin definitions, /xiao-zephyr for Zephyr RTOS APIs, build system, and configuration.

Prerequisites

1. Pin Definitions: Read /xiao skill first for board-specific pin mappings
2. Zephyr SDK: Native Zephyr SDK with west tool (PRIMARY method)
3. PlatformIO (optional): Alternative for nRF54L15 only
4. Build Tools: CMake, Ninja, Devicetree compiler, Python 3.8+

Environment Setup

For first-time Zephyr environment installation, see setup/:

• Zephyr SDK Installation (PRIMARY): setup/installation.md - Native SDK with west workflow
• PlatformIO (optional, nRF54L15 only): setup/platformio.md
• Tooling: setup/tooling.md - CMake, Devicetree compiler requirements

Zephyr Project Structure (CRITICAL)

Zephyr requires a specific project structure:

my-zephyr-project/
├── CMakeLists.txt          # Build configuration (required)
├── prj.conf                # Kconfig settings (required)
├── overlay.dtsh            # Devicetree overlay (optional, for custom pins)
└── src/
    └── main.c              # Application code

CMakeLists.txt (Minimum)

cmake_minimum_required(VERSION 3.20)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(my_project)
target_sources(app PRIVATE src/main.c)

prj.conf (Minimum)

# Minimum required configuration
CONFIG_MAIN_STACK_SIZE=1024
CONFIG_GPIO=y

Code Generation Workflow (CRITICAL)

When a user requests Zephyr code generation, you MUST:

Step 1: Select Board (Zephyr Board Name)

Step 2: Create Project Structure

Use the Write tool to create:

1. CMakeLists.txt - Build configuration
2. prj.conf - Kconfig settings
3. src/main.c - Application code
4. overlay.dtsh (if custom pin mapping needed)

Step 3: Configure with Kconfig

Add required subsystems to prj.conf:

# Enable GPIO
CONFIG_GPIO=y

# Enable I2C (if needed)
CONFIG_I2C=y

# Enable SPI (if needed)
CONFIG_SPI=y

# Enable UART (if needed)
CONFIG_SERIAL=y
CONFIG_UART_CONSOLE=y

# Enable Bluetooth (if needed)
CONFIG_BT=y
CONFIG_BT_PERIPHERAL=y

Step 4: Write Code Using Zephyr APIs

Use Zephyr kernel and driver APIs (see api/ reference files):

#include <zephyr/kernel.h>
#include <zephyr/drivers/gpio.h>

/* 1000 msec = 1 sec */
#define SLEEP_TIME_MS 1000

/* Get the device pointer for the GPIO */
static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(DT_ALIAS(led), gpios);

int main(void)
{
    if (!gpio_is_ready_dt(&led)) {
        return 0;
    }

    gpio_pin_configure_dt(&led, GPIO_OUTPUT_ACTIVE);

    while (1) {
        gpio_pin_toggle_dt(&led);
        k_msleep(SLEEP_TIME_MS);
    }
    return 0;
}

Step 5: Build with West

# Set Zephyr environment
source zephyr-env.sh   # Linux/macOS
# or
zephyr-env.bat        # Windows

# Build
west build -b <board_name>

# Example for XIAO nRF52840:
west build -b seeeduino_xiao_ble

Step 6: Flash with West

west flash

Quick Start by Board

Zephyr APIs and Subsystems

Basic Peripherals

Connectivity

Kernel Services

Configuration Systems

Code Patterns

Basic Structure (Blinky)

CMakeLists.txt:

cmake_minimum_required(VERSION 3.20)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(blinky)
target_sources(app PRIVATE src/main.c)

prj.conf:

CONFIG_GPIO=y

src/main.c:

#include <zephyr/kernel.h>
#include <zephyr/drivers/gpio.h>

#define SLEEP_TIME_MS 1000

/* LED on D10 (XIAO standard) - adjust per board */
#define LED_NODE DT_ALIAS(led)
static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(LED_NODE, gpios);

int main(void)
{
    if (!device_is_ready(led.port)) {
        return 0;
    }

    gpio_pin_configure_dt(&led, GPIO_OUTPUT_ACTIVE);

    while (1) {
        gpio_pin_toggle_dt(&led);
        k_msleep(SLEEP_TIME_MS);
    }
    return 0;
}

Non-blocking Delay (Kernel Timer)

#include <zephyr/kernel.h>

#define TIMER_INTERVAL_MS 1000

K_TIMER_DEFINE(my_timer, timer_expiry_callback, NULL);

void timer_expiry_callback(struct k_timer *timer)
{
    // Timer expired
}

int main(void)
{
    k_timer_start(&my_timer, K_MSEC(TIMER_INTERVAL_MS), K_MSEC(TIMER_INTERVAL_MS));

    while (1) {
        // Other work here
        k_msleep(100);
    }
    return 0;
}

Threading Example

#include <zephyr/kernel.h>

#define THREAD_STACK_SIZE 1024
#define THREAD_PRIORITY 5

K_THREAD_DEFINE(thread_id, THREAD_STACK_SIZE,
                thread_func, NULL, NULL, NULL,
                THREAD_PRIORITY, 0, 0);

void thread_func(void *p1, void *p2, void *p3)
{
    while (1) {
        // Thread work here
        k_msleep(1000);
    }
}

int main(void)
{
    // Main thread
    while (1) {
        k_msleep(1000);
    }
    return 0;
}

Code Verification

After generating Zephyr code, verify it builds correctly.

Build with West

# Set Zephyr environment
source zephyr-env.sh   # Linux/macOS
# or
zephyr-env.bat        # Windows

# Build for specific board
west build -b <board_name> -p always

# Example for XIAO nRF52840:
west build -b seeeduino_xiao_ble -p always

Common Build Errors and Solutions

Verification Checklist

After generating code, verify:

• CMakeLists.txt includes find_package(Zephyr REQUIRED)
• prj.conf enables required subsystems (GPIO, I2C, SPI, etc.)
• Pin definitions match the XIAO board (use /xiao skill)
• Board name matches Zephyr board identifier
• Code compiles without errors
• Memory usage is within board limits

Troubleshooting

Build Failures

1. Environment not set: Source zephyr-env.sh before building
2. Wrong board name: Check Zephyr board name in boards/seeed/
3. Missing Kconfig options: Enable required subsystems in prj.conf

Flash Failures

1. nRF52: Double-click RESET button to enter bootloader
2. ESP32: Hold BOOT button during flash
3. RP2040: Hold BOOTSEL while connecting USB

Device Tree Issues

1. Check node names match devicetree sources
2. Verify alias names in overlay.dtsh
3. Use west build -t menuconfig to inspect configuration

Sense Boards Support

XIAO Sense boards with onboard sensors are supported in Zephyr:

Expansion Boards

XIAO expansion boards are supported in Zephyr. For hardware specifications, see /xiao/references/expansion_boards/.

Resources

setup/

Environment installation and configuration:

• setup/installation.md - Zephyr SDK and west tool installation (Windows/macOS/Linux)
• setup/platformio.md - PlatformIO for nRF54L15 (optional alternative)
• setup/tooling.md - CMake, Devicetree compiler, and other tools

getting-started/

Board-specific setup instructions for all 9 supported XIAO boards:

• getting-started/xiao-ble.md - nRF52840 setup and first project
• getting-started/xiao-esp32c3.md - ESP32C3 setup
• getting-started/xiao-esp32c6.md - ESP32C6 setup
• getting-started/xiao-esp32s3.md - ESP32S3 setup
• getting-started/xiao-mg24.md - MG24 setup
• getting-started/xiao-nrf54l15.md - nRF54L15 setup
• getting-started/xiao-ra4m1.md - RA4M1 setup
• getting-started/xiao-rp2040.md - RP2040 setup
• getting-started/seeeduino-xiao.md - SAMD21 setup

api/

Zephyr API documentation:

• api/gpio-pwm-adc.md - GPIO, PWM, ADC APIs
• api/i2c-spi-uart.md - I2C, SPI, UART communication
• api/bluetooth.md - Bluetooth LE stack (80+ examples)
• api/wifi.md - WiFi (ESP32 boards)
• api/networking.md - IP networking, MQTT
• api/threads.md - Threading and scheduling
• api/timers.md - Kernel timers
• api/power-management.md - Sleep modes

configuration/

Zephyr configuration systems:

• configuration/kconfig.md - Kconfig system
• configuration/devicetree.md - Devicetree overlays
• configuration/cmake.md - CMakeLists.txt patterns
• configuration/prj-conf.md - prj.conf settings

examples/

Complete project examples combining Ref/zephyr and Ref/platform-seeedboards:

• examples/basic.md - Blinky, button, sensor examples
• examples/bluetooth.md - BLE peripheral, central, mesh
• examples/sensors.md - I2C/SPI sensor integration
• examples/lowpower.md - Low power modes

Related Skills

• /xiao - Core board reference with pin definitions
• /xiao-arduino - Arduino development for XIAO
• /xiao-micropython - MicroPython development for XIAO