English
English
简体中文
Contact Us
Register
Log In

IoT App SDK

Group Management

Last Updated on : 2022-08-19 07:44:51download

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

TuyaHomeSdk.newHomeInstance(homeId).queryDeviceListToAddGroup(groupId, productId,
        new ITuyaResultCallback<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

TuyaHomeSdk.newHomeInstance(mHomeId).createGroup(productId, name, selectedDeviceIds,
        new ITuyaResultCallback<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

TuyaHomeSdk.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

Group Management

A Zigbee group supports Zigbee sub-devices, Sub-G sub-devices, Smart Gateway Pro sub-devices, and more.

Query devices available to create or join a group

API description

TuyaHomeSdk.newHomeInstance(homeId).queryZigbeeDeviceListToAddGroup(groupId, productId, meshId,
          new ITuyaResultCallback<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

TuyaHomeSdk.newHomeInstance(homeId).createZigbeeGroup(productId, meshId, name,
        new ITuyaResultCallback<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

mITuyaZigbeeGroup.addDeviceToGroup(meshId, selectedDeviceIds, gid,
        new ITuyaResultCallback<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());
                    }
                }
            }

            @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

mITuyaZigbeeGroup.delDeviceToGroup(meshId, selectedDeviceIds, gid,
        new ITuyaResultCallback<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());
                    }
                }
            }

            @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

TuyaHomeSdk.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 a group

Initialize a group instance

API description

ITuyaGroup mITuyaGroup= TuyaHomeSdk.newGroupInstance(groupId);

Parameters

Parameter Description
groupId The group ID.

Rename a group

API description

TuyaHomeSdk.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

TuyaHomeSdk.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

mTuyaGroup.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());
mTuyaGroup.publishDps(JSONObject.toJSONString(hashMap),callback);

Execute callback

// The callback that is executed when a group is registered.
mITuyaGroup.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 that is executed when a group is unregistered.
mITuyaGroup.unRegisterGroupListener();

The result that is returned after a control command is sent to a group indicates that the command has been sent to the cloud. However, it does not mean that device control is implemented as expected.

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.
TuyaHomeSdk.getDataInstance().getGroupBean(long groupId);

// Returns a list of devices in the group.
TuyaHomeSdk.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.
mITuyaGroup.onDestroy();