Group Management

Group devices with the same features and control them all in one go. Both the group and scene can enable control of multiple devices at once, but they have different restrictions on actions. Scenes offer flexible and diverse actions on devices, whereas groups only support actions on features that are common to all devices in the group.

API list

The class ThingGroupBizManager is responsible for scheduling group management. The request parameter for each API is GroupOperateBuilder, but the payload varies by API. The following sections will describe the required parameters for each API.

API description

API	Description
fetchDeviceList	Get the list of devices that can be grouped.
createGroup	Create a group.
updateGroup	Update a group.
dismissGroup	Delete a group.

Parameter description

Description of GroupOperateBuilder

Property	Type	Description
groupId	long	The group ID.
groupName	String	The name of the group.
allSelectDeviceList	List< String >	The list of devices selected to group or the list of devices after a group is updated.
processCallback	String	The callback to invoke when a group is created or updated.
successCallback	SuccessCallback	The callback to invoke when a group is created or updated successfully.
failureCallback	FailureCallback	The callback to invoke when there is a failure in getting the list of devices, creating, updating, or deleting a group.
queryDeviceCallback	QueryDeviceCallback	The callback to invoke when the list of devices is returned successfully.

Initialization

Before using any of the above APIs, create a group management class ThingGroupBizManager and initialize the parameters for group management. The initial parameters vary by type of group, but they are all encapsulated into GroupInitBuilder. The ID of the current home is also required. The following sections will describe how different types of groups are initialized.

Initialization is required to enable the user to add, delete, modify, and query a group. You need to pass in deviceId or groupId for initialization.

• If a group already exists, pass in its groupId.
• If no group exists, pass in a deviceId to group devices of the same type as deviceId.

Parameter description

Property	Type	Description	Required
devId	String	The device ID.	No
groupId	long	The group ID.	No

Example

GroupInitBuilder initBuilder = new GroupInitBuilder.Builder()
        .setDevId(devId)
        .build();
IThingGroupManager thingGroupBizManager = ThingGroupBizKit.getGroupBizManager(homeId,initBuilder);

Get the list of devices to group

Before operating a group, get the list of devices that can be grouped together.

API description

fun fetchDeviceList(operateBuilder: GroupOperateBuilder)

Parameter description

Property	Type	Description	Required
failureCallback	FailureCallback	The callback to invoke when there is a failure in getting the list of devices, creating, updating, or deleting a group.	Yes
queryDeviceCallback	QueryDeviceCallback	The callback to invoke when the list of devices is returned successfully.	Yes

Example

GroupInitBuilder initBuilder = new GroupInitBuilder.Builder()
        .setDevId(devId)
        .build();

GroupOperateBuilder operateBuilder = new GroupOperateBuilder.Builder()
        .setQueryDeviceCallback(new QueryDeviceCallback() {
            @Override
            public void result(@NonNull List<? extends GroupInfo> list) {

            }
        })
        .setFailureCallback(new FailureCallback() {
            @Override
            public void onError(@Nullable String errorCode, @Nullable String errorMessage, long groupId, @Nullable List<GroupResult> failDevices) {

            }
        })
        .build();
thingGroupBizManager.fetchDeviceList(operateBuilder);

Description of return values

GroupInfo class

Property	Type	Description
devId	String	The device ID.
iconUrl	String	The icon of the device.
devName	String	The name of the device.
nodeId	String	The nodeId of the device.
checked	boolean	Indicates whether the device is selected. true: The device is already in the group. false: The device is not in the group.
isOnline	boolean	Indicates whether the device is online.
productId	String	The product ID (PID) of the device.
belongHomeName	String	The home to which the device belongs.
belongRoomName	String	The room to which the device belongs.

Create a group

From the device list returned by fetchDeviceList, select the devices to group and call this method to create a group.

API description

fun createGroup(operateBuilder: GroupOperateBuilder)

Parameter description

Property	Type	Description	Required
allSelectDeviceList	List< String >	The list of selected devices.	Yes
groupName	String	The name of the group.	Yes
queryDeviceCallback	QueryDeviceCallback	The callback to invoke when the list of devices is returned successfully.	Yes
failureCallback	FailureCallback	The callback to invoke when there is a failure in getting the list of devices, creating, updating, or deleting a group.	Yes
successCallback	SuccessCallback	The callback to invoke when a group is created or updated successfully.	Yes

Example

GroupInitBuilder initBuilder = new GroupInitBuilder.Builder()
        .setDevId(devId)
        .build();

GroupOperateBuilder operateBuilder = new GroupOperateBuilder.Builder()
        .setAllSelectDeviceList(allSelectDeviceList)
        .setSuccessCallback(new SuccessCallback() {
            @Override
            public void result(long groupId, @Nullable List<GroupResult> failDevices) {

            }
        })
        .setProcessCallback(new ProcessCallback() {
            @Override
            public void result(int process, int size) {

            }
        })
        .setFailureCallback(new FailureCallback() {
            @Override
            public void onError(@Nullable String errorCode, @Nullable String errorMessage, long groupId, @Nullable List<GroupResult> failDevices) {

            }
        })
        .build();
thingGroupBizManager.createGroup(operateBuilder);

Update the device in a group

From the device list returned by fetchDeviceList, select the devices to group and call this method to update the device in the group.

API description

fun updateGroup(operateBuilder: GroupOperateBuilder)

Parameter description

Property	Type	Description	Required
allSelectDeviceList	List< String >	The list of selected devices.	Yes
queryDeviceCallback	QueryDeviceCallback	The callback to invoke when the list of devices is returned successfully.	Yes
failureCallback	FailureCallback	The callback to invoke when there is a failure in getting the list of devices, creating, updating, or deleting a group.	Yes
successCallback	SuccessCallback	The callback to invoke when a group is created or updated successfully.	Yes

Example

GroupInitBuilder initBuilder = new GroupInitBuilder.Builder()
        .setGroupId(groupId)
        .build();

GroupOperateBuilder operateBuilder = new GroupOperateBuilder.Builder()
        .setAllSelectDeviceList(allSelectDeviceList)
        .setSuccessCallback(new SuccessCallback() {
            @Override
            public void result(long groupId, @Nullable List<GroupResult> failDevices) {

            }
        })
        .setProcessCallback(new ProcessCallback() {
            @Override
            public void result(int process, int size) {

            }
        })
        .setFailureCallback(new FailureCallback() {
            @Override
            public void onError(@Nullable String errorCode, @Nullable String errorMessage, long groupId, @Nullable List<GroupResult> failDevices) {

            }
        })
        .build();
thingGroupBizManager.updateGroup(operateBuilder);

Delete a group

Pass in groupId and delete the group.

API description

fun dismissGroup(operateBuilder: GroupOperateBuilder)

Parameter description

Property	Type	Description	Required
groupId	long	The group ID.	Yes
failureCallback	FailureCallback	The callback to invoke when there is a failure in getting the list of devices, creating, updating, or deleting a group.	Yes
successCallback	SuccessCallback	The callback to invoke when a group is created or updated successfully.	Yes

Example

GroupInitBuilder initBuilder = new GroupInitBuilder.Builder()
        .setDevId(groupId)
        .build();

GroupOperateBuilder operateBuilder = new GroupOperateBuilder.Builder()
        .setGroupId(groupId)
        .setSuccessCallback(new SuccessCallback() {
            @Override
            public void result(long groupId, @Nullable List<GroupResult> failDevices) {

            }
        })
        .setFailureCallback(new FailureCallback() {
            @Override
            public void onError(@Nullable String errorCode, @Nullable String errorMessage, long groupId, @Nullable List<GroupResult> failDevices) {

            }
        })
        .build();
thingGroupBizManager.dismissGroup(operateBuilder);

Error codes

Error codes	Description
1001	Failed to get the home details or incorrect configurations.