English
English
简体中文
Contact Us
Register
Log In

Multi-Control Linkage

Last Updated on : 2021-12-27 10:52:57download

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.

Multi-Control Linkage

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

Multi-Control Linkage

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.

The details of the multi-control group are fully updated in this call.

- (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

}