Lighting

This lighting sample demonstrates the usage of the Matter application layer to build a lighting bulb device and how to do the single light control. It covers setting up the environment, wiring LEDs, modifying configurations, building, and downloading. Additionally, it includes steps for testing using the CHIP Tool and commissioning the device into a Thread network. You can use this sample as a reference for creating your own application.

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.

Wiring

Connect the pins of three LEDs in the red box.

LED1: Indicates the On/Off state.

LED2: Indicates the identify state.

LED3: Indicates the system state. During the factory reset, the LED will blink every 500ms. After factory reset, the LED will flash by staying on for 50ms and off for 950ms. If the system has Bluetooth LE connection(s), the LED will blink every 100ms.

Wiring

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 lighting app.

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

Downloading

After the app is successfully built, the app bin matter-cli-ftd_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

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 device were not erased during the programming, press and hold SW2 for more than 6.5 seconds until the factory reset takes place.

4. Press RST to start the Bluetooth LE advertising.

5. Commission device to the Matter network. See Commissioning the Device for more information. During the commissioning process, write down the value for the light bulb node ID for later use(<light_bulb_node_ID>).

Testing Phase

After preparing device for testing, you can use CHIP Tool to test the single light control.

Run the following commands:

1. Check on-off attribute value before toggle command.

   $ ./chip-tool onoff read on-off <light_bulb_node_ID> <endpoint_id>
   

   • <light_bulb_node_ID>: Obtaind from previous step

   • <endpoint_id>: ID of the endpoint with OnOff cluster implemented

   For example:

   $ ./chip-tool onoff read on-off 2 1
   

   The following message will appear in logs:

   CHIP:TOO:    OnOff: False
   

2. Toggle the on-off attribute state.

   $ ./chip-tool onoff toggle <light_bulb_node_ID> <endpoint_id>
   

   For example:

   $ ./chip-tool onoff toggle 2 1
   

3. Check on-off attribute value has changed after toggle command.

   $ ./chip-tool onoff read on-off <light_bulb_node_ID> <endpoint_id>
   

   For example:

   $ ./chip-tool onoff read on-off 2 1
   

   The following message will appear in logs:

   CHIP:TOO:    OnOff: True
   

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