Matter: Light switch
This light switch sample demonstrates the usage of the Matter application layer to build a switch device that binds with lighting devices and changes the state of their LEDs. When configured together with the Matter light bulb sample (or other lighting sample) and when using a Matter controller, the light switch can control one light bulb directly or a group of light bulbs remotely over a Matter network built on top of a low-power, 802.15.4 Thread, or on top of a Wi-Fi® network.
This device works as a Matter accessory device, meaning it can be paired and controlled remotely over a Matter network built on top of a low-power 802.11ax (Wi-Fi® 6) or 802.15.4 (Thread) protocol.
In case of Thread, this device works as a Thread Sleepy End Device.
In case of Wi-Fi, this device works in the Legacy Power Save mode. This means that the device sleeps most of the time and wakes up on each Delivery Traffic Indication Message (DTIM) interval to poll for pending messages.
You can use this sample as a reference for creating your own application. See the Adding clusters to Matter application page for an overview of the process you need to follow.
Requirements
The sample supports the following development kits:
Hardware platforms |
PCA |
Board name |
Shields |
|
|---|---|---|---|---|
PCA10184 |
|
|
||
PCA10156 |
|
|||
PCA10095 |
|
|||
PCA10056 |
|
If you want to commission the Light switch device and control it remotely through a Thread or Wi-Fi network, you need to set-up the Thread Border Router (Matter over Thread only) and control it with the chip-tool, or use a commercial ecosystem controller. When this happens, you will also be able to control it through a Matter controller device configured on PC or smartphone. This requires additional hardware depending on the setup you choose.
Note
Matter requires the GN tool. If you are updating from the nRF Connect SDK version earlier than v1.5.0, see the GN installation instructions.
IPv6 network support
The following development kits for this sample offer IPv6 network support for Matter:
Matter over Thread is supported for the
nrf52840dk/nrf52840,nrf5340dk/nrf5340/cpuapp,nrf54l15dk/nrf54l15/cpuapp,nrf54lm20dk/nrf54lm20b/cpuapp, andnrf54lm20dk/nrf54lm20a/cpuappboard targets.Matter over Wi-Fi is supported for the
nrf54lm20dk/nrf54lm20b/cpuappandnrf54lm20dk/nrf54lm20a/cpuappboard targets with thenrf7002eb2shield attached.
For this sample to work, you also need at least one Matter light bulb sample programmed to another supported development kit.
Overview
The sample controls the state of the state-indication LED on connected light bulbs devices. After configuring the light switch sample, the lighting devices get proper Access Control List from the Matter controller to start receiving commands sent from the light switch. Then, the light switch device prepares a new binding table to be able to discover light bulb devices and perform Binding.
After the binding is complete, the application can control the state of the connected lighting devices in one of the following ways:
With a single light bulb, it uses a Certificate-Authenticated Session Establishment session (CASE session) for direct communication with the single light bulb.
With a group of light bulbs, it uses multicast messages sent through the IPv6 network using Group communication with all light bulbs in the group.
Light switch features
The light switch sample implements the following features:
Access Control List - The light switch can control the state of the connected lighting devices.
Group communication - The light switch can control a group of lighting devices.
Binding - The light switch can bind with the lighting devices to be able to control them.
LIT ICD - The light switch can be used as an Intermittently Connected Device (ICD) with a Long Idle Time (LIT).
Use the click to show toggle to expand the content.
Access Control List
The Access Control List (ACL) is a list related to the Access Control cluster. The list contains rules for managing and enforcing access control for a node’s endpoints and their associated cluster instances. In this sample’s case, this allows the lighting devices to receive messages from the light switch and run them.
For more details about ACLs, see the Access Control Guide in the Matter documentation.
Group communication
Group communication (groupcast or multicast) refers to messages and commands sent to the address of a group that includes multiple devices with the same Groups cluster.
The cluster manages the content of a node-wide Group Table that is part of the underlying interaction layer.
This is done for each endpoint.
After creating the Group cluster with specific ID and Name, a device gets its own IPv6 multicast address and is ready to receive groupcast commands.
In this sample, the binding device can create a groupcast message and send it to the chosen IPv6 multicast address. This allows the binding device to control multiple bound devices simultaneously.
Note
Writing the groupcast table on the devices blocks sending unicast commands. If you want to return to the original state, perform a factory reset of the device.
Binding
Binding refers to establishing a relationship between endpoints on the local and remote nodes. With binding, local endpoints are pointed and bound to the corresponding remote endpoints. Both must belong to the same cluster type. Binding lets the local endpoint know which endpoints are the target for the client-generated actions on one or more remote nodes.
In this sample, the Light switch controls one or more bound devices, but does not know their remote endpoints (on remote nodes). Using binding, the Light switch device updates its Binding cluster with all relevant information about the bound devices, such as their IPv6 address, node ID, and the IDs of the remote endpoints that contain the supported clusters, respectively.
ICD LIT device type
The device works as a Matter Intermittently Connected Device (ICD) with a Long Idle Time (LIT). The device starts operation in the Short Idle Time (SIT) mode and remains in it until it is commissioned to the Matter fabric and registers the first ICD client. It then switches the operation mode to LIT to reduce the power consumption.
In the LIT mode, the device is less responsive than in the SIT mode. However, you can request the device to become responsive, for example, to change its configuration. Press the Third Button to use the User Active Mode Trigger (UAT) feature.
See the User interface section for information on how to switch the operation modes.
Configuration
This section describes the configuration options for the sample.
See Configuring and building for information about how to permanently or temporarily change the configuration.
The sample uses a prj.conf configuration file located in the sample root directory for the default configuration.
It also provides additional files for different custom configurations.
When you build the sample, you can select one of these configurations using the FILE_SUFFIX variable.
See Custom configurations and Providing CMake options for more information.
Note
If you are working with multiple devices, set a unique discriminator for each one, or commission them one at a time. See Matter device identification for more information.
The sample supports the following build configurations:
Configuration |
File name |
FILE_SUFFIX |
Supported board |
Description |
|---|---|---|---|---|
Debug (default) |
|
No suffix |
All from Requirements |
Debug version of the application. Enables additional features for verifying the application behavior, such as logs. |
Release |
|
|
All from Requirements |
Release version of the application. Enables only the necessary application functionalities to optimize its performance. |
Internal memory only |
— |
|
nRF54LM20 DK |
Debug version of the application with external flash disabled. Enables the Light switch to work using internal memory only. |
Advanced configuration options
This section describes advanced configuration options that you can apply in this sample.
Use the click to show toggle to expand the content.
Support for Trusted Firmware-M
The sample supports using Trusted Firmware-M on the nrf54l15dk/nrf54l15/cpuapp board target.
The memory map of the sample has been aligned to meet the TF-M partition alignment requirements.
To build the sample with Trusted Firmware-M support, add the ns suffix to the nrf54l15dk/nrf54l15/cpuapp board target board target, and use the FILE_SUFFIX=tfm variable:
When building with nRF Connect for VS Code, complete the following steps:
set the board target to include the
nssuffix (for examplenrf54l15dk/nrf54l15/cpuapp/ns) in your build configuration.Add
-DFILE_SUFFIX=tfmto Extra CMake arguments in your build configuration.
west build -p -b nrf54l15dk/nrf54l15/cpuapp/ns -DFILE_SUFFIX=tfm
Device firmware upgrade support
The sample supports device firmware upgrade (DFU) over-the-air (OTA) using the following protocols:
Matter OTA update protocol that uses the Matter operational network for querying and downloading a new firmware image.
Simple Management Protocol (SMP) over Bluetooth® LE. In this case, the DFU can be done either using a smartphone application or a PC command-line tool. This protocol is not part of the Matter specification.
In both cases, the MCUboot secure bootloader is used to apply the new firmware image.
The DFU over Matter is enabled by default.
Additionally, you can enable the DFU over SMP by using the -DCONFIG_CHIP_DFU_OVER_BT_SMP=y build flag.
See Providing CMake options for instructions on how to add these options to your build.
The following platforms require external flash memory to perform the DFU:
nRF52840 DK
nRF5340 DK
nRF54L10 DK
You can run DFU without external flash memory on the nRF54L15 and nRF54LM20 DKs using the MCUboot image compression feature.
To see if the sample supports this feature, check whether the internal build configuration is available in the build configuration table.
When building with nRF Connect for VS Code, add your desired dfu_build_flag to Extra CMake arguments.
For example add -DCONFIG_CHIP_DFU_OVER_BT_SMP=y to enable DFU over BT SMP.
When building on the command line, run the following command with board_target replaced with the board target name of the hardware platform you are using (see Requirements), and dfu_build_flag replaced with the desired DFU build flag:
west build -b board_target -- dfu_build_flag
For example:
west build -b nrf54l15dk/nrf54l15/cpuapp -- -DCONFIG_CHIP_DFU_OVER_BT_SMP=y
Factory data support
In this sample, factory data support specific to the nRF Connect SDK is enabled by default for all configurations. This means that a new factory data set will be automatically generated when building for the target board.
To disable factory data support, set the following Kconfig options to n:
To learn more about factory data, read the Factory provisioning in Matter user guide.
Custom board with Nordic SoC
To prepare the sample to work with a custom board, complete the following steps:
Refer to the Create your board directory Zephyr guide and create your board directory.
Modify the contents of the
board.yamlfile according to the Write your board YAML user guide.Update the Write your devicetree (all .dts and .dtsi files) to match your board’s requirements.
Write Kconfig files to enable all required Kconfig options for your board.
If you want to build your custom board with nRF70 Wi-Fi support, set the
CONFIG_CHIP_WIFIandSB_CONFIG_WIFI_NRF70Kconfig options toy.If your device uses external flash, add its devicetree definition under the
board/<board_name>_<soc_name>.overlayfile, and setnordic,pm-ext-flashin the devicetree’schosenconfiguration.Refer to the Advanced Matter Kconfig options user guide, create your list of advanced configurations for your board, and apply the selected Kconfig options in the
prj.conffile.See the list of threads used in Matter application and adjust stack sizes according to your board and project requirements.
A custom board does not have support for LEDs and buttons by default. Therefore, you need to provide your own implementation of the
nrf/samples/matter/common/src/board/board.cppboard file.
For more information, see the following guides:
Board Porting Guide and Custom Board, Devicetree and SOC Definitions to learn how to create a custom board directory.
Optimizing memory usage in Matter applications to learn how to optimize memory on your board.
Advanced Matter Kconfig options to learn about Matter configuration.
Matter hardware and memory requirements to learn about hardware requirements for Nordic Development Kits and to use as a reference when planning your custom board.
Internal memory only
For the nRF54LM20 DK, you can configure the sample to use only the internal RRAM for storage. It applies to the DFU as well, which means that both the currently running firmware and the new firmware to be updated will be stored within the device’s internal RRAM memory.
The DFU image fits in the internal flash memory if you use MCUboot image compression.
This configuration is disabled by default for the Matter Light switch sample.
To enable it, set the FILE_SUFFIX CMake option to internal.
To build the sample for the nRF54LM20 DK with support for Matter OTA DFU and DFU over Bluetooth SMP, and using internal RRAM only:
Add -DCONFIG_CHIP_DFU_OVER_BT_SMP=y -DFILE_SUFFIX=internal to Extra CMake arguments in your build configuration.
west build -p -b nrf54lm20dk/nrf54lm20b/cpuapp -- -DCONFIG_CHIP_DFU_OVER_BT_SMP=y -DFILE_SUFFIX=internal
To build the sample for the same purpose in the release configuration:
Add -DCONFIG_CHIP_DFU_OVER_BT_SMP=y -DFILE_SUFFIX=internal -D<sample_name>_EXTRA_CONF_FILE=prj_release.conf to Extra CMake arguments in your build configuration, replacing <sample_name> with the actual sample name (for example light_bulb or matter_bridge).
Replace <sample_name> with the actual sample name and run:
west build -p -b nrf54lm20dk/nrf54lm20b/cpuapp -- -DCONFIG_CHIP_DFU_OVER_BT_SMP=y -DFILE_SUFFIX=internal -D<sample_name>_EXTRA_CONF_FILE=prj_release.conf
In this case, the size of the MCUboot secondary partition used for storing the new application image is approximately 30-40% smaller than it would be when using a configuration with external flash memory support.
LIT ICD support
To enable the Long Idle Time (LIT) support:
Add -DEXTRA_CONF_FILE=icd_lit.conf to Extra CMake arguments in your build configuration.
Run the following command with board_target replaced with the board target name:
west build -b board_target -p -- -DEXTRA_CONF_FILE=icd_lit.conf
User interface
This section describes the user interface available on the development kit in this sample.
Development kit interface
This sample implements the following interface available on a development kit. While reading the names, refer to the Buttons and LEDs map.
- First LED:
Shows the overall state of the device and its connectivity. The following states are possible:
Short Flash On (50 ms on/950 ms off) - The device is in the unprovisioned (unpaired) state and is waiting for a commissioning application to connect.
Rapid Even Flashing (100 ms on/100 ms off) - The device is in the unprovisioned state and a commissioning application is connected over Bluetooth LE.
Solid On - The device is fully provisioned.
- Second LED:
The LED starts blinking evenly (500 ms on/500 ms off) when the Identify command of the Identify cluster is received on the endpoint
1. The command’s argument can be used to specify the duration of the effect.- First Button:
Depending on how long you press the button:
If pressed for less than three seconds:
If the device is not provisioned to the Matter network, it initiates the Simple Management Protocol (SMP) server and Bluetooth LE advertising for Matter commissioning. After that, the Device Firmware Update (DFU) over Bluetooth Low Energy can be started. Bluetooth LE advertising makes the device discoverable over Bluetooth LE for the predefined period of time (1 hour by default).
If the device is already provisioned to the Matter network, it re-enables the SMP server. After that, the DFU over Bluetooth Low Energy can be started.
If pressed for more than three seconds, it initiates the factory reset of the device. Releasing the button within three seconds of the initiation cancels the factory reset procedure.
- Second Button:
Controls the light on the bound lighting device. Depending on how long you press the button:
If pressed for less than 0.5 seconds, it changes the light state to the opposite one on the bound lighting device (light bulb).
If pressed for more than 0.5 seconds, it changes the brightness of the light on the bound lighting bulb device (light bulb). The brightness is changing from 0% to 100% with 1% increments every 300 milliseconds as long as the Second Button is pressed.
- Third Button:
Functions as the User Active Mode Trigger (UAT) button. For more information about Intermittently Connected Devices (ICD) and User Active Mode Trigger, see the Enable Matter Intermittently Connected Devices support documentation section.
Note
To use this functionality, enable the LIT ICD support. ICD and UAT functionality is currently supported only for Matter over Thread.
- SEGGER J-Link USB Port:
Used for getting logs from the device or for communicating with it through the command-line interface.
- NFC port with antenna attached:
Optionally used for obtaining the onboarding information from the Matter accessory device to start the commissioning the device procedure while using a commercial ecosystem. See the Testing with commercial ecosystem section.
Matter CLI commands
You can use a series of commands to control the light switch device. These commands can be sent to one device (unicast) or a group of devices (groupcast).
Unicast commands
You can use the following commands for direct communication with the single lighting device:
- switch onoff on
This command turns on the state-indication LED on the bound lighting device. For example:
uart:~$ matter switch onoff on
- switch onoff off
This command turns off the state-indication LED on the bound lighting device. For example:
uart:~$ matter switch onoff off
- switch onoff toggle
This command changes the state of the state-indication LED to the opposite state on the bound lighting device. For example:
uart:~$ matter switch onoff toggle
Groupcast commands
You can use the following commands a group of devices that are programmed with the Light Switch Example application by using the Matter CLI:
- switch groups onoff on
This command turns on the state-indication LED on each bound lighting device connected to the same group. For example:
uart:~$ matter switch groups onoff on
- switch groups onoff off
This command turns off the state-indication LED on each bound lighting device connected to the same group. For example:
uart:~$ matter switch groups onoff off
- switch groups onoff toggle
This command changes the state of the state-indication LED to the opposite state on each bound lighting device connected to the same group. For example:
uart:~$ matter switch groups onoff toggle
Building and running
This section describes how to build the sample and commission it to the Matter network.
This sample can be found under samples/matter/light_switch in the nRF Connect SDK folder structure.
To build the sample, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.
Note
When building repository applications in the SDK repositories, building with sysbuild is enabled by default.
If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.
When building this sample with Sysbuild for an SoC that has a network core, the IPC radio firmware is automatically applied to the build.
The IPC radio is one of the companion components in the nRF Connect SDK and allows to use the radio peripheral from another core in a multicore device.
If needed, you can modify the IPC radio configuration in the prj.conf source file in the sample’s sysbuild/ipc_radio directory.
Before starting the commissioning procedure, make sure that the device is discoverable over Bluetooth LE. The device becomes discoverable automatically upon the device startup, but only for a predefined period of time (one hour by default). If the Bluetooth LE advertising times out, enable it again.
Advanced building options
This section describes advanced building options that you can use with this sample.
Use the click to show toggle to expand the content.
Building the Matter over Wi-Fi variant on nRF54LM20 DK with nRF7002-EB II shield
To build the Matter over Wi-Fi sample variant on nRF54LM20 DK with nRF7002-EB II attached, perform the following actions depending on the build tool:
When building an application as described in the nRF Connect for VS Code documentation, follow the steps for setting up the build configuration.
In the Add Build Configuration screen, click the Add argument button under the Extra CMake argument section.
Add the following Kconfig options:
-DSHIELD=nrf7002eb2 -DSB_CONFIG_WIFI_NRF70=y -DCONFIG_CHIP_WIFI=y
Use one of the following options:
west with the following command (
nrf54lm20aSoC variant is also supported):
west build -p -b nrf54lm20dk/nrf54lm20b/cpuapp -- -DSHIELD=nrf7002eb2 -DSB_CONFIG_WIFI_NRF70=y -DCONFIG_CHIP_WIFI=y
CMake with the following command:
cmake -GNinja -Bbuild -DBOARD=nrf54lm20dk/nrf54lm20b/cpuapp -DSHIELD=nrf7002eb2 -DSB_CONFIG_WIFI_NRF70=y -DCONFIG_CHIP_WIFI=y -DAPP_DIR=*app_path* *path_to_zephyr*/share/sysbuild
ninja -C build
Flashing the Matter over Wi-Fi sample variant
In the Matter over Wi-Fi variant of this sample, the portion of the application code related to the nRF70 Series Wi-Fi firmware is stored in the external memory. When you program the sample onto your development kit, the build process automatically includes the Wi-Fi firmware patch and programs it into the external memory.
By default, using the west flash command erases the entire external flash memory before writing the new Wi-Fi firmware patch.
This full-chip erase ensures that the patch is written to a clean memory area, but it can significantly increase the programming time - sometimes taking several minutes, especially if the external flash is large.
To optimize the programming process and reduce the time required, you can instruct west flash to erase only the specific memory ranges that will be overwritten by the Wi-Fi firmware patch.
This is done by adding the --ext-erase-mode=ranges argument to the command.
With this option, only the necessary sections of external memory are erased, making the programming process faster.
To speed up programming, use the Flash button instead of Erase and Flash to Board in the Actions View. Using Erase and Flash to Board erases the entire external flash and can take several minutes.
Run the following command to program the sample and minimize the erase time:
west flash --ext-erase-mode=ranges
To disable storing the Wi-Fi firmware patch in the external memory, complete the following steps:
Remove the Wi-Fi firmware patch partition from the partition list.
Set the
SB_CONFIG_WIFI_PATCHES_EXT_FLASH_STOREKconfig option ton.Set the
SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_WIFI_FW_PATCHKconfig option ton.Set the
SB_CONFIG_MCUBOOT_UPDATEABLE_IMAGESKconfig option to2.
To learn more about the Wi-Fi firmware patch, see the Adding nRF70 Series firmware patch partitions user guide.
Testing
This section shows how to test the sample. You can test it using your PC and the CHIP Tool for Linux or macOS or commercial ecosystem that supports Matter.
Testing with CHIP Tool
Complete the following steps to test the Light switch device using CHIP Tool:
Note
In this guide, the light bulb device’s node ID is 1 and the light switch device’s node ID is 2.
Prepare Matter network
To set up the Matter over Thread, complete the following steps:
Configure the Thread Border Router. See the Running OTBR using Docker section on the Thread Border Router page.
Download the prebuilt CHIP tool package from the Matter nRF Connect releases GitHub page. Make sure that the package is compatible with your nRF Connect SDK version.
Prepare your DK
To flash your DK with the sample and prepare it for testing, complete the following steps:
Connect the kit to the computer using a USB cable. The kit is assigned a serial port. Serial ports are referred to as COM ports on Windows, /dev/ttyACM devices on Linux, and /dev/tty devices on macOS. To list Nordic Semiconductor devices connected to your computer together with their serial ports, open a terminal and run the
nrfutil device listcommand. Alternatively, check your operating system’s device manager or its equivalent.Open a serial port connection to the kit using a terminal emulator that supports VT100/ANSI escape characters (for example, the Serial Terminal app). See Testing and optimization for the required settings and steps.
If the device was not erased during the programming, perform the factory reset procedure.
To restore the device settings and state to its factory set press the First Button for six seconds to initiate the factory reset of the device.
Commission to Matter network
To commission the device to the Matter network complete the following steps:
Obtain a Thread active dataset from OTBR:
Connect to the Raspberry Pi through USB or SSH.
Run the following commands:
sudo ot-ctl > dataset active -x
Run the following command:
sudo docker exec -it otbr sh -c "ot-ctl dataset active -x"The output should look like:
080000000000000000000300001735060004001fffe00208deadbeefcafe12340708fd123456789abc00000510112233445566778899aabbccddeeff00030a54657374576f726b3031010211220410aabbccddeeff00112233445566778899aa0c0402a0f7f8 Done
Run the following command and fill the <thread dataset> argument obtain in the previous step:
chip-tool pairing ble-thread 2 hex:<thread dataset> 20202021 3840
Prepare the light bulb device
Complete the first three steps once again for the light bulb device.
Use 1 as the node ID for the light bulb device.
Bind the light switch with the light bulb device
Use the CHIP Tool (“Writing ACL to the
accesscontrolcluster” section) to add proper ACL for the light bulb devices, establish a group for groupcast and bind the light switch. Depending on the number of the light bulb devices you are using, use one of the following commands, where node ID 2 refers to the light switch device and node ID 1 refers to the light bulb device commissioned in the previous steps.If you are using only one light bulb device, follow the instructions in the unicast tab to bind the light switch with the light bulb device. If you are using more than one light bulb device, follow the instructions in the groupcast tab to connect all devices to the multicast group
The unicast binding is used to bind the light switch with only one light bulb device. Run the following commands to bind the light switch with the light bulb device:
Write ACL to the
accesscontrolcluster:chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": [2], "targets": [{"cluster": 6, "endpoint": 1, "deviceType": null}, {"cluster": 8, "endpoint": 1, "deviceType": null}]}]' 1 0
Write a binding table to the light switch to inform the device about all endpoints by running this command (only for light switch):
chip-tool binding write binding '[{"fabricIndex": 1, "node": 1, "endpoint": 1, "cluster": 6}, {"fabricIndex": 1, "node": 1, "endpoint": 1, "cluster": 8}]' 2 1
The groupcast binding is used to bind the light switch with multiple light bulb devices. The following example shows how to estabilish a new group communication with the following parameters:
Group ID: 258
Group Name: Test_Group
Group Key Set ID: 349
Group Key Set Security Policy: 0
Epoch Key 0: a0a1a2a3a4a5a6a7a8a9aaabacad7531
Epoch Start Time 0: 1110000
Epoch Key 1: b0b1b2b3b4b5b6b7b8b9babbbcbd7531
Epoch Start Time 1: 1110001
Epoch Key 2: c0c1c2c3c4c5c6c7c8c9cacbcccd7531
Epoch Start Time 2: 1110002
To learn more about groups in Matter, see the Matter Group Communication user guide.
Run the following commands to bind the light switch with all light bulb devices:
Set up a new group in the doc:CHIP Tool <matter:chip_tool_guide>:
chip-tool groupsettings add-keysets 349 0 2220000 hex:a0a1a2a3a4a5a6a7a8a9aaabacad7531 chip-tool groupsettings bind-keyset 258 349
Set up all light bulb devices:
chip-tool groupkeymanagement key-set-write {"groupKeySetID": 349, "groupKeySecurityPolicy": 0, "epochKey0": "a0a1a2a3a4a5a6a7a8a9aaabacad7531", "epochStartTime0": 1110000, "epochKey1": "b0b1b2b3b4b5b6b7b8b9babbbcbd7531", "epochStartTime1": 1110001, "epochKey2": "c0c1c2c3c4c5c6c7c8c9cacbcccd7531", "epochStartTime2": 1110002} 1 0 chip-tool groupkeymanagement write group-key-map [{"groupId": 258, "groupKeySetID": 349, "fabricIndex": 1}] 1 0 chip-tool groups add-group 258 Test_Group 1 1 chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 3, "subjects": [258], "targets": [{"cluster": null, "endpoint": 1, "deviceType": null}]}]' 1 0
Set up the light switch device:
chip-tool groupkeymanagement key-set-write {"groupKeySetID": 349, "groupKeySecurityPolicy": 0, "epochKey0": "a0a1a2a3a4a5a6a7a8a9aaabacad7531", "epochStartTime0": 1110000, "epochKey1": "b0b1b2b3b4b5b6b7b8b9babbbcbd7531", "epochStartTime1": 1110001, "epochKey2": "c0c1c2c3c4c5c6c7c8c9cacbcccd7531", "epochStartTime2": 1110002} 2 0 chip-tool groupkeymanagement write group-key-map [{"groupId": 258, "groupKeySetID": 349, "fabricIndex": 1}] 2 0 chip-tool accesscontrol write acl [{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 3, "subjects": [258], "targets": null}] 2 0 chip-tool binding write binding [{"fabricIndex": 1, "group": 258}] 2 1
All devices are now bound and ready for testing communication.
Control the light bulb device
On the light switch device, use the buttons to control the bound light bulbs:
Press the Second Button to turn off the state-indication LED located on the bound light bulb device.
Press the Second Button to turn the LED on again.
Press the Second Button and hold it for more than 0.5 seconds to test the dimmer functionality.
The state-indication LED on the bound light bulb device changes its brightness from 0% to 100% with 1% increments every 300 milliseconds as long as the Second Button is pressed.
Using the terminal emulator connected to the light switch, run the following Matter CLI commands:
Write the following command to turn on state-indication LED located on the bound light bulb device:
For a single bound light bulb:
matter switch onoff on
For a group of light bulbs:
matter switch groups onoff on
Write the following command to turn off the state-indication LED located on the bound light bulb device:
For a single bound light bulb:
matter switch onoff off
For a group of light bulbs:
matter switch groups onoff off
Testing with commercial ecosystem
Before starting testing, ensure that the ecosystem supports the device types enabled in this sample. See the ecosystem manual page for instructions on how to use it.
When you start the commissioning procedure, the ecosystem controller must get the onboarding information from the Matter accessory device. The onboarding information representation depends on your commissioner setup.
For this sample, you can use one of the following onboarding information formats to provide the commissioner with the data payload that includes the device discriminator and the setup PIN code:
Light switch sample onboarding information QR Code
QR Code Payload
Manual pairing code
Scan the following QR code with the app for your ecosystem:
MT:K.K9042C00KA0648G00
34970112332
When the factory data support is enabled, the onboarding information will be stored in the build directory in the following files:
The
factory_data.pngfile includes the generated QR code.The
factory_data.txtfile includes the QR code payload and the manual pairing code.
This data payload also includes test Device Attestation, with test Certification Declaration, Product ID, and Vendor ID. These are used for Device Attestation within commissioning, and you can generate your own test Certification Declaration when you work on Matter end product.
Dependencies
This sample uses the Matter library that includes the nRF Connect SDK platform integration layer:
In addition, the sample uses the following nRF Connect SDK components:
The sample depends on the following Zephyr libraries:
