Light Switch

Overview

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. You can use this sample as a reference for creating your own application.

When configured together with the Lighting 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. This device works as a Thread Sleepy End Device.

The sample controls the state of the LED 0 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.

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.

You can read more about ACLs on 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 on a per endpoint basis. 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 light switch device is able to create a groupcast message and send it to the chosen IPv6 multicast address. This allows the light switch to control more than one lighting device at the same time.

Note

Writing the groupcast table on the devices blocks sending unicast commands. If the original state is desired, 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 going to be the target for the client-generated actions on one or more remote nodes.

In this sample, the light switch controls one or more lighting devices, but does not know the remote endpoints of the lights (on remote nodes). Using binding, the light switch device updates its Binding cluster with all relevant information about the lighting devices, such as their IPv6 address, node ID, and the IDs of the remote endpoints that contain the On/Off cluster and the LevelControl cluster, respectively.

Requirements

The sample supports the following development kits:

Supported Development Kits

Hardware platforms	Board name
RTL8777G HDK	RTL8777G EVB

Prepare Matter Environment

To set up the Matter environment, follow the steps listed in Development Setup.

Prepare CHIP Tool

The CHIP Tool (chip-tool) is a Matter controller implementation that allows commissioning a Matter device into the network and communicating with it using Matter messages, which may encode Data Model actions, such as cluster commands. The tool also provides other utilities specific to Matter, such as parsing the setup payload or performing discovery actions.

To build the target, follow the steps listed on the CHIP Tool.

Configurations

Sample Configurations

Our example samples all have default configurations. If wanting to modify the sample configuration, change CHIPProjectConfig.h under the path matter/connectedhomeip/examples/<app_name>/realtek_bee/main/include, where app_name refers to the name of the application, for example, lighting-app.

See APP Config for more information about configuration items.

Factory Data Configurations

The factory data is disabled by default for the evb board. To use factory data, follow the section Enable Factory Data Support and Factory Data Generation in Factory Data.

Building and Downloading

Building

Navigate to the specified directory and build light-switch app.

$ cd beeSDK/subsys/matter/samples
$ rm -r build/
$ ./build.py rtl8777g light-switch

Downloading

After a successful compilation, the app bin matter-cli-mtd_bank0_MP_dev_*.bin will be generated in the directory build/bank0/bin.

To download app bin into EVB board, follow the steps listed on the Downloading in Quick Start. If the factory data is enabled, also refer to Program Factory Data in Factory Data.

Then press reset button on EVB board and it will start running.

Experimental Verification

After programming the sample to your EVB board, complete the steps in the following sections.

Preparation Phase

After building this and the Lighting samples, and programming them to the development kits, complete the following steps:

Note

In both samples (light switch and light bulb), a Bluetooth LE discriminator is set with the same value by default (hexadecimal: 0xF00; decimal: 3840). This means that only one uncommissioned device can be powered up before commissioning. If both are powered up at the same time, the CHIP Tool can commission a random device and the node ID assignment is also random. When one device is commissioned, power up the next device and perform the commissioning. To avoid this unclear situation, you can set up your unique discriminator in main/include/CHIPProjectConfig.h file by changing CHIP_DEVICE_CONFIG_USE_TEST_SETUP_DISCRIMINATOR value. Then build an example and commission with your unique discriminator.

1. Connect the kit to the computer using a USB cable.

2. Open a serial port connection to the kit using a terminal emulator (for example, Tera Term).

3. If devices were not erased during the programming, press and hold SW2 for more than 6.5 seconds until the factory reset takes place.

4. On each device, press RST to start the Bluetooth LE advertising.

5. Commission devices to the Matter network. See Commissioning the Device for more information. During the commissioning process, write down the values for the light switch node ID and the light bulb node ID (or IDs, if you are using more than one light bulb). These IDs are going to be used in the next steps (<light_switch_node_ID> and <light_bulb_node_ID>, respectively).

6. Add proper ACL for the light bulb device. Depending on the number of the light bulb devices you are using, use one of the following commands, with <light_switch_node_ID> and <light_bulb_node_ID> values from the previous step about commissioning:

   • If using only one light bulb device, run the following command for the light bulb device:

     $ ./chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": [<light_switch_node_ID>], "targets": [{"cluster": 6, "endpoint": 1, "deviceType": null}, {"cluster": 8, "endpoint": 1, "deviceType": null}]}]' <light_bulb_node_ID> 0
     

   • If using more than one light bulb device, connect all devices to the multicast group by running the following command for each device, including the light switch:

     $ ./chip-tool groupkeymanagement key-set-write '{"groupKeySetID": 417, "groupKeySecurityPolicy": 0, "epochKey0":"a0a1a2a3a4a5a6a7a8a9aaabacadaeaf", "epochStartTime0": 1110000, "epochKey1":"b0b1b2b3b4b5b6b7b8b9babbbcbdbebf", "epochStartTime1": 1110001, "epochKey2":"c0c1c2c3c4c5c6c7c8c9cacbcccdcecf", "epochStartTime2": 1110002 }' <node_ID> 0
     $ ./chip-tool groupkeymanagement write group-key-map '[{"groupId": 257, "groupKeySetID": 417, "fabricIndex": 1},{"groupId": 16705, "groupKeySetID": 417, "fabricIndex": 1}]' <node_ID> 0
     $ ./chip-tool groups add-group 257 switch <node_ID> 1
     $ ./chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": null, "targets": null},{"fabricIndex": 1, "privilege": 3, "authMode": 3, "subjects": null, "targets": null}]' <node_ID> 0
     

     • Use the <node_ID> values from the commissioning step.

7. Write a binding table to the light switch to inform the device about all endpoints by running this command (only for light switch):

   • For unicast binding to bind the light switch with only one light bulb:

     $ ./chip-tool binding write binding '[{"fabricIndex": 1, "node": <light bulb node id>, "endpoint": 1, "cluster": 6}, {"fabricIndex": 1, "node": <light bulb node id>, "endpoint": 1, "cluster": 8}]' <light switch node id> 1
     

   • For groupcast binding to bind the light switch with multiple light bulbs:

     $ ./chip-tool binding write binding '[{"fabricIndex": 1, "group": 257}]' <light_switch_node_ID> 1
     

All devices are now bound and ready for testing communication.

Note

In this sample, the ACL cluster is inserted into the light bulb’s endpoint 0, and the Binding cluster is inserted into the light switch’s endpoint 1.

Testing Phase

After preparing devices for testing, you can test the communication either of a single light bulb or of a group of light bulbs with the light switch (but not both a single device and a group at the same time).

Complete the following steps:

1. On the light switch device, press SW 1 to turn off the LED 0 located on the bound light bulb device.

2. On the light switch device, press SW 1 to turn on the light again. LED 0 on the light bulb device turns back on.