8. vble_adv无线收发接口介绍

8.1. 简介

本章介绍应用层封装、管理BLE广播应用收发接口的vble_adv管理：

该封装层统一，让用户聚焦于蓝牙数据收发

该封装层管理的相关章节：周期广播(periodic_advertise)介绍

该接口非蓝牙标准协议，仅为应用层管理接口！

主要涉及的文件如下：

apps/app/bsp/common/bt_user/vble_adv/vble_adv.c

apps/app/bsp/common/bt_user/vble_adv/vble_adv_trans.c

8.2. 数据发送/接收流程

发送端使用流程（可参考BLE广播式对讲机应用流程）：

调用函数ble_clock_init()进行蓝牙硬件初始化；

调用函数vble_adv_init()进行蓝牙协议栈初始化；

调用函数vble_padv_param_init()进行周期广播参数初始化；

调用函数vble_adv_rx_cb_register()注册接收回调函数与同步断开回调；

调用函数vble_adv_tx_init()初始化周期广播；

调用函数vble_adv_tx_open()启动周期广播，蓝牙根据广播参数初始化时传入的周期广播间隔，定时往回调中推出PUSH_DATA事件，用户此时可在该事件分支进行广播数据；

接收端端使用流程（可参考BLE广播式对讲机应用流程）：

调用函数ble_clock_init()进行蓝牙硬件初始化；

调用函数vble_adv_init()进行蓝牙协议栈初始化；

调用函数vble_padv_param_init()进行周期广播参数初始化；

调用函数vble_adv_rx_cb_register()注册接收回调函数与同步断开回调；

调用函数vble_adv_rx_init()初始化周期广播扫描；

调用函数vble_adv_rx_open()启动扫描，当蓝牙扫描到对应的广播包时会进行同步，同步成功时，回调函数推出PADVB_EVENT_SYNC_SUCCESS事件

蓝牙收到广播包时PADVB_EVENT_POP_DATA传入事件回调，用户此时将一个空指针的指针传入pop_data函数，如果指针被更新为非空，即为蓝牙收到用户数据，如果指针依然为空，则蓝牙出现丢包；

8.3. 广播端（发送端）和扫描端（接收端）配置说明

用户需要配置的广播和扫描参数在vble_adv_trans.c中的结构体，收发两端的蓝牙名、广播间隔、广播包长度需要保持一致才能正常通信。

其中广播端(发送端)参数：

u_pa_tx.adv_name：广播端蓝牙名，广播端和扫描端的蓝牙名需要一致才能通信；

u_pa_tx.frame_len：广播包长度，最大可配置长度不超过160byte；

u_pa_tx.frame_interval：周期广播间隔，单位0.625ms，最小不低于5ms；

u_pa_tx.retry_num：重发次数，按照1.25ms重发一次配置重发次数，内部会做最大值限制，比如间隔配置为10ms(按照1.25ms换算只有8次重发)，用户配置10次也会被限制成8次；

u_pa_tx.flow_mode：默认配置为0，蓝牙按照配置的间隔定时取数进行广播；

u_pa_tx.user_cb.event_cb：蓝牙广播端（发送端）事件回调，注册该事件回调之后，蓝牙会根据相应状态推出对应的事件到回调，用户可根据事件信息做回调操作；

扫描端(接收端)参数如下：

u_pa_rx.adv_name：扫描端蓝牙名，广播端和扫描端的蓝牙名需要一致才能通信；

u_pa_rx.frame_len：广播包长度，最大可配置长度不超过160byte；

u_pa_rx.frame_interval：周期广播间隔，单位0.625ms，最小不低于5ms；

u_pa_rx.retry_num：重发次数，按照1.25ms重发一次配置重发次数，内部会做最大值限制，比如间隔配置为10ms(按照1.25ms换算只有8次重发)，用户配置10次也会被限制成8次；

u_pa_rx.flow_mode：默认配置为0，蓝牙按照配置的间隔定时接收数据传给应用层；

u_pa_rx.user_cb.event_cb：蓝牙扫描端（接收端）事件回调，注册该事件回调之后，蓝牙会根据相应状态推出对应的事件到回调，用户可根据事件信息做回调操作；

8.4. 接口说明

8.4.1. 函数void vble_adv_init(void)

备注

该函数实现初始化周期广播用到的蓝牙协议栈。

返回值：无

8.4.2. 函数void vble_padv_parm_init(void)

备注

该函数实现初始化周期广播tx（发送端）与rx（接收端）的参数给相关结构体，tx与rx的名字需要一致才能同步进行通信

返回值：无

8.4.3. 函数void vble_adv_tx_init(padvb_user_param_t *param)

备注

该函数实现初始化蓝牙广播tx功能，用户需要将初始化好的参数结构体指针传入该函数

param：用户配置的tx参数结构体。

返回值：无

8.4.4. 函数void vble_adv_tx_open(void)

备注

该函数实现开启蓝牙广播tx功能，开启后，蓝牙会推送对应事件到tx回调，并且按用户配置的间隔，定时调用vble_adv_tx_push_data广播数据

返回值：无

8.4.5. 函数void vble_adv_tx_close(void)

备注

该函数实现关闭蓝牙广播tx功能

8.4.6. 函数void vble_adv_tx_uninit(void)

备注

该函数实现注销蓝牙广播tx初始化。

返回值：无

8.4.7. 函数void vble_adv_tx_push_data(u8 *data, u16 len)

备注

该函数实现将用户数据推给蓝牙广播缓存，蓝牙会将用户数据进行广播。该函数需要在tx_callback的PADVB_EVENT_PUSH_DATA事件分支使用，并且一次PUSH_DATA事件只能调用一次该函数，否则会出现前一次的数据被覆盖的问题。

data：用户数据指针。

len：广播数据长度。一般与用户配置的广播包长度一致

8.4.8. 函数void vble_padv_radio_tx_callback(const PADVB_EVENT event)

备注

该函数作为用户注册给蓝牙广播tx的回调示例

event：蓝牙广播tx根据对应状态推出的事件

PADVB_EVENT_INIT：调用tx_init时，蓝牙会在该回调中推出该事件。

PADVB_EVENT_OPEN：调用tx_open时，蓝牙会在该回调中推出该事件。

PADVB_EVENT_CLOSE：调用tx_close时，蓝牙会在该回调中推出该事件。

PADVB_EVENT_UNINIT：调用tx_uninit时，蓝牙会在该回调中推出该事件。

PADVB_EVENT_PUSH_DATA：开启广播后。蓝牙会按照用户配置的间隔。定时推出该事件，用户需要将数据整理到一个缓存，调用一次vble_adv_tx_push_data广播数据。

注意！！！！！：

注1：周期广播应用中，蓝牙是按用户配置的间隔定时取数进行广播，两个间隔之间主要做重发，所以用户在发送数据是需要按照蓝牙的节奏进行发送，即在事件回调推出PADVB_EVENT_PUSH_DATA事件分支才可调用vble_adv_tx_push_data进行发送数据！

注2：由于蓝牙周期广播特性，用户在PADVB_EVENT_PUSH_DATA事件回调没有数据输出给蓝牙时，蓝牙会按照1.25ms间隔不断重发广播上一次用户填入的数据，因此用户在接收数据时需要做好过滤！

使用示例如图：

图1.1 周期广播tx事件回调示例

8.4.9. 函数void vble_adv_rx_init(padvb_user_param_t *param)

备注

该函数实现初始化蓝牙广播tx功能，用户需要将初始化好的参数结构体指针传入该函数

param：用户配置的rx参数结构体。

返回值：无

8.4.10. 函数void vble_adv_rx_open(void)

备注

该函数实现开启蓝牙广播tx功能，开启后，蓝牙会推送对应事件到tx回调，并且按用户配置的间隔，定时调用vble_adv_tx_push_data广播数据

返回值：无

8.4.11. 函数void vble_adv_rx_close(void)

备注

该函数实现关闭蓝牙广播tx功能

返回值：无

8.4.12. 函数void vble_adv_rx_uninit(void)

备注

该函数实现注销蓝牙广播tx初始化。

返回值：无

8.4.13. 函数void vble_adv_rx_close(void)

备注

该函数实现关闭蓝牙广播tx功能

返回值：无

8.4.14. 函数void vble_adv_rx_pop_data(u8 **data)

备注

该函数实现将蓝牙收到的数据传给应用层，收到的数据地址会更新到传入的data指针，当蓝牙没收到数据时，指针就为空。

data：用户数据二级指针，pop_data后用户可以直接从一级指针获取数据。

8.4.15. 函数void vble_padv_radio_rx_callback(const PADVB_EVENT event)

备注

该函数作为用户注册给蓝牙广播tx的回调示例

event：蓝牙广播tx根据对应状态推出的事件

PADVB_EVENT_INIT：调用rx_init时，蓝牙会在该回调中推出该事件。

PADVB_EVENT_OPEN：调用rx_open时，蓝牙会在该回调中推出该事件。

PADVB_EVENT_CLOSE：调用rx_close时，蓝牙会在该回调中推出该事件。

PADVB_EVENT_UNINIT：调用rx_uninit时，蓝牙会在该回调中推出该事件。

PADVB_EVENT_SYNC_SUCCESS：扫描端（接收端）与广播端（发送端）同步成功时，蓝牙会在该回调中推出该事件。

PADVB_EVENT_SYNC_LOST：扫描端（接收端）与广播端（发送端）同步失败(超时)，蓝牙会在该回调中推出该事件。

PADVB_EVENT_POP_DATA：SYNC_SUCCESS之后。蓝牙会按照用户配置的间隔。定时推出该事件，用户需要在此事件回调中将一个自定义指针的指针传入vble_adv_rx_pop_data函数，如果收到数据，数据的地址会更新到用户传入的指针，如果出现丢包，用户传入的指针会被修改为空指针。

返回值：无

图1.2 周期广播rx事件回调示例