Advanced Capabilities

The advanced capabilities set includes: send commands with transaction identifiers (TID), set vendor heartbeat, and pack responses to device status queries.

Advanced capabilities

Send commands with TID

Longer Bluetooth mesh packets are segmented for transmission, resulting in increased latency and packet losses as more packets are delivered. After executing a command, the device usually needs to report its current status to the mobile app. If the packet sent to the device or mobile app is large, it will be segmented for transmission. When a device receives a command with TID, it only needs to confirm receipt to enhance response speed and success rate.

If this feature is enabled, it applies when messages are segmented and transmitted through the vendor model.

Set vendor heartbeat

The vendor model can use the custom opcode to include extra information for heartbeat checks. For example, the source of the heartbeat packet can be the device response or power-on status. This feature has been integrated into the SDK to automatically process the response to a heartbeat check.

You can include the device’s on/off status in the heartbeat packet. If you register the on/off status to the heartbeat, you can get both the device’s online and on/off status through a heartbeat check.

Pack responses to device status queries

When the app panel is opened, it will request the current status from the Bluetooth mesh device. Packet loss may occur if there is a large amount of data to be synchronized. In this case, assembling data into one or more packets can enhance synchronization efficiency.

However, this feature does not apply to legacy mobile apps and gateways. To ensure compatibility with legacy mobile apps and gateways, retain the original logic for responding to status queries using the Bluetooth SIG model get command and opcode 0xCCD007 (0x01 CMD).

API description

Enable advanced capability

The advanced capability is disabled by default. Call the following API to enable the advanced capability set.

VOID_T tal_mesh_advanced_ability_1(UINT8_T enable);

Note: Once you enable the advanced capability set, all three capabilities will be activated simultaneously.

Send commands with TID

#define TAL_MESH_OPCODE_WRITE_WITH_TID                  (0xC8D007)

Set vendor heartbeat

This API enables you to include the on/off status in the vendor heartbeat packet for optimizing the status display on the quick toggle in the mobile app.

OPERATE_RET tal_mesh_heartbeat_onoff_info_set(UINT8_T enable, UINT8_T* onoff_status, UINT8_T onoff_dp_id);

• enable: Specifies whether to include the on/off status in the heartbeat packet.

• onoff_status: On/off status.

• onoff_dp_id: The DP ID of on/off.

Pack responses to device status queries

typedef OPERATE_RET (*tal_mesh_vendor_get_cb)(UINT8_T dp_id, UINT8_T *dp_type, UINT8_T *dp_len, UINT8_T *dp_data);

The application implements the callback for packing responses to device status queries and registers it to the SDK.

OPERATE_RET tal_mesh_vendor_get_cb_init(tal_mesh_vendor_get_cb vendor_data_get_cb);

The initialization API for callback registration.

Related protocols

Send commands with TID

The mobile app sends:

opcode: 0xC8D007 (WRITE_WITH_TID)

Payload data:

The device returns:

opcode: 0xCBD007 (STATUS)

Payload data:

How-to

Send commands with TID

In OPERATE_RET app_mesh_data_recv(TAL_MESH_ACCESS_MSG_T *msg_raw, TAL_MESH_NET_PARAM_T *net_param), process the opcode data with TAL_MESH_OPCODE_WRITE_WITH_TID and return the reception status. See the app_common.c in the demo for details.

OPERATE_RET app_mesh_data_recv(TAL_MESH_ACCESS_MSG_T *msg_raw, TAL_MESH_NET_PARAM_T *net_param)
{
    switch (msg_raw->opcode) {
        case TAL_MESH_OPCODE_WRITE_WITH_TID:{
            // data_proc(); Data processing

            // Data receiving response
            UINT8_T data[2] = {0};
            data[0] = msg_raw->data[0]; // TID
            data[1] = 0x00;
            tal_mesh_data_send(net_param->dst_addr, net_param->src_addr, TAL_MESH_OPCODE_STATUS, data, 2);
        }
        break;

        default:
        break;
    }

    return OPRT_OK;
}

Pack responses to device status queries

OPERATE_RET app_mesh_vendor_get_recv(UINT8_T dp_id, UINT8_T *dp_type, UINT8_T *dp_len, UINT8_T *dp_data)
{
    switch (dp_id) {
        case DP_ID_ONOFF:
            *dp_type = DP_TYPE_BOOL;
            *dp_len = 1;
            dp_data[0] = onoff_data;
        break;
        /* other DP */
        default:
            return OPRT_NOT_FOUND;
    }
    return OPRT_OK;
}

OPERATE_RET tuya_init_third(VOID_T)
{
    /* other init process */

    tal_mesh_advanced_ability_1(1);
    tal_mesh_vendor_get_cb_init(app_mesh_vendor_get_recv);
    tal_mesh_heartbeat_onoff_info_set(1, &onoff_data, 1);

    return OPRT_OK;
}

The SDK provides the message handler and response packing. The device status is obtained from the callback registered at the application layer.

Find OPERATE_RET tuya_init_third(VOID_T) in app_common.c. Register the status query callback to the SDK using tal_mesh_vendor_get_cb_init(app_mesh_vendor_get_recv).

Implement OPERATE_RET app_mesh_vendor_get_recv(UINT8_T dp_id, UINT8_T *dp_type, UINT8_T *dp_len, UINT8_T *dp_data) in the application. The SDK uses this callback to query device status when receiving a status request. You need to specify the DP data in this callback.

See the implementation in app_common.c for details.