简体中文
简体中文
English
联系我们
注册
登录

群组管理

更新时间:2022-02-17 05:22:28下载pdf

概念介绍

  • 群组是一个或多个设备按照一定规则的聚合体,通过对群组的控制以达到群控该群组下设备的目的。
  • 组合群组是指一个或多个不同类型的小群组的聚合体,通过对组合群组的控制以达到群控该组合群组内的小群组的目的,进而控制所有小群组中的设备。
  • 商用照明 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");
}];