1. Group Management
1.1. Functional Overview
The Tuya Cloud supports the group management system. User can create group, change group name, manage devices of group, manage multiple devices via the group and dismiss group. Tuya Smart provides some interfaces for device group control.
All functions of group are realized by using the TuyaSmartGroup
class, and all functions need to be initiated by using the group Id. Wrong group Id may cause initiation failure, and the nil
will be returned.
Class | Description |
---|---|
TuyaGroupDevice | Tuya Group Class |
TuyaSmartGroupModel | Tuya Group Model Class |
TuyaSmartGroupModel
Data Model
Field | Type | Description |
---|---|---|
groupId | NSString | group id |
productId | NSString | group product id |
time | long long | group create time |
name | NSString | group name |
iconUrl | NSString | group icon url |
type | TuyaSmartGroupType | group type |
isShare | BOOL | is share group |
dps | NSDictionary | group data point |
dpCodes | NSDictionary | group dp code |
localKey | NSString | A Key Used For Device Communication |
deviceNum | NSInteger | group device number |
productInfo | NSDictionary | group product info |
pv | NSString | protocol version |
homeId | long long | group home id |
roomId | long long | group room id |
displayOrder | NSInteger | group room display order |
homeDisplayOrder | NSInteger | group home display order |
deviceList | NSArray | group device list |
localId | NSString | group local id |
meshId | NSString | group mesh id |
schemaArray | NSArray | data point detail |
standard | BOOL | is a standardized device |
1.2. Create Group
1.2.1. Create Wi-Fi Group
Group List Acquisition
Obtain the device list of product when the group is not created.
+ (void)getDevList:(NSString *)productId
homeId:(long long)homeId
success:(nullable void(^)(NSArray <TuyaSmartGroupDevListModel *> *list))success
failure:(nullable TYFailureError)failure;
Parameters
Parameter | Description |
---|---|
productId | 创建群组入口设备的产品 id |
homeId | home id |
success | success call back |
failure | failure call back |
Example
Objc:
- (void)getGroupDevList {
[TuyaSmartGroup getDevList:@"your_group_product_id" homeId:homeId success:^(NSArray<TuyaSmartGroupDevListModel *> *list) {
NSLog(@"get group dev list success %@:", list);
} failure:^(NSError *error) {
NSLog(@"get group dev list failure");
}];
}
Swift:
func getGroupDevList() {
TuyaSmartGroup.getDevList("your_group_product_id", homeId: 1, success: { (list) in
print("get group dev list success \(list)")
}) { (error) in
print("get group dev list failure")
}
}
Obtain the Device List of a Group
Obtain the device list of a group when the group is created.
- (void)getDevList:(NSString *)productId
homeId:(long long)homeId
success:(nullable void(^)(NSArray <TuyaSmartGroupDevListModel *> *list))success
failure:(nullable TYFailureError)failure;
Parameters
Parameter | Description |
---|---|
productId | product id |
homeId | home id |
success | success callback |
failure | 失败回调 |
Example
Objc:
- (void)getGroupDevList {
// self.smartGroup = [TuyaSmartGroup groupWithGroupId:@"your_group_id"];
[self.smartGroup getDevList:@"your_group_product_id" success:^(NSArray<TuyaSmartGroupDevListModel *> *list) {
NSLog(@"get group dev list success %@:", list);
} failure:^(NSError *error) {
NSLog(@"get group dev list failure");
}];
}
Swift:
func getGroupDevList() {
smartGroup?.getDevList("your_group_product_id", success: { (list) in
print("get group dev list success \(list)")
}, failure: { (error) in
print("get group dev list failure")
})
}
Creating a Group
+ (void)createGroupWithName:(NSString *)name
productId:(NSString *)productId
homeId:(long long)homeId
devIdList:(NSArray<NSString *> *)devIdList
success:(nullable void (^)(TuyaSmartGroup *group))success
failure:(nullable TYFailureError)failure;
Parameters
Parameter | Description |
---|---|
name | name |
productId | product id |
homeId | group's home id |
devIdList | device list |
success | success callback |
failure | failure callback |
Example
Objc:
- (void)createNewGroup {
[TuyaSmartGroup createGroupWithName:@"your_group_name" productId:@"your_group_product_id" homeId:homeId devIdList:(NSArray<NSString *> *)selectedDevIdList success:^(TuyaSmartGroup *group) {
NSLog(@"create new group success %@:", group);
} failure:^(NSError *error) {
NSLog(@"create new group failure");
}];
}
Swift:
func createNewGroup() {
TuyaSmartGroup.createGroup(withName: "your_group_name", productId: "your_group_product_id", homeId: homeId, devIdList: ["selectedDevIdList"], success: { (group) in
print("create new group success: \(group)")
}) { (error) in
print("create new group failure")
}
}
Update and Save Group
- (void)updateGroupRelations:(NSArray <NSString *>*)devList
success:(nullable TYSuccessHandler)success
failure:(nullable TYFailureError)failure;
Parameters
Parameter | Description |
---|---|
devList | device list |
success | success callback |
failure | failure callback |
Example
Objc:
- (void)updateGroupRelations {
// self.smartGroup = [TuyaSmartGroup groupWithGroupId:@"your_group_id"];
[self.smartGroup updateGroupRelations:(NSArray<NSString *> *)selectedDevIdList success:^ {
NSLog(@"update group relations success");
} failure:^(NSError *error) {
NSLog(@"update group relations failure: %@", error);
}];
}
Swift:
func updateGroupRelations() {
smartGroup?.updateRelations(["selectedDevIdList"], success: {
print("update group relations success")
}, failure: { (error) in
if let e = error {
print("update group relations failure: \(e)")
}
})
}
Callback interface
Callback and data updating after the group sends DP.
Objc:
#pragma mark - TuyaSmartGroupDelegate
- (void)group:(TuyaSmartGroup *)group dpsUpdate:(NSDictionary *)dps {
// TODO: update group panel UI here
}
Swift:
// MARK: TuyaSmartGroupDelegate
func group(_ group: TuyaSmartGroup!, dpsUpdate dps: [AnyHashable : Any]!) {
// TODO: update group panel UI here
}
1.2.2. Create ZigBee Group
Group List Acquisition
+ (void)getDevListWithProductId:(NSString *)productId
gwId:(NSString *)gwId
homeId:(long long)homeId
success:(nullable void (^)(NSArray<TuyaSmartGroupDevListModel *> *))success
failure:(nullable TYFailureError)failure;
Parameters
Parameter | Description |
---|---|
productId | group product id |
gwId | gateway id |
homeId | home id |
success | success callback |
failure | failure callback |
Example
Objc:
- (void)getGroupDevList {
[TuyaSmartGroup getDevListWithProductId:@"your_group_product_id" gwId:@"gwId" homeId:homeId success:^(NSArray<TuyaSmartGroupDevListModel *> *list) {
NSLog(@"get group dev list success %@:", list);
} failure:^(NSError *error) {
NSLog(@"get group dev list failure");
}];
}
Swift:
func getGroupDevList() {
TuyaSmartGroup.getDevList(withProductId: "your_group_product_id", gwId: "gwId", homeId: hoemId, success: { (list) in
print("get group dev list success \(list)")
}) { (error) in
print("get group dev list failure")
}
}
Creating a Group
+ (void)createGroupWithName:(NSString *)name
homeId:(long long)homeId
gwId:(NSString *)gwId
productId:(NSString *)productId
success:(nullable void (^)(TuyaSmartGroup *))success
failure:(nullable TYFailureError)failure;
Parameters
Parameter | Description |
---|---|
name | group name |
homeId | group home id |
gwId | group gateway id |
productId | group product id |
success | success callback |
failure | failure callback |
Example
Objc:
- (void)createNewGroup {
[TuyaSmartGroup createGroupWithName:@"your_group_name" homeId:homeID gwId:@"gwId" productId:@"your_group_product_id" success:^(TuyaSmartGroup *group) {
NSLog(@"create new group success %@:", group);
} failure:^(NSError *error) {
NSLog(@"create new group failure");
}];
}
Swift:
func createNewGroup() {
TuyaSmartGroup.createGroup(withName: "your_group_name", homeId: homeId, gwId: "gwId" productId: "your_group_product_id", success: { (group) in
print("create new group success: \(group)")
}) { (error) in
print("create new group failure")
}
}
Add Devices to the ZigBee Group
- (void)addZigbeeDeviceWithNodeList:(NSArray <NSString *>*)nodeList
success:(nullable TYSuccessHandler)success
failure:(nullable TYFailureError)failure;
Parameters
Parameter | Description |
---|---|
nodeList | device's nodeId |
success | success callback |
failure | failure callback |
Example
Objc:
- (void)addDevice {
// self.smartGroup = [TuyaSmartGroup groupWithGroupId:@"your_group_id"];
[self.smartGroup addZigbeeDeviceWithNodeList:@[@"nodeId1", @"nodeId2"] success:^() {
NSLog(@"get group dev list success %@:", list);
} failure:^(NSError *error) {
NSLog(@"get group dev list failure");
}];
}
Swift:
func addDevice() {
martGroup.addZigbeeDevice(withNodeList: ["nodeId1", "nodeId2"], success: {
print("add device success")
}) { (error) in
print("add device failure")
}
}
Remove Devices from ZigBee Groups
- (void)removeZigbeeDeviceWithNodeList:(NSArray <NSString *>*)nodeList
success:(nullable TYSuccessHandler)success
failure:(nullable TYFailureError)failure;
Parameter
Parameter | Description |
---|---|
nodeList | device's nodeId |
success | success call back |
failure | failure call back |
Example
Objc:
- (void)removeDevice {
[self.smartGroup removeZigbeeDeviceWithNodeList:@[@"nodeId1", @"nodeId2"] success:^() {
NSLog(@"get group dev list success %@:", list);
} failure:^(NSError *error) {
NSLog(@"get group dev list failure");
}];
}
Swift:
func removeDevice() {
martGroup.addZigbeeDevice(withNodeList: ["nodeId1", "nodeId2"], success: {
print("remove device success")
}) { (error) in
print("remove device failure")
}
}
Callback Interface
Response of ZigBee devices to join or remove gateway groups
errorCode :
- 1:Over the Scene Number Upper Limit
- 2: Subdevice timeout
- 3: Setting values beyond range
- 4: Writing errors
- 5: Other mistakes
Objc:
#pragma mark - TuyaSmartGroupDelegate
- (void)group:(TuyaSmartGroup *)group addResponseCode:(NSArray <NSNumber *>*)responseCode {
// Responses of ZigBee devices joining groups
}
- (void)group:(TuyaSmartGroup *)group removeResponseCode:(NSArray <NSNumber *>*)responseCode {
// sub devices joined the gateway group successfully
}
Swift:
// MARK: TuyaSmartGroupDelegate
func group(_ group: TuyaSmartGroup?, addResponseCode responseCode: [NSNumber]?) {
// Responses of ZigBee devices joining groups
}
func group(_ group: TuyaSmartGroup?, removeResponseCode responseCode: [NSNumber]?) {
// sub devices joined the gateway group successfully
}
1.3. Group Operation
1.3.1. Instantiation
Objc:
TuyaSmartGroup *smartGroup = [TuyaSmartGroup groupWithGroupId:groupId];
Swift:
let smartGroup = TuyaSmartGroup(groupId: groupId);
Parameters
Parameters | Description |
---|---|
groupId | group id |
1.3.2. Modifying group name
- (void)updateGroupName:(NSString *)name
success:(nullable TYSuccessHandler)success
failure:(nullable TYFailureError)failure;
Parameters
Parameter | Description |
---|---|
name | group name |
success | success callback |
failure | failure callback |
Example
Objc:
- (void)updateGroupName {
// self.smartGroup = [TuyaSmartGroup groupWithGroupId:@"your_group_id"];
[self.smartGroup updateGroupName:@"your_group_name" success:^{
NSLog(@"update group name success");
} failure:^(NSError *error) {
NSLog(@"update group name failure: %@", error);
}];
}
Swift:
func updateGroupName() {
smartGroup?.updateName("your_group_name", success: {
print("updateGroupName success")
}, failure: { (error) in
if let e = error {
print("updateGroupName failure: \(e)")
}
})
}
1.3.3. Dismiss Group
- (void)dismissGroup:(nullable TYSuccessHandler)success failure:(nullable TYFailureError)failure;
Parameters
Parameters | Description |
---|---|
success | success callbck |
failure | failure callback |
Example
Objc:
- (void)dismissGroup {
// self.smartGroup = [TuyaSmartGroup groupWithGroupId:@"your_group_id"];
[self.smartGroup dismissGroup:^{
NSLog(@"dismiss group success");
} failure:^(NSError *error) {
NSLog(@"dismiss group failure: %@", error);
}];
}
Swift:
func dismissGroup() {
smartGroup?.dismiss({
print("dismiss group success")
}, failure: { (error) in
if let e = error {
print("dismiss group failure: \(e)")
}
})
}
1.3.4. Sending group control command
- (void)publishDps:(NSDictionary *)dps
success:(nullable TYSuccessHandler)success failure:(nullable TYFailureError)failure;
Parameters
Parameter | Description |
---|---|
dps | dp command |
success | success callbck |
failure | failure callback |
Example
Objc:
- (void)publishDps {
// self.smartGroup = [TuyaSmartGroup groupWithGroupId:@"your_group_id"];
NSDictionary *dps = @{@"1": @(YES)};
[self.smartGroup publishDps:dps success:^{
NSLog(@"publishDps success");
} failure:^(NSError *error) {
NSLog(@"publishDps failure: %@", error);
}];
}
Swift:
func publishDps() {
let dps = ["1" : true]
smartGroup?.publishDps(dps, success: {
print("publishDps success")
}, failure: { (error) in
print("publishDps failure")
})
}
1.3.5. Group callback event
Control callback is triggered by TuyaSmartHomeDelegate
- (void)home:(TuyaSmartHome *)home group:(TuyaSmartGroupModel *)group dpsUpdate:(NSDictionary *)dps;
Example
Objc:
#pragma mark - TuyaSmartHomeDelegate
- (void)home:(TuyaSmartHome *)home group:(TuyaSmartGroupModel *)group dpsUpdate:(NSDictionary *)dps {
}
Swift:
extension YourViewController: TuyaSmartHomeDelegate {
func home(_ home: TuyaSmartHome!, group: TuyaSmartGroupModel!, dpsUpdate dps: [AnyHashable : Any]!) {
}
}
1.3.6. Group data acquisition
Objc:
//Get customized group data
TuyaSmartGroupModel *smartGroupModel = [TuyaSmartGroup groupWithGroupId:groupId].groupModel;
//Get device list under group
NSArray<TuyaSmartDeviceModel *> *deviceList = [TuyaSmartGroup groupWithGroupId:groupId].groupModel.deviceList;
Swift:
//Get customized group data
let smartGroupModel = TuyaSmartGroup(groupId: "groupId")?.groupModel
//Get device list under group
let deviceList = TuyaSmartGroup(groupId: "groupId")?.groupModel.deviceList