Matter ESP32 Lighting Example (Zephyr)#

This example demonstrates the Matter Lighting application on the ESP32-C6 running Zephyr RTOS, with Wi-Fi transport and BLE commissioning.

Supported Hardware#

Board	SoC	Transport
`esp32c6_devkitc/esp32c6/hpcore`	ESP32-C6	Wi-Fi (2.4 GHz), BLE setup

The light output is GPIO2 (led0 alias in the board overlay).

Prerequisites#

Follow BUILDING.md to set up the Matter environment.
Install the Zephyr SDK (toolchain, version 1.0.1 or newer; separate from the Zephyr RTOS version below) as described in the Zephyr Getting Started Guide.
Build chip-tool.

The Zephyr RTOS version used here is v4.4.2. It requires Python 3.12 or newer, so it uses its own venv.

Setting up the Zephyr workspace#

export ZEPHYR_WORKSPACE=~/zephyr-4.4.2   # west workspace
export CHIP=~/connectedhomeip             # this repository

mkdir -p "$ZEPHYR_WORKSPACE" && cd "$ZEPHYR_WORKSPACE"
west init -m https://github.com/zephyrproject-rtos/zephyr --mr v4.4.2 .
west update
west blobs fetch hal_espressif

python3 -m venv "$ZEPHYR_WORKSPACE/.venv"
"$ZEPHYR_WORKSPACE/.venv/bin/pip" install west esptool
"$ZEPHYR_WORKSPACE/.venv/bin/pip" install -r "$ZEPHYR_WORKSPACE/zephyr/scripts/requirements.txt"
"$ZEPHYR_WORKSPACE/.venv/bin/pip" install \
    -r "$CHIP/scripts/setup/requirements.build.txt" \
    -r "$CHIP/scripts/setup/requirements.zephyr.txt"

Setting up the build environment#

In every new terminal, activate the Matter environment first, then the Zephyr venv so that its Python and west come first on PATH:

source "$CHIP/scripts/activate.sh"
source "$ZEPHYR_WORKSPACE/.venv/bin/activate"
source "$ZEPHYR_WORKSPACE/zephyr/zephyr-env.sh"

TODO: The Matter environment ships Python 3.11, so scripts/activate.sh alone cannot run this build. Drop the separate venv once it moves to 3.12.

Note: west: unknown command "build" means zephyr-env.sh was not sourced in this terminal. If which west points to the Matter .environment, the Zephyr venv was activated before scripts/activate.sh.

Building the example#

cd "$CHIP/examples/lighting-app/esp32_zephyr"
west build -b esp32c6_devkitc/esp32c6/hpcore

Pristine build (after changing Kconfig or board files):

west build -p always -b esp32c6_devkitc/esp32c6/hpcore

Using the helper script:

export ESP32_ZEPHYR_BASE="$ZEPHYR_WORKSPACE/zephyr"
scripts/examples/esp32_zephyr_example.sh lighting-app esp32c6_devkitc/esp32c6/hpcore

Using build_examples.py:

export ESP32_ZEPHYR_BASE="$ZEPHYR_WORKSPACE/zephyr"
export ESP32_ZEPHYR_VENV="$ZEPHYR_WORKSPACE/.venv"
scripts/run_in_build_env.sh \
    "./scripts/build/build_examples.py --target esp32-zephyr-c6devkitc-light build"

Wi-Fi only build (no BLE, provisioned from the Zephyr shell):

west build -b esp32c6_devkitc/esp32c6/hpcore -- -DCONFIG_BT=n -DCONFIG_SHELL=y -DCONFIG_NET_L2_WIFI_SHELL=y -DCONFIG_NET_SHELL=y

uart:~$ wifi connect "MyNetwork" -p "MyPassword" -k 1

Configure options with menuconfig:
```
west build -t menuconfig
```

Flashing and Monitoring#

west flash --esp-device /dev/ttyUSB0
west espressif monitor -p /dev/ttyUSB0 -e build/zephyr/zephyr.elf

Note: Keep only one process open on the serial port.

Commissioning and Control#

The example uses the test passcode 20202021 and discriminator 3840.

Commission over BLE-Wi-Fi:

./out/linux-x64-chip-tool/chip-tool pairing ble-wifi <NODE ID> <SSID> <PASSWORD> 20202021 3840

Commission on-network (Wi-Fi only build):

./out/linux-x64-chip-tool/chip-tool pairing onnetwork <NODE ID> 20202021

Control the light:

./out/linux-x64-chip-tool/chip-tool onoff on <NODE ID> 1
./out/linux-x64-chip-tool/chip-tool onoff off <NODE ID> 1
./out/linux-x64-chip-tool/chip-tool onoff read on-off <NODE ID> 1

Limitations#

Uses test attestation credentials; factory data is not enabled.
No OTA support.
Only a single GPIO light output; no buttons or status LEDs.

Matter ESP32 Lighting Example (Zephyr)

Contents