群组管理

更新时间:2023-03-31 05:45:38下载pdf

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

功能概述

TuyaSmartGroup 类需要使用群组 ID(groupId)初始化。错误的群组 ID 会导致初始化失败,并且实例返回 nil

  • 封装类

    类名 说明
    TuyaSmartGroup 群组类
    TuyaSmartGroupModel 群组数据模型类
  • TuyaSmartGroupModel 数据模型

    字段 类型 描述
    groupId NSString 群组唯一 ID
    productId NSString 群组对应的产品 ID
    time long long 群组的创建时间
    name NSString 群组名称
    iconUrl NSString 群组展示图标的 URL
    type TuyaSmartGroupType 群组类型
    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 <TuyaSmartGroupDevListModel *> *list))success
           failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objective C:

- (void)getGroupDevList {

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

Swift:

func getGroupDevList() {
    TuyaSmartGroup.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 <TuyaSmartGroupDevListModel *> *list))success
           failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objective C:

- (void)getGroupDevList {
//    self.smartGroup = [TuyaSmartGroup groupWithGroupId:@"your_group_id"];
    [self.smartGroup getDevList:@"your_group_product_id" success:^(NSArray<TuyaSmartGroupDevListModel *> *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 (^)(TuyaSmartGroup *group))success
                    failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objective C:

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

Swift:

func createNewGroup() {
    TuyaSmartGroup.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 TYSuccessHandler)success
                     failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objective C:

- (void)updateGroupRelations {
//    self.smartGroup = [TuyaSmartGroup 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 - TuyaSmartGroupDelegate

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

Swift:

// MARK: TuyaSmartGroupDelegate
func group(_ group: TuyaSmartGroup!, 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<TuyaSmartGroupDevListModel *> *))success
                        failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objective C:

- (void)getGroupDevList {
    // 例如:通过当前 Zigbee 子设备去查可以一起创建群组的其他子设备
    TuyaSmartDevice *oneSubDevice = [TuyaSmartDevice deviceWithDeviceId:@"sub device id"];
    NSString *productId = oneSubDevice.deviceModel.productId;
    NSString *gwId = oneSubDevice.deviceModel.parentId;

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

Swift:

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

    TuyaSmartGroup.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 (^)(TuyaSmartGroup *))success
                    failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objective C:

- (void)createNewGroup {

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

Swift:

func createNewGroup() {
    TuyaSmartGroup.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 TYSuccessHandler)success
                            failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objective C:

- (void)addDevice {
    // nodeId 可从 TuyaSmartDeviceModel::nodeId 获取

      // self.smartGroup = [TuyaSmartGroup 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 可从 TuyaSmartDeviceModel::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 TYSuccessHandler)success
                               failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objective C:

- (void)removeDevice {
    // 请先用 `TuyaSmartGroup::groupModel.deviceList` 获取群组内设备列表
        // nodeId 可从 TuyaSmartDeviceModel::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() {
      // 请先用 `TuyaSmartGroup::groupModel.deviceList` 获取群组内设备列表
      // nodeId 可从 TuyaSmartDeviceModel::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 - TuyaSmartGroupDelegate

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

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

Swift:

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

func group(_ group: TuyaSmartGroup?, 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 TYSuccessHandler)success
                     failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objective C:

- (void)updateGroupRelations {
    // self.smartGroup = [TuyaSmartGroup 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:

TuyaSmartGroup *smartGroup = [TuyaSmartGroup groupWithGroupId:groupId];

Swift:

let smartGroup = TuyaSmartGroup(groupId: groupId);

参数说明

参数 说明
groupId 群组 ID

修改群组名称

- (void)updateGroupName:(NSString *)name
                success:(nullable TYSuccessHandler)success
                failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objective C:

- (void)updateGroupName {
        // self.smartGroup = [TuyaSmartGroup 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 TYSuccessHandler)success failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objective C:

- (void)dismissGroup {
        // self.smartGroup = [TuyaSmartGroup 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 TYSuccessHandler)success failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objective C:

- (void)publishDps {
//    self.smartGroup = [TuyaSmartGroup 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")
    })
}

控制回调接口

控制回调由 TuyaSmartHomeDelegate 触发。

- (void)home:(TuyaSmartHome *)home group:(TuyaSmartGroupModel *)group dpsUpdate:(NSDictionary *)dps;

示例代码

Objective C:

#pragma mark - TuyaSmartHomeDelegate
- (void)home:(TuyaSmartHome *)home group:(TuyaSmartGroupModel *)group dpsUpdate:(NSDictionary *)dps {

}

Swift:

extension YourViewController: TuyaSmartHomeDelegate {
    func home(_ home: TuyaSmartHome!, group: TuyaSmartGroupModel!, dpsUpdate dps: [AnyHashable : Any]!) {

    }
}

查询群组列表

Objective C:

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

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

Swift:

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

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