Group Management

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.

  

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.