Getting Started with Simplicity SDK for Zephyr#

1 Overview#

This document describes how to get started with Simplicity SDK for Zephyr on Silicon Labs devices. It covers host and workspace set-up, project creation, build and flash commands, initial validation, and troubleshooting guidance for setup and run-time issues.

2 Prerequisites#

Before working through the examples, make sure you have the following:

  • Python, CMake, and Devicetree compiler required by the selected release. Refer to the upstream Zephyr Getting Started Guide for the expected versions and installation instructions.

  • Silicon Labs Simplicity Commander installed and available from the command line. For steps to bring up Simplicity Commander refer to Getting Started with Simplicity Commander.

  • A Silicon Labs Series 2 or SiWx917 development kit

  • For Wi-Fi tests, a 2.4 GHz access point

Use short workspace paths and application directory names. Paths that contain spaces or very long directory names can complicate command-line usage, especially on Windows.

3 Getting Started#

3.1 Workspace Bring-Up#

For development using Simplicity SDK for Zephyr, initialize the workspace from the SiliconLabsSoftware/zephyr-silabs repository, following the steps below:

  1. Create the workspace directory:

mkdir workspace
cd workspace

  1. Create a Python virtual environment in the workspace:

python -m venv .venv

  1. Activate the virtual environment:

source .venv/bin/activate

On Windows PowerShell, activate the virtual environment with:

.venv\Scripts\Activate.ps1

  1. Install west in the active virtual environment:

pip install west

  1. Install Toolchain:

west sdk install -t arm-zephyr-eabi

  1. Install Python dependencies using west packages:

#For Ubuntu and Linux:
west packages pip --install

#For Windows Powershell:
python -m pip install @((west packages pip) -split ' ')

  1. Initialize the workspace from the Silicon Labs manifest repository:

west init -m https://github.com/SiliconLabsSoftware/zephyr-silabs --mr v2026.6.0

  1. Update the workspace:

west update

NOTE: To fetch the Silicon Labs prebuilt binary content, run the below command:

west blobs fetch hal_silabs

After the workspace has been initialized, follow the steps below to validate with Silicon Labs hardware. For SiWG917, refer to the additional steps in Section 3.2.

3.2 Zephyr Application bring up with SiWG917#

In this guide, the SiWx917-RB4338A board is used for Zephyr applications running on the Silicon Labs SiWx917 Wi-Fi 6 and Bluetooth LE SoC radio board. The radio board is normally used with a Wireless Pro Kit Mainboard, which provides power, debug access, and serial connectivity.

Use the following board target when applying the generic build and flash flow described in Section 3.1:

siwx917_rb4338a

SiWx917 Wi-Fi applications require compatible SiWG917 network processor (NWP) firmware. To program the connectivity firmware provided with the workspace:

commander flash modules/hal/silabs/zephyr/blobs/wiseconnect/connectivity_firmware/standard/SiWG917-*.rps

This step programs the NWP firmware and is separate from flashing the Zephyr application image generated by west build to the Cortex-M4 application core. The application image does not replace the NWP connectivity firmware.

To build an application for the SiWx917-RB4338A from the workspace root, run:

west build -p=always -b siwx917_rb4338a zephyr/samples/basic/blinky
west flash

You can also flash the generated application image directly by using Simplicity Commander:

  1. For SiWx917 devices:

    commander flash build/zephyr/zephyr.rps

  2. For Series 2 devices:

    commander flash build/zephyr/zephyr.hex

Keep the workspace modules, binary blobs, NWP firmware, and application build aligned to the same release.

4 Create a Zephyr SiWx917 Project#

Create a custom project by copying a known working Zephyr sample. Rename the copied directory, make one controlled change, and rebuild the copied project. This approach keeps the first custom application close to a sample that already has a valid Zephyr project structure.

The following examples place custom applications in an applications directory at the workspace level. If the project has an established application layout, refer to that layout instead.

4.1 Create a Basic Custom Project#

Use this path for a minimal application that validates the board, build system, flashing workflow, and serial console before adding Wi-Fi functionality.

From the workspace root, run:

mkdir -p applications
cp -r zephyr/samples/basic/blinky applications/siwx917_blinky_custom

On Windows PowerShell, run:

New-Item -ItemType Directory -Force applications
Copy-Item -Recurse zephyr/samples/basic/blinky applications/siwx917_blinky_custom

Make a small change in applications/siwx917_blinky_custom/src/main.c, such as changing a log message, LED timing value, or application banner. Keep the initial change simple to make build-time and run-time issues easier to isolate.

Build and flash the copied project:

west build -p=always -b siwx917_rb4338a applications/siwx917_blinky_custom
west flash

4.2 Create a Wi-Fi Custom Project#

Use this approach if the application must include SiWx917 Wi-Fi functionality from the start. The Zephyr Wi-Fi shell sample is a suitable base because it enables interactive scan, connect, disconnect, and network-interface commands.

From the workspace root, run:

mkdir -p applications
cp -r zephyr/samples/net/wifi/shell applications/siwx917_wifi_custom

On Windows PowerShell:

New-Item -ItemType Directory -Force applications
Copy-Item -Recurse zephyr/samples/net/wifi/shell applications/siwx917_wifi_custom

Build and flash the copied Wi-Fi project:

west build -p=always -b siwx917_rb4338a applications/siwx917_wifi_custom
west flash

After the first successful build and flash, make project-specific changes incrementally. Common early modifications include:

  • Adding application logic around Wi-Fi state changes

  • Updating Kconfig options in prj.conf

  • Adding socket or protocol handling after the Wi-Fi connection is established

  • Adding a board overlay when board-specific devicetree changes are required

4.3 Validate Wi-Fi Operation#

Open the serial console and wait for the Zephyr shell prompt. Begin with a scan:

wifi scan

Confirm that nearby 2.4 GHz access points appear. Then connect to a known access point.

wifi connect -s <SSID> -k <key-mgmt> -p <passphrase>

For advanced configurations, including specific security protocols and channels, use the following parameters:

  • -c: Scan channel

  • -p: Passphrase/password for the network

  • -k: Key management type (0: Open, 1: WPA2-PSK, 2: WPA2-PSK-256, 3: SAE)

  • -m: Specify the Access Point's MAC address (BSSID)

After association succeeds, inspect the network interface:

net iface

Add higher-level socket, TLS, or application protocol logic after scanning, association, and IP configuration are confirmed.

5 Troubleshooting Guide#

Begin troubleshooting from the first failure shown in the build log, flash output, boot log, or UART console. Avoid changing several variables at once. Preserve the full command line, Zephyr revision, board target, Kconfig changes, devicetree overlays, Wi-Fi mode, access point configuration, and UART output around the first failing operation.

5.1 Workspace and Environment Issues#

If the application does not build, first confirm that the workspace and tools are complete:

  • Run west update after changing branches, manifests, or revisions.

  • Run west blobs fetch hal_silabs when Silicon Labs blobs or connectivity firmware are required.

  • Confirm that the active Python environment and Zephyr toolchain match the selected release.

  • Confirm that west, CMake, Ninja, and Commander are available in the active shell.

  • Run a pristine build when changing board targets, workspace revisions, or important configuration.

5.2 Build and Configuration Issues#

Build failures are often caused by an incorrect board target, missing Kconfig dependency, invalid devicetree overlay, conflicting networking option, or memory pressure from optional features.

Check the board target first:

west build -p=always -b siwx917_rb4338a <application_path>

For build and config issues, kindly refer to dtdoctor.

For Kconfig errors, inspect the first dependency error in the build output. For devicetree failures, inspect overlays for incorrect node names, disabled peripherals, invalid GPIO references, or properties that do not apply to the selected board. If the image links but is too large, reduce optional logging, shell commands, network buffers, TLS options, or application modules until the memory report fits the target configuration.

5.3 Flashing and Boot Issues#

If flashing fails or the application does not boot:

  • Confirm that the board is powered and connected through the debug interface.

  • Confirm that the selected image came from the intended build directory.

  • Add --serialno <serial_number> to the Commander command if multiple debug probes are attached.

  • Try west flash and direct commander flash separately to distinguish Zephyr runner issues from lower-level device connection issues.

  • Confirm that the UART terminal is attached to the correct COM port and set to 115200 8-N-1.

  • Power cycle or reset the board after flashing if no boot output appears.

5.4 NWP Firmware and Wi-Fi Initialization Issues#

If Wi-Fi commands fail before scan or connection starts, check the NWP firmware and driver initialization path:

  • Confirm that the NWP connectivity firmware was programmed from the same release as the workspace.

  • Re-run west blobs fetch hal_silabs after workspace updates.

  • Rebuild from a pristine build directory after changing Wi-Fi, networking, Bluetooth, or power-management options.

  • Return to the unmodified Wi-Fi shell sample if initialization fails after project-specific changes.

  • Capture UART logs from reset through the first Wi-Fi command.

5.5 Scan, Association, and IP Issues#

If scan, connection, or IP bring-up fails:

  • Confirm that the access point operates on 2.4 GHz. A 5 GHz-only network is not suitable for this test.

  • Confirm SSID, channel, security mode, and passphrase.

  • Confirm that the regulatory domain permits the selected channel.

  • Place the board near the access point while debugging association or DHCP failures.

  • Start with wifi scan before connecting so RF visibility is separated from authentication failures.

  • Run net iface after association to confirm interface state and IP configuration.

If a Soft-AP project is used, verify that the requested band is 2.4 GHz and that the requested bandwidth is 20 MHz. Confirm that clients can associate and receive valid IP configuration before testing application traffic.

5.6 Data Path Issues#

For UDP, TCP, TLS, or application protocol failures, confirm that Wi-Fi is connected and IP configuration is complete before opening sockets. Start the peer endpoint first when the SiWx917 application acts as a client. If throughput or reliability is lower than expected, test in a clean RF environment, keep the access point and peer server on a stable backhaul, and avoid comparing results across different security, power-save, or buffer configurations.