Skip to content

meta-nxp-connectivity-iwxxx-dualpan.md

Latest commit

 

History

History
218 lines (158 loc) · 9.31 KB

meta-nxp-connectivity-iwxxx-dualpan.md

File metadata and controls

218 lines (158 loc) · 9.31 KB

IWxxx Thread & Zigbee Dualpan solution in NXP i.MX Matter

Table of contents

Introduction
IWxxx Dualpan Architecture
IWxxx Zigbee Stack and Examples
Matter to Zigbee Bridge Example

Introduction

The IWxxx NXP chipsets (IW612, IW610) features highly integrated 2.4/5 GHz dual-band 1x1 Wi-Fi 6, Bluetooth/Bluetooth Low Energy 5.4 and 802.15.4 tri-radio single-chip solution
NXP i.MX meta-nxp-connectivity Yocto layer provides Yocto recipes to enable Matter, OpenThread and Zigbee for i.MX MPU
Prerequisite is to follow instructions to first build the complete i.MX Matter image

Following sections specifically describe how to experiment Zigbee & Thread Dualpan features with 3-radio IWxxx NXP chipsets e.g. IW612 or IW610
Dedicated IWxxx Zigbee stack and examples are first introduced
Finally, last section details a complete IWxxx Dualpan example on i.MX: Matter to Zigbee Bridge Application

IWxxx Dualpan Architecture

i.MX Dualpan IWxxx

Thread and Zigbee i.MX Host applications run on top of a SPI Multiplexer daemon called zb_mux
The zb_mux daemon uses i.MX SPI kernel device to exchange Spinel messages with IWxxx Firmware through SPI Bus
The zb_mux daemon also creates two Virtual UART Devices that both Zigbee and Thread applications use to communicate seamlessly with IWxxx Firmware

IWxxx Zigbee Stack and Examples

meta-nxp-connectivity comes with a certified Zigbee stack for IWxxx chipsets
It is provided by a single Yocto recipe:

  • zigbee-rcp-sdk: zb_mux daemon, IWxxx Zigbee Stack header files and static libraries, Linux Systemd services & scripts, IWxxx Zigbee Stack Development Guide documentation, and example applications C source code with CMAKE build files

NOTE: Additional important resources can be accessed from NXP website. It requires login and granted access to these resources: Latest IW612 Zigbee DualPan package is available SD-WLAN-UART-BT-SPI-OT-Zigbee-DualPAN-IW612-LNX_6_12_20-IMX8-18.99.3.p25.7-18.99.3.p25.7-MM6X18537.p9-GPL
It includes: - README_Zboss_package_for_Zigbee.txt - Example applications source code

Zigbee SDK

Once the i.MX Matter image is built, all zigbee-rcp-sdk components can be found in the Yocto build folder
For example, for a MACHINE=imx93evk-iwxxx-matter build, the fetched nxp_zboss_libs_sdk repository is unpacked in ${MY_YOCTO}/bld-xwayland-imx93evk-iwxxx-matter/tmp/work/armv8a-poky-linux/zigbee-rcp-sdk/1.0/sources/zigbee-rcp-sdk-1.0/

zigbee-rcp-sdk recipe goal is to:

  • fetch and build the nxp_zboss_libs_sdk repository which contains the Zigbee Stack and example applications
  • apply patches to add and/or modify example applications (hello, cli_nxp, dualpan_nxp, etc.)
  • install zb_mux daemon and Systemd Zigbee services on the i.MX Root Filesystem
  • install Zigbee header files and static libraries in Yocto build system to build Zigbee example applications
  • install IWxxx Zigbee Stack Development Guide documentation
  • install example application executables in /usr/bin

Zigbee Examples

Example applications are included in the nxp_zboss_libs_sdk repository
The zigbee-rcp-sdk recipe applies patches to add and/or modify example applications

Create a new Zigbee application

To develop a new Zigbee application, follow these steps:

Step 1: Modify the fetched repository

After the initial build, modify the fetched repository directly in the build directory:

cd ${MY_YOCTO}/bld-xwayland-imx93evk-iwxxx-matter/tmp/work/armv8a-poky-linux/zigbee-rcp-sdk/1.0/sources/zigbee-rcp-sdk-1.0

Create your new application files:

mkdir -p examples/my_zigbee_gateway
cat << 'EOF' > examples/my_zigbee_gateway/CMakeLists.txt
#
# Copyright 2026 NXP
#
# NXP Proprietary. This software is owned or controlled by NXP and may only be
# used strictly in accordance with the applicable license terms.
#

cmake_minimum_required(VERSION 3.10.2)

project(my_zigbee_gateway)

# Build my_zigbee_gateway Coordinator executable
add_zigbee_executable(
    NAME my_zigbee_gw_zc
    ROLE COORDINATOR
    SOURCES 
        examples/my_zigbee_gateway/my_gw_zc.c
)
EOF

Create your application source files (my_gw_zc.c, etc.) with your custom implementation

Step 2: Add your application to the build

Edit the main CMakeLists.txt to include your application:

echo "include(\${CMAKE_CURRENT_SOURCE_DIR}/examples/my_zigbee_gateway/CMakeLists.txt)" >> CMakeLists.txt

Step 3: Test the build

Compile and test your application without creating a permanent patch:

cd ${MY_YOCTO}/bld-xwayland-imx93evk-iwxxx-matter
bitbake -fc compile zigbee-rcp-sdk

The application will be built. Transfer the executable to your i.MX target and test:

ls -l tmp/work/armv8a-poky-linux/zigbee-rcp-sdk/1.0/build/my_zigbee_gw_zc

Step 4: Create a patch (once testing is successful)

Once your application is verified on the i.MX target, create a permanent patch similarly as done in existing 0001-Add-new-hello-Zigbee-application.patch

cd ${MY_YOCTO}/sources/meta-nxp-connectivity/meta-nxp-zigbee-rcp/recipes-zigbee-rcp-sdk/files

cat << 'EOF' > 0002-Add-my-zigbee-gateway-application.patch
Upstream-Status: Inappropriate [new application]
From: Your Name <your.email@nxp.com>
Date: <date>
Subject: [PATCH] Add new my_zigbee_gateway application

--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -36,3 +36,4 @@ include(${CMAKE_CURRENT_SOURCE_DIR}/examples/r23_new_api/CMakeLists.txt)
 include(${CMAKE_CURRENT_SOURCE_DIR}/examples/hello/CMakeLists.txt)
 include(${CMAKE_CURRENT_SOURCE_DIR}/examples/cli_nxp/CMakeLists.txt)
 include(${CMAKE_CURRENT_SOURCE_DIR}/examples/dualpan_nxp/CMakeLists.txt)
+include(${CMAKE_CURRENT_SOURCE_DIR}/examples/my_zigbee_gateway/CMakeLists.txt)

--- /dev/null
+++ b/examples/my_zigbee_gateway/CMakeLists.txt
@@ -0,0 +1,18 @@
+#
+# Copyright 2026 NXP
+#
+# NXP Proprietary. This software is owned or controlled by NXP and may only be
+# used strictly in accordance with the applicable license terms.
+#
+
+cmake_minimum_required(VERSION 3.10.2)
+
+project(my_zigbee_gateway)
+
+add_zigbee_executable(
+    NAME my_zigbee_gw_zc
+    ROLE COORDINATOR
+    SOURCES 
+        examples/my_zigbee_gateway/my_gw_zc.c
+)
+
+--- /dev/null
+++ b/examples/my_zigbee_gateway/my_gw_zc.c
@@ -0,0 +1,xx @@
+/* Your application source code */
EOF

Step 5: Add the patch to the recipe

Add the new patch to the recipe file:

cd ${MY_YOCTO}/sources/meta-nxp-connectivity/meta-nxp-zigbee-rcp/recipes-zigbee-rcp-sdk
echo 'SRC_URI += "file://0002-Add-my-zigbee-gateway-application.patch"' >> ../zigbee-rcp-sdk.bb

Step 6: Clean build and rebuild

Perform a clean build to apply the patch:

cd ${MY_YOCTO}/bld-xwayland-imx93evk-iwxxx-matter
bitbake -fc cleanall zigbee-rcp-sdk
bitbake zigbee-rcp-sdk

Step 7: Verify the final build

Verify that your application is in the final install directory:

ls -l tmp/work/armv8a-poky-linux/zigbee-rcp-sdk/1.0/image/usr/bin/my_zigbee_gw_zc

The application is now ready to be deployed on the i.MX target

Matter to Zigbee Bridge Example

MatterZigbeeRcp-bridge application demonstrates the complete Matter example on i.MX93 & IW612
i.MX becomes a Matter to Zigbee Bridge

The i.MX Matter image allows to have a complete Matter Controller on one single i.MX93&IW612 platform:

  • Embedded Posix Openthread BorderRouter manages a Thread network and provides Ethernet or Wi-Fi networks connectivity
  • Matter chip-tool is used to commission and control Matter Wireless End-Devices, either on Wi-Fi or on Thread networks
  • M2ZigbeeRcp-bridge is a Zigbee Coordinator allowing Zigbee End-Devices to join, and transforming them into Matter Bridged End-Devices

NOTE: Both meta-nxp-connectivity native otbr-agent-iwxxx and chip-tool executables are not intended to be modified
M2ZigbeeRcp-bridge is currently an example of a Matter to Zigbee bridge
It is intended to be modified, and its features improved as explained in the dynamic-endpoint-control section