The all-clusters example implements a server which can be accessed by a CHIP controller and can accept basic cluster commands.
The example is based on Project CHIP and the NXP Zephyr SDK, and provides a prototype application that demonstrates device commissioning and different cluster control.
The Zephyr application provides a working demonstration of supported board integration from Zephyr, built using the Project CHIP codebase and the NXP/Zephyr SDK.
The example supports:
The supported boards are:
rd_rw612_bgaIn order to build the Project CHIP example, we recommend using a Linux distribution (the demo-application was compiled on Ubuntu 20.04).
Prerequisites:
$ west init zephyrproject -m https://github.com/nxp-zephyr/nxp-zsdk.git --mr nxp-v3.7.0
Note: While some of NXP platforms are supported in Zephyr upstream, we recommend using nxp-zsdk downstream to get access to all NXP features that are not upstream yet. While you can decide to use nxp-zsdk top of tree, we recommend using a proper release tag delivered by NXP. This will ensure a certain level of quality of the nxp-zsdk in use. Currently, we highly recommend using the
nxp-v3.7.0tag, based on Zephyr 3.7 LTS release. Reach to your NXP contact for more details.
Steps to build the example, targeting rd_rw612_bga board:
source <path to CHIP workspace>/scripts/activate.sh
source <path to zephyr repo>/zephyr-env.sh
west build -b rd_rw612_bga -p auto -d build_zephyr <path to example folder>
A folder build_zephyr will be created in the same folder you run the command from. The binaries will be created in build_zephyr/zephyr with the name zephyr.elf and zephyr.bin. We recommend using the -d build_zephyr if you are building from Matter repo root folder as a build folder already exists and is tracked by git.
You can get more details on west build with Zephyr's building guide
west can be used to flash a target, as an example for rd_rw612_bga board:
west flash -i <J-Link serial number>
You can get more details on west flash with Zephyr's flashing guide
Note:
west flashwill not start a debug session, it will only flash and reset the device
To debug a Matter with Zephyr application, you could use several methods:
Note: As the build provides an elf file, any compatible debugging tool can be used.
NXP Zephyr examples are not using factory data support by default. Please refer the the section below to build with factory data.
You may refer to src/platform/nxp/zephyr/boards/<board>/<board>.overlay file to obtain the memory region used by this partition.
For example, the factory data partition on rd_rw612_bga is reserved in the last sector of the flexspi flash of RD BGA board, at 0x1BFFF000.
&flexspi {
status = "okay";
mx25u51245g: mx25u51245g@0 {
...
factory_partition: partition@3FFF000 {
label = "factory-data";
reg = <0x03FFF000 DT_SIZE_K(4)>;
};
};
};
Note: You may also refer to
src/platform/nxp/zephyr/boards/<board>/<board>.overlayfile to check other memory partitions used by the platform, such as the file system partition mentioned with thestoragelabel.
To build the example with factory data support, you can add -DFILE_SUFFIX=fdata in the west build command line.
Example:
west build -b rd_rw612_bga -p <path to example folder> -- -DFILE_SUFFIX=fdata
prj_fdata.conf configuration file will enable CONFIG_CHIP_FACTORY_DATA Kconfig so the application will load the factory data at boot.
The factory data can be generated automatically during the build of the application. To do so, you can use the configuration CONFIG_CHIP_FACTORY_DATA_BUILD=y in prj_fdata.conf.
You will have to specify the source of the certificates to be used for the factory data. Please refer to CHIP_FACTORY_DATA_CERT_SOURCE Kconfig for more info.
Note: The application demonstrates the usage of encrypted Matter factory data storage. Matter factory data should be encrypted using an AES 128 software key before flashing them to the device flash. You can encrypt the factory data automatically during the build by enabling
CHIP_ENCRYPTED_FACTORY_DATAKconfig. See alsoCHIP_ENCRYPTED_FACTORY_DATA_AES128_KEYKconfig if you want to use a specific key.
The resulting factory data will be provided along zephyr.bin as a binary file named factory_data.bin. In order to flash it to your device, you need to know the partition address: please refer to factory_partition defined in src/platform/nxp/zephyr/boards/<board>/<board>.overlay.
See Guide for writing manufacturing data on NXP devices
See Guide for OTA Software Update on NXP devices using Zephyr SDK
To know how to commission a device over BLE, follow the instructions from chip-tool's README.md ‘Commission a device over BLE’.
Some Matter examples for the development kits from NXP include a command-line interface that allows access to application logs and Zephyr shell.
Depending on the platform, the CLI console and the logs can be split on two different interfaces.
You may refer to boards/<board name>.overlay file to check how the board is configured for the example. The binding zephyr,console is used to print the logs, while the binding zephyr,shell-uart is used for the CLI. If the logs and the CLI are split among two serial interfaces, you will have to open both ports.
As an example, the Matter CLI on rd_rw612_bga is configured to be output on flexcomm3 with a baudrate of 115200. The logs are configured to be output on flexcomm0 with a baudrate of 115200.
Note:
flexcomm3is wired to the USBFTDIport of theRD BGAboard by default.flexcomm0is wired toGPIO2(RX) andGPIO3(TX). Those pins are accessible onHD2pin header.
To access the CLI console, use a serial terminal emulator of your choice, like Minicom or GNU Screen. Use the baud rate set to 115200.
For example, to start using the CLI console with Minicom, run the following command with /dev/ttyACM0 replaced with the device node name of your development kit:
minicom -D /dev/ttyACM0 -b 115200
When you reboot the kit, you will see the boot logs in the console, similar to the following messages:
uart:~$ MAC Address: C0:95:DA:00:00:6E ... wlan-version wlan-mac wlan-thread-info wlan-net-stats ... *** Booting Zephyr OS build zephyr-v3.4.0-187-g2ddf1330209b *** I: Init CHIP stack ...
This means that the console is working correctly and you can start using shell commands. For example, issuing the kernel threads command will print information about all running threads:
uart:~$ kernel threads Scheduler: 277 since last call Threads: 0x20006518 CHIP options: 0x0, priority: -1 timeout: 536896912 state: pending stack size 8192, unused 7256, usage 936 / 8192 (11 %) 0x20004ab0 SDC RX options: 0x0, priority: -10 timeout: 536890152 state: pending stack size 1024, unused 848, usage 176 / 1024 (17 %) ...
To list all available commands, use the Tab key, which is normally used for the command completion feature.
Pressing the Tab key in an empty command line prints the list of available commands:
uart:~$ clear device help history hwinfo kernel matter resize retval shell
Pressing the Tab key with a command entered in the command line cycles through available options for the given command.
You can also run the help command:
uart:~$ help Please press the <Tab> button to see all available commands. You can also use the <Tab> button to prompt or auto-complete all commands or its subcommands. You can try to call commands with <-h> or <--help> parameter for more information. Shell supports following meta-keys: Ctrl + (a key from: abcdefklnpuw) Alt + (a key from: bf) Please refer to shell documentation for more details. Available commands: clear :Clear screen. device :Device commands help :Prints the help message. history :Command history. hwinfo :HWINFO commands kernel :Kernel commands matter :Matter commands resize :Console gets terminal screen size or assumes default in case the readout fails. It must be executed after each terminal width change to ensure correct text display. retval :Print return value of most recent command shell :Useful, not Unix-like shell commands.
kernel command groupreboot subcommandPerforms either a warm or cold reset. Difference between warm and cold resets may vary from a platform to another, but on default Cortex-M architectures, both methods are the same, so use either one if nothing is specific to your platform.
uart:~$ kernel reboot cold|warm
The NXP Zephyr examples let you use several Matter-specific CLI commands.
These commands are not available by default and to enable using them, set the CONFIG_CHIP_LIB_SHELL=y Kconfig option in the prj.conf file of the given example.
Every invoked command must be preceded by the matter prefix.
See the following subsections for the description of each Matter-specific command.
device command groupHandles a group of commands that are used to manage the device. You must use this command together with one of the additional subcommands listed below.
factoryreset subcommandPerforms device factory reset that is hardware reset preceded by erasing of the whole Matter settings stored in a non-volatile memory.
uart:~$ matter device factoryreset Performing factory reset ...
onboardingcodes command groupHandles a group of commands that are used to view information about device onboarding codes. The onboardingcodes command takes one required parameter for the rendezvous type, then an optional parameter for printing a specific type of onboarding code.
The full format of the command is as follows:
onboardingcodes none|softap|ble|onnetwork [qrcode|qrcodeurl|manualpairingcode]
none subcommandPrints all onboarding codes. For example:
uart:~$ matter onboardingcodes none QRCode: MT:W0GU2OTB00KA0648G00 QRCodeUrl: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AW0GU2OTB00KA0648G00 ManualPairingCode: 34970112332
none qrcode subcommandPrints the device onboarding QR code payload. Takes no arguments.
uart:~$ matter onboardingcodes none qrcode MT:W0GU2OTB00KA0648G00
none qrcodeurl subcommandPrints the URL to view the device onboarding QR code in a web browser. Takes no arguments.
uart:~$ matter onboardingcodes none qrcodeurl https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AW0GU2OTB00KA0648G00
none manualpairingcode subcommandPrints the pairing code for the manual onboarding of a device. Takes no arguments.
uart:~$ matter onboardingcodes none manualpairingcode 34970112332
config command groupHandles a group of commands that are used to view device configuration information. You can use this command without any subcommand to print all available configuration data or to add a specific subcommand.
uart:~$ matter config VendorId: 65521 (0xFFF1) ProductId: 32768 (0x8000) HardwareVersion: 1 (0x1) FabricId: PinCode: 020202021 Discriminator: f00 DeviceId:
The config command can also take the subcommands listed below.
pincode subcommandPrints the PIN code for device setup. Takes no arguments.
uart:~$ matter config pincode 020202021
discriminator subcommandPrints the device setup discriminator. Takes no arguments.
uart:~$ matter config discriminator f00
vendorid subcommandPrints the vendor ID of the device. Takes no arguments.
uart:~$ matter config vendorid 65521 (0xFFFF1)
productid subcommandPrints the product ID of the device. Takes no arguments.
uart:~$ matter config productid 32768 (0x8000)
hardwarever subcommandPrints the hardware version of the device. Takes no arguments.
uart:~$ matter config hardwarever 1 (0x1)
deviceid subcommandPrints the device identifier. Takes no arguments.
fabricid subcommandPrints the fabric identifier. Takes no arguments.
ble command groupHandles a group of commands that are used to control the device Bluetooth LE transport state. You must use this command together with one of the additional subcommands listed below.
help subcommandPrints help information about the ble command group.
uart:~$ matter ble help help Usage: ble <subcommand> adv Enable or disable advertisement. Usage: ble adv <start|stop|state>
adv start subcommandEnables Bluetooth LE advertising.
uart:~$ matter ble adv start Starting BLE advertising
adv stop subcommandDisables Bluetooth LE advertising.
uart:~$ matter ble adv stop Stopping BLE advertising
adv status subcommandPrints the information about the current Bluetooth LE advertising status.
uart:~$ matter ble adv state BLE advertising is disabled
dns command groupHandles a group of commands that are used to trigger performing DNS queries. You must use this command together with one of the additional subcommands listed below.
browse subcommandBrowses for DNS services of _matterc_udp type and prints the received response. Takes no argument.
uart:~$ matter dns browse Browsing ... DNS browse succeeded: Hostname: 0E824F0CA6DE309C Vendor ID: 9050 Product ID: 20043 Long discriminator: 3840 Device type: 0 Device name: Commissioning mode: 0 IP addresses: fd08:b65e:db8e:f9c7:2cc2:2043:1366:3b31
resolve subcommandResolves the specified Matter node service given by the fabric-id and node-id.
uart:~$ matter dns resolve fabric-id node-id Resolving ... DNS resolve for 000000014A77CBB3-0000000000BC5C01 succeeded: IP address: fd08:b65e:db8e:f9c7:8052:1a8e:4dd4:e1f3 Port: 5540
stat command groupHandles a group of commands that are used to get and reset the peak usage of critical system resources used by Matter. These commands are only available when the CONFIG_CHIP_STATISTICS=y Kconfig option is set.
peak subcommandPrints the peak usage of system resources.
uart:~$ matter stat peak Packet Buffers: 1 Timers: 2 TCP endpoints: 0 UDP endpoints: 1 Exchange contexts: 0 Unsolicited message handlers: 5 Platform events: 2
reset subcommandResets the peak usage of system resources.
uart:~$ matter stat reset