群组管理

更新时间:2024-03-28 01:35:58下载pdf

概念介绍

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

组合群组、(小)群组和设备三者之前的关系如图所示:

群组管理

功能说明

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

类名 说明
ThingSmartPackedGroup 组合群组类
ThingSmartPackedGroupModel 组合群组数据模型类
ThingSmartPackedGroupManager 组合群组管理类

初始化 ThingSmartPackedGroup

接口说明

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

参数说明

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

ThingSmartPackedGroupModel 数据模型

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

ThingSmartPackedGroupType 枚举含义

字段 类型 描述
ThingSmartPackedGroupEmptyType NSUInteger 空的组合群组,无设备
ThingSmartPackedGroupStandardType NSUInteger 组合群组内只包含一种协议的群组
ThingSmartPackedGroupMixedType NSUInteger 组合群组内包含多种协议的群组

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

接口说明

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

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

参数说明

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

示例代码

Objective-C:

- (void)loadData {

    ThingSmartPackedGroup *group = [ThingSmartPackedGroup groupWithGroupId:groupId projectId:projectId];
    [group getAvailableDevices2JoinPackedGroupWithAreaId:self.areaId
                                             topCategory:ThingSmartTopCategoryZM
                                                   limit:20
                                               offsetKey:@"1"
                                                 success:^(NSArray<ThingSmartDeviceModel *> * _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:(ThingSmartTopCategory)topCategory
                              complete:(nullable TYPackedGroupCreateComplete)complete;

参数说明

参数 说明
projectId 当前项目 ID
areaId 当前空间 ID
packedGroupName 组合群组名称
addDevices 要加入该组合群组的设备列表,该设备列表为 获取可加入组合群组的设备 接口返回的设备 ID
topCategory 一级品类 Code,当前版本仅支持创建照明品类组合群组,固定传 ThingSmartTopCategoryZM
完成回调 创建组合群组的回调

TYPackedGroupCreateComplete 信息

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

示例代码

Objective-C:

[ThingSmartPackedGroupManager createPackedGroupWithProjectId:self.project.model.projectId
                                                     areaId:self.areaId
                                              groupPackName:name
                                                 addDevices:self.addDevices
                                                topCategory:ThingSmartTopCategoryZM
                                                   complete:^(ThingSmartPackedGroupModel * _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 失败回调

示例代码

Objective-C:

[self.packedGroup editPackedGroupWithAddDevices:addDevices
                                  deleteDevices:deleteDevices
                                        success:^{

} failure:^(NSError *error) {

}];

获取组合群组信息

获取组合群组的相关信息。

接口说明

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

参数说明

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

示例代码

Objective-C:

[group getPackedGroupInfoWithSuccess:^{

} failure:^(NSError *error) {

}];

组合群组重命名

接口说明

重命名一个组合群组。

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

参数说明

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

示例代码

Objective-C:

[packedGroup renamePackedGroupWithName:name
                    success:^{

} failure:^(NSError *error) {

}];

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

接口说明

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

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

参数说明

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

示例代码

Objective-C:

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

} failure:^(NSError *error) {

}];

解散组合群组

解散组合群组。

接口说明

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

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

参数说明

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

示例代码

Objective-C:

- (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<ThingSmartPackedGroupModel *> *groups,
                                                  NSString *nextOffsetKey,
                                                  BOOL end))success
                                failure:(nullable TYFailureError)failure;

参数说明

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

示例代码

Objective-C:

- (void)loadData {
    [ThingSmartPackedGroupManager getPackedGroupListWithProjectId:ThingLightingProject.currentProjectId
                                                          areaId:self.areaId
                                                           limit:20
                                                       offsetKey:@""
                                                         success:^(NSArray<ThingSmartPackedGroupModel *> * _Nonnull groups, NSString * _Nonnull nextOffsetKey, BOOL end) {

    } failure:^(NSError *error) {

    }];
}