Matter 设备配网

配网流程

下图以涂鸦双模 Matter 设备为例，描述 Matter 双模设备配网流程：

设备发现

支持以下两种发现设备的方式：

• 扫码或输入编码

  Matter 标准方式，支持 涂鸦 Matter 设备、三方 Matter 设备

• 自发现搜索

  涂鸦特色功能，目前 仅 支持 涂鸦 Matter 设备

Matter 设备发现在涂鸦 SDK 中有两种方式：

方式一：扫码或输码

此方式是 Matter 的标准接入方式，您可将用户通过扫描 Matter 配网二维码 的内容或者用户输入的 Matter 配网码 传递至 SDK 接口中进行解析，再将解析返回的 ThingSmartMatterSetupPayload 对象按照本文内 配网流程 进一步执行。

接口说明

- (nullable ThingSmartMatterSetupPayload *)parseSetupCode:(NSString *)matterCode;

参数说明

参数	说明
matterCode	外包装上设备二维码信息或数字配网码

示例代码

Objective C：

- (void)checkCode{
    ThingSmartMatterSetupPayload *payload = [[ThingSmartMatterActivator sharedInstance]parseSetupCode:@""];
    if(payload){
        //Use the payload to build `ThingSmartConnectDeviceBuilder` object
    }else{
        //Code is invalid;
    }
}

Swift：

func checkCode() {
    var payload = ThingSmartMatterActivator.sharedInstance().parseSetupCode("code")
    if payload != nil{
         // Use the payload to build `ThingSmartConnectDeviceBuilder` object
    }else{
        //Code is invalid;
    }
}

方式二：自发现搜索

自发现搜索会扫描周边支持自发现配网的 Matter 设备。

接口说明

- (void)startDiscovery;

示例代码

Objective C：

[[ThingSmartMatterDiscoveryActivator sharedInstance] startDiscovery];

Swift：

ThingSmartMatterDiscoveryActivator.sharedInstance().startDiscovery()

设备扫描回调

当扫到周边支持自发现配网的 Matter 设备时，会触发该回调。每发现一个 Matter 设备，都将触发一次本回调。

接口说明

- (void)discoveryedDevice:(ThingSmartMatterDiscoveryModel *)model;

参数说明

参数	说明
model	自发现配网数据模型

示例代码

Objective C：

- (void)discoveryedDevice:(ThingSmartMatterDiscoveryModel *)model{
    NSLog(@"Discovery a Matter Device!");
}

Swift：

func discoveryedDevice(_ model: ThingSmartMatterDiscoveryModel) {
    print("Discovery a Matter Device!");
}

自发现设备配网模型释义

当发现到支持自发现配网的 Matter 设备时，会生成数据模型回调给业务层。

参数说明

参数	说明
payload	代码生成的部分数据配网码，缺失配网 Key 字段
iconUrl	该设备的图标
deviceName	该设备的设备名
productId	该设备的产品 ID
isThingDevice	是否涂鸦设备
deviceType	设备类型

停止设备自发现

当您退出自发现页面时，应调用该方法停止自发现搜索，避免资源浪费。

接口说明

- (void)stopDiscovery;

示例代码

Objective C：

[[ThingSmartMatterDiscoveryActivator sharedInstance] stopDiscovery];

Swift：

ThingSmartMatterDiscoveryActivator.sharedInstance().stopDiscovery()

开始配网流程

使用发现的 ThingSmartMatterDiscoveryModel 模型对象的 payload 属性对象，按照本文内 配网流程 进一步执行。

构建配网参数

获取 SetupPayload

在本文 设备发现 中已说明如何获取 ThingSmartMatterSetupPayload 对象。

获取 Token

开始配网之前，SDK 需要在联网状态下从涂鸦查询配网 Token，然后才可以开始有线设备激活配网。Token 的有效期为 10 分钟，且配置成功后就会失效。再次配网时，需要重新查询 Token。

接口说明

- (void)getTokenWithHomeId:(long long)homeId
                   success:(ThingSuccessString)success
                   failure:(ThingFailureError)failure;

参数说明

参数	说明
homeId	设备将要绑定到的家庭的 ID
success	成功回调，返回配网 Token
failure	失败回调，返回失败原因

示例代码

Objective C：

- (void)getToken {
    [[ThingSmartActivator new] getTokenWithHomeId:homeId success:^(NSString *token) {
            NSLog(@"getToken success: %@", token);
    } failure:^(NSError *error) {
            NSLog(@"getToken failure: %@", error.localizedDescription);
    }];
}

Swift：

func getToken() {
    ThingSmartActivator().getTokenWithHomeId(homeId, success: { (token) in
        print("getToken success: \(token)")
    }, failure: { (error) in
        if let e = error {
            print("getToken failure: \(e)")
        }
    })
}

组装配网参数对象

进行开始配网前的最后一个准备工作，提供必要的配网参数进行配网。

接口说明

- (instancetype)initWithPayload:(ThingSmartMatterSetupPayload *)payload spaceId:(long long)spaceId token:(NSString *)token;

参数说明

参数	说明
payload	使用 扫码/输码 或者 使用自发现搜索 获取的 ThingSmartMatterSetupPayload 对象
spaceId	家庭 ID，通常是当前家庭的 homeId
token	从获取 Token 接口获取

示例代码

Objective C：

- (ThingSmartConnectDeviceBuilder *)connectBuilder{
    ThingSmartConnectDeviceBuilder *builder = [[ThingSmartConnectDeviceBuilder alloc]initWithPayload:payload spaceId:homeId token:token];
    return builder;
}

Swift：

func connectBuilder() -> ThingSmartConnectDeviceBuilder?{
    let builder = ThingSmartConnectDeviceBuilder(payload: payload, spaceId: homeId, token: token)
    return builder
}

配网流程

连接设备

Matter 设备连接后建立完成 PASE 会话，将触发 PASE 会话成功回调。

接口说明

- (void)connectDeviceWithConnectDeviceBuilder:(ThingSmartConnectDeviceBuilder *)builder timeout:(NSTimeInterval)timeout;

参数说明

参数	说明
builder	组装好的配网参数 ThingSmartConnectDeviceBuilder 模型对象
timeout	超时时间

示例代码

Objective C：

- (void)startActivator{
    // ThingSmartConnectDeviceBuilder *builder = [self connectBuilder];
    [[ThingSmartMatterActivator sharedInstance]connectDeviceWithConnectDeviceBuilder:builder timeout:300];

Swift：

func startActivator(){
    // guard let builder = connectBuilder() else {return}
    ThingSmartMatterActivator.sharedInstance().connectDevice(with: builder, timeout: 300)
}

连接设备回调

尝试进行 connect 连接后，会触发发现回调，告知业务层配网类型和设备类型。

接口说明

- (void)matterDeviceDiscoveryed:(BOOL)isThingDevice deviceType:(ThingSmartMatterDeviceType)deviceType;

参数说明

参数	说明
isThingDevice	是否是涂鸦设备
deviceType	具体的设备类型

示例代码

Objective C：

- (void)matterDeviceDiscoveryed:(BOOL)isThingDevice deviceType:(ThingSmartMatterDeviceType)deviceType{
    NSLog(@"Discoveryed Device");
}

Swift：

func matterDeviceDiscoveryed(_ isThingDevice: Bool, deviceType: ThingSmartMatterDeviceType) {
    print("Discoveryed Device")
}

Matter 配网链路回调

SDK 会根据设备广播包自动选择最合适的配网链路，并回调给业务层进行相应的页面显示。共有三种类型：

• 涂鸦链路（ThingMatterRoutingTypeThing）

• 分享配网链路（ThingMatterRoutingTypeSupport）

• MatterSupport 链路（ThingMatterRoutingTypeShare）（针对其他第三方 Matter 设备）

  如您需要支持 MatterSupport 链路配网，请参考 Matter 设备接入准备 文档配置好 Matter Extension Target，否则会配网失败。

接口说明

- (void)matterRoutingComplete:(ThingMatterRoutingType)routingType

参数说明

参数	说明
routingType	具体配网链路

示例代码

Objective C：

- (void)matterRoutingComplete:(ThingMatterRoutingType)routingType{
    NSLog(@"Routing Complete");
}

Swift：

func matterRoutingComplete(_ routingType: ThingMatterRoutingType) {
    print("Routing Complete");
}

PASE 会话建立成功回调

Matter 设备连接后建立完成 PASE（Passcode-Authenticated Session Establishment）会话，将触发 PASE 会话成功回调。

接口说明

- (void)matterCommissioningSessionEstablishmentComplete:(ThingSmartMatterDeviceModel *)deviceModel;

参数说明

参数	说明
deviceModel	PASE 会话阶段的 Matter 设备模型，可用于部分数据提取

示例代码

Objective C：

- (void)matterCommissioningSessionEstablishmentComplete:(ThingSmartMatterDeviceModel *)deviceModel {
    NSLog(@"Establishment Complete!");
}

Swift：

func matterCommissioningSessionEstablishmentComplete(_ deviceModel: ThingSmartMatterDeviceModel) {
    print("Establishment Complete!");
}

涂鸦双模设备调试参数组装

如要建立完整的 CASE（Certificate Authenticated Session Establishment）会话，需提供必要的参数，组装完毕后再进行 调试。仅涂鸦 Matter 设备需要且必须组装。

接口说明

- (instancetype)initWithSSid:(NSString *)ssid password:(NSString *)password;

参数说明

参数	说明
ssid	Wi-Fi 名称
password	Wi-Fi 密码

示例代码

Objective C：

- (ThingSmartMatterCommissionModel *)commissionBuilder{
    ThingSmartMatterCommissionModel *builder = [[ThingSmartMatterCommissionModel alloc]initWithSSid:@"ssid" password:@"password"];
    return builder;
}

Swift：

func commissionBuilder() -> ThingSmartMatterCommissionModel{
    let commissionBuilder = ThingSmartMatterCommissionModel(sSid: "ssid", password: "password")
    return commissionBuilder
}

Thread 子设备调试参数组装

子设备依赖 Matter 网关提供的 OTBR 网络进行配网，因此在建立 CASE 会话前，需要指定网关 ID。

在 PASE 会话阶段，涂鸦会扫描周围可用的 Thread 网络并根据信号强度选择最佳网关 ID。在 - (void)matterCommissioningSessionEstablishmentComplete:(ThingSmartMatterDeviceModel *)deviceModel; 回调中，ThingSmartMatterDeviceModel 会提供可用的 gatewayId，如该参数为空或您想要指定网关，也可以使用家庭中其他的网关 ID。

接口说明

- (instancetype)initWithGatewayId:(NSString *)gwId;

参数说明

参数	说明
gwId	网关设备 ID

示例代码

Objective C：

- (ThingSmartMatterCommissionModel *)commissionBuilder{
    ThingSmartMatterCommissionModel *builder = [[ThingSmartMatterCommissionModel alloc] initWithGatewayId:@"gwId"];
    return builder;
}

Swift：

func commissionBuilder() -> ThingSmartMatterCommissionModel{
    let commissionBuilder = ThingSmartMatterCommissionModel(gatewayId:"gwId")
    return commissionBuilder
}

调试 Matter 设备

完成 PASE 会话后，部分关键信息如设备类型等已经可以获取。如果您确认需要激活设备上云，且完成了 CASE 会话的必要参数组装，则需要继续调用该接口完成 CASE 会话建立。

接口说明

- (void)commissionDevice:(nonnull ThingSmartMatterDeviceModel *)deviceModel commissionModel:(ThingSmartMatterCommissionModel *) commissionModel;

参数说明

参数	说明
deviceModel	PASE 会话阶段完成后回调的 Matter 设备模型，从 matterCommissioningSessionEstablishmentComplete 回调中获取
commissionModel	组装的 CASE 会话参数模型

示例代码

Objective C：

- (void)continueActivator{
    ThingSmartMatterCommissionModel *builder = [self commissionBuilder];
    [[ThingSmartMatterActivator sharedInstance]commissionDevice:self.matterDeviceModel commissionModel:builder];
}

Swift：

func continueActivator(){
    let builder = commissionBuilder()
    ThingSmartMatterActivator.sharedInstance().commissionDevice(self.matterDeviceModel, commissionModel: builder)
}

设备认证回调

如果您配对的是一个未经过官方认证的设备，那么会触发认证回调。如果触发了该回调，在您选择继续或放弃前，配网流程将会暂停。

接口说明

- (void)matterDeviceAttestation:(void *)device error:(NSError * _Nonnull)error;

参数说明

参数	说明
device	配网链路中的设备对象地址指针
error	未通过认证的错误信息

示例代码

Objective C：

- (void)matterDeviceAttestation:(void *)device error:(NSError *)error{
    NSLog(@"Device Attestation!");
}

Swift：

func matterDeviceAttestation(_ device: UnsafeMutableRawPointer, error: Error) {
    print("Device Attestation!")
}

信任未认证的设备并继续配网

如您认为该设备证书可以被信任，可以调用该接口继续配网。

接口说明

- (void)continueCommissioningDevice:(void *)device
           ignoreAttestationFailure:(BOOL)ignoreAttestationFailure
                              error:(NSError * __autoreleasing *)error;

参数说明

参数	说明
device	Attestation 回调方法中的设备对象地址指针，必须透传 回调上来的参数，不可进行其他操作
ignoreAttestationFailure	是否忽略未认证信息
error	该操作执行后可能的错误信息

示例代码

Objective C：

- (void)matterDeviceAttestation:(void *)device error:(NSError *)error{
    UIAlertController * alertController = [UIAlertController
        alertControllerWithTitle:@"Device Attestation"
                         message:@"Device Attestation failed for device under commissioning. Do you wish to continue pairing?"
                  preferredStyle:UIAlertControllerStyleAlert];

    [alertController addAction:[UIAlertAction actionWithTitle:@"No"
                                                        style:UIAlertActionStyleDefault
                                                      handler:^(UIAlertAction * action) {
                                                          NSError * err;
        [[ThingSmartMatterActivator sharedInstance]continueCommissioningDevice:device ignoreAttestationFailure:NO error:&err];
                                                      }]];

    [alertController addAction:[UIAlertAction actionWithTitle:@"Continue"
                                                        style:UIAlertActionStyleDefault
                                                      handler:^(UIAlertAction * action) {
                                                          NSError * err;
        [[ThingSmartMatterActivator sharedInstance]continueCommissioningDevice:device ignoreAttestationFailure:YES error:&err];
                                                      }]];

    [self presentViewController:alertController animated:YES completion:nil];
}

Swift：

func matterDeviceAttestation(_ device: UnsafeMutableRawPointer, error: Error) {

    let alertController = UIAlertController(title: "Device Attestation", message: "Device Attestation failed for device under commissioning. Do you wish to continue pairing?", preferredStyle: .alert)
    alertController.addAction(UIAlertAction(title: "NO", style: .default, handler: { _ in
        ThingSmartMatterActivator.sharedInstance().continueCommissioningDevice(device, ignoreAttestationFailure: false, error: nil)
    }))

    alertController.addAction(UIAlertAction(title: "Continue", style: .default, handler: { _ in
        ThingSmartMatterActivator.sharedInstance().continueCommissioningDevice(device, ignoreAttestationFailure: true, error: nil)
    }))

    self.present(alertController, animated: true)
}

配网成功回调

Matter 设备配网成功上云后，会触发该回调。

接口说明

- (void)matterDeviceActivatorSuccess:(ThingSmartMatterDeviceModel *)matterDevice;

参数说明

参数	说明
matterDevice	完整的 Matter 设备数据模型

示例代码

Objective C：

- (void)matterDeviceActivatorSuccess:(ThingSmartMatterDeviceModel *)matterDevice{
    NSLog(@"Activator Success!");
}

Swift：

func matterDeviceActivatorSuccess(_ matterDevice: ThingSmartMatterDeviceModel) {
    print("Activator Success!")
}

配网失败回调

Matter 设备配网失败后，会触发该回调。

接口说明

- (void)matterDevice:(ThingSmartMatterSetupPayload *)payload activatorFailed:(NSError *)error;

参数说明

参数	说明
payload	报错的 Matter 设备配网码数据模型
error	报错信息，具体的 Code 释义请参考 ThingSmartMatterKitErrors 中的注释

示例代码

Objective C：

- (void)matterDevice:(ThingSmartMatterSetupPayload *)payload activatorFailed:(NSError *)error{
    NSLog(@"Activator Failed");
}

Swift：

func matterDevice(_ payload: ThingSmartMatterSetupPayload, activatorFailed error: Error) {
    print("Activator Failed")
}

MatterSupport 配网成功回调

如果配网时使用了 MatterSupport 流程（第三方 Wi-Fi、三方 Thread 设备)，那么 MatterSupport 是整个配网流程中的一部分，在 MatterSupport 流程完成后，将触发该方法回调，并自动继续涂鸦配网流程。

接口说明

- (void)matterSupportComplete:(NSString *)gatewayName;

参数说明

参数	说明
gatewayName	MatterSupport 所使用的 OTBR 网络所属的涂鸦网关 ID，如为空，说明使用的是 HomePod 或 Apple TV

示例代码

Objective C：

- (void)matterSupportComplete:(NSString *)gatewayName{
    NSLog(@"Matte Support Completed");
}

Swift：

func matterSupportComplete(_ gatewayName: String) {
    print("Matte Support Completed")
}

错误码定义

错误码声明可见 ThingSmartMatterKitErrors.h 中声明释义。