群组管理

设备群组由同一种类型设备组成，是一系列设备的集合。常见的有 Wi-Fi 设备群组和 Zigbee 设备群组。涂鸦支持群组管理体系，您可以创建群组、修改群组名称、管理群组设备，通过群组管理多个设备，解散群组。

功能概述

ThingSmartGroup 类需要使用群组 ID（groupId）初始化。错误的群组 ID 会导致初始化失败，并且实例返回 nil。

• 封装类

  类名	说明
  ThingSmartGroup	群组类
  ThingSmartGroupModel	群组数据模型类

• ThingSmartGroupModel 数据模型

  字段	类型	描述
  groupId	NSString	群组唯一 ID
  productId	NSString	群组对应的产品 ID
  time	long long	群组的创建时间
  name	NSString	群组名称
  iconUrl	NSString	群组展示图标的 URL
  type	ThingSmartGroupType	群组类型
  isShare	BOOL	是否为分享群组
  dps	NSDictionary	群组中设备的功能数据
  dpCodes	NSDictionary	群组中设备的功能数据，以键值对的形式存储
  localKey	NSString	群组通信使用的 Key
  deviceNum	NSInteger	群组下的设备数量
  productInfo	NSDictionary	群组对应的产品相关信息
  pv	NSString	群组协议版本，Wi-Fi 协议版本
  homeId	long long	群组所在的家庭 ID
  roomId	long long	群组所在的房间 ID
  displayOrder	NSInteger	群组在房间维度的排序
  homeDisplayOrder	NSInteger	群组在家庭维度的排序
  deviceList	NSArray	群组的设备列表
  localId	NSString	群组在局域网通讯中的 ID
  meshId	NSString	群组的 Mesh ID
  schemaArray	NSArray	群组 DP 规则信息
  standard	BOOL	是否是标准群组

创建 Wi-Fi 群组

查询可创建群组的设备

根据入口设备的产品 ID，查询家庭下有哪些设备可以与这个设备创建成群组。

+ (void)getDevList:(NSString *)productId
            homeId:(long long)homeId
           success:(nullable void(^)(NSArray <ThingSmartGroupDevListModel *> *list))success
           failure:(nullable ThingFailureError)failure;

参数说明

参数	说明
productId	创建群组入口设备的产品 ID
homeId	群组所在的家庭 ID
success	成功回调
failure	失败回调

示例代码

Objective C：

- (void)getGroupDevList {

    [ThingSmartGroup getDevList:@"your_group_product_id" homeId:homeId success:^(NSArray<ThingSmartGroupDevListModel *> *list) {
        NSLog(@"get group dev list success %@:", list);
    } failure:^(NSError *error) {
        NSLog(@"get group dev list failure");
    }];
}

Swift：

func getGroupDevList() {
    ThingSmartGroup.getDevList("your_group_product_id", homeId:homeId, success: { (list) in
        print("get group dev list success \(list)")
    }) { (error) in
        print("get group dev list failure")
    }
}

查询可加入群组的设备

根据群组的产品 ID，查询家庭下可加入和已加入该群组的设备列表。

- (void)getDevList:(NSString *)productId
           success:(nullable void(^)(NSArray <ThingSmartGroupDevListModel *> *list))success
           failure:(nullable ThingFailureError)failure;

参数说明

参数	说明
productId	群组的产品 ID
success	成功回调
failure	失败回调

示例代码

Objective C：

- (void)getGroupDevList {
//    self.smartGroup = [ThingSmartGroup groupWithGroupId:@"your_group_id"];
    [self.smartGroup getDevList:@"your_group_product_id" success:^(NSArray<ThingSmartGroupDevListModel *> *list) {
        NSLog(@"get group dev list success %@:", list);
    } failure:^(NSError *error) {
        NSLog(@"get group dev list failure");
    }];
}

Swift：

func getGroupDevList() {
    smartGroup?.getDevList("your_group_product_id", success: { (list) in
        print("get group dev list success \(list)")
    }, failure: { (error) in
        print("get group dev list failure")
    })
}

创建一个群组

+ (void)createGroupWithName:(NSString *)name
                  productId:(NSString *)productId
                     homeId:(long long)homeId
                  devIdList:(NSArray<NSString *> *)devIdList
                    success:(nullable void (^)(ThingSmartGroup *group))success
                    failure:(nullable ThingFailureError)failure;

参数说明

参数	说明
name	选择创建群组的名称
productId	选择创建群组的设备的 PID（即 Product ID）
homeId	家庭 ID
devIdList	选择的设备 ID 列表
success	成功回调
failure	失败回调

示例代码

Objective C：

- (void)createNewGroup {
    [ThingSmartGroup createGroupWithName:@"your_group_name" productId:@"your_group_product_id" homeId:homeId devIdList:(NSArray<NSString *> *)selectedDevIdList success:^(ThingSmartGroup *group) {
        NSLog(@"create new group success %@:", group);
    } failure:^(NSError *error) {
        NSLog(@"create new group failure");
    }];
}

Swift：

func createNewGroup() {
    ThingSmartGroup.createGroup(withName: "your_group_name", productId: "your_group_product_id", homeId: homeId, devIdList: ["selectedDevIdList"], success: { (group) in
        print("create new group success: \(group)")
    }) { (error) in
        print("create new group failure")
    }
}

更新保存群组关系

- (void)updateGroupRelations:(NSArray <NSString *>*)devList
                     success:(nullable ThingSuccessHandler)success
                     failure:(nullable ThingFailureError)failure;

参数说明

参数	说明
devList	设备列表的 ID 数组
success	成功回调
failure	失败回调

示例代码

Objective C：

- (void)updateGroupRelations {
//    self.smartGroup = [ThingSmartGroup groupWithGroupId:@"your_group_id"];

    [self.smartGroup updateGroupRelations:(NSArray<NSString *> *)selectedDevIdList success:^ {
        NSLog(@"update group relations success");
    } failure:^(NSError *error) {
        NSLog(@"update group relations failure: %@", error);
    }];
}

Swift：

func updateGroupRelations() {
    smartGroup?.updateRelations(["selectedDevIdList"], success: {
        print("update group relations success")
    }, failure: { (error) in
        if let e = error {
            print("update group relations failure: \(e)")
        }
    })
}

回调接口

群组 DP 下发之后的数据回调更新。

Objective C：

#pragma mark - ThingSmartGroupDelegate

- (void)group:(ThingSmartGroup *)group dpsUpdate:(NSDictionary *)dps {
    //可以在这里刷新群组操作面板的 UI
}

Swift：

// MARK: ThingSmartGroupDelegate
func group(_ group: ThingSmartGroup!, dpsUpdate dps: [AnyHashable : Any]!) {
    //可以在这里刷新群组操作面板的 UI
}

创建 Zigbee 群组

支持 Zigbee 子设备、智能网关 pro 子设备、Sub-G 子设备等复用 Zigbee 网络协议的设备组建群组

查询可创建/加入群组的设备

+ (void)getDevListWithProductId:(NSString *)productId
                           gwId:(NSString *)gwId
                         homeId:(long long)homeId
                        success:(nullable void (^)(NSArray<ThingSmartGroupDevListModel *> *))success
                        failure:(nullable ThingFailureError)failure;

参数说明

参数	说明
productId	群组的产品 ID
gwId	群组的网关 ID
homeId	家庭 ID
success	成功回调
failure	失败回调

示例代码

Objective C：

- (void)getGroupDevList {

    // 例如：通过当前 Zigbee 子设备去查询可以一起创建群组的其他子设备。
    ThingSmartDevice *oneSubDevice = [ThingSmartDevice deviceWithDeviceId:@"sub device id"];
    NSString *productId = oneSubDevice.deviceModel.productId;
    NSString *gwId = oneSubDevice.deviceModel.parentId;

    [ThingSmartGroup getDevListWithProductId:productId gwId:gwId homeId:homeId success:^(NSArray<ThingSmartGroupDevListModel *> *list) {
        NSLog(@"get group dev list success %@:", list);
    } failure:^(NSError *error) {
        NSLog(@"get group dev list failure");
    }];
}

Swift：

func getGroupDevList() {
    // 例如：通过当前 Zigbee 子设备去查询可以一起创建群组的其他子设备。
    guard let oneSubDevice = ThingSmartDevice(deviceId: "sub device id"),
          let productId = oneSubDevice.deviceModel.productId,
          let gwId = oneSubDevice.deviceModel.parentId
    else { return }

    ThingSmartGroup.getDevList(withProductId: productId, gwId: gwId, homeId: hoemId, success: { (list) in
        print("get group dev list success \(list)")
    }) { (error) in
        print("get group dev list failure")
    }
}

创建一个群组

+ (void)createGroupWithName:(NSString *)name
                     homeId:(long long)homeId
                       gwId:(NSString *)gwId
                  productId:(NSString *)productId
                    success:(nullable void (^)(ThingSmartGroup *))success
                    failure:(nullable ThingFailureError)failure;

参数说明

参数	说明
name	群组名称
homeId	要创建群组的家庭 ID
gwId	要创建群组的网关 ID
productId	创建群组入口设备的产品 ID
success	成功回调
failure	失败回调

示例代码

Objective C：

- (void)createNewGroup {

    [ThingSmartGroup createGroupWithName:@"your_group_name" homeId:homeID gwId:@"gwId" productId:@"your_group_product_id" success:^(ThingSmartGroup *group) {
        NSLog(@"create new group success %@:", group);
    } failure:^(NSError *error) {
        NSLog(@"create new group failure");
    }];
}

Swift：

func createNewGroup() {
    ThingSmartGroup.createGroup(withName: "your_group_name", homeId: homeId, gwId: "gwId" productId: "your_group_product_id", success: { (group) in
        print("create new group success: \(group)")
    }) { (error) in
        print("create new group failure")
    }
}

添加设备到群组

接口说明

添加新设备到群组。该过程主要和网关固件交互，会写入群组设备到网关。

- (void)addZigbeeDeviceWithNodeList:(NSArray <NSString *>*)nodeList
                            success:(nullable ThingSuccessHandler)success
                            failure:(nullable ThingFailureError)failure;

参数说明

参数	说明
nodeList	需要添加的设备的节点（Node） ID
success	成功回调
failure	失败回调

示例代码

Objective C：

- (void)addDevice {
    // nodeId 可从 ThingSmartDeviceModel::nodeId 获取
    // self.smartGroup = [ThingSmartGroup groupWithGroupId:@"your_group_id"];

    [self.smartGroup addZigbeeDeviceWithNodeList:@[@"nodeId1", @"nodeId2"] success:^() {
        NSLog(@"send add device msg success");
        // 实际操作结果需要监听 -group:addResponseCode: 回调。
    // 在收到回调后，选择合适的时机调用 -updateGroupRelations:success:failure: 更新关系
    } failure:^(NSError *error) {
        NSLog(@"send add device msg failure");
    }];
}

Swift：

func addDevice() {
    // nodeId 可从 ThingSmartDeviceModel::nodeId 获取。

    smartGroup?.addZigbeeDevice(withNodeList: ["nodeId1", "nodeId2"], success: {
        print("send add device msg success")
        // 实际操作结果需要监听 group(_, addResponseCode) 回调。
    // 在收到回调后，选择合适的时机调用 updateGroupRelations(_, success, failure) 更新关系
    }) { (error) in
        print("send add device msg failure")
    }
}

移除群组中的设备

接口说明

移除网关中存储的群组中的已有设备。

- (void)removeZigbeeDeviceWithNodeList:(NSArray <NSString *>*)nodeList
                               success:(nullable ThingSuccessHandler)success
                               failure:(nullable ThingFailureError)failure;

参数说明

参数	说明
nodeList	需要移除的设备的节点（Node） ID
success	成功回调
failure	失败回调

示例代码

Objective C：

- (void)removeDevice {
  // 请先用 `ThingSmartGroup::groupModel.deviceList`，获取群组内设备列表。
  // nodeId 可从 ThingSmartDeviceModel::nodeId 获取。
  [self.smartGroup removeZigbeeDeviceWithNodeList:@[@"nodeId1", @"nodeId2"] success:^() {
        NSLog(@"send remove device msg success");
        // 实际操作结果需要监听 -group:removeResponseCode: 回调。
        // 在收到回调后，选择合适的时机调用 -updateGroupRelations:success:failure: 更新关系
  } failure:^(NSError *error) {
        NSLog(@"send remove device msg failure");
    }];
}

Swift：

func removeDevice() {
    // 请先用 `ThingSmartGroup::groupModel.deviceList`，获取群组内设备列表。
    // nodeId 可从 ThingSmartDeviceModel::nodeId 获取。

    smartGroup?.addZigbeeDevice(withNodeList: ["nodeId1", "nodeId2"], success: {
        print("send remove device msg success")
        // 实际操作结果需要监听 group(_, removeResponseCode) 回调。
    // 在收到回调后，选择合适的时机调用 updateGroupRelations(_, success, failure) 更新关系
    }) { (error) in
        print("send remove device msg failure")
    }
}

设备加入群组/被移除的回调接口

Zigbee 设备加入或者移除网关群组的操作结果的响应。回调中 responseCode 为 0 时操作成功，其余均为失败，详细定义如下：

responseCode	含义
0	添加或移除成功
1	超过群组数量上限
2	子设备超时
3	设置值超出范围
4	写文件错误
5	其他错误

回调中 responseCode 是响应结果的数组，与添加或移除时传入的设备顺序一致。例如：

1. 添加或移除设备时：
   • 传入为 nodeList=[a, b, c]
   • 响应为 responseCode=[0, 1, 0]
2. 则本次操作结果为：
   • 设备 a 添加或移除成功
   • 设备 b 添加或移除失败
   • 设备 c 添加或移除成功

Objective C：

#pragma mark - ThingSmartGroupDelegate

- (void)group:(ThingSmartGroup *)group addResponseCode:(NSArray <NSNumber *>*)responseCode {
    // Zigbee 设备加入到网关的群组响应
}

- (void)group:(ThingSmartGroup *)group removeResponseCode:(NSArray <NSNumber *>*)responseCode {
    // Zigbee 设备从网关群组移除响应
}

Swift：

// MARK: ThingSmartGroupDelegate
func group(_ group: ThingSmartGroup?, addResponseCode responseCode: [NSNumber]?) {
    // Zigbee 设备加入到网关的群组响应
}

func group(_ group: ThingSmartGroup?, removeResponseCode responseCode: [NSNumber]?) {
    // Zigbee 设备从网关群组移除响应
}

更新保存群组关系

在 操作添加或移除 并 收到操作响应回调 后，根据响应回调结果，在合适的时机，调用本方法可以更新保存群组设备关系。

举例说明

原本群组里有设备 [a, b, c]：

• 用户 UI 操作：
  1. 添加 [e, f]
  2. 移除 [a, b]
  3. 保存群组
• App 开发顺序：

  1. 调用群组设备添加接口及群组设备移除接口。

  2. 收到添加设备回调：

     • responseCode [0, 1]，则代表：添加 设备 e 成功，添加 设备 f 失败。
     • responseCode [1, 0]，则代表：移除 设备 a 失败，移除 设备 b 成功

  3. 最终这个群组的设备列表为 [a, c, e]，调用更新保存群组关系接口，传递 devList = [a, c, e]。

     更新保存群组关系接口传递的是设备 devId 而非 nodeId。

接口说明

- (void)updateGroupRelations:(NSArray <NSString *>*)devList
                     success:(nullable ThingSuccessHandler)success
                     failure:(nullable ThingFailureError)failure;

参数说明

参数	说明
devList	设备列表的 ID 数组
success	成功回调
failure	失败回调

示例代码

Objective C：

- (void)updateGroupRelations {
    // self.smartGroup = [ThingSmartGroup groupWithGroupId:@"your_group_id"];
    [self.smartGroup updateGroupRelations:@[@"deviceId 2", @"deviceId3", ....] success:^ {
        NSLog(@"update group relations success");
    } failure:^(NSError *error) {
        NSLog(@"update group relations failure: %@", error);
    }];
}

Swift：

func updateGroupRelations() {
    smartGroup?.updateRelations(["deviceId 2", "deviceId3", ....], success: {
        print("update group relations success")
    }, failure: { (error) in
        if let e = error {
            print("update group relations failure: \(e)")
        }
    })
}

群组控制

初始化群组实例

Objective C：

ThingSmartGroup *smartGroup = [ThingSmartGroup groupWithGroupId:groupId];

Swift：

let smartGroup = ThingSmartGroup(groupId: groupId);

参数说明

参数	说明
groupId	群组 ID

修改群组名称

- (void)updateGroupName:(NSString *)name
                success:(nullable ThingSuccessHandler)success
                failure:(nullable ThingFailureError)failure;

参数说明

参数	说明
name	群组名称
success	成功回调
failure	失败回调

示例代码

Objective C：

- (void)updateGroupName {
// self.smartGroup = [ThingSmartGroup groupWithGroupId:@"your_group_id"];

    [self.smartGroup updateGroupName:@"your_group_name" success:^{
        NSLog(@"update group name success");
    } failure:^(NSError *error) {
        NSLog(@"update group name failure: %@", error);
    }];
}

Swift：

func updateGroupName() {
    smartGroup?.updateName("your_group_name", success: {
        print("updateGroupName success")
    }, failure: { (error) in
        if let e = error {
            print("updateGroupName failure: \(e)")
        }
    })
}

解散一个群组

- (void)dismissGroup:(nullable ThingSuccessHandler)success failure:(nullable ThingFailureError)failure;

参数说明

参数	说明
success	成功回调
failure	失败回调

示例代码

Objective C：

- (void)dismissGroup {
// self.smartGroup = [ThingSmartGroup groupWithGroupId:@"your_group_id"];

    [self.smartGroup dismissGroup:^{
      NSLog(@"dismiss group success");
    } failure:^(NSError *error) {
      NSLog(@"dismiss group failure: %@", error);
    }];
}

Swift：

func dismissGroup() {
    smartGroup?.dismiss({
        print("dismiss group success")
    }, failure: { (error) in
        if let e = error {
            print("dismiss group failure: \(e)")
        }
    })
}

发送群组控制指令

接口说明

- (void)publishDps:(NSDictionary *)dps
           success:(nullable ThingSuccessHandler)success failure:(nullable ThingFailureError)failure;

参数说明

参数	说明
dps	要下发的 DP，用来控制设备功能
success	成功回调
failure	失败回调

示例代码

Objective C：

- (void)publishDps {
//    self.smartGroup = [ThingSmartGroup groupWithGroupId:@"your_group_id"];

    NSDictionary *dps = @{@"1": @(YES)};
    [self.smartGroup publishDps:dps success:^{
        NSLog(@"publishDps success");
    } failure:^(NSError *error) {
        NSLog(@"publishDps failure: %@", error);
    }];
}

Swift：

func publishDps() {
    let dps = ["1" : true]
    smartGroup?.publishDps(dps, success: {
        print("publishDps success")
    }, failure: { (error) in
        print("publishDps failure")
    })
}

控制回调接口

控制回调由 ThingSmartHomeDelegate 触发。

- (void)home:(ThingSmartHome *)home group:(ThingSmartGroupModel *)group dpsUpdate:(NSDictionary *)dps;

示例代码

Objective C：

#pragma mark - ThingSmartHomeDelegate
- (void)home:(ThingSmartHome *)home group:(ThingSmartGroupModel *)group dpsUpdate:(NSDictionary *)dps {

}

Swift：

extension YourViewController: ThingSmartHomeDelegate {
    func home(_ home: ThingSmartHome!, group: ThingSmartGroupModel!, dpsUpdate dps: [AnyHashable : Any]!) {

    }
}

查询群组列表

Objective C：

//查询指定群组数据
ThingSmartGroupModel *smartGroupModel = [ThingSmartGroup groupWithGroupId:groupId].groupModel;

//查询群组下设备列表
NSArray<ThingSmartDeviceModel *> *deviceList = [ThingSmartGroup groupWithGroupId:groupId].groupModel.deviceList;

Swift：

//查询指定群组数据
let smartGroupModel = ThingSmartGroup(groupId: "groupId")?.groupModel

//查询群组下设备列表
let deviceList = ThingSmartGroup(groupId: "groupId")?.groupModel.deviceList