Multi-Control Linkage

Multi-control linkage is a device control feature. In this feature, a device data point (DP) is linked with a DP of another device to create a multi-control group. When a device of the multi-control group is controlled, the linked status of other devices in the group is synchronously changed.

For example, 3 two-gang Zigbee sub-device switches, the first DP of each switch is linked with the first DP of the other two switches to create a multi-control group. When the first DP for one of these switches is set to off, the first DP of the other two switches is synchronously set to off.

Limits

• Only DPs in the following format are supported: switch_number and sub_switch_number.
• Switches of Zigbee sub-devices and Bluetooth mesh sub-devices are supported.
• Devices for multiple product IDs (PIDs) can be added to the same multi-control group.

Functional description

Class name	Description
TuyaSmartMultiControl	Encapsulates API methods to implement multi-control linkage.

Flowchart

Get a list of DPs for a device

API description

Returns multilingual names and other details of all DPs for a device from the cloud.

- (void)getDeviceDpInfoWithDevId:(NSString *)devId success:(void (^)(NSArray<TuyaSmartMultiControlDatapointModel *> *))success failure:(TYFailureError)failure;

Parameters

Parameter	Description
devId	The device ID.
success	The success callback. The response parameter NSArray<TuyaSmartMultiControlDatapointModel *> is returned.
failure	The failure callback.

Data types of TuyaSmartMultiControlDatapointModel

Field	Type	Description
dpId	NSString	The DP ID of the device.
name	NSString	The DP name of the device.
code	NSString	The DP identifier denoted by dpCode of the device.
schemaId	NSString	The schema ID for a button DP of a device.

Example

ObjC:

TuyaSmartMultiControl *multiControl = [[TuyaSmartMultiControl alloc] init];
[multiControl getDeviceDpInfoWithDevId:@"your_devId" success:^(NSArray<TuyaSmartMultiControlDatapointModel *> * list) {

} failure:^(NSError *error) {

}];

Swift:

let multiControl = TuyaSmartMultiControl.init()
multiControl.getDeviceDpInfo(withDevId: "your_devId", success: { (list) in

}) { (error) in

}

Query linkage details of a DP

API description

Returns multi-control and automation scene data linked with a specified DP of the current device. This device is regarded as the main device and the associated devices are regarded as auxiliary devices.

- (void)queryDeviceLinkInfoWithDevId:(NSString *)devId dpId:(NSString *)dpId success:(void (^)(TuyaSmartMultiControlLinkModel *))success failure:(TYFailureError)failure;

Parameters

Parameter	Description
devId	The main device ID.
dpId	The DP ID of the main device.
success	The success callback. The response parameter TuyaSmartMultiControlLinkModel * is returned.
failure	The failure callback.

Data types of TuyaSmartMultiControlLinkModel

Field	Type	Description
multiGroup	TuyaSmartMultiControlGroupModel	The data structure of the associated multi-control group.
parentRules	NSArray<TuyaSmartMultiControlParentRuleModel *>	The data structure of the associated automation scene.

Data types of TuyaSmartMultiControlGroupModel

Field	Type	Description
multiControlId	NSString	The multi-control group ID.
groupName	NSString	The name of the multi-control group.
groupType	NSInteger	The type of multi-control group.
groupDetail	NSArray<TuyaSmartMultiControlGroupDetailModel *>	The details of the multi-control group.
enabled	BOOL	Specifies whether to enable this multi-control group.
multiRuleId	NSString	The automation scene ID.
ownerId	NSString	The home ID.
uid	NSString	The user ID.

Data types of TuyaSmartMultiControlGroupDetailModel

Field	Type	Description
detailId	NSString	The details ID.
multiControlId	NSString	The multi-control group ID.
devId	NSString	The auxiliary device ID.
devName	NSString	The name of the auxiliary device.
dpId	NSString	The linked DP ID of the auxiliary device.
dpName	NSString	The linked DP name of the auxiliary device.
enabled	BOOL	Indicates whether the associated auxiliary device can be controlled with a multi-control linkage.
datapoints	NSArray<TuyaSmartMultiControlDatapointModel *>	The DP data.

Data types of TuyaSmartMultiControlParentRuleModel

Field	Type	Description
ruleId	NSString	The automation scene ID.
name	NSString	The name of the automation scene.

Example

ObjC:

TuyaSmartMultiControl *multiControl = [[TuyaSmartMultiControl alloc] init];
[multiControl queryDeviceLinkInfoWithDevId:@"your_devId" dpId:@"your_dpId" success:^(TuyaSmartMultiControlLinkModel * model) {

} failure:^(NSError *error) {

}];

Swift:

let multiControl = TuyaSmartMultiControl.init()
multiControl.queryDeviceLinkInfo(withDevId: "your_devId", dpId: "your_dpId", success: { (linkModel) in

}) { (error) in

}

Add a multi-control group

API description

- (void)addMultiControlWithDevId:(NSString *)devId groupName:(NSString *)groupName groupDetail:(NSArray<TuyaSmartMultiControlDetailModel *> *)groupDetail success:(void (^)(TuyaSmartMultiControlModel *))success failure:(TYFailureError)failure;

Parameters

Parameter	Description
devId	The main device ID.
groupName	The name of the multi-control group.
groupDetail	The details of the multi-control group, specified by the request parameter NSArray<TuyaSmartMultiControlDetailModel *>).
success	The success callback.
failure	The failure callback.

Data types of TuyaSmartMultiControlDetailModel

Field	Type	Description
detailId	NSString
devId	NSString	The auxiliary device ID.
dpId	NSString	The linked DP ID of the auxiliary device.
enable	BOOL	Indicates whether the associated auxiliary device can be controlled with a multi-control linkage.

Example

ObjC:

TuyaSmartMultiControl *multiControl = [[TuyaSmartMultiControl alloc] init];

TuyaSmartMultiControlDetailModel *detailModel = [[TuyaSmartMultiControlDetailModel alloc] init];
detailModel.dpId = @"";
detailModel.devId = @"";
detailModel.enable = true;

[multiControl addMultiControlWithDevId:@"your_devId" groupName:@"groupName" groupDetail:@[detailModel] success:^(TuyaSmartMultiControlModel * model) {

} failure:^(NSError *error) {

}];

Swift:

let multiControl = TuyaSmartMultiControl.init()

let detail = TuyaSmartMultiControlDetailModel.init()
detail.devId = ""
detail.dpId = ""
detail.enable = true

multiControl.add(withDevId: "your_devId", groupName: "groupName", groupDetail: [detail], success: { (model) in

}) { (error) in

}

Update name or device list of multi-control group

API description

Updates the name of a multi-control group and the list of devices in this group after devices are added to this group for the main device.

- (void)updateMultiControlWithDevId:(NSString *)devId multiControlModel:(TuyaSmartMultiControlModel *)model success:(void (^)(TuyaSmartMultiControlModel *))success failure:(TYFailureError)failure;

Parameters

Parameter	Description
devId	The main device ID.
model	The data structure of the multi-control group.
success	The success callback.
failure	The failure callback.

Data types of TuyaSmartMultiControlModel

Field	Type	Description
multiControlId	NSString	The multi-control group ID.
groupName	NSString	The name of the multi-control group.
groupType	NSInteger	The type of multi-control group. Default value: 1.
groupDetail	NSArray<TuyaSmartMultiControlDetailModel *>	The details of the multi-control group.

Example

ObjC:

TuyaSmartMultiControl *multiControl = [[TuyaSmartMultiControl alloc] init];

TuyaSmartMultiControlDetailModel *detailModel = [[TuyaSmartMultiControlDetailModel alloc] init];
detailModel.detailId = @"";
detailModel.dpId = @"";
detailModel.devId = @"";
detailModel.enable = true;

TuyaSmartMultiControlModel *model = [[TuyaSmartMultiControlModel alloc] init];
model.multiControlId = @"";
model.groupName = @"";
model.groupType = 1;

model.groupDetail = @[detailModel];

[multiControl updateMultiControlWithDevId:@"your_devId" multiControlModel:model success:^(TuyaSmartMultiControlModel * model) {

} failure:^(NSError *error) {

}];

Swift:

let multiControl = TuyaSmartMultiControl.init()

let detailModel = TuyaSmartMultiControlDetailModel.init()
detailModel.detailId = ""
detailModel.dpId = ""
detailModel.devId = ""
detailModel.enable = true

let model = TuyaSmartMultiControlModel.init()
model.multiControlId = ""
model.groupName = ""
model.groupDetail = [detailModel]
multiControl.update(withDevId: "your_devId", multiControlModel: model, success: { (model) in

}) { (error) in

}

Enable or disable a multi-control group

API description

- (void)enableMultiControlWithMultiControlId:(NSString *)multiControlId enable:(BOOL)enable success:(TYSuccessBOOL)success failure:(TYFailureError)failure;

Parameters

Parameter	Description
multiControlId	The multi-control group ID.
enable	Specifies whether to enable the multi-control group.
success	The success callback.
failure	The failure callback.

Example

ObjC:

TuyaSmartMultiControl *multiControl = [[TuyaSmartMultiControl alloc] init];
[multiControl enableMultiControlWithMultiControlId:@"multiControlId" enable:true/false success:^(BOOL result) {

} failure:^(NSError *error) {

}];

Swift:

let multiControl = TuyaSmartMultiControl.init()
multiControl.enableMultiControl(withMultiControlId: "multiControlId", enable: true, success: { (result) in

}) { (error) in

}

Query multi-control devices

API description

Query multi-control devices available for users or homes.

- (void)getMultiControlDeviceListWithHomeId:(long long)homeId success:(void (^)(NSArray<TuyaSmartMultiControlDeviceModel *> *))success failure:(TYFailureError)failure;

Parameters

Parameter	Description
homeId	The home ID.
success	The success callback. The response parameter NSArray<TuyaSmartMultiControlDeviceModel *> is returned.
failure	The failure callback.

Data types of TuyaSmartMultiControlDeviceModel

Field	Type	Description
devId	NSString	The device ID.
productId	NSString	The product ID.
name	NSString	The name of the device.
iconUrl	NSString	The URL of a device icon.
roomName	NSString	The name of the room.
inRule	BOOL	Indicates whether the device can serve as a condition for automation scenes.
datapoints	NSArray<TuyaSmartMultiControlDatapointModel *>	The DP data.
multiControlIds	NSArray<NSString *>	The list of multi-control group IDs associated with the device.

Example

ObjC:

TuyaSmartMultiControl *multiControl = [[TuyaSmartMultiControl alloc] init];
[multiControl getMultiControlDeviceListWithHomeId:123 success:^(NSArray<TuyaSmartMultiControlDeviceModel *> * list) {

} failure:^(NSError *error) {

}];

Swift:

let multiControl = TuyaSmartMultiControl.init()
multiControl.getDeviceList(withHomeId: 123, success: { (list) in

}) { (error) in

}

Query details of multi-control linkage for an auxiliary device

API description

Returns DP data, associated multi-control group, and automation scenes of an auxiliary device.

- (void)queryDeviceDpRelationWithDevId:(NSString *)devId success:(void (^)(TuyaSmartMultiControlDpRelationModel *))success failure:(TYFailureError)failure;

Parameters

Parameter	Description
devId	The device ID.
success	The success callback. The response parameter TuyaSmartMultiControlDpRelationModel * is returned.
failure	The failure callback.

Fields of TuyaSmartMultiControlDpRelationModel

Field	Type	Description
datapoints	NSArray<TuyaSmartMultiControlDatapointModel *>	The DP data.
mcGroups	NSArray<TuyaSmartMcGroupModel *>	The details of the associated multi-control group.
parentRules	NSArray<TuyaSmartMultiControlParentRuleModel *>	The details of the associated automation scene.

Data types of TuyaSmartMcGroupModel

Field	Type	Description
multiControlId	NSString	The multi-control group ID.
groupName	NSString	The name of the multi-control group.
groupDetail	NSArray<TuyaSmartMcGroupDetailModel *>	The details of the multi-control linkage group.
enabled	BOOL	Indicates whether the multi-control group is available.
groupType	NSInteger	The type of multi-control group.
multiRuleId	NSString
ownerId	NSString	The home ID.
uid	NSString	The user ID.

Data types of TuyaSmartMcGroupDetailModel

Field	Type	Description
detailId	NSString
dpId	NSString	The DP ID.
dpName	NSString	The name of the DP.
devId	NSString	The device ID.
devName	NSString	The name of the device.
enabled	BOOL	Indicates whether the device is available.
multiControlId	NSString	The multi-control group ID.

Example

ObjC:

TuyaSmartMultiControl *multiControl = [[TuyaSmartMultiControl alloc] init];
[multiControl queryDeviceDpRelationWithDevId:@"your_devId" success:^(TuyaSmartMultiControlDpRelationModel * model) {

} failure:^(NSError *error) {

}];

Swift:

let multiControl = TuyaSmartMultiControl.init()
multiControl.queryDeviceDpRelation(withDevId: "your_devId", success: { (model) in

}) { (error) in

}