Matter 设备接入准备

在开始接入 Matter 设备之前，您需要对项目工程进行配置。在涂鸦，Matter 设备被分为 涂鸦 Matter 设备 和 其他第三方 Matter 设备。对于第三方 Matter 设备，您需对 Xcode 工程进行额外的 Extension Target 配置。

前提条件

• 请确保已经完成 SDK 的 快速集成 工作。

• 若您需要使用 UI 业务包，请确保您集成的 Cube App SDK 版本和 UI 业务包版本保持一致，以确保配网、控制的稳定。

主工程配置与集成

权限配置

1. 打开项目设置。

2. 选中 主工程 Target > Signing & Capabilities，单击 + Capability，如下图所示：

   

3. 添加 Matter Allow Setup Payload 权限，用于处理 Matter 二维码解析。

4. 添加 App Groups 权限，用于与 Matter Extension Target 共享数据，注意勾选的 App Group Id 需要与 Matter Extension Target 中配置的一致。

5. 添加 Background Modes 权限，勾选 Uses Bluetooth LE accessories 权限，用于保证蓝牙通讯稳定性

   配置后最终如图所示：

   

Info.plist 配置

1. 打开 Xcode 项目设置。

2. 选中 主工程 Target > Info > Custom iOS Target Properties，如下图所示：

   

   • 蓝牙隐私权限

     添加 NSBluetoothPeripheralUsageDescription 权限，用于蓝牙使用隐私声明。

   • Bonjour 服务权限

     Matter 强依赖局域网通信，因此需要在主工程的 Info.plist 文件中配置 Bonjour 服务，代码如下：

     <key>NSBonjourServices</key>
         <array>
             <string>_meshcop._udp</string>
             <string>_matter._tcp</string>
             <string>_matterc._udp</string>
             <string>_matterd._udp</string>
         </array>
     

使用 CocoaPods 快速集成

1. CocoaPods 建议更新至最新版本。

2. 在 Podfile 文件中添加以下内容：

   platform :ios, '9.0'
   
   target 'Your_Project_Name' do
       pod "ThingSmartMatterKit"
   end
   

3. 在项目根目录下执行 pod update 命令进行集成。

   CocoaPods 的使用请参考 CocoaPods 官方文档。

模块初始化

根据 快速集成 章节指引，在初始化 SDK 完成之后，完成 Matter 模块初始化：

// 初始化 SDK
[[ThingSmartSDK sharedInstance] startWithAppKey:<#your_app_key#> secretKey:<#your_secret_key#>];

// 初始化 Matter 模块
[ThingSmartMatterActivatorConfig setMatterConfigKey:<#YOUR_APP_GROUP_ID#>];

接口说明

+ (void)setMatterConfigKey:(NSString *)configKey;

参数说明

参数	说明
configKey	工程 App Group ID

示例代码

Objective-C：

[ThingSmartMatterActivatorConfig setMatterConfigKey:<#YOUR_APP_GROUP_ID#>];

Swift：

ThingSmartMatterActivatorConfig.setMatterKey("YOUR_APP_GROUP_ID")

Extension Target 配置与集成

注意事项

• 需要使用 14.1 及以上版本 Xcode。
• 需要使用 16.1 及以上版本 iOS 系统。
• 新建 Matter Extension Target，使用默认生成的代码文件即可，然后 请跟随本文配置修改代码文件。
• Matter Extension Target 仅支持 Swift 项目。

权限配置

1. 打开项目设置。
2. 选中 主工程 Target > Signing & Capabilities，单击 + Capability。
3. 添加 App Groups 权限，用于与 主工程 Target 共享数据，注意勾选的 App Group ID 需要与 主工程 Target 中配置的一致。

使用 CocoaPods 快速集成

1. CocoaPods 建议更新至最新版本。

2. 在 Podfile 文件中添加以下内容：

   platform :ios, '9.0'
   
   target 'Your_Matter_Extension_Target_Name' do
       pod "ThingSmartMatterExtensionKit"
   end
   

3. 在项目根目录下执行 pod update 命令进行集成。

   CocoaPods 的使用请参考 CocoaPods 官方文档。

模块初始化

打开 ExtensionTarget 工程中的 RequestHandler.swift 文件，重写 init 方法。

override init()

接口说明

+ (void)setMatterConfigKey:(NSString *)configKey;

参数说明

参数	说明
configKey	工程 App Group ID

示例代码

Swift：

override init() {
  super.init()
  ThingMatterExtensionSupport.shared.setMatterConfigKey(configKey: <#YOUR_APP_GROUP_ID#>)
}

使用 ThingSmartMatterExtensionKit

按文档生成 Matter Extension Target 工程后，会在 Extension 工程中看到RequestHandler.swift 文件，API 方法由系统提供，按如下代码调用 ThingSmartMatterExtensionKit 接口。

1. 将 ThingSmartMatterExtensionKit 引入库。

   import ThingSmartMatterExtensionKit
   

2. 按照以下示例代码，在官方自动生成的方法中调用 API。

   RequestHandler.swift 中的回调方法均由系统自动生成，不可更改。

       override func validateDeviceCredential(_ deviceCredential: MatterAddDeviceExtensionRequestHandler.DeviceCredential) async throws {
           ThingMatterExtensionSupport.shared.validateDeviceCredential(deviceCredential)
       }
   
       override func selectWi-FiNetwork(from wifiScanResults: [MatterAddDeviceExtensionRequestHandler.Wi-FiScanResult]) async throws -> MatterAddDeviceExtensionRequestHandler.Wi-FiNetworkAssociation {
           // Use this function to select a Wi-Fi network for the device if your ecosystem has special requirements.
           // Or, return .defaultSystemNetwork` to use the iOS device's current network.
           return ThingMatterExtensionSupport.shared.selectWi-FiNetwork(from: wifiScanResults)
       }
   
       override func selectThreadNetwork(from threadScanResults: [MatterAddDeviceExtensionRequestHandler.ThreadScanResult]) async throws -> MatterAddDeviceExtensionRequestHandler.ThreadNetworkAssociation {
           // Use this function to select a Thread network for the device if your ecosystem has special requirements.
           // Or, return .defaultSystemNetwork to use the default Thread network.
           return ThingMatterExtensionSupport.shared.selectThreadNetwork(from: threadScanResults)
       }
   
       override func commissionDevice(in home: MatterAddDeviceRequest.Home?, onboardingPayload: String, commissioningID: UUID) async throws {
           // Use this function to commission the device with your Matter stack.
           ThingMatterExtensionSupport.shared.commissionDevice(in: home, onboardingPayload: onboardingPayload, commissioningID: commissioningID)
       }
   
       override func rooms(in home: MatterAddDeviceRequest.Home?) async -> [MatterAddDeviceRequest.Room] {
           // Use this function to return the rooms your ecosystem manages.
           // If your ecosystem manages multiple homes, ensure you are returning rooms that belong to the provided home.
           return ThingMatterExtensionSupport.shared.rooms(in: home)
       }
   
       override func configureDevice(named name: String, in room: MatterAddDeviceRequest.Room?) async {
           // Use this function to configure the (now) commissioned device with the given name and room.
           ThingMatterExtensionSupport.shared.configureDevice(named: name, in: room)
       }
   

Matter 能力使用配置

由于 Matter 设备的特性，其一切能力都建立在 Matter Fabric 网络之上。在使用 Matter 设备配网和控制管理等功能前，您需要调用相关接口进行 Matter 基础信息配置。该配置操作需要在进行 Matter 相关业务处理前完成。

配置时序

配置时序如下图所示：

Fabric 信息准备

Matter 相关的信息与家庭相关联，因此需在 家庭切换完成 或 家庭首次加载完成 时，调用 - loadFabricWithSpaceId 查询该家庭对应的 Fabric 信息。

接口说明

@interface ThingSmartMatterManager : NSObject
+ (instancetype)sharedInstance;
- (void)loadFabricWithSpaceId:(long long)spaceId
                success:(ThingSuccessHandler)success
                      failure:(ThingFailureError)failure;
@end

参数说明

参数	说明
spaceId	当前家庭 HomeID
success	成功回调
failure	失败回调

示例代码

Objective-C：

- (void)loadMatterCurrentHomeFabric:(long long)homeId {
    // 在完成切换家庭/首次加载家庭完成后调用
    [[ThingSmartMatterManager sharedInstance] loadFabricWithSpaceId:homeId success:^{
        NSLog(@"load fabric success");
    } failure:^(NSError *error) {
        NSLog(@"load fabric fail");
    }];
}

Swift：

func loadMatterCurrentHomeFabric(homeId: Int64) {
    // 在完成切换家庭/首次加载家庭完成后调用
    ThingSmartMatterManager.sharedInstance().loadFabric(withSpaceId: homeId) {
        print("load fabric success")
    } failure: { error in
        print("load fabric fail")
    }
}

设备信息准备

相较于其他涂鸦设备，有部分 Matter 设备信息需要提前处理，必须在 家庭设备 和 Fabric 信息准备 两者加载完成后，调用 - getDevicesFabricNodesWithdevIds:callback: 处理家庭中的 Matter 设备。

接口说明

@interface ThingSmartMatterShareManager : NSObject
+ (instancetype)sharedInstance;
- (void)getDevicesFabricNodesWithdevIds:(NSArray <NSString *>*)devIds callback:(void(^)(NSArray <ThingSmartMatterDeviceNodeModel *>*result))callback;
@end

参数说明

参数	说明
devIds	设备 ID 列表

示例代码

Objective-C：

- (void)loadMatterDeviceInfo {
    // 在 - loadFabric 和家庭设备加载完成之后调用
    [[ThingSmartMatterShareManager sharedInstance] getDevicesFabricNodesWithdevIds:deviceIdList callback:^(NSArray<ThingSmartMatterDeviceNodeModel *> *result) {
        NSLog(@"load matter device node succes");
    }];
}

Swift：

func loadMatterDeviceInfo(){
  // 在 - loadFabric 和家庭设备加载完成之后调用
  ThingSmartMatterShareManager.sharedInstance().getDevicesFabricNodesWithdevIds(deviceIdList) { modelList in
      print("load matter device info success")
  }
}