English
English
简体中文
Contact Us
Register
Log In

Group Management

Last Updated on : 2022-08-22 06:09:17download

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.
  • 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