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.

Access the feature

IThingDeviceMultiControl iThingDeviceMultiControl = ThingHomeSdk.getDeviceMultiControlInstance();

Flowchart

Query a list of DPs for a device

API description

void getDeviceDpInfoList(String devId, IThingDataCallback<ArrayList<DeviceDpInfoBean>> callback);

Parameters

Parameter	Description
devId	The device ID.
callback	The callback.

Example

IThingDeviceMultiControl iThingDeviceMultiControl =ThingHomeSdk.getDeviceMultiControlInstance();
iThingDeviceMultiControl.getDeviceDpInfoList(mDevId, new IThingDataCallback<ArrayList<DeviceDpInfoBean>>() {
    @Override
    public void onSuccess(ArrayList<DeviceDpInfoBean> result) {

    }

    @Override
    public void onError(String errorCode, String errorMessage) {
        ToastUtil.shortToast(mContext,errorMessage);
    }
});

Query linkage details of a DP

API description

void queryLinkInfoByDp(String devId, String dpId, IThingDataCallback<MultiControlLinkBean> callback);

Parameters

Parameter	Description
devId	The device ID.
dpId	The DP ID of the device.
callback	The callback.

Example

iThingDeviceMultiControl.queryLinkInfoByDp(mDevId, dpId, new IThingDataCallback<MultiControlLinkBean>() {
    @Override
    public void onSuccess(MultiControlLinkBean result) {

    }

    @Override
    public void onError(String errorCode, String errorMessage) {
        ToastUtil.shortToast(mContext,errorMessage);
    }
});

Fields of MultiControlLinkBean

Field	Type	Description
multiGroup	MultiControlLinkBean.MultiGroupBean	The data structure of the associated multi-control group.
parentRules	List<MultiControlLinkBean.ParentRulesBean>	The data structure of the associated automation scene.

Fields of MultiControlLinkBean.MultiGroupBean

Field	Type	Description
uid	String	The user ID.
groupName	String	The name of the multi-control group.
groupType	int	The type of multi-control group.
multiRuleId	String	The rule ID.
id	int	The multi-control group ID.
ownerId	String	The home ID.
enabled	Boolean	Specifies whether to enable this multi-control group.
status	int	The status of the multi-control group.
groupDetail	List	The details of the multi-control group.

Fields of GroupDetailBean

Field	Type	Description
devId	String	The auxiliary device ID.
dpName	String	The linked DP name of the auxiliary device.
multiControlId	int	The multi-control group ID.
dpId	int	The linked DP ID of the auxiliary device.
devName	String	The name of the auxiliary device.
enabled	Boolean	Indicates whether the associated auxiliary device can be controlled with a multi-control linkage.
status	int	The status of the multi-control group.
datapoints	List	The DP data.

Fields of MultiControlDataPointsBean

Field	Type	Description
code	String	The DP identifier denoted by dpCode of the device.
dpId	int	The DP ID.
name	String	The name of the DP.

Fields of ParentRulesBean

Field	Type	Description
id	String	The automation scene ID.
name	String	The name of the automation scene.

Query multi-control devices

API description

void getMultiControlDeviceList(long mHomeId, IThingDataCallback<ArrayList<MultiControlDevInfoBean>> callback);

Parameters

Parameter	Description
mHomeId	The home ID.
callback	The callback.

Example

iThingDeviceMultiControl.getMultiControlDeviceList(Constant.HOME_ID, new IThingDataCallback<ArrayList<MultiControlDevInfoBean>>() {
    @Override
    public void onSuccess(ArrayList<MultiControlDevInfoBean> result) {
        iMultiControlDeviceView.setData(result);
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
        ToastUtil.shortToast(mContext,errorMessage);
    }
});

Fields of MultiControlDevInfoBean

Field	Type	Description
productId	String	The product ID.
devId	String	The device ID.
iconUrl	String	The URL of a device icon.
name	String	The name of the device.
roomName	String	The name of a room.
inRule	Boolean	Indicates whether the device is linked with the main device.
datapoints	List	The DP data.

Add, update, or delete a multi-control group

API description

• In the API method to add a multi-control group, the multi-control group ID is not required. In this process, the data points (DPs) of auxiliary devices are linked with those of the main device. Therefore, GroupDetail must include information about the main device.
• To update a multi-control group, you can either update it in the JSON format, or use MultiControlBean. You implement the following features with MultiControlBean:
  • Add devices to a multi-control group that includes the target main device
  • Rename the multi-control group
  • Update devices in the multi-control group
  • Remove devices from the multi-control group
• To delete a multi-control group, set GroupDetail to an empty value.

void saveDeviceMultiControl(long mHomeId, MultiControlBean multiControlBean, IThingResultCallback<MultiControlBean> callback);

void saveDeviceMultiControl(long mHomeId, String json, IThingResultCallback<MultiControlBean> callback);

Parameters

Parameter	Description
mHomeId	The home ID.
MultiControlBean	The data structure of the multi-control group.
json	The data structure of the multi-control group.
callback	The callback.

The following code block shows the full data structure in the JSON format:

{
    "groupName":"Multi-control group 1",
    "groupType":1,
    "groupDetail":[{"devId":"adadwfw3e234ferf41","dpId":2, "id":22, "enable":true}],
    "id":22         // The multi-control group ID.
}

Example

iThingDeviceMultiControl.saveDeviceMultiControl(Constant.HOME_ID, multiControlBean, new IThingResultCallback<MultiControlBean>() {
    @Override
    public void onSuccess(MultiControlBean result) {
        ToastUtil.shortToast(mContext,"success");
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
        ToastUtil.shortToast(mContext,errorMessage);
    }
});

Fields of MultiControlBean

Field	Type	Optional	Description
groupName	String	Yes	The name of the multi-control group.
groupType	int	No	The type of multi-control group. The value is 1.
groupDetail	List	Yes	The device details of the multi-control group.
id	int	Yes	The multi-control group ID.

Enable or disable a multi-control group

API description

void enableMultiControl(long multiControlId, IThingResultCallback<Boolean> callback);

void disableMultiControl(long multiControlId, IThingResultCallback<Boolean> callback);

Parameters

Parameter	Description
multiControlId	The multi-control group ID.
callback	The callback.

Example

iThingDeviceMultiControl.enableMultiControl(id, new IThingResultCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean result) {
        ToastUtil.shortToast(mContext,"success");
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
        ToastUtil.shortToast(mContext,errorMessage);
    }
});

iThingDeviceMultiControl.disableMultiControl( id, new IThingResultCallback<Boolean>() {
    @Override
    public void onSuccess(Boolean result) {
        ToastUtil.shortToast(mContext,"success");
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
        ToastUtil.shortToast(mContext,errorMessage);
    }
});

Query details of multi-control linkage for an auxiliary device

API description

void getDeviceDpLinkRelation(String devId, IThingDataCallback<DeviceMultiControlRelationBean> callback);

Parameters

Parameter	Description
devId	The device ID.
callback	The callback.

Example

iThingDeviceMultiControl.getDeviceDpLinkRelation(devId, new IThingDataCallback<DeviceMultiControlRelationBean>() {
    @Override
    public void onSuccess(DeviceMultiControlRelationBean result) {
        L.d("MultiControlDeviceListPresenter",result.toString());
    }

    @Override
    public void onError(String errorCode, String errorMessage) {
        ToastUtil.shortToast(mContext,errorMessage);
    }
});

Fields of DeviceMultiControlRelationBean

Field	Type	Description
datapoints	List	The DP data.
mcGroups	List	The details of the associated multi-control group.
parentRules	List	The details of the associated automation scene.