Group Management

Last Updated on : 2023-05-22 06:38:26

A device group includes devices of the same type and gathers a series of devices. Wi-Fi and Zigbee devices can be grouped in most cases. Tuya provides the capabilities to implement device group management. For example, create, rename, manage, or dismiss a group, and manage multiple devices in the same group.

Feature description

The TuyaSmartGroup class requires the group ID specified by groupId to implement initialization. An incorrect group ID might cause failed initialization. In this case, the instance returns nil.

Encapsulation class

Class name Description

TuyaSmartGroup The group class.

TuyaSmartGroupModel The group data model class.

Class name	Description
TuyaSmartGroup	The group class.
TuyaSmartGroupModel	The group data model class.

Data model of TuyaSmartGroupModel

Field	Type	Description
groupId	NSString	The unique group ID.
productId	NSString	The product ID (PID) of a group.
time	long long	The time when the group was created.
name	NSString	The name of the group.
iconUrl	NSString	The URL of the group icon.
type	TuyaSmartGroupType	The type of group.
isShare	BOOL	Indicates whether the group is a shared group.
dps	NSDictionary	The data points (DPs) of devices in the group.
dpCodes	NSDictionary	The DPs of the group devices, stored in the key-value pair format.
localKey	NSString	The key that the group uses for communication.
deviceNum	NSInteger	The number of devices managed in the group.
productInfo	NSDictionary	The PID information of the group.
pv	NSString	The protocol version of the group. A Wi-Fi protocol version is supported.
homeId	long long	The ID of the home to which the group belongs.
roomId	long long	The ID of the room to which the group belongs.
displayOrder	NSInteger	The sequence in which the group is sorted by room.
homeDisplayOrder	NSInteger	The sequence in which the group is sorted by home.
deviceList	NSArray	The list of group devices.
localId	NSString	The group ID used on a local area network (LAN).
meshId	NSString	The mesh ID of the group.
schemaArray	NSArray	The schema array of group DP rules.
standard	BOOL	Indicates whether a standard group is used.

Create a Wi-Fi group

Query devices available to create a group

Returns a list of devices that can be used to create a group together with a device specified by product ID (PID) of the device.

+ (void)getDevList:(NSString *)productId
            homeId:(long long)homeId
           success:(nullable void(^)(NSArray <TuyaSmartGroupDevListModel *> *list))success
           failure:(nullable TYFailureError)failure;

Parameters

Parameter	Description
productId	The PID of the device from which the target group can be accessed.
homeId	The ID of the home to which the group belongs.
success	The success callback.
failure	The failure callback.

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:homeId, success: { (list) in
        print("get group dev list success \(list)")
    }) { (error) in
        print("get group dev list failure")
    }
}

Query devices available to join a group

Returns a list of devices that can be added or that have been added to a group specified by PID of the group.

- (void)getDevList:(NSString *)productId
            homeId:(long long)homeId
           success:(nullable void(^)(NSArray <TuyaSmartGroupDevListModel *> *list))success
           failure:(nullable TYFailureError)failure;

Parameters

Parameter	Description
productId	The PID of the group.
homeId	The ID of the home to which the group belongs.
success	The success callback.
failure	The failure callback.

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

Create 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	The name of the group.
productId	The PID of the devices used to create a group.
homeId	The home ID.
devIdList	The list of device IDs used to create a group.
success	The success callback.
failure	The 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 a group

- (void)updateGroupRelations:(NSArray <NSString *>*)devList
                     success:(nullable TYSuccessHandler)success
                     failure:(nullable TYFailureError)failure;

Parameters

Parameter	Description
devList	The list of device IDs in the group.
success	The success callback.
failure	The 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)")
        }
    })
}

Execute callback

Returns the data update result after group DPs are sent.

ObjC:

#pragma mark - TuyaSmartGroupDelegate

- (void)group:(TuyaSmartGroup *)group dpsUpdate:(NSDictionary *)dps {
	// Refreshes the panel UI after a group operation.
}

Swift:

// MARK: TuyaSmartGroupDelegate
func group(_ group: TuyaSmartGroup!, dpsUpdate dps: [AnyHashable : Any]!) {
// Refreshes the panel UI after a group operation.
}

Create a Zigbee group

Group Management

A Zigbee group supports Zigbee sub-devices, Smart Gateway Pro sub-devices, Sub-G sub-devices, and other devices that can communicate over Zigbee.

Query devices available to create or join a group

+ (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	The PID of the group.
gwId	The gateway ID of the group.
homeId	The home ID.
success	The success callback.
failure	The failure callback.

Example

ObjC:

- (void)getGroupDevList {

    // For example, query the available sub-devices that can be used to create a group with the current Zigbee sub-device.
    TuyaSmartDevice *oneSubDevice = [TuyaSmartDevice deviceWithDeviceId:@"sub device id"];
    NSString *productId = oneSubDevice.deviceModel.productId;
    NSString *gwId = oneSubDevice.deviceModel.parentId;
  
    [TuyaSmartGroup getDevListWithProductId:productId 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() {
    // For example, query the available sub-devices that can be used to create a group with the current Zigbee sub-device.
    guard let oneSubDevice = TuyaSmartDevice(deviceId: "sub device id"),
          let productId = oneSubDevice.deviceModel.productId,
          let gwId = oneSubDevice.deviceModel.parentId
    else { return }
  
    TuyaSmartGroup.getDevList(withProductId: productId, gwId: gwId, homeId: hoemId, success: { (list) in
        print("get group dev list success \(list)")
    }) { (error) in
        print("get group dev list failure")
    }
}

Create 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	The name of the group.
homeId	The ID of the home to which the group belongs.
gwId	The gateway ID of the group.
productId	The PID of the device from which the target group can be accessed.
success	The success callback.
failure	The 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")
    }
}

Update and save a group

- (void)updateGroupRelations:(NSArray <NSString *>*)devList
                     success:(nullable TYSuccessHandler)success
                     failure:(nullable TYFailureError)failure;

Parameters

Parameter	Description
devList	The list of device IDs in the group.
success	The success callback.
failure	The failure callback.

Example

ObjC:

- (void)updateGroupRelations {
// Example:
    // The current group includes the devices: ["deviceId 1", "deviceId 2"]. They can be returned by `TuyaSmartGroup::groupModel.deviceList`.
    // The user opens the app, adds "deviceId 3", and then removes "deviceId 1".
    // Then, pass in ["deviceId 2", "deviceId 3"] to update the group information.
  
    // self.smartGroup = [TuyaSmartGroup groupWithGroupId:@"your_group_id"];
    [self.smartGroup updateGroupRelations:@[@"deviceId 2", @"deviceId3", ....] success:^ {
        NSLog(@"update group relations success");
    } failure:^(NSError *error) {
        NSLog(@"update group relations failure: %@", error);
    }];
}

Swift:

func updateGroupRelations() {
    // Example:
    // The current group includes the devices: ["deviceId 1", "deviceId 2"]. They can be returned by `TuyaSmartGroup::groupModel.deviceList`.
    // The user opens the app, adds "deviceId 3", and then removes "deviceId 1".
    // Then, pass in ["deviceId 2", "deviceId 3"] to update the group information.

    smartGroup?.updateRelations(["deviceId 2", "deviceId3", ....], success: {
        print("update group relations success")
    }, failure: { (error) in
        if let e = error {
            print("update group relations failure: \(e)")
        }
    })
}

Add devices to a group

API description

Adds one or more devices to a group. In this interaction, the node IDs of the new devices are written to the gateway firmware of the group.

- (void)addZigbeeDeviceWithNodeList:(NSArray <NSString *>*)nodeList
                            success:(nullable TYSuccessHandler)success
                            failure:(nullable TYFailureError)failure;

Parameters

Parameter	Description
nodeList	The list of the target node IDs.
success	The success callback.
failure	The failure callback.

Example

ObjC:

- (void)addDevice {
    // The value of `nodeId` can be obtained from `TuyaSmartDeviceModel::nodeId`.
   // 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() {
    // The value of `nodeId` can be obtained from `TuyaSmartDeviceModel::nodeId`.
  	
    smartGroup?.addZigbeeDevice(withNodeList: ["nodeId1", "nodeId2"], success: {
        print("add device success")
    }) { (error) in
        print("add device failure")
    }
}

Remove devices from a group

API description

Removes one or more devices from a group through a gateway.

- (void)removeZigbeeDeviceWithNodeList:(NSArray <NSString *>*)nodeList
                               success:(nullable TYSuccessHandler)success
                               failure:(nullable TYFailureError)failure;

Parameters

Parameter	Description
nodeList	The list of the target node IDs.
success	The success callback.
failure	The failure callback.

Example

ObjC:

- (void)removeDevice {
    // Call `TuyaSmartGroup::groupModel.deviceList` to get a list of devices in the group.
    // The value of `nodeId` can be obtained from `TuyaSmartDeviceModel::nodeId`.
    [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() {
      	// Call `TuyaSmartGroup::groupModel.deviceList` to get a list of devices in the group.
  	// The value of `nodeId` can be obtained from `TuyaSmartDeviceModel::nodeId`.
  
    smartGroup?.addZigbeeDevice(withNodeList: ["nodeId1", "nodeId2"], success: {
        print("remove device success")
    }) { (error) in
        print("remove device failure")
    }
}

Execute callback

Returns the result after Zigbee devices are added to or removed from a group through a gateway. The following table lists the possible error codes.

errorCode	Description
1	The number of groups exceeded the upper limit.
2	A timeout error has occurred while processing sub-devices.
3	The specified values are out of range.
4	An error has occurred while writing to files.
5	Other errors have occurred while processing your request.

ObjC:

#pragma mark - TuyaSmartGroupDelegate

- (void)group:(TuyaSmartGroup *)group addResponseCode:(NSArray <NSNumber *>*)responseCode {
	// Returns the result after Zigbee devices are added to a group through a gateway.
}

- (void)group:(TuyaSmartGroup *)group removeResponseCode:(NSArray <NSNumber *>*)responseCode {
	// Returns the result after Zigbee devices are removed from a group through a gateway.
}

Swift:

// MARK: TuyaSmartGroupDelegate
func group(_ group: TuyaSmartGroup?, addResponseCode responseCode: [NSNumber]?) {
    // Returns the result after Zigbee devices are added to a group through a gateway.
}

func group(_ group: TuyaSmartGroup?, removeResponseCode responseCode: [NSNumber]?) {
    // Returns the result after Zigbee devices are removed from a group through a gateway.
}

Control groups

Initialize a group instance

ObjC:

TuyaSmartGroup *smartGroup = [TuyaSmartGroup groupWithGroupId:groupId];

Swift:

let smartGroup = TuyaSmartGroup(groupId: groupId);

Parameters

Parameter	Description
groupId	The group ID.

Rename a group

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

Parameters

Parameter	Description
name	The name of the group.
success	The success callback.
failure	The 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)")
        }
    })
}

Dismiss a group

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

Parameters

Parameter	Description
success	The success callback.
failure	The 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)")
        }
    })
}

Send group control commands

API description

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

Parameters

Parameter	Description
dps	The list of DPs to be sent for device control.
success	The success callback.
failure	The 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")
    })
}

Execute callback

Returns the result of device control. The 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]!) {

    }
}

Query group data

ObjC:

// Returns the details of a specified group.
TuyaSmartGroupModel *smartGroupModel = [TuyaSmartGroup groupWithGroupId:groupId].groupModel;

// Returns a list of devices in the group.
NSArray<TuyaSmartDeviceModel *> *deviceList = [TuyaSmartGroup groupWithGroupId:groupId].groupModel.deviceList;

Swift:

// Returns the details of a specified group.
let smartGroupModel = TuyaSmartGroup(groupId: "groupId")?.groupModel

// Returns a list of devices in the group.
let deviceList = TuyaSmartGroup(groupId: "groupId")?.groupModel.deviceList

Prev DocSmart Scenes

Next DocExtension SDK