IoT App SDKCommercial Lighting App SDKiOS PlatformGroup Management

Group Management

Last Updated on : 2022-02-17 05:22:28download

Overview

A group is an aggregation of one or more devices according to certain rules, through the control of the group to achieve the purpose of group control of the devices under the group.
A packed group is an aggregation of one or more different types of small groups, through the control of the packed groups to achieve the purpose of group control of the small groups within the packed groups, and then control all the small groups of devices.
The Commercial Lighting SDK provides the capabilities to create, edit, and control combinatorial groups, but does not support the operation of individual sub-groups at this time.
Packed groups are attached to the space dimension and cannot be created when no space is available.

The relationship between packed groups - (small) groups - devices is shown in the figure below.

The TuyaSmartPackedGroup class needs to be initialized with the packed group id. Incorrect packed of group id may cause initialization failure, the instance at this time returns nil

Class name	Description
TuyaSmartPackedGroup	packed group class
TuyaSmartPackedGroupModel	packed group data model class
TuyaSmartPackedGroupManager	Portfolio Group Management Class

Initialize TuyaSmartPackedGroup

Interface Description

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

Parameter Description

Parameters	Description
groupId	Packed group ID
projectId	ID of the project where the packed group is located

TuyaSmartPackedGroupModel data model

Field	Type	Description
projectId	long long	Corresponding project ID
groupPackageId	NSString	packed group unique id
areaId	long long	Location ID
name	NSString	Packed group name
deviceNum	NSInteger	Number of devices under the packed group
topCategory	NSInteger	First-class category code
joinedGroups	NSArray	Common group collection under packed group
type	TuyaSmartPackedGroupType	Type of packed group
dps	NSDictionary	Packed group DP data
schemaArray	NSArray	Packed group DP rule information

TuyaSmartPackedGroupType enumeration meaning

Field	Type	Description
TuyaSmartPackedGroupEmptyType	NSUInteger	Empty packed group, no device
TuyaSmartPackedGroupStandardType	NSUInteger	Groups that contain only one protocol in the packed group. For more information, see [TuyaSmartGroup](https://developer.tuya.com/en/docs/Device%20Core%20for%20iOS/DeviceControlGroup?id= Kampy4jph79ds)
TuyaSmartPackedGroupMixedType	NSUInteger	A group containing multiple protocols in a packed group

Get devices that can be added to a packed group

Interface Description

Returns a list of devices that can be added to the current group from the cloud. The returned entries can be displayed on pages.

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

Parameter Description

Parameters	Description
areaId	Packed group ID corresponding to the packed group
groupPackId	Packed group ID. If no packed group ID is available for creation, pass an empty string
topCategory	The first-level category code. The current version only supports the creation of lighting category packed groups, and the fixed transmission `TuyaSmartTopCategoryZM`
limit	The number of device lists requested per page
offsetKey	The number of pages currently requested. The first page is “1” by default, and the number of subsequent pages is obtained by callback
success	Success callback
failure	Failure callback

Example

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

    }];
}

Create a packed group

Interface description

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

Parameters

Parameter	Description
projectId	Current project ID
areaId	ID of the current packed group. The packed group is attached to the packed group dimension. If there is no packed group, the packed group cannot be created.
packedGroupName	packed group name
addDevices	The list of devices to be added to the packed group, the device list is the device ID returned by the Get the list of devices that can be added to the packed group interface
topCategory	The first-level category code. The current version only supports the creation of lighting category packed groups, and the fixed transmission `TuyaSmartTopCategoryZM`
Completion callback	Create packed group callback

TYPackedGroupCreateComplete information

Field	Type	Description
group	TuyaSmartPackedGroupModel	Packed group data model class
failedInfos	NSDictionary	Join failed device ID and failure type

Example

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

}];

Edit and update a list of packed group devices

Edits or updates a list of packed group devices

Interface description

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

Parameters

Parameters	Description
addDevices	Set of device IDs newly added to the current packed group
removeDevices	The set of device IDs removed from the current packed group
success	Success callback
failure	Failure callback

Example

ObjC:

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

} failure:^(NSError *error) {

}];

Get packed group information

Returns packed group information.

Interface description

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

Parameters

Parameters	Description
success	Success callback
failure	Failure callback

Example

ObjC:

[group getPackedGroupInfoWithSuccess:^{

} failure:^(NSError *error) {

}];

Rename a packed group

Interface description

Renames a packed group.

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

Parameters

Parameters	Description
name	Packed group name
success	Success callback
failure	Failure callback

Example

ObjC:

[packedGroup renamePackedGroupWithName:name
                    success:^{

} failure:^(NSError *error) {

}];

Get the list of devices in the packed group

Interface description

Returns a list of devices in the packed group.

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

Parameters

Parameters	Description
limit	The number of device lists requested per page
offsetKey	The number of pages currently requested, the first page is “1” by default, and the number of subsequent pages is obtained by callback
success	Success callback
failure	Failure callback

Example

ObjC:

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

} failure:^(NSError *error) {

}];

Delete a packed group

Deletes a packed group.

Interface description

**To delete a packed group, we recommend that you remove all devices from the packed group first. ** The number of groups that Bluetooth mesh devices can join is limited. After the maximum number of groups is exceeded, the devices cannot join more groups.

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

Parameters

Parameters	Description
success	Success callback
failure	Failure callback

Example

ObjC:

-(void)doDismissGroup:(NSString *)groupId {
    [group dismissWithSuccess:^(id result) {

    } failure:^(NSError *error) {

    }];
}

Get the list of packed groups

Returns a list of packed groups.

Interface description

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

Parameters

Parameters	Description
projectId	Current project ID
areaId	Current packed group ID
limit	The number of device lists requested per page
offsetKey	The number of pages currently requested, the first page is “1” by default, and the number of subsequent pages is obtained by callback
success	Success callback
failure	Failure callback

Example

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

    }];
}

Packed group control

A packed group is used to control devices in the group. Currently, group devices can be controlled in terms of the switch status, brightness, mode, color temperature, and more. The following properties of the TuyaSmartPackedGroup class can be used to get the status of the current packed group.

TuyaSmartPackedGroup data model

Field	Type	Description
dps	NSDictionary	DP data
switchStatus	BOOL	Switch status
sceneStatus	NSString	Scene mode, including the following three TUYA_LIGHTING_SCENE_WORK (work), TUYA_LIGHTING_SCENE_MEETING (meeting), TUYA_LIGHTING_SCENE_SIESTA (lunch break), TUYA_LIGHTING_SCENE_OFF_DUTY (off work)
workModel	NSString	Three working modes are supported: TUYA_LIGHTING_MODE_WHITE (white light), TUYA_LIGHTING_MODE_COLOUR (color light), and TUYA_LIGHTING_MODE_SCENE (scene)
brightPercent	NSInteger	Current brightness, range 0 to 100
temperaturePercent	NSInteger	Current color temperature, ranging from `0` to `100`
colorData	NSString	Color light. This operation is only valid in the color light mode of the packed group, the return value is 12-bit packed data, and the packed rule is `hhhhssssvvvv`, where `hhhh` represents the hexadecimal hue value, `ssss` represents the saturation value after hexadecimal, and `vvvv` represents the brightness value after hexadecimal. You can use the `decodeNewHsvWithHsvString` method of `TuyaLightingColorUtil` to decode `colorData` into the value of `hsv`.

Send packed group DP commands

Interface description

-(void)publishDps:(NSDictionary *)dps
           success:(nullable TYSuccessHandler)success
           failure:(nullable TYFailureError)failure;

Parameters

Parameters	Description
dps	A collect of packed group DPs
success	Success callback
failure	Failure callback

Example

ObjC:

[self.packedGroup publishDps:@{@"1": @"1"} success:^(void) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

Set packed group shortcut switch

Interface description

-(void)publishSwitchStauts:(BOOL)switchValue
                    success:(nullable TYSuccessID)success
                    failure:(nullable TYFailureError)failure;

Parameters

Parameters	Description
switchStatus	Switch Status
success	Success callback
failure	Failure callback

Example

ObjC:

[self.packedGroup publishSwitchStatus:YES success:^(id result) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

Set the scene mode

Interface description

This operation is only valid in scene mode in the packed group

-(void)publishSceneStatus:(NSString *)sceneId
                   success:(nullable TYSuccessID)success
                   failure:(nullable TYFailureError)failure;

Parameters

Parameters	Description
sceneId	Scene ID, including the following three types: TUYA_LIGHTING_SCENE_WORK (work), TUYA_LIGHTING_SCENE_MEETING (meeting), TUYA_LIGHTING_SCENE_SIESTA (lunch break), TUYA_LIGHTING_SCENE_OFF_DUTY (off work)
success	Success callback
failure	Failure callback

Example

ObjC:

[self.packedGroup publishSceneStatus:TUYA_LIGHTING_SCENE_WORK success:^(id result) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

Set the working mode

Interface description

-(void)publishWorkMode:(NSString *)workMode
                success:(nullable TYSuccessID)success
                failure:(nullable TYFailureError)failure;

Parameters

Parameters	Description
workMode	The working mode. Valid values: `TUYA_LIGHTING_MODE_WHITE` (white light) and `TUYA_LIGHTING_MODE_COLOUR` (color light), TUYA_LIGHTING_MODE_SCENE (scene)
success	Success callback
failure	Failure callback

Example

ObjC:

[self.packedGroup publishWorkMode:TUYA_LIGHTING_MODE_WHITE success:^(id result) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

##Set brightness

Interface description

This operation is only valid in the white light mode in the packed group.

-(void)publishBrightPercent:(NSInteger)brightPercent
                     success:(nullable TYSuccessID)success
                     failure:(nullable TYFailureError)failure;

Parameters

Parameters	Description
brightPercent	Brightness, ranging from `0` to `100`
success	Success callback
failure	Failure callback

Example

ObjC:

[self.packedGroup publishBrightPercent:100 success:^(id result) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

Set color temperature

Interface description

This operation is only valid in the white light mode in the packed group.

-(void)publishTemperaturePercent:(NSInteger)temperaturePercent
                          success:(nullable TYSuccessID)success
                          failure:(nullable TYFailureError)failure;

Parameters

Parameters	Description
TemperaturePercent	Color temperature, ranging from `0` to `100`
success	Success callback
failure	Failure callback

Example

ObjC:

[self.packedGroup publishTemperaturePercent:100 success:^(id result) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

Set brightness and color temperature

Interface description

This operation is only valid in the white light mode in the packed group.

-(void)publishBrightPercent:(NSInteger)brightPercent
          temperaturePercent:(NSInteger)temperaturePercent
                     success:(nullable TYSuccessID)success
                     failure:(nullable TYFailureError)failure;

Parameters

Parameters	Description
brightPercent	Brightness, ranging from `0` to `100`
temperaturePercent	Color temperature, ranging from `0` to `100`
success	Success callback
failure	Failure callback

Example

ObjC:

[self.packedGroup publishBrightPercent:100 temperaturePercent:100 success:^(id result) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

Set IPL

Interface description

This operation is only valid when the packed group is in the color light mode. Colors is a string encoded by hsv. You can use the encodeNewHsvWithHue:saturation:brightness: method of TuyaLightingAreaHelper to encode the hsv value into colorData.

-(void)publishColors:(NSString *)colors
              success:(nullable TYSuccessID)success
              failure:(nullable TYFailureError)failure;

Parameters

Parameters	Description
colors	IPL
success	Success callback
failure	Failure callback

Example

ObjC:

[self.packedGroup publishColors:@"" success:^(id result) {
    NSLog(@"success");
} failure:^(NSError *error){
    NSLog(@"failure");
}];

Prev DocArea Management

Next DocEnergy Consumption