群组管理

设备群组由同一种类型设备组成，是一系列设备的集合。常见的有 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	失败回调

示例代码

Objc:

- (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
            homeId:(long long)homeId
           success:(nullable void(^)(NSArray <TuyaSmartGroupDevListModel *> *list))success
           failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objc:

- (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	失败回调

示例代码

Objc:

- (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	失败回调

示例代码

Objc:

- (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 下发之后的数据回调更新。

Objc:

#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	失败回调

示例代码

Objc:

- (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	失败回调

示例代码

Objc:

- (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)updateGroupRelations:(NSArray <NSString *>*)devList
                     success:(nullable TYSuccessHandler)success
                     failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objc:

- (void)updateGroupRelations {
// 示例: 
    //  当前群组里有设备：["deviceId 1", "deviceId 2"] （可通过 TuyaSmartGroup::groupModel.deviceList 获取）。
    //  用户在 UI 上操作：添加 "deviceId 3"，移除 "deviceId 1"，
    //  那么可以传递 ["deviceId 2", "deviceId 3"] 来更新保存群组。
  
    // 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() {
    // 示例: 
    //  当前群组里有设备：["deviceId 1", "deviceId 2"] （可通过 TuyaSmartGroup::groupModel.deviceList 获取）。
    //  用户在UI上操作：添加 "deviceId 3"，移除 "deviceId 1"，
    //  那么可以传递 ["deviceId 2", "deviceId 3"] 来更新保存群组。

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

添加设备到群组

接口说明

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

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

参数说明

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

示例代码

Objc:

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

    [self.smartGroup addZigbeeDeviceWithNodeList:@[@"nodeId1", @"nodeId2"]  success:^() {
        NSLog(@"get group dev list success %@:", list);
    } failure:^(NSError *error) {
        NSLog(@"get group dev list failure");
    }];
}

Swift:

func addDevice() {
    // nodeId 可从 TuyaSmartDeviceModel::nodeId 获取。
  	
    smartGroup?.addZigbeeDevice(withNodeList: ["nodeId1", "nodeId2"], success: {
        print("add device success")
    }) { (error) in
        print("add device failure")
    }
}

移除群组中的设备

接口说明

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

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

参数说明

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

示例代码

Objc:

- (void)removeDevice {
    // 请先用 `TuyaSmartGroup::groupModel.deviceList`，获取群组内设备列表。
    // nodeId 可从 TuyaSmartDeviceModel::nodeId 获取。
    [self.smartGroup removeZigbeeDeviceWithNodeList:@[@"nodeId1", @"nodeId2"]  success:^() {
        NSLog(@"get group dev list success %@:", list);
    } failure:^(NSError *error) {
        NSLog(@"get group dev list failure");
    }];
}

Swift:

func removeDevice() {
      	// 请先用 `TuyaSmartGroup::groupModel.deviceList`，获取群组内设备列表。
  	// nodeId 可从 TuyaSmartDeviceModel::nodeId 获取。
  
    smartGroup?.addZigbeeDevice(withNodeList: ["nodeId1", "nodeId2"], success: {
        print("remove device success")
    }) { (error) in
        print("remove device failure")
    }
}

回调接口

Zigbee 设备加入或者移除网关群组的响应。如果返回错误回调，相应的错误码为：

errorCode	说明
1	超过群组数量上限
2	子设备超时
3	设置值超出范围
4	写文件错误
5	其他错误

Objc:

#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 设备从网关群组移除响应
}

群组控制

初始化群组实例

Objc:

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	失败回调

示例代码

Objc:

- (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	失败回调

示例代码

Objc:

- (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	失败回调

示例代码

Objc:

- (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;

示例代码

Objc:

#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]!) {

    }
}

查询群组列表

Objc:

//查询指定群组数据
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