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 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 more than one lighting devices at the same time.

Note

Writing the groupcast table on the devices blocks sending unicast commands. If you want to go back to the original state, perform 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 contains 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 to commission a Matter device into the network and to communicate 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 of the setup payload or performing discovery actions.

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

Configurations

Sample Configurations

Our example samples all have default configurations. If you want to modify the sample configuration, you can 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 Factory Data Generation and Enable Factory Data for Matter APP building in Factory Data.

Building and Downloading

Building

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

$ cd beeSDK/subsys/openthread/
$ rm -r build/
$ OT_CMAKE_NINJA_TARGET="matter-cli-mtd" ./Realtek/build bee4 sdk 8777g light-switch-app

Downloading

After a successful compilation, the app bin matter-cli-mtd_bank0_MP_dev_*.bin will be generated in the directory build/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 Download Factory Data Bin to RTL8777G 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 you are 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 you are 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 groups add-group 0x4141 chiptool <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.

Commissioning the Device

1. Ensure that the Chip Tool and OTBR(OpenThread Border Router) are on the same network segment. For the process of setting up OTBR, see the OpenThread Border Router Build and Configuration.

2. Form a Thread network with OTBR.

   $ sudo ot-ctl factoryreset
   $ sleep 1
   $ sudo ot-ctl dataset init new
   $ sudo ot-ctl dataset channel 25
   $ sudo ot-ctl dataset panid 0x5b35
   $ sudo ot-ctl dataset extpanid 5b35dead5b35beef
   $ sudo ot-ctl dataset networkname 5b35
   $ sudo ot-ctl dataset networkkey 00112233445566778899aabbccddeeff
   $ sudo ot-ctl dataset commit active
   $ sudo ot-ctl prefix add fd11:35::/64 pasor
   $ sudo ot-ctl dataset meshlocalprefix fb73:b7bd:20e5:053d::
   $ sudo ot-ctl dataset commit active
   $ sudo ot-ctl ifconfig up
   $ sleep 1
   $ sudo ot-ctl thread start
   $ sleep 1
   $ sudo ot-ctl state
   $ sudo ot-ctl netdata register
   $ sleep 1
   $ sudo ot-ctl netdata show
   $ sudo ot-ctl ipaddr
   

   Please ensure that OTBR is the leader.

   $ sudo ot-ctl state
   leader
   done
   

3. Obtain the device’s PIN code and Discriminator.

   • PIN code: A 27-bit value used to authenticate the device. Default: 20202021

   • Discriminator: A 12-bit value used to discern between multiple commissionable device advertisements. Default: 3840

   If you are using factory data, you can scan the QR code generated in section Factory Data Generation to obtain this information.

   

   QR Code & Scan Results

   You can parse its content through CHIP Tool, as in the following example:

   $ ./chip-tool payload parse-setup-payload "MT:Q5AA0CEK010O0648G00"
   CHIP:DL: ChipLinuxStorage::Init: Using KVS config file: /tmp/chip_tool_kvs
   CHIP:SPL: Parsing base38Representation: MT:Q5AA0CEK010O0648G00
   CHIP:SPL: Version:             0
   CHIP:SPL: VendorID:            4886
   CHIP:SPL: ProductID:           32769
   CHIP:SPL: Custom flow:         0    (STANDARD)
   CHIP:SPL: Discovery Bitmask:   0x02 (BLE)
   CHIP:SPL: Long discriminator:  3841   (0xf01)
   CHIP:SPL: Passcode:            20202022
   

4. Commission device into a Thread network over Bluetooth LE.

   $ ./chip-tool pairing ble-thread <node_id> hex:<operational_dataset> <pin_code> <discriminator> --bypass-attestation-verifier true
   

   • <node_id>: User-defined ID of the node being commissioned.

   • <operational_dataset>: Current Active Operational Dataset from the Thread Border Router. To obtain it, execute sudo ot-ctl dataset active -x in the terminal of the Raspberry Pi with OTBR.

   • <pin_code>: Obtained in step 3.

   • <discriminator>: Obtained in step 3.

   • --bypass-attestation-verifier: Use this to bypass the attestation verifier. If this flag is not provided or it is provided with the value false, the attestation verifier is not bypassed. If it is provided with the value true(--bypass-attestation-verifier true), the commissioning will continue in case of the attestation verification failure. The failure can be caused by errors in Certification Declaration, PAA or PAI certificates, or in the Device Attestation Certificate. This option can be helpful if you want to quickly commission a device with PAI and DAC certificates based on an unknown PAA and/or with a Certification Declaration signed by an unknown key.

   For example:

   $ ./chip-tool pairing ble-thread 2 hex:0e08000000000001000035060004001fffe00410df7d53dd16ad16f407cd13efa93b285e0c0402a0f7f800030000190102123402081111111122222222030431323334051000112233445566778899aabbccddeeff0708fb73b7bd20e5053d 20202022 3841 --bypass-attestation-verifier true
   

   Commissioning might take a while. If it’s successful, the following message will appear in logs:

   Device commissioning completed with success