蓝牙 Beacon 遥控器

概述

蓝牙子设备通过 Scan 能力，获取蓝牙广播包并解析出 DP 数据或控制命令，实现 Bluetooth Low Energy (LE) Beacon 能力的设备对蓝牙子设备的控制。

主要用于常供电设备的脱网关、非连接控制。例如，家电相关的设备：取暖器、风扇等配合温湿度计进行联动。

本文将接收端的设备视为受控设备，而发起 Beacon 或者 Bluetooth LE Beacon 数据包的设备都统一抽象成遥控器设备。

数据结构

// Beacon 遥控器 DP 部分数据格式
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;

// Beacon 遥控器广播包数据格式
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;

// Beacon 遥控器设备信息，子设备通过该信息与收到广播的信息比对，来区分数据的来源
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;

// 子设备管理 Beacon 遥控器设备的数据结构
typedef struct {
    TAL_BLE_BEACON_REMOTE_INFO_T *info;
    UINT8_T device_num_max;
}TAL_BLE_BEACON_DEVICE_T;

API 说明

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);

该接口用于对扫描到的广播数据进行解析，并将其中有效的数据提取出来。

参数说明

• p_adv_report：输入参数，输入内容为扫描到的广播数据。注意，扫描到的广播包要按照 TAL_BLE_ADV_REPORT_T 格式打包。

• p_service_data：输出参数，该数据为遥控器发送的有效数据，其中包括遥控器信息和 DP 数据。

• mac：输出参数，解析出的数据为该遥控器的 MAC 地址。

• index：输出参数，解析出的数据为该遥控器在管理队列中的位置。

返回结果

• 0：成功。
• 其他：失败。

tal_ble_beacon_remoter_init

OPERATE_RET tal_ble_beacon_remoter_init(TAL_BLE_BEACON_REMOTE_INFO_T *info, UINT8_T max);

子设备上电时，向组件传入遥控器设备信息，以便组件进行设备管理和数据解析。遥控器的设备信息由用户在应用层做好存储逻辑，确保掉电不丢失。

参数说明

• info：遥控器信息数组地址。

• max：最大允许存储的遥控器信息。

返回结果

• 0：成功。
• 其他：失败。

tal_ble_beacon_info_save

子设备存储接口函数：

OPERATE_RET tal_ble_beacon_info_save(VOID_T)

该函数为虚函数，用户需要在应用层对该函数进行重新实现，以达到适配不同平台存储的需求。

tal_ble_beacon_remoter_find

UINT8_T tal_ble_beacon_remoter_find(UINT8_T* p_mac);

通过传入的 MAC 地址，查询是否是已匹配的遥控器。

参数说明

p_mac：MAC 地址指针。

返回结果

• 小于 tal_ble_beacon_remoter_init 中传入的 max：匹配成功。
• 大于等于 max：未匹配的遥控器。

tal_ble_beacon_remoter_auth_rsp

OPERATE_RET tal_ble_beacon_remoter_auth_rsp(tuya_ble_remoter_proxy_auth_data_rsp_t data);

遥控器云端校验结果回复。由组件来处理云端下发的信息，如果是新设备接入或者旧设备有变动，则会调用一次 tal_ble_beacon_info_save 函数存储信息。

参数说明

data：校验的遥控器信息。

返回结果

• 0：成功。
• 其他：失败。

tal_ble_beacon_remoter_group_add

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

新增遥控器。

返回结果

• 0：成功。
• 其他：失败。

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);

遥控器删除命令，可以是遥控器删除，也可以是群组解散。可以由遥控器发起解绑命令，也可以由 App 面板删除遥控器发起。

参数说明

• cmd_type：输入参数，删除命令来源，即遥控器或者 App。

• p_mac：输入参数，要删除的设备的 MAC 地址。

• p_cmd_data：输入参数，通过此参数的值，确定是删除遥控器还是解散群组。

返回结果

• 0：成功。
• 其他：失败。

tal_ble_beacon_remoter_group_subscribe

OPERATE_RET tal_ble_beacon_remoter_group_subscribe(UINT8_T* p_mac, UINT8_T id);

遥控器群组订阅。

参数说明

• p_mac：要订阅的 MAC 地址。

• id：群组 ID。如果 0，则表示解散群组。

返回结果

• 0：成功。
• 其他：失败。

tal_ble_beacon_remoter_group_query

OPERATE_RET tal_ble_beacon_remoter_group_query(UINT8_T* p_mac);

遥控器查询。

参数说明

p_mac：要查询的遥控器 MAC 地址。

返回结果

• 0：成功。
• 其他：失败。

OPERATE_RET tal_ble_beacon_device_auth_reset(VOID_T);

遥控器信息清空，一般只在子设备解绑时调用。

返回结果

• 0：成功。
• 其他：失败。

使用方法

• 虚函数实现

TUYA_WEAK_ATTRIBUTE OPERATE_RET tal_ble_beacon_info_save(VOID_T)

在使用时，用户需要先在应用层实现此虚函数。实现的内容就是将已配对的遥控器信息保存，用于下次上电时读取。

• 开启蓝牙扫描

  不同的平台开启蓝牙的接口不同。开发平台 说明了如何开启不同芯片平台的 Scan 能力。

• SDK 事件响应

  需要对如下四个事件进行处理：

  • 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;
  

更多详细信息，见 tuyaos_demo_ble_beacon_receiver Demo。

注意事项

• Scan 能力开启后就不能进入休眠，否则无法进行广播扫描。

• Scan 能力会占用较大的内存空间，开启后需要注意内存使用。

支持与帮助

在开发过程遇到问题，您可以登录 TuyaOS 开发者论坛 TuyaOS-蓝牙设备开发 版块进行沟通咨询。

咨询前建议首先查阅 官方资料 或参考已有帖子，并认真阅读 发帖规范。