Group Management

Concepts

• A group is an aggregation of one or more devices that follow certain rules. This way, devices can be easily controlled by group.
• A combination group is an aggregation of one or more types of groups. This way, devices and groups can be controlled by combination group.
• The Commercial Lighting App SDK provides the capabilities to create, edit, and control combination groups. A single group in a combination group cannot be managed.
• Each combination group must belong to an area and cannot be created without an area.

The following figure shows the relationships among the combination group, group, and devices.

Functional description

The ThingSmartPackedGroup class requires the combination group ID to implement initialization. An incorrect combination group ID might cause failed initialization. In this case, the instance returns nil.

Class name	Description
ThingSmartPackedGroup	The combination group class.
ThingSmartPackedGroupModel	The data model class of a specified combination group.
ThingSmartPackedGroupManager	The management class of a specified combination group.

Initialize ThingSmartPackedGroup

API description

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

Parameters

Parameter	Description
groupId	The ID of a specified combination group.
projectId	The ID of the project to which a specified combination group belongs.

Data model of ThingSmartPackedGroupModel

Field	Type	Description
projectId	long long	The project ID.
groupPackageId	NSString	The unique ID of a specified combination group.
areaId	long long	The ID of the area to which a specified combination group belongs.
name	NSString	The name of a specified combination group.
deviceNum	NSInteger	The number of devices managed in the combination group.
topCategory	NSInteger	The code of a specified level-1 category.
joinedGroups	NSArray	A collection of common groups under a specified combination group.
type	ThingSmartPackedGroupType	The type of a specified combination group.
dps	NSDictionary	The data point (DP) of a specified combination group.
schemaArray	NSArray	The schema array of DP rules of a specified combination group.

Enumeration of ThingSmartPackedGroupType

Field	Type	Description
ThingSmartPackedGroupEmptyType	NSUInteger	The combination group is empty, with no devices found.
ThingSmartPackedGroupStandardType	NSUInteger	A combination group contains only groups of one protocol.
ThingSmartPackedGroupMixedType	NSUInteger	A combination group contains groups of various protocols.

Query devices available to join a combination group

API description

Returns a list of devices available to join a combination group. The results are displayed on pages.

- (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;

Parameters

Parameter	Description
areaId	The ID of the area to which the specified combination group belongs.
groupPackId	The ID of a specified combination group. If the combination group ID is unavailable at the time of creation, pass an empty string.
topCategory	The code of a specified level-1 category. In the current version, you can only create a combination group of lighting category and pass in ThingSmartTopCategoryZM.
limit	The number of devices returned per page.
offsetKey	The requested page number. The first page defaults to 1, and subsequent page numbers are obtained through callbacks.
success	The success callback.
failure	The failure callback.

Sample code

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) {
    }];
}

Create a combination group

Creates a combination group.

API description

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

Parameters

Parameter	Description
projectId	The project ID.
areaId	The area ID.
packedGroupName	The name of a specified combination group.
addDevices	The list of devices to join the specified combination group. The device list is the device IDs returned by the API getAvailableDevices2JoinPackedGroup.
topCategory	The code of a specified level-1 category. In the current version, you can only create a combination group of lighting category and pass in ThingSmartTopCategoryZM.
Completion callback	The callback of creating a combination group.

Description of TYPackedGroupCreateComplete

Field	Type	Description
group	ThingSmartPackedGroupModel	The data model class of a specified combination group.
failedInfos	NSDictionary	The device IDs that failed to join the group, as well as failure types.

Sample code

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) {

}];

Edit/update group device list

Edits or updates the device list for a specified combination group.

API description

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

Parameters

Parameter	Description
addDevices	The IDs of devices that are newly added to a specified combination group.
removeDevices	The IDs of devices that are removed from a specified combination group.
success	The success callback.
failure	The failure callback.

Sample code

Objective-C:

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

} failure:^(NSError *error) {

}];

Get information of a combination group

Gets the information of a specified combination group.

API description

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

Parameters

Parameter	Description
success	The success callback.
failure	The failure callback.

Sample code

Objective-C:

[group getPackedGroupInfoWithSuccess:^{

} failure:^(NSError *error) {

}];

Rename a combination group

API description

Renames a specified combination group.

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

Parameters

Parameter	Description
name	The name of a specified combination group.
success	The success callback.
failure	The failure callback.

Sample code

Objective-C:

[packedGroup renamePackedGroupWithName:name
                    success:^{

} failure:^(NSError *error) {

}];

Get the list of devices in a combination group

API description

Gets the list of devices in a specified combination group.

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

Parameters

Parameter	Description
limit	The number of devices returned per page.
offsetKey	The requested page number. The first page defaults to 1, and subsequent page numbers are obtained through callbacks.
success	The success callback.
failure	The failure callback.

Sample code

Objective-C:

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

} failure:^(NSError *error) {

}];

Dismiss a combination group

Dismisses a specified combination group.

API description

Before dismissing a combination group, it is recommended to remove all devices from the combination group. There is a limit to the number of groups that a Bluetooth mesh device can join. Once the maximum number of groups is reached, it will be impossible to join a new group.

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

Parameters

Parameter	Description
success	The success callback.
failure	The failure callback.

Sample code

Objective-C:

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

Get a list of combination groups

Gets a list of combination groups.

API description

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

Parameters

Parameter	Description
projectId	The project ID.
areaId	The ID of a specified combination group.
limit	The number of devices returned per page.
offsetKey	The requested page number. The first page defaults to 1, and subsequent page numbers are obtained through callbacks.
success	The success callback.
The failure callback.	failure

Sample code

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) {
    }];
}