Group Management

Last Updated on : 2024-06-12 10:22:49download

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.

Group Management

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