Group

This topic describes how to group and control multiple devices of the same category in one go. Compared to individual control, group control can offer a quicker and more stable pairing experience with higher success rates.

Concepts

Subscription

Bluetooth mesh groups operate using a subscription mechanism. When a device subscribes to a group address, the network layer forwards data with that address to the upper layer for processing. Otherwise, the data is relayed based on packet rules without additional processing. When adding a device to a group, you send the device a group address for subscription.

Addresses are subscribed as per model, enabling different elements or models within the same element to subscribe to a group address individually.

Group limits

Up to 32 groups can be subscribed. The maximum number of groups in a mesh network is subject to the range of group addresses, which spans from 0xC000 to 0xFEFF.

Data structure

This section outlines the data format for the group subscription and deletion commands as defined in the Bluetooth mesh specification. The configuration model in the SDK implements the group commands. To subscribe to a group, the application can use the API to specify the group for the model in an element.

TAL_MESH_MODEL_SUB_ADD_T

typedef struct {
    USHORT_T    element_addr;
    USHORT_T    addr;
    UINT_T      model_id;   /**<  2 bytes or 4 bytes */
} PACKED TAL_MESH_MODEL_SUB_ADD_T;

• element_addr: The element address of the command receiver. A device can have multiple elements. Models in different elements can subscribe to a group address individually.

• addr: The group address to be subscribed.

• model_id: The model that subscribes to the group address.

TAL_MESH_MODEL_SUB_DELETE_T

typedef struct {
    USHORT_T    element_addr;
    USHORT_T    addr;
    UINT_T      model_id;   /**<  2 bytes or 4 bytes */
} PACKED TAL_MESH_MODEL_SUB_DELETE_T;

• element_addr: The element address of the command receiver. A device can have multiple elements. Models in different elements can subscribe to a group address individually.

• addr: The group address to be deleted.

• model_id: The model that deletes the group address.

TAL_MESH_MODEL_SUB_STATUS_T

Opcode: 0x801F

typedef struct {
    UCHAR_T     status;
    USHORT_T    element_addr;
    USHORT_T    addr;
    UINT_T      model_id;   /**<  2 bytes or 4 bytes */
} PACKED TAL_MESH_MODEL_SUB_STATUS_T;

• status: The result of adding a group.

• element_addr: The element address of the command receiver. A device can have multiple elements. Models in different elements can subscribe to a group address individually.

• addr: The group address to be deleted.

• model_id: The model that deletes the group address.

API description

The SDK offers APIs for configuring groups and querying their current status.

These APIs can enable linkage across devices. For example, when Device A sends data to the group address 0xC010, Devices B and C that subscribe to the address 0xC010 can receive the data from Device A and act accordingly.

Validate group address

#define MESH_IS_GROUP_ADDR(addr)    (((addr) & 0xC000) == 0xC000)

This macro definition is used to validate a group address.

Add or delete group

#define TAL_MESH_OPCODE_CFG_MODEL_SUB_ADD               (0x801B)
#define TAL_MESH_OPCODE_CFG_MODEL_SUB_DELETE            (0x801C)

OPERATE_RET tal_group_addr_sub_set(UINT_T opcode, USHORT_T ele_index, USHORT_T group_addr);

This API is used to subscribe to or unsubscribe from a specific group address.

Query the list of subscribed groups

USHORT_T* tal_group_addr_sub_list_get(USHORT_T ele_idx, UINT_T model_id);

This API is used to request the list of group addresses subscribed by an element. The return value is the pointer to the list, which is of UINT16_T, 32 bytes in length.

You can validate the group address using the macro definition mentioned above.

Things to note

Group control

The opcode for group control is an unacknowledged message, so devices do not need to respond. This is because network congestion and packet loss can occur when multiple devices in a group respond simultaneously to a group control message. Even with a random delay in the response, it is not possible to completely avoid data losses.

Note: After group control, the device should not report its status or send data packets that might trigger a network storm.

Synchronize group status

After group control, if a device does not report its status, the actual status cannot be reflected on the mobile app. There are two solutions available to address this issue:

• After group control, the mobile app automatically updates the DP of the devices in the group.

• After group control, the gateway queries the status of the controlled DP in the group sequentially through a queue. It then synchronizes the device’s status with both the mobile app and cloud.