群组管理

概念介绍

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

    }];
}