简体中文
简体中文
English
联系我们
注册
登录
layout空间导航

群组管理

更新时间:2021-11-23 01:47:51下载pdf

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

功能概述

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

  • 封装类

    类名 说明
    TuyaGroupDevice 群组类
    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 群组

查询可创建群组的设备

+ (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 {

    [TuyaSmartGroup getDevListWithProductId:@"your_group_product_id" 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() {
    TuyaSmartGroup.getDevList(withProductId: "your_group_product_id", 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)addZigbeeDeviceWithNodeList:(NSArray <NSString *>*)nodeList
                            success:(nullable TYSuccessHandler)success
                            failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objc:

- (void)addDevice {
//    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() {
    martGroup.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 {

    [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() {
    martGroup.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