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.

    Group Management

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

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