Bluetooth Beacon Remote

Overview

With the scanning capability, Bluetooth sub-devices can receive and parse Bluetooth advertising packets to extract DP data or control commands. This enables Bluetooth Low Energy (LE) beacon devices to control Bluetooth sub-devices.

A Bluetooth beacon remote is used to control devices without requiring a gateway or network connection. For example, connect home appliances such as heaters and fans to thermo-hygrometers for linkage.

In this topic, the receiver is considered a controlled device, and devices that initiate beacon or Bluetooth LE packets are referred to as remote devices.

Data structure

//  DP data format for beacon remotes
typedef struct {
    UINT8_T  dp_id;
    UINT8_T  dp_len:4;
    UINT8_T  dp_type:4;
    UINT8_T  group_id;
    UINT8_T  catagory_id;
    UINT8_T  cmd;
    UINT8_T  cmd_data[4];
    UINT8_T  mic[3];
    UINT8_T  mic_reserve;
} TAL_BLE_BEACON_REMOTE_DP_DATA_T;

// Advertising packet format for beacon remotes
typedef struct {
    UINT8_T  len;
    UINT8_T  type;
    UINT8_T  uuid[2];
    UINT8_T  frame_control[2];
    UINT8_T  dp_control;
    UINT8_T  sn[4];
    TAL_BLE_BEACON_REMOTE_DP_DATA_T dp_data;
} TAL_BLE_BEACON_REMOTE_SERVICE_DATA_T;

//  Device information for beacon remotes, allowing sub-devices to compare this information with the received advertising data to identify the source of the data.
typedef struct {
    UINT8_T  mac[6];
    UINT8_T  group_id;
    UINT8_T  s1[2];
    UINT8_T  s3[16];
    UINT32_T sn;
    UINT8_T  valid;
    UINT8_T  is_auth;
    UINT8_T  reserve[1]; // Note the 4-byte alignment issue
} TAL_BLE_BEACON_REMOTE_INFO_T;

// Data structure used for the sub-device to manage beacon remotes.
typedef struct {
    TAL_BLE_BEACON_REMOTE_INFO_T *info;
    UINT8_T device_num_max;
}TAL_BLE_BEACON_DEVICE_T;

API description

tal_ble_beacon_service_data_parser

OPERATE_RET tal_ble_beacon_service_data_parser(TAL_BLE_ADV_REPORT_T *p_adv_report, TAL_BLE_BEACON_REMOTE_SERVICE_DATA_T *p_service_data, UINT8_T *mac, UINT8_T *index);

Parse the scanned advertising data and extract the payload.

Description

• p_adv_report: The input parameter, containing the scanned advertising data. The scanned advertising packet must be formatted as TAL_BLE_ADV_REPORT_T.

• p_service_data: The output parameter, containing the payload sent from the remote, including remote information and DP data.

• mac: The output parameter, containing the MAC address of the remote.

• index: The output parameter, containing the position of the remote in the queue.

Return result

• 0: Success.
• Other values: Failure.

tal_ble_beacon_remoter_init

OPERATE_RET tal_ble_beacon_remoter_init(TAL_BLE_BEACON_REMOTE_INFO_T *info, UINT8_T max);

After power on, the sub-device sends remote device information to the component for device management and data parsing. You should store the remote device information in non-volatile memory at the application layer.

Description

• info: The address of the remote information array.

• max: The maximum size for storing remote information.

Return result

• 0: Success.
• Other values: Failure.

tal_ble_beacon_info_save

Save sub-device information.

OPERATE_RET tal_ble_beacon_info_save(VOID_T)

This is a virtual function. You need to adapt it at the application layer to meet your platform’s storage requirements.

tal_ble_beacon_remoter_find

UINT8_T tal_ble_beacon_remoter_find(UINT8_T* p_mac);

Check if the remote is matched through the MAC address.

Description

p_mac: The pointer to the MAC address.

Return result

• Value less than max from tal_ble_beacon_remoter_init: Matched.
• Value greater than or equal to max: Unmatched.

tal_ble_beacon_remoter_auth_rsp

OPERATE_RET tal_ble_beacon_remoter_auth_rsp(tuya_ble_remoter_proxy_auth_data_rsp_t data);

Respond to the verification result from the cloud. The component processes data received from the cloud. When a new device is connected or an existing device changes, it will invoke tal_ble_beacon_info_save to save the information.

Description

data: The remote information to verify.

Return result

• 0: Success.
• Other values: Failure.

tal_ble_beacon_remoter_group_add

OPERATE_RET tal_ble_beacon_remoter_group_add(UINT8_T* p_mac, UINT8_T* p_cmd_data);

Add a remote.

Return result

• 0: Success.
• Other values: Failure.

tal_ble_beacon_remoter_group_delete

OPERATE_RET tal_ble_beacon_remoter_group_delete(TAL_BLE_BEACON_ACT_TYPE_E cmd_type, UINT8_T* p_mac, UINT8_T* p_cmd_data);

Remove a remote device or dismiss a group. The removal command can be initiated by the remote or the app.

Description

• cmd_type: The input parameter, indicating the source of the removal command, either the remote or the app.

• p_mac: The input parameter, the MAC address of the device to be removed.

• p_cmd_data: The input parameter, determining whether to remove a remote or dismiss a group.

Return result

• 0: Success.
• Other values: Failure.

tal_ble_beacon_remoter_group_subscribe

OPERATE_RET tal_ble_beacon_remoter_group_subscribe(UINT8_T* p_mac, UINT8_T id);

Subscribe to a remote group.

Description

• p_mac: The MAC address to subscribe to.

• id: The group ID. 0 means to dismiss a group.

Return result

• 0: Success.
• Other values: Failure.

tal_ble_beacon_remoter_group_query

OPERATE_RET tal_ble_beacon_remoter_group_query(UINT8_T* p_mac);

Query a remote.

Description

p_mac: The MAC address of the remote to be queried.

Return result

• 0: Success.
• Other values: Failure.

OPERATE_RET tal_ble_beacon_device_auth_reset(VOID_T);

Clear the remote information, typically called when unbinding a sub-device.

Return result

• 0: Success.
• Other values: Failure.

How to use

• Implement the virtual function

TUYA_WEAK_ATTRIBUTE OPERATE_RET tal_ble_beacon_info_save(VOID_T)

Implement this virtual function at the application layer. This function saves the paired remote information in non-volatile memory for retrieval upon the next power up.

• Enable Bluetooth scanning

  The function to enable Bluetooth scanning varies by chip platform. Check Development Platform to learn how to enable scanning for your chip platform.

• Respond to events

  Manage the following four events:

  • TUYA_BLE_CB_EVT_REMOTER_PROXY_AUTH_RESP
  • TUYA_BLE_CB_EVT_REMOTER_GROUP_SET
  • TUYA_BLE_CB_EVT_REMOTER_GROUP_DELETE
  • TUYA_BLE_CB_EVT_REMOTER_GROUP_GET

          case TUYA_BLE_CB_EVT_REMOTER_PROXY_AUTH_RESP: {
              tal_ble_beacon_remoter_auth_rsp(event->remoter_proxy_auth_data_rsp);
          } break;
  
          case TUYA_BLE_CB_EVT_REMOTER_GROUP_SET: {
              TAL_PR_HEXDUMP_DEBUG("REMOTER_GROUP_SET", event->remoter_group_set_data.mac, sizeof(tuya_ble_remoter_group_set_data_t));
              tal_ble_beacon_remoter_group_subscribe(event->remoter_group_set_data.mac, event->remoter_group_set_data.id);
  
          } break;
  
          case TUYA_BLE_CB_EVT_REMOTER_GROUP_DELETE: {
              TAL_PR_HEXDUMP_DEBUG("TUYA_BLE_CB_EVT_REMOTER_GROUP_DELETE", event->remoter_group_delete_data.mac, sizeof(tuya_ble_remoter_group_delete_data_t));
              tal_ble_beacon_remoter_group_delete(TAL_BLE_BEACON_CLOUD_CMD, event->remoter_group_delete_data.mac, &event->remoter_group_delete_data.id);
          } break;
  
          case TUYA_BLE_CB_EVT_REMOTER_GROUP_GET: {
              TAL_PR_HEXDUMP_DEBUG("TUYA_BLE_CB_EVT_REMOTER_GROUP_GET", event->remoter_group_get_data.mac, sizeof(tuya_ble_remoter_group_get_data_t));
              tal_ble_beacon_remoter_group_query(event->remoter_group_get_data.mac);
          } break;
  

For more information, see the tuyaos_demo_ble_beacon_receiver demo.

Things to note

• When the scanning capability is enabled, the device should not enter sleep mode to ensure it continues scanning advertising packets.

• Take care of memory usage because the scanning capability consumes a significant amount of memory.

Support and help

If you have any problems with TuyaOS development, you can post your questions in the Tuya Developer Forum.