Group Management

Last Updated on : 2024-06-12 10:22:48download

Concepts

  • A group is a collection of devices that match specific rules. This enables multiple devices to be controlled in one go.

  • A combination group is a collection of groups, allowing for simultaneous control of devices within them.

  • The Commercial Lighting App SDK provides the capabilities to create, edit, and control combination groups. A single group in a combination group cannot be managed.

  • Each combination group must belong to an area and cannot be created without an area.

    The following figure shows the relationships among the combination groups, groups, and devices.

    Group Management

Get the device list for creating a combination group

API description

// Create a combination group instance.
ILightingGroupPack groupPackInstance = ThingCommercialLightingGroupPack.newGroupPackInstance(long projectId,String groupPackId);

// Get the list of devices that can be added to this combination group.
groupPackInstance.getAvailableDevices2JoinGroupPack(long areaId, @GroupPackType String topCategory, int limit,
                                    String offsetKey,IThingResultCallback<GroupDeviceListRespBean> callback)

Parameter description

Parameter Description
projectId The project ID.
groupPackId The ID of the combination group. If not specified, set it to an empty string.
areaId The ID of the area. Each combination group must belong to an area and cannot be created without an area.
topCategory The code of the level-1 category. The SDK currently only supports creating combination groups for lighting products, so the value is fixed to GroupPackCategory.CATEGORY_LIGHTING.
limit The number of items returned per page.
offsetKey The current page number. The page number starts at 1 and is incremented by 1 for subsequent pages.
callback The callback.

Create combination group

API description

ThingCommercialLightingGroupPack.getGroupPackManager()
  .createPackedGroup(long projectId,long areaId,String packedGroupName,List<ComplexDeviceBean> addDevices,
                                        @GroupPackCategory int topCategory,String deviceId,DefaultDeviceTransferListener listener)

Parameter description

Parameter Description
projectId The project ID.
areaId The ID of the area. Each combination group must belong to an area and cannot be created without an area.
packedGroupName The name of the combination group.
addDevices The list of devices to join the combination group. The list is returned by the method Get the Device List for Creating a Combination Group.
topCategory The code of the level-1 category. The SDK currently only supports creating combination groups for lighting products, so the value is fixed to GroupPackCategory.CATEGORY_LIGHTING.
deviceId The ID of the main device, defaulting to an empty string.
listener The callback for creating a combination group. See DefaultDeviceTransferListener in Area Management for the specific callbacks.

Update device list in combination group

API description

//Create a combination group instance object.
ILightingGroupPack groupPackInstance = ThingCommercialLightingGroupPack.newGroupPackInstance(long projectId,String groupPackId);

//Update the list of devices in the group.
groupPackInstance.updateDevicesByIds(List<String> bindDevIds, List<String> unbindDevIds, final IThingResultCallback<DeviceTaskResultBean> callback);

Parameter description

Parameter Description
projectId The project ID.
groupPackId The ID of the combination group.
bindDevIds The list of devices that are newly added to the combination group.
unbindDevIds The list of devices that are removed from the combination group.
callback The callback, with DeviceTaskResultBean#success for the list of devices on success, while failed for the list of devices on failure.

Get combination group information

API description

//Create a combination group instance object.
ILightingGroupPack groupPackInstance = ThingCommercialLightingGroupPack.newGroupPackInstance(long projectId,String groupPackId);

// Get information
groupPackInstance.getPackedGroupInfo(IThingResultCallback<GroupPackBean> resultListener);

Parameter description

Parameter Description
projectId The project ID.
groupPackId The ID of the combination group.
resultListener The callback.

Rename combination group

API description

//Create a combination group instance object.
ILightingGroupPack groupPackInstance = ThingCommercialLightingGroupPack.newGroupPackInstance(long projectId,String groupPackId);

groupPackInstance.renamePackedGroup(String name,IResultCallback callback);

Parameter description

Parameter Description
projectId The project ID.
groupPackId The ID of the combination group.
name The new name of the combination group.
callback The callback.

Get device list in combination group

API description

//Create a combination group instance object.
ILightingGroupPack groupPackInstance = ThingCommercialLightingGroupPack.newGroupPackInstance(long projectId,String groupPackId);

groupPackInstance.getDevicesInGroupPack(int limit,String offsetKey,IThingResultCallback<GroupDeviceListRespBean> callback);

Parameter description

Parameter Description
projectId The project ID.
groupPackId The ID of the combination group.
limit The number of items returned per page.
offsetKey The current page number. The page number starts at 1 and is incremented by 1 for subsequent pages.
callback The callback.

Dismiss combination group

API description

It is recommended to remove all devices from the combination group before dismissing. Bluetooth mesh devices have a limit on the number of groups they can join. If this limit is reached, they cannot join additional groups.

// Create a combination group instance object.
ILightingGroupPack groupPackInstance = ThingCommercialLightingGroupPack.newGroupPackInstance(long projectId,String groupPackId);

groupPackInstance.dismiss(IResultCallback callback);

Parameter description

Parameter Description
projectId The project ID.
groupPackId The ID of the combination group.
callback The callback.

Get combination group list

API description

ILightingGroupPackManager groupPackManager = ThingCommercialLightingGroupPack.getGroupPackManager();
groupPackManager.getPackedGroupList(long areaId, int limit, String offsetKey, IThingResultCallback<GroupPackListBean> callback);

Parameter description

Parameter Description
areaId The ID of the area.
limit The number of items returned per page.
offsetKey The current page number. The page number starts at 1 and is incremented by 1 for subsequent pages.
callback The callback.

Example

ThingCommercialLightingGroupPack.getGroupPackManager().unRegisterGroupPackListener(listener);

Register a listener for combination group changes

API description

ILightingGroupPackManager groupPackManager = ThingCommercialLightingGroupPack.getGroupPackManager();
groupPackManager.registerGroupPackListener(ILightingGroupPackListener listener);

Parameter description

Parameter Description
listener The callback.

Remove a listener for combination group changes

API description

ILightingGroupPackManager groupPackManager = ThingCommercialLightingGroupPack.getGroupPackManager();
groupPackManager.unRegisterGroupPackListener(ILightingGroupPackListener listener);

Parameter description

Parameter Description
listener The callback.