LE Peripheral Extended ADV

ble_bt5_peripheral 示例工程可以作为开发基于 Peripheral 角色的 APP 的框架。

特征：

• 使用 LE Advertising Extensions 发送 advertising events。

• 同时使能一个或多个 advertising set。

• 设定 advertising set 使能的 duration 或最大的 extended advertising events 数目。

• 使用 extended advertising PDUs 传输更多数据。

• 可以作为 Peripheral 角色建立一条 LE 链路， PHY 为 LE 1M PHY 、 LE 2M PHY 或 LE Coded PHY。

简介

• 使用 LE Advertising Extensions 的 peripheral 设备可以设置广播的持续时间或 extended advertising event 的最大数目，使能或禁用一个或多个 advertising set。

• 若使用 extended advertising PDUs，可以扩展 adv data 或 scan response data 的长度，以及使用 LE Coded PHY 增大可以建立连线的距离。关于 extended advertising PDUs 和 legacy advertising PDUs 的信息参见 LE Host 中的 Extended Advertising 相关参数的配置。

• 若 Peripheral 设备使用 LE Advertising Extensions，开发者需要考虑与不同蓝牙版本的对端设备的兼容性，与不同蓝牙版本的对端设备的兼容性如下表所示：

使用 LE Advertising Extensions 的 Peripheral 设备的兼容性

Bluetooth 5 Feature	Advertising PDUs	Bluetooth 4.0	Bluetooth 4.1	Bluetooth 4.2	Bluetooth 5.0 (Not Use LE Advertising Extensions)	Bluetooth 5.0 (Use LE Advertising Extensions)
LE Advertising Extensions	Extended advertising PDUs	N	N	N	N	Y
LE Advertising Extensions	Legacy advertising PDUs	Y	Y	Y	Y	Y

环境需求

该示例支持以下开发套件:

开发套件

Hardware Platforms	Board Name
RTL8752H HDK	RTL8752H EVB

为快速搭建起开发环境，可参考 快速入门 中提供的详细指导。

硬件连线

请参考 快速入门 中的 RTL8752H EVB 接口和模块。

配置

配置选项

该示例工程全部配置选项在 src\sample\ble_bt5_peripheral\app_flags.h 中， 开发者可以根据实际需求配置。

/** @brief Configure Advertising PHY */
#define ADVERTISING_PHY            APP_PRIMARY_CODED_SECONDARY_CODED
/** @brief Configure coding scheme of LE Coded PHY: 0 - S = 2, 1 - S = 8 */
#define LE_CODED_PHY_S8            0
/** @brief Configure APP LE link number */
#define APP_MAX_LINKS              1
/** @brief Configure DLPS: 0 - Disable DLPS, 1 - Enable DLPS */
#define F_BT_DLPS_EN               1

生成系统配置文件

开发者可以通过 MP Tool 配置以下项目：

MP Tool 配置

Configurable Item	Value
LE Slave Link Num	≥ APP_MAX_LINKS
Support LE AE ADV	Enable

更多有关于 MP Tool 配置的信息请参考 快速入门 中的 生成 System Config File。

编译和下载

该示例可以在 SDK 文件夹中找到:

Keil

Project file: board\evb\ble_bt5_peripheral\mdk

GCC

Project file: board\evb\ble_bt5_peripheral\gcc

编译和运行该示例请遵循以下步骤:

1. 打开项目文件。

2. 要编译目标文件，请参考 快速入门 的 编译 APP Image 中列出的步骤。

3. 编译成功后，目录 board\evb\ble_bt5_peripheral\mdk\bin 下会生成 app bin 文件 app_MP_sdk_xxx.bin。

4. 要下载 app bin 到 EVB，请参考 快速入门 的 MP Tool 中列出的步骤。

5. 在 EVB 上按下 reset 键，程序将开始运行。

测试验证

将示例工程烧录到 EVB 后，开发者可以使用另一个运行 ble_bt5_central 工程的开发板来与之对测。

与另一块开发板对测

测试流程请参考 LE Central Extended Scan 中的 与另一块开发板对测。

代码介绍

本章将按照以下几个部分进行介绍：

• 源码路径 中介绍项目目录和源代码文件。

• Bluetooth Host 介绍 中介绍了 Bluetooth Host 相关信息。

• 初始化 中介绍可配 GAP 参数和 Bluetooth Host 初始化。

• 启动 Extended Advertising 中介绍启动 Extended Advertising 的流程。

• GAP 消息处理 中介绍本示例工程的 GAP 消息处理。

• GAP 回调函数处理 中介绍本示例工程的 GAP 回调函数处理。

源码路径

• 工程目录: board\evb\ble_bt5_peripheral。

• 源码目录: src\sample\ble_bt5_peripheral。

ble_bt5_peripheral 示例工程中的源文件当前被分为几个组，如下所示：

└── Project: bt5_peripheral
    └── bt5_peripheral
        └── include
        ├── lib                      Includes all binary symbol files that user application is built on.
            ├── ROM.lib
            ├── gap_utils.lib
            ├── lowerstack.lib
            └── rtl8752h_sdk.lib
        ├── cmsis                    Includes startup code.
        ├── peripheral               Includes all peripheral drivers and module code used by the application.
        └── app                      Includes the ble_bt5_peripheral user application implementation.
            ├── main.c
            ├── bt5_peripheral_stack_api.c
            ├── bt5_peripheral_app.c
            ├── app_task.c
            └── overlay_mgr.c

示例工程使用与 upperstack_0_0 匹配的默认 GAP LIB，请参阅文档 Host Image 中的 GAP LIB 的使用方法 以获取更多信息。

Bluetooth Host 介绍

示例工程默认使用 Bluetooth Host image 版本 upperstack_0_0，更多信息可参阅 Host Image。

关于 Bluetooth Host 所支持的蓝牙功能的详细信息，请参阅文件 bin\upperstack_img\upperstack_0_0\upperstack_config.h。

初始化

当 EVB 启动并且芯片复位时， main() 函数将被调用，它执行以下初始化函数：

int main(void)
{
   board_init();
   le_gap_init(APP_MAX_LINKS);
   gap_lib_init();
   app_le_gap_init();
   pwr_mgr_init();
   task_init();
   os_sched_start();

   return 0;
 }

• le_gap_init() 用于初始化 GAP 并配置链接个数。

• app_le_gap_init() 用于初始化 GAP 参数，开发者可以自行配置以下参数：Device name 和 device appearance，LE Advertising Extensions 参数，GAP Bond Manager 参数（请参考 LE Host 中的 Device Name 和 Device Appearance 的配置， LE Advertising Extensions 参数的配置， Pairing 参数的配置）。

void app_le_gap_init(void)
{
   /* Device name and device appearance */
   ......

   /* GAP Bond Manager parameters */
   ......

   /* LE Advertising Extensions parameters */
   bool use_extended = true;

   /* Set device name and device appearance */
   le_set_gap_param(GAP_PARAM_DEVICE_NAME, GAP_DEVICE_NAME_LEN, device_name);
   le_set_gap_param(GAP_PARAM_APPEARANCE, sizeof(appearance), &appearance);
   le_set_gap_param(GAP_PARAM_SLAVE_INIT_GATT_MTU_REQ, sizeof(slave_init_mtu_req),
                   &slave_init_mtu_req);

   le_set_gap_param(GAP_PARAM_DEFAULT_DATA_LEN_MAX_TX_OCTETS, sizeof(max_data_len_tx_oct),
                   &max_data_len_tx_oct);
   le_set_gap_param(GAP_PARAM_DEFAULT_DATA_LEN_MAX_TX_TIME, sizeof(max_data_len_tx_time),
                   &max_data_len_tx_time);

   /* Setup the GAP Bond Manager */
   gap_set_param(GAP_PARAM_BOND_PAIRING_MODE, sizeof(auth_pair_mode), &auth_pair_mode);
   gap_set_param(GAP_PARAM_BOND_AUTHEN_REQUIREMENTS_FLAGS, sizeof(auth_flags), &auth_flags);
   gap_set_param(GAP_PARAM_BOND_IO_CAPABILITIES, sizeof(auth_io_cap), &auth_io_cap);
   gap_set_param(GAP_PARAM_BOND_OOB_ENABLED, sizeof(auth_oob), &auth_oob);
   le_bond_set_param(GAP_PARAM_BOND_FIXED_PASSKEY, sizeof(auth_fix_passkey), &auth_fix_passkey);
   le_bond_set_param(GAP_PARAM_BOND_FIXED_PASSKEY_ENABLE, sizeof(auth_use_fix_passkey),
                     &auth_use_fix_passkey);
   le_bond_set_param(GAP_PARAM_BOND_SEC_REQ_REQUIREMENT, sizeof(auth_sec_req_flags),
                     &auth_sec_req_flags);

   /* Use LE Advertising Extensions */
   le_set_gap_param(GAP_PARAM_USE_EXTENDED_ADV, sizeof(use_extended), &use_extended);

   /* Initialize extended advertising related parameters */
   le_init_ext_adv_params_ext_conn();

   /* Register gap message callback */
   le_register_app_cb(app_gap_callback);
}

更多关于 LE GAP 初始化和启动流程的信息可以查阅 LE Host 中的 GAP 参数的初始化。

启动 Extended Advertising

由于支持 LE Advertising Extensions，设备可以使用一个或多个 advertising sets。 APP 需要创建 advertising handle 以识别 advertising set，extended advertising 相关参数是针对指定 advertising set 配置的。 使用 LE Advertising Extensions 时，APP 可以通过修改 advertising event properties 选择发送 legacy advertising PDUs （LE Peripheral 示例工程只能发送 legacy advertising PDUs）或 extended advertising PDUs。

开启 extended advertising 的流程图如下所示。 Optional 部分取决于 advertising event properties。

开启 Extended Advertising 流程图

GAP Extended Advertising 相关参数配置

请参考 LE Host 中的 Extended Advertising 相关参数的配置 章节。

GAP 消息处理

当 APP 从 Bluetooth Host 接收到 GAP 消息时，函数 app_handle_gap_msg() 会被调用。更多关于 GAP 消息的信息参见 LE Host 中的 蓝牙状态消息。

void app_handle_gap_msg(T_IO_MSG *p_gap_msg)
{
   T_LE_GAP_MSG gap_msg;
   uint8_t conn_id;
   memcpy(&gap_msg, &p_gap_msg->u.param, sizeof(p_gap_msg->u.param));

   APP_PRINT_TRACE1("app_handle_gap_msg: subtype %d", p_gap_msg->subtype);
   switch (p_gap_msg->subtype)
   {
   case GAP_MSG_LE_DEV_STATE_CHANGE:
       {
           app_handle_dev_state_evt(gap_msg.msg_data.gap_dev_state_change.new_state,
                                   gap_msg.msg_data.gap_dev_state_change.cause);
       }
       break;
   .......
 }
 void app_handle_dev_state_evt(T_GAP_DEV_STATE new_state, uint16_t cause)
{
   APP_PRINT_INFO3("app_handle_dev_state_evt: init state %d, ADV state %d, cause 0x%x",
                  new_state.gap_init_state, new_state.gap_adv_state, cause);
   if (gap_dev_state.gap_init_state != new_state.gap_init_state)
   {
      if (new_state.gap_init_state == GAP_INIT_STATE_STACK_READY)
      {
            APP_PRINT_INFO0("GAP stack ready");
            /* Stack ready */
            ......
            /* Set extended advertising related parameters */
            le_ext_adv_start_setting(adv_handle, EXT_ADV_SET_AUTO);
      }
   }
   gap_dev_state = new_state;
}

当收到 GAP_INIT_STATE_STACK_READY 消息时，该示例工程将调用 le_ext_adv_start_setting() 设置 extended advertising 相关参数。 EXT_ADV_SET_AUTO 表示将根据 advertising event properties 自动设置针对指定 advertising set 的 extended advertising 相关参数（包括 advertising 参数、advertising 数据和 scan response 数据）。否则，application 需要参考表-使用 legacy advertising PDUs 的 Extended Advertising 参数设置 或表-使用 extended advertising PDUs 的 Extended Advertising 参数设置 根据 advertising event properties 设置 flags。

void app_handle_dev_state_evt(T_GAP_DEV_STATE new_state, uint16_t cause)
{
   APP_PRINT_INFO3("app_handle_dev_state_evt: init state %d, ADV state %d, cause 0x%x",
                  new_state.gap_init_state, new_state.gap_adv_state, cause);
   if (gap_dev_state.gap_init_state != new_state.gap_init_state)
   {
      if (new_state.gap_init_state == GAP_INIT_STATE_STACK_READY)
      {
            APP_PRINT_INFO0("GAP stack ready");
            /* Stack ready */
            ......
            /* Set extended advertising related parameters */
            le_ext_adv_start_setting(adv_handle, EXT_ADV_SET_AUTO);
      }
   }
   gap_dev_state = new_state;
}

在 app_gap_callback() 调用 le_ext_adv_enable() 之后，APP 将收到 extended advertising 状态消息。更多关于处理 extended advertising 状态消息的信息参见 LE Host 中的 Extended Advertising 状态消息。 当收到 GAP_CONN_STATE_DISCONNECTED 消息时，APP 将调用 le_ext_adv_enable() 以使能指定 advertising set。在连接断开之后，APP 将恢复为可连接状态。

void app_handle_conn_state_evt(uint8_t conn_id, T_GAP_CONN_STATE new_state, uint16_t disc_cause)
{
   APP_PRINT_INFO4("app_handle_conn_state_evt: conn_id %d old_state %d new_state %d, disc_cause 0x%x",
                  conn_id, gap_conn_state, new_state, disc_cause);
   switch (new_state)
   {
   case GAP_CONN_STATE_DISCONNECTED:
      {
            if ((disc_cause != (HCI_ERR | HCI_ERR_REMOTE_USER_TERMINATE))
               && (disc_cause != (HCI_ERR | HCI_ERR_LOCAL_HOST_TERMINATE)))
            {
               APP_PRINT_ERROR1("app_handle_conn_state_evt: connection lost cause 0x%x", disc_cause);
            }
            /* Enable one advertising set */
            le_ext_adv_enable(1, &adv_handle);
      }
      break;
   ......
   }
   gap_conn_state = new_state;
}

GAP 回调函数处理

app_gap_callback() 用于处理 GAP 回调函数消息，更多关于 GAP 回调函数的信息参见 LE Host 中的 Bluetooth LE GAP 回调函数。

在协议栈准备就绪之后调用 le_ext_adv_start_setting()，设置 extended advertising 参数的结果将在函数 app_gap_callback() 中以回调类型 GAP_MSG_LE_EXT_ADV_START_SETTING 返回。若返回结果表示参数设置成功，APP 将使能 extended advertising。

首先，APP 设置 GAP extended advertising 使能参数，以决定是否通过使用 duration 或最大的 extended advertising events 数目停止 extended advertising。APP 调用 le_ext_adv_enable() 对一个 advertising set 使能 extended advertising，示例代码如下：

T_APP_RESULT app_gap_callback(uint8_t cb_type, void *p_cb_data)
{
   T_APP_RESULT result = APP_RESULT_SUCCESS;
   T_LE_CB_DATA *p_data = (T_LE_CB_DATA *)p_cb_data;

   APP_PRINT_TRACE1("app_gap_callback: cb_type = 0x%x", cb_type);

   switch (cb_type)
   {
   case GAP_MSG_LE_EXT_ADV_START_SETTING:
      APP_PRINT_INFO3("GAP_MSG_LE_EXT_ADV_START_SETTING:cause 0x%x, flag 0x%x, adv_handle %d",
                        p_data->p_le_ext_adv_start_setting_rsp->cause, p_data->p_le_ext_adv_start_setting_rsp->flag,
                        p_data->p_le_ext_adv_start_setting_rsp->adv_handle);

      if (p_data->p_le_ext_adv_start_setting_rsp->cause == GAP_CAUSE_SUCCESS)
      {
            /* Initialize enable parameters */
            le_init_ext_adv_enable_params(p_data->p_le_ext_adv_start_setting_rsp->adv_handle);
            /* Enable one advertising set */
            le_ext_adv_enable(1, &p_data->p_le_ext_adv_start_setting_rsp->adv_handle);
      }
      break;
   ......
   }
}

Extended advertising 状态消息在 app_handle_gap_msg() 函数中处理。使能 advertising set 的结果将在 app_gap_callback() 中以回调类型 GAP_MSG_LE_EXT_ADV_ENABLE 返回，示例代码如下：

T_APP_RESULT app_gap_callback(uint8_t cb_type, void *p_cb_data)
{
   T_APP_RESULT result = APP_RESULT_SUCCESS;
   T_LE_CB_DATA *p_data = (T_LE_CB_DATA *)p_cb_data;

   APP_PRINT_TRACE1("app_gap_callback: cb_type = 0x%x", cb_type);

   switch (cb_type)
   {
   case GAP_MSG_LE_EXT_ADV_ENABLE:
      APP_PRINT_INFO1("GAP_MSG_LE_EXT_ADV_ENABLE:cause 0x%x", p_data->le_cause.cause);
      break;
   ......
   }
}

当 ble_bt5_peripheral 示例工程在开发板上运行时，设备是可发现且可连接的。对端设备可以对 peripheral 设备进行扫描，并创建连线。