群组管理

概念介绍

• 群组是一个或多个设备按照一定规则的聚合体，通过对群组的控制以达到群控该群组下设备的目的。
• 组合群组是指一个或多个不同类型的小群组的聚合体，通过对组合群组的控制以达到群控该组合群组内的小群组的目的，进而控制所有小群组中的设备。
• 商用照明 SDK 提供组合群组的创建、编辑、控制等能力，暂不支持对单个小群组进行操作。
• 组合群组附属于空间维度下，没有空间时无法创建组合群组。

组合群组、（小）群组、设备三者之前的关系如图所示：

功能说明

TuyaSmartPackedGroup 类需要使用组合群组 id 进行初始化。错误的组合群组 id 可能会导致初始化失败，此时的实例返回 nil

类名	说明
TuyaSmartPackedGroup	组合群组类
TuyaSmartPackedGroupModel	组合群组数据模型类
TuyaSmartPackedGroupManager	组合群组管理类

初始化 TuyaSmartPackedGroup

接口说明

- (instancetype)initWithGroupId:(NSString *)groupId projectId:(long long)projectId;

参数说明

参数	说明
groupId	组合群组 ID
projectId	组合群组所在项目 ID

TuyaSmartPackedGroupModel 数据模型

字段	类型	描述
projectId	long long	对应的项目 ID
groupPackageId	NSString	组合群组唯一 id
areaId	long long	所在的空间 ID
name	NSString	组合群组名称
deviceNum	NSInteger	组合群组下的设备数量
topCategory	NSInteger	一级品类code
joinedGroups	NSArray	组合群组下的普通群组集合
type	TuyaSmartPackedGroupType	组合群组的类型
dps	NSDictionary	组合群组功能点数据
schemaArray	NSArray	组合群组 dp 点规则信息

TuyaSmartPackedGroupType 枚举含义

字段	类型	描述
TuyaSmartPackedGroupEmptyType	NSUInteger	空的组合群组，无设备
TuyaSmartPackedGroupStandardType	NSUInteger	组合群组内只包含一种协议的群组，请参考 TuyaSmartGroup
TuyaSmartPackedGroupMixedType	NSUInteger	组合群组内包含了多种协议的群组

获取可加入组合群组的设备

接口说明

从云端获取可以加入当前群组的设备列表，支持翻页

- (void)getAvailableDevices2JoinPackedGroupWithAreaId:(long long)areaId
                                          topCategory:(TuyaSmartTopCategory)topCategory
                                                limit:(NSInteger)limit
                                            offsetKey:(NSString *)offsetKey
                                              success:(nullable void(^)(NSArray <TuyaSmartDeviceModel *> *devices, NSString *nextOffsetKey, BOOL  end))success
                                              failure:(nullable TYFailureError)failure;

参数说明

参数	说明
areaId	组合群组对应的组合群组 ID
groupPackId	组合群组 ID，创建时无组合群组 ID 时，传空字符串
topCategory	一级品类code，当前版本仅支持创建照明品类组合群组，固定传 TuyaSmartTopCategoryZM
limit	每页请求的设备列表数量
offsetKey	当前请求的页数，第一页为默认为 “1”，后续页数通过回调获取
success	成功回调
failure	失败回调

示例代码

Objc:

- (void)loadData {

    TuyaSmartPackedGroup *group = [TuyaSmartPackedGroup groupWithGroupId:groupId projectId:projectId];
    [group getAvailableDevices2JoinPackedGroupWithAreaId:self.areaId
                                             topCategory:TuyaSmartTopCategoryZM
                                                   limit:20
                                               offsetKey:@"1"
                                                 success:^(NSArray<TuyaSmartDeviceModel *> * _Nonnull devices, NSString * _Nonnull nextOffsetKey, BOOL end) {
        
    } failure:^(NSError *error) {
    
    }];
}

创建组合群组

创建组合群组

接口说明

+ (void)createPackedGroupWithProjectId:(long long)projectId
                                areaId:(long long)areaId
                         groupPackName:(NSString *)groupPackName
                            addDevices:(NSArray<NSString *> *)addDevices
                           topCategory:(TuyaSmartTopCategory)topCategory
                              complete:(nullable TYPackedGroupCreateComplete)complete;

参数说明

参数	说明
projectId	当前项目 ID
areaId	当前组合群组 ID，组合群组附属于组合群组维度下，没有组合群组时无法创建组合群组。
packedGroupName	组合群组名称
addDevices	要加入该组合群组的设备列表，该设备列表为获取能够加入组合群组的设备列表接口返回的设备 ID
topCategory	一级品类code，当前版本仅支持创建照明品类组合群组，固定传 TuyaSmartTopCategoryZM
完成回调	创建组合群组的回调

TYPackedGroupCreateComplete信息

字段	类型	说明
group	TuyaSmartPackedGroupModel	组合群组数据模型类
failedInfos	NSDictionary	加入失败的设备 ID 和失败类型

示例代码

Objc:

[TuyaSmartPackedGroupManager createPackedGroupWithProjectId:self.project.model.projectId
                                                     areaId:self.areaId
                                              groupPackName:name
                                                 addDevices:self.addDevices
                                                topCategory:TuyaSmartTopCategoryZM
                                                   complete:^(TuyaSmartPackedGroupModel * _Nonnull group, NSDictionary<NSString *, NSNumber *> * _Nonnull failedInfos) {

}];

编辑/更新组合群组设备列表

编辑或是更新组合群组设备列表

接口说明

- (void)editPackedGroupWithAddDevices:(NSArray<NSString *> *)addDevices
                        deleteDevices:(NSArray<NSString *> *)removeDevices
                              success:(nullable TYSuccessHandler)success
                              failure:(nullable TYFailureError)failure;

参数说明

参数	说明
addDevices	新添加到当前组合群组的设备ID集合
removeDevices	从当前组合群组中移除的设备ID集合
success	成功回调
failure	失败回调

示例代码

Objc:

[self.packedGroup editPackedGroupWithAddDevices:addDevices
                                  deleteDevices:deleteDevices
                                        success:^{
    
} failure:^(NSError *error) {
    
}];

获取组合群组信息

获取组合群组信息

接口说明

- (void)getPackedGroupInfoWithSuccess:(nullable TYSuccessHandler)success failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objc:

[group getPackedGroupInfoWithSuccess:^{
    
} failure:^(NSError *error) {
    
}];

组合群组重命名

接口说明

组合群组重命名

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

参数说明

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

示例代码

Objc:

[packedGroup renamePackedGroupWithName:name
                    success:^{
    
} failure:^(NSError *error) {
                      
}];

获取组合群组中的设备列表

接口说明

获取组合群组中的设备列表

- (void)getDevicesInPackedGroupWithLimit:(NSInteger)limit
                               offsetKey:(NSString *)offsetKey
                                 success:(nullable void(^)(NSArray <TuyaSmartDeviceModel *> *devices, NSString *nextOffsetKey, BOOL  end))success
                                 failure:(nullable TYFailureError)failure;

参数说明

参数	说明
limit	每页请求的设备列表数量
offsetKey	当前请求的页数，第一页为默认为 “1”，后续页数通过回调获取
success	成功回调
failure	失败回调

示例代码

Objc:

[packedGroup getDevicesInPackedGroupWithLimit:20
                                    offsetKey:@"1"
                                      success:^(NSArray<TuyaSmartDeviceModel *> * _Nonnull devices, NSString * _Nonnull nextOffsetKey, BOOL end) {

} failure:^(NSError *error) {

}];

解散组合群组

解散组合群组

接口说明

**解散组合群组时，建议先将该组合群组中的所有设备移出。**蓝牙Mesh设备能够加入的群组的数量是有限制的，超出群组数量后会出现无法再次加入群组的情况。

- (void)dismissWithSuccess:(nullable TYSuccessID)success failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objc:

- (void)doDismissGroup:(NSString *)groupId {
    [group dismissWithSuccess:^(id result) {
        
    } failure:^(NSError *error) {
      
    }];
}

获取组合群组列表

获取组合群组列表

接口说明

+ (void)getPackedGroupListWithProjectId:(long long)projectId
                                 areaId:(long long)areaId
                                  limit:(NSInteger)limit
                              offsetKey:(NSString *)offsetKey
                                success:(void (^)(NSArray<TuyaSmartPackedGroupModel *> *groups,
                                                  NSString *nextOffsetKey,
                                                  BOOL end))success
                                failure:(nullable TYFailureError)failure;

参数说明

参数	说明
projectId	当前项目 ID
areaId	当前组合群组 ID
limit	每页请求的设备列表数量
offsetKey	当前请求的页数，第一页为默认为 “1”，后续页数通过回调获取
success	成功回调
失败回调	failure

示例代码

Objc:

- (void)loadData {
    [TuyaSmartPackedGroupManager getPackedGroupListWithProjectId:TuyaLightingProject.currentProjectId
                                                          areaId:self.areaId
                                                           limit:20
                                                       offsetKey:@""
                                                         success:^(NSArray<TuyaSmartPackedGroupModel *> * _Nonnull groups, NSString * _Nonnull nextOffsetKey, BOOL end) {
        
    } failure:^(NSError *error) {
                                                           
    }];
}

组合群组控制

组合群组是指对该群组下的设备进行总控的一种功能，目前支持的控制功能为开关、亮度、模式、色温等。TuyaSmartPackedGroup类的以下属性可以获取当前组合群组的状态

TuyaSmartPackedGroup 数据模型

字段	类型	描述
dps	NSDictionary	功能点数据
switchStatus	BOOL	开关状态
sceneStatus	NSString	场景模式，包含以下三种 TUYA_LIGHTING_SCENE_WORK（工作）, TUYA_LIGHTING_SCENE_MEETING（会议）, TUYA_LIGHTING_SCENE_SIESTA（午休）, TUYA_LIGHTING_SCENE_OFF_DUTY（下班）
workModel	NSString	工作模式，有 TUYA_LIGHTING_MODE_WHITE（白光），TUYA_LIGHTING_MODE_COLOUR（彩光），TUYA_LIGHTING_MODE_SCENE（场景）三种
brightPercent	NSInteger	当前亮度，范围0到100
temperaturePercent	NSInteger	当前色温，范围0到100
colorData	NSString	彩光，该操作仅在组合群组处在彩光模式下有效，返回值为12位的组合数据，组合的规则为hhhhssssvvvv，其中hhhh表示16进制后的色调值，ssss表示16进制后的饱和度值，vvvv表示16进制后的亮度值，可使用TuyaLightingColorUtil的decodeNewHsvWithHsvString方法将colorData解码成hsv的值。

组合群组 dp 命令下发

接口说明

- (void)publishDps:(NSDictionary *)dps
           success:(nullable TYSuccessHandler)success
           failure:(nullable TYFailureError)failure;

参数说明

参数	说明
dps	组合群组dp点集合
success	成功回调
failure	失败回调

示例代码

Objc:

[self.packedGroup publishDps:@{@"1" : @"1"} success:^(void) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

设置组合群组快捷开关

接口说明

- (void)publishSwitchStauts:(BOOL)switchValue
                    success:(nullable TYSuccessID)success
                    failure:(nullable TYFailureError)failure;

参数说明

参数	说明
switchStatus	开关状态
success	成功回调
failure	失败回调

示例代码

Objc:

[self.packedGroup publishSwitchStatus:YES success:^(id result) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

设置场景模式

接口说明

该操作仅在组合群组处在场景模式下有效

- (void)publishSceneStatus:(NSString *)sceneId
                   success:(nullable TYSuccessID)success
                   failure:(nullable TYFailureError)failure;

参数说明

参数	说明
sceneId	场景ID，包含以下三种 TUYA_LIGHTING_SCENE_WORK（工作）, TUYA_LIGHTING_SCENE_MEETING（会议）, TUYA_LIGHTING_SCENE_SIESTA（午休）, TUYA_LIGHTING_SCENE_OFF_DUTY（下班）
success	成功回调
failure	失败回调

示例代码

Objc:

[self.packedGroup publishSceneStatus:TUYA_LIGHTING_SCENE_WORK success:^(id result) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

设置工作模式

接口说明

- (void)publishWorkMode:(NSString *)workMode
                success:(nullable TYSuccessID)success
                failure:(nullable TYFailureError)failure;

参数说明

参数	说明
workMode	工作模式，在TUYA_LIGHTING_MODE_WHITE（白光），TUYA_LIGHTING_MODE_COLOUR（彩光），TUYA_LIGHTING_MODE_SCENE（场景）中选一个
success	成功回调
failure	失败回调

示例代码

Objc:

[self.packedGroup publishWorkMode:TUYA_LIGHTING_MODE_WHITE success:^(id result) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

设置亮度

接口说明

该操作仅在组合群组处在白光模式下有效

- (void)publishBrightPercent:(NSInteger)brightPercent
                     success:(nullable TYSuccessID)success
                     failure:(nullable TYFailureError)failure;

参数说明

参数	说明
brightPercent	亮度，范围0到100
success	成功回调
failure	失败回调

示例代码

Objc:

[self.packedGroup publishBrightPercent:100 success:^(id result) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

设置色温

接口说明

该操作仅在组合群组处在白光模式下有效

- (void)publishTemperaturePercent:(NSInteger)temperaturePercent
                          success:(nullable TYSuccessID)success
                          failure:(nullable TYFailureError)failure;

参数说明

参数	说明
TemperaturePercent	色温，范围0到100
success	成功回调
failure	失败回调

示例代码

Objc:

[self.packedGroup publishTemperaturePercent:100 success:^(id result) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

设置亮度和色温

接口说明

该操作仅在组合群组处在白光模式下有效

- (void)publishBrightPercent:(NSInteger)brightPercent
          temperaturePercent:(NSInteger)temperaturePercent
                     success:(nullable TYSuccessID)success
                     failure:(nullable TYFailureError)failure;

参数说明

参数	说明
brightPercent	亮度，范围0到100
temperaturePercent	色温，范围0到100
success	成功回调
failure	失败回调

示例代码

Objc:

[self.packedGroup publishBrightPercent:100 temperaturePercent:100 success:^(id result) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

设置彩光

接口说明

该操作仅在组合群组处在彩光模式下有效，colors为hsv编码后的字符串，可使用TuyaLightingAreaHelper的encodeNewHsvWithHue:saturation:brightness:方法将hsv值编码成colorData。

- (void)publishColors:(NSString *)colors
              success:(nullable TYSuccessID)success
              failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objc:

[self.packedGroup publishColors:@"" success:^(id result) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];