Multi-Control Linkage

Last Updated on : 2023-04-13 09:31:10download

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
ThingSmartMultiControl 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<ThingSmartMultiControlDatapointModel *> *))success failure:(ThingFailureError)failure;

Parameters

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

Data types of ThingSmartMultiControlDatapointModel

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:

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

} failure:^(NSError *error) {

}];

Swift:

let multiControl = ThingSmartMultiControl.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 (^)(ThingSmartMultiControlLinkModel *))success failure:(ThingFailureError)failure;

Parameters

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

Data types of ThingSmartMultiControlLinkModel

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

Data types of ThingSmartMultiControlGroupModel

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<ThingSmartMultiControlGroupDetailModel *> 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 ThingSmartMultiControlGroupDetailModel

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<ThingSmartMultiControlDatapointModel *> The DP data.

Data types of ThingSmartMultiControlParentRuleModel

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

Example

ObjC:

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

} failure:^(NSError *error) {

}];

Swift:

let multiControl = ThingSmartMultiControl.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<ThingSmartMultiControlDetailModel *> *)groupDetail success:(void (^)(ThingSmartMultiControlModel *))success failure:(ThingFailureError)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<ThingSmartMultiControlDetailModel *>).
success The success callback.
failure The failure callback.

Data types of ThingSmartMultiControlDetailModel

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:

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

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

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

} failure:^(NSError *error) {

}];

Swift:

let multiControl = ThingSmartMultiControl.init()

let detail = ThingSmartMultiControlDetailModel.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:(ThingSmartMultiControlModel *)model success:(void (^)(ThingSmartMultiControlModel *))success failure:(ThingFailureError)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 ThingSmartMultiControlModel

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<ThingSmartMultiControlDetailModel *> The details of the multi-control group.

Example

ObjC:

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

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

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

model.groupDetail = @[detailModel];

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

} failure:^(NSError *error) {

}];

Swift:

let multiControl = ThingSmartMultiControl.init()

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

let model = ThingSmartMultiControlModel.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:(ThingSuccessBOOL)success failure:(ThingFailureError)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:

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

} failure:^(NSError *error) {

}];

Swift:

let multiControl = ThingSmartMultiControl.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<ThingSmartMultiControlDeviceModel *> *))success failure:(ThingFailureError)failure;

Parameters

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

Data types of ThingSmartMultiControlDeviceModel

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<ThingSmartMultiControlDatapointModel *> The DP data.
multiControlIds NSArray<NSString *> The list of multi-control group IDs associated with the device.

Example

ObjC:

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

} failure:^(NSError *error) {

}];

Swift:

let multiControl = ThingSmartMultiControl.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 (^)(ThingSmartMultiControlDpRelationModel *))success failure:(ThingFailureError)failure;

Parameters

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

Fields of ThingSmartMultiControlDpRelationModel

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

Data types of ThingSmartMcGroupModel

Field Type Description
multiControlId NSString The multi-control group ID.
groupName NSString The name of the multi-control group.
groupDetail NSArray<ThingSmartMcGroupDetailModel *> 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 ThingSmartMcGroupDetailModel

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:

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

} failure:^(NSError *error) {

}];

Swift:

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

}) { (error) in

}