照明开关

概述

此照明开关示例演示了使用Matter应用层来构建一个开关设备，与照明设备绑定并改变其LED状态。您可以将此示例作为创建自己应用程序的参考。

当结合使用 照明 示例（或其他照明示例）并使用Matter控制器时，照明开关可以直接通过Matter网络远程控制一个灯泡或一组灯泡，Matter网络建立在低功耗802.15.4 Thread之上。 此设备作为Thread Sleepy End Device工作。

该示例控制连接的灯泡设备上的 LED 0 的状态。配置照明开关示例后，照明设备从Matter控制器获得适当的 访问控制列表 以开始接收从照明开关发送的命令。 然后，照明开关设备准备一个新的绑定表，以便能够发现灯泡设备并进行 绑定。

绑定完成后，应用程序可以通过以下方式之一控制连接的照明设备的状态：

• 对于单个灯泡，它使用经过证书认证的会话建立会话（CASE会话）与单个灯泡直接通信。

• 对于一组灯泡，它使用通过IPv6网络发送的多播消息，通过 组播通信 与组内所有灯泡通信。

访问控制列表

访问控制列表（ACL）是与访问控制Cluster相关的列表，该列表包含用于管理和执行节点端点及其关联Cluster实例的访问控制规则。 在此示例中，这使得照明设备可以接收来自照明开关的消息并运行它们。

您可以在Matter文档中的 访问控制指南 阅读更多关于ACL的信息。

组播通信

组播通信（groupcast or multicast）是指发送给包含多个具有相同Groups Cluster的设备的组地址的消息和命令。 Group Cluster管理一个节点范围的Group Table，此Group Table是底层交互层的一部分，这是基于每个端点进行的。 在创建具有特定 ID 和 Name 的Group Cluster后，设备获得自己的IPv6多播地址并准备接收groupcast命令。

在此示例中，照明开关设备能够创建groupcast消息并将其发送到选定的IPv6多播地址，这使得照明开关可以同时控制多个照明设备。

备注

在设备上写入groupcast表会阻塞发送单播命令。 如果您想恢复原始状态，请执行设备的出厂重置。

绑定

绑定是指在本地和远程节点上的端点之间建立关系。通过绑定，本地端点指向并绑定到相应的远程端点。 两者必须属于同一Cluster类型。绑定使本地端点知道哪些端点是客户端生成的操作的目标节点。

在此示例中，照明开关控制一个或多个照明设备，但不知道照明设备的远程端点（在远程节点上）。 使用绑定，照明开关设备更新其Binding Cluster，包括关于照明设备的所有相关信息，例如它们的IPv6地址、节点ID、以及包含On/Off Cluster和LevelControl Cluster的远程端点的ID。

环境需求

该示例支持以下开发套件：

支持的开发套件

硬件平台	板卡名称
RTL8777G HDK	RTL8777G EVB

准备Matter环境

要设置Matter环境，请按照 开发环境设置 中列出的步骤操作。

准备CHIP Tool

CHIP Tool（chip-tool）是Matter的控制器实现，允许将Matter设备加入网络并使用Matter消息与其通信，这些消息可能包含数据模型的相关操作，例如群集命令。该工具还提供其他特定于Matter的实用程序，如解析设置负载或执行发现操作。

要构建CHIP Tool，请按照 Matter工具 中的 CHIP Tool 步骤操作。

配置选项

示例样本配置

我们的示例样本都有默认配置。 如果要修改示例配置， 可以更改 matter/connectedhomeip/examples/<app_name>/realtek_bee/main/include 路径下的 CHIPProjectConfig.h，其中 app_name 指的是应用程序的名称，例如 lighting-app。

有关配置项的更多信息，请参见 APP配置。

工厂数据配置

对于EVB板，工厂数据默认是禁用的。要使用工厂数据，请参阅 工厂数据 中的 工厂数据生成 和 启用Matter应用程序构建的工厂数据 部分。

编译和下载

编译

导航到openthread目录并编译light-switch应用程序。

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

下载

编译成功后，应用程序bin文件 matter-cli-mtd_bank0_MP_dev_*.bin 将生成在目录 build/bin 中。

要将应用程序bin文件下载到EVB板，按照 快速入门 中 固件下载 中列出的步骤操作。如果工厂数据已启用，请参阅 工厂数据 中的 下载工厂数据文件到RTL8777G。

然后按下EVB板上的重置按钮，它将开始运行。

测试验证

在将示例工程烧录到您的EVB板后，完成以下各节中的步骤。

准备阶段

在编译此示例和 照明 示例并将它们烧录到开发套件后，完成以下步骤：

备注

在两个示例（照明开关和灯泡）中，蓝牙LE判别器默认设置为相同的值（十六进制: 0xF00；十进制: 3840），这意味着在配网之前只能有一个未配网的设备通电。 如果这两个设备同时通电，CHIP工具可能会将随机设备配网，并且节点ID分配也是随机的。 当一个设备被配网之后时，将下一个设备上电并执行配网。 为避免这种不明确的情况，您可以通过更改 CHIP_DEVICE_CONFIG_USE_TEST_SETUP_DISCRIMINATOR 值来在 main/include/CHIPProjectConfig.h 文件中设置唯一的判别器。 然后编译一个示例并使用您的唯一判别器进行配网。

1. 使用USB线将套件连接到计算机。

2. 使用终端仿真器（例如，Tera Term）打开与套件的串行端口连接。

3. 如果设备在编程期间未擦除，请按住SW2并保持6.5s以上，直到执行出厂重置。

4. 在每个设备上，按下RST以启动蓝牙LE广播。

5. 将设备配网到Matter网络。 有关更多信息，请参阅 设备配网。 在配网过程中，记录下照明开关节点ID和灯泡节点ID的值（这些值分别为<light_switch_node_ID>和<light_bulb_node_ID>，将在接下来的步骤中使用）。

6. 为灯泡设备添加适当的ACL。根据您使用的灯泡设备的数量，使用以下命令之一，使用上一步中关于配网的 <light_switch_node_ID> 和 <light_bulb_node_ID> 值：

   • 如果您只使用一个灯泡设备，为该灯泡设备运行以下命令：

     $ ./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
     

   • 如果您使用多个灯泡设备，将所有设备连接到多播组中，包括照明开关，分别为每个设备运行以下命令：

     $ ./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
     

     • 使用来自配网步骤的 <node_ID> 值。

7. 运行此命令，写一个绑定表到照明开关以通知设备所有端点（仅针对照明开关）：

   • 对于单播绑定，仅将照明开关与一个灯泡绑定：

     $ ./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
     

   • 对于组播绑定，将照明开关与多个灯泡绑定：

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

所有设备现在都已绑定并准备好进行通信测试。

备注

在此示例中，ACL Cluster插入到灯泡的端点 0 中，Binding Cluster插入到照明开关的端点 1 中。

测试阶段

在准备好用于测试的设备之后，您可以测试照明开关与单个灯泡或一组灯泡的通信（但不能同时测试单个设备和一组设备）。

完成以下步骤：

1. 在照明开关设备上， 按 SW 1 关闭绑定灯泡设备上的 LED 0。

2. 在照明开关设备上， 按 SW 1 打开灯光。绑定的灯泡设备上的 LED 0 会重新亮起。

设备配网

1. 确保CHIP Tool和OTBR（OpenThread Border Router）在同一网络段中。有关设置OTBR的过程，请参见 OpenThread 边界路由器构建和配置。

2. 使用OTBR组建一个Thread网络。

   $ 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
   

   请确保OTBR是leader。

   $ sudo ot-ctl state
   leader
   done
   

3. 获取设备的PIN码和Discriminator。

   • PIN码：用来认证设备的27位值。默认值：20202021

   • Discriminator：用来区分多个可配网设备广播的12位值。默认值：3840

   如果您使用工厂数据，可以扫描 工厂数据生成 部分生成的QR码来获取此信息。

   

   QR码和解析结果

   可以通过CHIP Tool解析其内容，示例如下：

   $ ./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. 将设备通过Bluetooth LE加入到Thread网络。

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

   • <node_id>：用户定义的正在配网的节点ID。

   • <operational_dataset>：从Thread Border Router获取的当前的operational dataset。获取方法是，在安装OTBR的Raspberry Pi终端中执行命令 sudo ot-ctl dataset active -x。

   • <pin_code>：在步骤3中获得。

   • <discriminator>：在步骤3中获得。

   • --bypass-attestation-verifier：用于绕过验证。如果未提供此标志或其值为false，则不绕过验证。如果其值为true (--bypass-attestation-verifier true)，那么如果验证失败，配网仍将继续。验证失败可能由认证声明、PAA或PAI证书，或者设备认证证书中的错误导致。如果希望快速配网具有基于未知PAA的PAI和DAC证书的设备，并且使用的是未知密钥签名的认证声明，此选项将非常有用。

   例如：

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

   配网可能需要一些时间。如果成功，日志中将出现以下消息：

   Device commissioning completed with success