Group Management

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 or control multiple devices in the same group.

Create a Wi-Fi group

Query devices available to create a group

API description

ThingHomeSdk.newHomeInstance(homeId).queryDeviceListToAddGroup(groupId, productId,
        new IThingResultCallback<List<GroupDeviceBean>>() {
               @Override
               public void onSuccess(List<GroupDeviceBean> arrayList) {
               }

               @Override
               public void onError(String errorCode, String errorMsg) {
               }
        });

Parameters

Parameter	Description
homeId	The home ID.
groupId	The group ID. If the devices are not added to any group, set the value to -1. If these devices will be added to an existing group, set the value to the actual group ID.
productId	The product ID (PID) of the devices through which a group can be accessed.

Create a group

API description

ThingHomeSdk.newHomeInstance(mHomeId).createGroup(productId, name, selectedDeviceIds,
        new IThingResultCallback<Long>() {
            @Override
            public void onSuccess(Long groupId) {
                    // Returns the value of groupId.
            }

            @Override
            public void onError(String errorCode, String errorMsg) {
            }
        });

Parameters

Parameter	Description
homeId	The home ID.
productId	The PID of the devices used to create a group.
name	The name of the group.
selectedDeviceIds	The list of the target device IDs specified by deviceId.

Update and save a group

Updates and saves the changes in a group to the cloud after devices are added to or removed from the group.

API description

ThingHomeSdk.newGroupInstance(groupId).updateDeviceList(deviceIds,
        new IResultCallback() {

            @Override
            public void onError(String s, String s1) {

            }

            @Override
            public void onSuccess() {

            }
        });

Parameters

Parameter	Description
groupId	The group ID.
deviceIds	The list of target device IDs.

Create a Zigbee group

A Zigbee group supports Zigbee sub-devices, Sub-G sub-devices, Smart Gateway Pro sub-devices, and other devices that can communicate over Zigbee.

Query devices available to create or join a group

API description

ThingHomeSdk.newHomeInstance(homeId).queryZigbeeDeviceListToAddGroup(groupId, productId, meshId,
          new IThingResultCallback<List<GroupDeviceBean>>() {
                @Override
                public void onSuccess(List<GroupDeviceBean> arrayList) {
                }

                @Override
                public void onError(String errorCode, String errorMsg) {
                }
          });

Parameters

Parameter	Description
homeId	The home ID.
groupId	The group ID. If the devices are not added to any group, set the value to -1. If these devices will be added to an existing group, set the value to the actual group ID.
productId	The product ID (PID) of the devices through which a group can be accessed.
meshId	The gateway ID of the group devices. You can call deviceBean.getMeshId() to get the value.

Create a group

API description

ThingHomeSdk.newHomeInstance(homeId).createZigbeeGroup(productId, meshId, name,
        new IThingResultCallback<CloudZigbeeGroupCreateBean>() {

            @Override
            public void onSuccess(CloudZigbeeGroupCreateBean cloudZigbeeGroupCreateBean) {
                // Returns the result.
                long mGroupId = cloudZigbeeGroupCreateBean.getGroupId();
                String mGId = cloudZigbeeGroupCreateBean.getLocalId();
            }

            @Override
            public void onError(String errorCode, String errorMsg) {

            }
        });

Parameters

Parameter	Description
homeId	The home ID.
productId	The PID of the devices used to create a group.
meshId	The gateway ID of the group devices. You can call deviceBean.getMeshId() to get the value.
name	The name of the group.

Add devices to a group

In this interaction, the node IDs of the new devices are written to the gateway firmware of the group.

API description

mIThingZigbeeGroup.addDeviceToGroup(meshId, selectedDeviceIds, gid,
        new IThingResultCallback<ZigbeeGroupCreateResultBean>() {

            @Override
            public void onSuccess(ZigbeeGroupCreateResultBean zigbeeGroupCreateResultBean) {
                if (zigbeeGroupCreateResultBean != null) {
                    // The success callback.
                    if (zigbeeGroupCreateResultBean.getSuccess() != null && zigbeeGroupCreateResultBean.getSuccess().size() > 0) {
                        List<String> mAddSuccessDeviceIds = new ArrayList<>();
                        mAddSuccessDeviceIds.addAll(zigbeeGroupCreateResultBean.getSuccess());
                    }
                    // The failure callback.
                    if (zigbeeGroupCreateResultBean.getFailure() != null && zigbeeGroupCreateResultBean.getFailure().size() > 0) {
                        List<String>mAddFailDeviceIds = new ArrayList<>();
                        mAddFailDeviceIds.addAll(zigbeeGroupCreateResultBean.getFailure());
                    }
                    // Call the API method at the right time to update and save the group relationship.
                    //ThingHomeSdk.newZigbeeGroupInstance(groupId).updateGroupDeviceList()
                }
            }

            @Override
            public void onError(String errorCode, String errorMsg) {

            }
        });

Parameters

Parameter	Description
meshId	The gateway ID of the group devices. You can call deviceBean.getMeshId() to get the value.
selectedDeviceIds	The list of the target device IDs specified by deviceId.
gid	The value of localId for the group. If the target devices do not belong to any group, this parameter is returned. If the target devices belong to an existing group, you can call groupBean.getLocalId() to get the value.

Remove devices from a group

Removes one or more devices from a group through a gateway.

API description

mIThingZigbeeGroup.delDeviceToGroup(meshId, selectedDeviceIds, gid,
        new IThingResultCallback<ZigbeeGroupCreateResultBean>() {

            @Override
            public void onSuccess(ZigbeeGroupCreateResultBean zigbeeGroupCreateResultBean) {
                if (zigbeeGroupCreateResultBean != null) {
                    // The success callback.
                    if (zigbeeGroupCreateResultBean.getSuccess() != null && zigbeeGroupCreateResultBean.getSuccess().size() > 0) {
                        List<String> mDelSuccessDeviceIds = new ArrayList<>();
                        mDelSuccessDeviceIds.addAll(zigbeeGroupCreateResultBean.getSuccess());
                    }
                    // The failure callback.
                    if (zigbeeGroupCreateResultBean.getFailure() != null && zigbeeGroupCreateResultBean.getFailure().size() > 0) {
                        List<String> mDelFailDeviceIds = new ArrayList<>();
                        mDelFailDeviceIds.addAll(zigbeeGroupCreateResultBean.getFailure());
                    }
                    // Call the API method at the right time to update and save the group relationship.
                    //ThingHomeSdk.newZigbeeGroupInstance(groupId).updateGroupDeviceList()
                }
            }

            @Override
            public void onError(String errorCode, String errorMsg) {

            }
        });

Parameters

Parameter	Description
meshId	The gateway ID of the group devices. You can call deviceBean.getMeshId() to get the value.
selectedDeviceIds	The list of the target device IDs specified by deviceId.
gid	The value of localId for the group. If the target devices do not belong to any group, this parameter is returned. If the target devices belong to an existing group, you can call groupBean.getLocalId() to get the value.

Update and save a group

Updates and saves the changes in a group to the cloud by using the interaction with the gateway firmware after devices are added to or removed from the group.

API description

ThingHomeSdk.newZigbeeGroupInstance(groupId).updateGroupDeviceList(homeId, selectedDeviceIds,
        new IResultCallback() {

            @Override
            public void onError(String s, String s1) {

            }

            @Override
            public void onSuccess() {

            }
        });

Parameters

Parameter	Description
groupId	The group ID.
homeId	The home ID.
selectedDeviceIds	The success callback. A list of existing device IDs is returned.

Control groups

Initialize a group instance

API description

IThingGroup mIThingGroup= ThingHomeSdk.newGroupInstance(groupId);

Parameters

Parameter	Description
groupId	The group ID.

Rename a group

API description

ThingHomeSdk.newGroupInstance(groupId).renameGroup(titleName,
            new IResultCallback() {

            @Override
            public void onError(String s, String s1) {

            }

            @Override
            public void onSuccess() {

            }
        });

Parameters

Parameter	Description
groupId	The group ID.
titleName	The name of the group.

Dismiss a group

API description

ThingHomeSdk.newGroupInstance(groupId).dismissGroup(new IResultCallback() {

            @Override
            public void onError(String s, String s1) {

            }

            @Override
            public void onSuccess() {

            }
        });

Parameters

Parameter	Description
groupId	The target group ID.

Send group control commands

API description

mThingGroup.publishDps(String command, IResultCallback listener);

Parameters

Parameter	Description
command	The control commands.

Example

// Sample code for switching on a light in a group.
LampBean bean = new LampBean();
bean.setOpen(true);
HashMap<String, Object> hashMap = new HashMap<>();
hashMap.put(STHEME_LAMP_DPID_1, bean.isOpen());
mThingGroup.publishDps(JSONObject.toJSONString(hashMap),callback);

Execute callback

// The callback to invoke when a group is registered.
mIThingGroup.registerGroupListener(new IGroupListener() {

            @Override
            public void onDpUpdate(long l, String s) {

            }

            @Override
            public void onGroupInfoUpdate(long l) {

            }

            @Override
            public void onGroupRemoved(long l) {

            }
        });

// The callback to invoke when a group is unregistered.
mIThingGroup.unRegisterGroupListener();

Query group details

Before this call, you must call getHomeDetail() or getHomeLocalCache() to initialize a home. Then, group details can be queried.

// Returns the details of a specified group.
ThingHomeSdk.getDataInstance().getGroupBean(long groupId);

// Returns a list of devices in the group.
ThingHomeSdk.getDataInstance().getGroupDeviceList(long groupId);

Destroy data and exit group control

// Destroys group data. We recommend that you call this API method to exit group control.
mIThingGroup.onDestroy();