中文 简体BLE开发指南
引言
移远通信FC41D、FCM100D、FCM740D和FLMx40D模块支持QuecOpen®方案；QuecOpen®是基于RTOS的嵌入式开发平台，可简化IoT应用的软件设计和开发过程。有关QuecOpen®的详细信息，请参考 快速入门指南。
本文档适用于SDK构建环境的QuecOpen®方案，主要介绍在QuecOpen®方案下，FC41D、FCM100D、FCM740D和FLMx40D模块的低功耗蓝牙（BLE）API和相关示例以及低功耗蓝牙配网的步骤和代码示例。
适用模块
适用模块：
| 模块系列 | 模块 |
|---|---|
| FC41D | |
| FCM100D | |
| FCM740D | |
| FLMx40D | FLM040D |
| FLM140D | |
| FLM240D | |
| FLM340D |
BLE API
头文件
BLE API的头文件为ql_ble.h和ble_api_5_x.h，分别位于SDK包的ql_components/qadpt/include/和ql_kernel/driver/include/下。若无特别说明，本文档所涉及头文件均在上述目录下。
函数概览
函数概览：
| 函数 | 说明 |
|---|---|
ql_ble_init() |
初始化BLE并使用默认BLE服务 |
ql_ble_create_db() |
初始化BLE并自定义BLE服务 |
ql_ble_set_notice_cb() |
注册BLE事件回调函数 |
ql_ble_set_tx_power() |
设置BLE发射功率 |
ql_ble_get_idle_actv_idx_handle() |
获取空闲的BLE活动序号 |
ql_ble_actv_state_get() |
获取指定BLE活动的状态 |
ql_ble_create_advertising() |
创建BLE广播 |
ql_ble_set_adv_data() |
设置广播数据 |
ql_ble_set_scan_rsp_data() |
设置扫描响应数据 |
ql_ble_start_advertising() |
开启BLE广播 |
ql_ble_adv_start() |
快速开启BLE广播 |
ql_ble_stop_advertising() |
停止BLE广播 |
ql_ble_delete_advertising() |
删除BLE广播 |
ql_ble_create_scaning() |
创建BLE扫描 |
ql_ble_start_scaning() |
开启BLE扫描 |
ql_ble_scan_start() |
快速开启BLE扫描 |
ql_ble_stop_scaning() |
停止BLE扫描 |
ql_ble_delete_scaning() |
删除BLE扫描 |
ql_ble_update_param() |
更新连接参数 |
ql_ble_gatts_disconnect() |
服务器主动断开与客户端的连接 |
ql_ble_gatt_mtu_changes() |
更改MTU大小 |
ql_ble_gatt_mtu_get() |
获取MTU大小 |
ql_ble_create_conn() |
创建连接 |
ql_ble_set_connect_dev_addr() |
设置待连接的BLE设备地址 |
ql_ble_gattc_register_discovery_callback() |
客户端注册发现服务器服务的回调函数 |
ql_ble_gattc_register_event_recv_callback() |
客户端注册事件接收回调函数 |
ql_ble_start_conn() |
发起连接 |
ql_ble_stop_conn() |
停止连接 |
ql_ble_gattc_disconnect() |
客户端主动断开与服务器的连接 |
ql_ble_gattc_read_service_data_by_handle_req() |
客户端通过服务句柄读取服务器数据 |
ql_ble_gattc_write_service_data_req() |
客户端通过服务句柄写数据至服务器 |
ql_ble_gatts_send_ntf_value() |
服务器通过通知方式发送数据至客户端 |
ql_ble_gatts_send_ind_value() |
服务器通过指示方式发送数据至客户端 |
ql_ble_address_get() |
获取BLE MAC地址 |
ql_ble_gattc_ntf_enable() |
启用指定特征句柄的通知 |
ql_ble_gattc_all_service_discovery() |
客户端发现服务器的所有服务 |
ql_ble_security_param_init() |
配置安全配对参数 |
ql_ble_security_req() |
发送安全连接请求 |
ql_ble_bond_delete_all() |
删除所有绑定的BLE设备信息 |
ql_ble_delete_specified_bound_device() |
删除指定的绑定的BLE设备 |
ql_ble_get_random_number() |
获取硬件随机值 |
ql_ble_get_idle_conn_idx_handle() |
获取空闲BLE连接的索引 |
ql_ble_get_bonded_devices() |
获取绑定的BLE设备信息 |
ql_ble_is_device_bonded() |
判断对端BLE设备是否为绑定过的设备 |
ql_ble_set_device_name() |
设置BLE设备名称 |
ql_ble_get_device_name() |
获取BLE设备名称 |
函数详解
ql_ble_init
该函数用于初始化BLE并使用默认BLE服务。
函数原型：
ql_errcode_bt_e ql_ble_init(void)
参数：
无
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_errcode_bt_e
函数执行结果码枚举定义如下：
typedef enum
{
QL_BT_SUCCESS = 0,
QL_BT_ERR_PROFILE,
QL_BT_ERR_CREATE_DB,
QL_BT_ERR_CMD_NOT_SUPPORT,
QL_BT_ERR_UNKNOW_IDX,
QL_BT_ERR_BLE_STATUS,
QL_BT_ERR_BLE_PARAM,
QL_BT_ERR_ADV_DATA,
QL_BT_ERR_CMD_RUN,
QL_BT_ERR_NO_MEM,
QL_BT_ERR_INIT_CREATE,
QL_BT_ERR_INIT_STATE,
QL_BT_ERR_ATTC_WRITE,
QL_BT_ERR_ATTC_WRITE_UNREGISTER,
} ql_errcode_bt_e
成员：
| 成员 | 描述 |
|---|---|
QL_BT_SUCCESS |
函数执行成功 |
QL_BT_ERR_PROFILE |
Profile错误 |
QL_BT_ERR_CREATE_DB |
添加BLE服务失败 |
QL_BT_ERR_CMD_NOT_SUPPORT |
不支持该命令 |
QL_BT_ERR_UNKNOW_IDX |
未知的BLE活动序号 |
QL_BT_ERR_BLE_STATUS |
状态错误 |
QL_BT_ERR_BLE_PARAM |
无效参数 |
QL_BT_ERR_ADV_DATA |
广播数据格式错误 |
QL_BT_ERR_CMD_RUN |
命令执行失败 |
QL_BT_ERR_NO_MEM |
内存不足 |
QL_BT_ERR_INIT_CREATE |
创建连接任务失败 |
QL_BT_ERR_INIT_STATE |
连接状态错误 |
QL_BT_ERR_ATTC_WRITE |
写数据错误 |
QL_BT_ERR_ATTC_WRITE_UNREGISTER |
写入数据的BLE服务未注册 |
ql_ble_create_db
该函数用于初始化BLE并自定义BLE服务。
函数原型：
ql_errcode_bt_e ql_ble_create_db(struct ql_ble_db_cfg* ble_db_cfg)
参数：
ble_db_cfg：
[In] BLE服务列表；详见ql_ble_db_cfg。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_db_cfg
BLE服务列表结构体定义如下：
struct ql_ble_db_cfg
{
uint16_t prf_task_id;
uint8_t uuid[16];
uint8_t att_db_nb;
uint16_t start_hdl;
ql_attm_desc_t* att_db;
uint8_t svc_perm;
}
成员：
| 类型 | 参数 | 描述 |
|---|---|---|
uint16_t |
prf_task_id |
BLE服务ID。 |
uint8_t |
uuid |
服务的UUID。 |
uint8_t |
att_db_nb |
属性数据库数量。 |
uint16_t |
start_hdl |
服务开始句柄。当参数值为0时，表示自动分配句柄。 |
ql_attm_desc_t* |
att_db |
属性数据库；详见ql_attm_desc_t。 |
uint8_t |
svc_perm |
服务配置。 |
ql_attm_desc_t
BLE属性数据库结构体定义如下：
typedef struct
{
uint8_t uuid[16];
uint16_t perm;
uint16_t ext_perm;
uint16_t max_size;
}ql_attm_desc_t
参数：
| 类型 | 参数 | 描述 |
|---|---|---|
uint8_t |
uuid |
16字节的UUID |
uint16_t |
perm |
权限设置 |
uint16_t |
ext_perm |
扩展权限设置 |
uint16_t |
max_size |
属性的最大字节数 |
ql_ble_set_notice_cb
该函数用于注册BLE事件回调函数。
函数原型：
ql_errcode_bt_e ql_ble_set_notice_cb(ble_notice_cb_t func)
参数：
func：
[In] BLE事件回调函数；详见ble_notice_cb_t。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ble_notice_cb_t
该函数为BLE事件回调函数。
函数原型：
typedef void (*ble_notice_cb_t)(ble_notice_t notice, void *param)
参数：
notice：
[In] BLE事件类型；详见ble_notice_t。
param：
[In] BLE事件参数。
ble_notice_t
BLE事件类型枚举定义如下：
typedef enum
{
BLE_5_STACK_OK,
BLE_5_WRITE_EVENT,
BLE_5_READ_EVENT,
BLE_5_REPORT_ADV,
BLE_5_MTU_CHANGE,
BLE_5_CONNECT_EVENT,
BLE_5_DISCONNECT_EVENT,
BLE_5_ATT_INFO_REQ,
BLE_5_CREATE_DB,
BLE_5_TX_DONE,
BLE_5_INIT_CONNECT_EVENT,
BLE_5_INIT_DISCONNECT_EVENT,
BLE_5_SDP_REGISTER_FAILED,
} ble_notice_t
成员：
| 参数 | 描述 |
|---|---|
BLE_5_STACK_OK |
BLE协议栈准备就绪 |
BLE_5_WRITE_EVENT |
服务器接收到客户端写数据事件 |
BLE_5_READ_EVENT |
服务器接收到客户端读数据事件 |
BLE_5_REPORT_ADV |
扫描结果返回事件 |
BLE_5_MTU_CHANGE |
MTU更改事件 |
BLE_5_CONNECT_EVENT |
连接事件 |
BLE_5_DISCONNECT_EVENT |
连接断开事件 |
BLE_5_ATT_INFO_REQ |
请求属性信息事件 |
BLE_5_CREATE_DB |
添加Profile完成事件 |
BLE_5_TX_DONE |
发送数据完成事件 |
BLE_5_INIT_CONNECT_EVENT |
客户端发起连接服务器活动事件 |
BLE_5_INIT_DISCONNECT_EVENT |
客户端与从服务器断开连接事件 |
BLE_5_SDP_REGISTER_FAILED |
SDP服务注册失败事件 |
ql_ble_set_tx_power
该函数用于设置BLE射频发射功率。
函数原型：
ql_errcode_bt_e ql_ble_set_tx_power(int8_t tx_power)
参数：
tx_power： [In] BLE发射功率。范围：-2~14；默认值：6；单位：dBm。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_get_idle_actv_idx_handle
该函数用于获取空闲的BLE活动序号。
函数原型：
uint8_t ql_ble_get_idle_actv_idx_handle(void)
参数：
无
返回值：
空闲BLE活动序号。
ql_ble_actv_state_get
该函数用于获取指定BLE活动的状态。
函数原型：
ql_actv_state_t ql_ble_actv_state_get(uint8_t actv_idx)
参数：
actv_idx：
[In] BLE活动序号。
返回值：
BLE活动状态；详见ql_actv_state_t。
ql_actv_state_t
BLE活动状态枚举定义如下：
typedef enum {
QL_ACTV_IDLE,
QL_ACTV_ADV_CREATED,
QL_ACTV_ADV_STARTED,
QL_ACTV_SCAN_CREATED,
QL_ACTV_SCAN_STARTED,
QL_ACTV_INIT_CREATED,
QL_ACTV_PER_SYNC_CREATED,
}ql_actv_state_t
成员：
| 成员 | 描述 |
|---|---|
QL_ACTV_IDLE |
空闲状态 |
QL_ACTV_ADV_CREATED |
广播创建完成 |
QL_ACTV_ADV_STARTED |
已开始广播 |
QL_ACTV_SCAN_CREATED |
扫描创建完成 |
QL_ACTV_SCAN_STARTED |
已开始扫描 |
QL_ACTV_INIT_CREATED |
连接创建完成 |
QL_ACTV_PER_SYNC_CREATED |
周期同步活动创建完成 |
ql_ble_create_advertising
该函数用于创建BLE广播。
函数原型：
ql_errcode_bt_e ql_ble_create_advertising(uint8_t actv_idx,unsigned char chnl_map,uint32_t intv_min,uint32_t intv_max,ble_cmd_cb_t callback)
参数：
actv_idx：[In] 通过
ql_ble_get_idle_actv_idx_handle()获取的空闲BLE活动序号。chnl_map：[In] 选择的广播通道。
137通道238通道337和38通道439通道537和39通道638和39通道737、38和39通道
intv_min：[In] 广播间隔最小值。范围：32~16384；单位：0.625毫秒。对应的时间范围：20毫秒~10.24秒。
intv_max：[In] 广播间隔最大值。范围：32~16384；单位：0.625毫秒。对应的时间范围：20毫秒~10.24秒。
callback：[In] 创建BLE活动命令的回调函数。该回调函数暂不支持，可设置为NULL。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
备注
当前该函数仅支持创建非定向可连接广播，无广播过滤，在1 Mbps PHY模式下广播。
ql_ble_set_adv_data
该函数用于设置广播数据。
函数原型：
ql_errcode_bt_e ql_ble_set_adv_data(uint8_t actv_idx, unsigned char* adv_buff, unsigned char adv_len, ble_cmd_cb_t callback)
参数：
actv_idx：[In] BLE活动序号，通常对应
ql_ble_create_advertising()创建的BLE活动。adv_buff：[In] 广播数据。需按照BLE广播数据规则写入。
adv_len：[In] 广播数据长度；单位：字节。
callback：[In] 设置广播数据命令的回调函数。该回调函数暂不支持，可设置为NULL。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_set_scan_rsp_data
该函数用于设置扫描响应数据。
函数原型：
ql_errcode_bt_e ql_ble_set_scan_rsp_data(uint8_t actv_idx, unsigned char* scan_buff, unsigned char scan_len, ble_cmd_cb_t callback)
参数：
actv_idx：[In] BLE活动序号，通常对应
ql_ble_create_advertising()创建的BLE活动。scan_buff：[In] 扫描响应数据。需按照BLE广播数据规则写入。
scan_len：[In] 扫描响应数据长度；单位：字节。
callback：[In] 设置扫描响应数据命令的回调函数。该回调函数暂不支持，可设置为NULL。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_start_advertising
该函数用于开启BLE广播。
函数原型：
ql_errcode_bt_e ql_ble_start_advertising(uint8_t actv_idx, uint16 duration, ble_cmd_cb_t callback)
参数：
actv_idx：[In] BLE活动序号，通常对应
ql_ble_create_advertising()创建的BLE活动。duration：[In] 广播持续时间；单位：10毫秒。
0表示不主动停止广播。callback：[In] 开始广播命令的回调函数。该回调函数暂不支持，可设置为NULL。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_adv_start
该函数用于快速开启BLE广播。
函数原型：
ql_errcode_bt_e ql_ble_adv_start(uint8_t actv_idx, struct adv_param *adv, ble_cmd_cb_t callback)
参数：
actv_idx：[In] 通过
ql_ble_get_idle_actv_idx_handle()获取的空闲BLE活动序号。adv：[In] 广播参数；详见adv_param。
callback：[In] 快速开启BLE广播命令的回调函数。该回调函数暂不支持，可设置为NULL。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
adv_param
广播参数结构体定义如下：
struct adv_param {
uint8_t advData[MAX_ADV_DATA_LEN];
uint8_t advDataLen;
uint8_t respData[MAX_ADV_DATA_LEN];
uint8_t respDataLen;
uint8_t channel_map;
uint16_t interval_min;
uint16_t interval_max;
uint16_t duration;
}
参数：
| 类型 | 参数 | 描述 |
|---|---|---|
| uint8_t | advData |
广播数据。最大31字节。 |
| uint8_t | advDataLen |
广播数据长度。单位：字节。 |
| uint8_t | respData |
扫描响应数据。最大31字节。 |
| uint8_t | respDataLen |
扫描响应数据长度。单位：字节。 |
| uint8_t | channel_map |
广播通道。 |
| uint16_t | interval_min |
广播间隔最小值。范围：32~16384；单位：0.625毫秒。对应的时间范围：20毫秒~10.24秒。 |
| uint16_t | interval_max |
广播间隔最大值。范围：32~16384；单位：0.625毫秒。对应的时间范围：20毫秒~10.24秒。 |
| uint16_t | duration |
广播持续时间；单位：10毫秒。0表示不主动停止广播。 |
ql_ble_stop_advertising
该函数用于停止BLE广播。
函数原型：
ql_errcode_bt_e ql_ble_stop_advertising(uint8_t actv_idx, ble_cmd_cb_t callback)
参数：
actv_idx：[In] BLE活动序号，通常对应
ql_ble_create_advertising()创建的BLE活动。callback：[In] 停止广播命令的回调函数。该回调函数暂不支持，可设置为NULL。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_delete_advertising
该函数用于删除BLE广播。
函数原型：
ql_errcode_bt_e ql_ble_delete_advertising(uint8_t actv_idx, ble_cmd_cb_t callback)
参数：
actv_idx：[In] BLE活动序号，通常对应
ql_ble_create_advertising()创建的BLE活动。callback：[In] 删除广播命令的回调函数。该回调函数暂不支持，可设置为NULL。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_create_scaning
该函数用于创建BLE扫描。
函数原型：
ql_errcode_bt_e ql_ble_create_scaning(uint8_t actv_idx, ble_cmd_cb_t callback)
参数：
actv_idx：[In] 通过
ql_ble_get_idle_actv_idx_handle()获取的空闲BLE活动序号。callback：[In] 创建BLE扫描命令的回调函数。该回调函数暂不支持，可设置为NULL。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_start_scaning
该函数用于开启BLE扫描。
函数原型：
ql_errcode_bt_e ql_ble_start_scaning(uint8_t actv_idx, uint16_t scan_intv, uint16_t scan_wd, ble_cmd_cb_t callback)
参数：
actv_idx：[In] BLE活动序号，通常对应
ql_ble_create_scaning()创建的BLE活动。scan_intv：[In] 扫描间隔。范围：18~4096；单位：0.625毫秒。对应的时间范围：11.25毫秒~2560毫秒。
scan_wd：[In] 扫描窗口。范围：17~4096；单位：0.625毫秒。对应的时间范围：10.625毫秒~2560毫秒。
callback：[In] 开启BLE扫描命令的回调函数。该回调函数暂不支持，可设置为NULL。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
备注
当前该函数开启的扫描在1 Mbps模式下工作，无重复广播包过滤，不主动停止。
ql_ble_scan_start
该函数用于快速开启BLE扫描。
函数原型：
ql_errcode_bt_e ql_ble_scan_start(uint8_t actv_idx, struct scan_param *scan, ble_cmd_cb_t callback)
参数：
actv_idx：[In] 通过
ql_ble_get_idle_actv_idx_handle()获取的空闲BLE活动序号。scan：[In] 扫描参数；详见scan_param。
callback：[In] 快速开启BLE扫描命令的回调函数。该回调函数暂不支持，可设置为NULL。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
scan_param
扫描参数结构体定义如下：
struct scan_param {
uint8_t filter_en;
uint8_t channel_map;
uint16_t interval;
uint16_t window;
}
参数：
| 类型 | 参数 | 描述 |
|---|---|---|
| uint8_t | filter_en |
选择扫描过滤方式；详见ql_scan_dup_filter_e。 |
| uint8_t | channel_map |
扫描通道。 |
| uint16_t | interval |
扫描间隔。范围：18~4096；单位：0.625毫秒。对应的时间范围：11.25毫秒~2560毫秒。 |
| uint16_t | window |
扫描窗口。范围：17~4096；单位：0.625毫秒。对应的时间范围：10.625毫秒~2560毫秒。 |
ql_scan_dup_filter_e
扫描过滤方式枚举定义如下：
typedef enum tag_scan_dup_filter_policy
{
QL_SCAN_FILT_DUPLIC_DIS = 0x00,
QL_SCAN_FILT_DUPLIC_EN,
QL_SCAN_FILT_DUPLIC_EN_PER_PERIOD,
}ql_scan_dup_filter_e
成员：
| 成员 | 描述 |
|---|---|
QL_SCAN_FILT_DUPLIC_DIS |
禁止扫描过滤 |
QL_SCAN_FILT_DUPLIC_EN |
使能扫描过滤 |
QL_SCAN_FILT_DUPLIC_EN_PER_PERIOD |
启用每个扫描周期的重复数据包过滤 |
ql_ble_stop_scaning
该函数用于停止BLE扫描。
函数原型：
ql_errcode_bt_e ql_ble_stop_scaning(uint8_t actv_idx, ble_cmd_cb_t callback)
参数：
actv_idx：[In] BLE活动序号，通常对应
ql_ble_create_scaning()创建的BLE活动。callback：[In] 停止扫描命令的回调函数。该回调函数暂不支持，可设置为NULL。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_delete_scaning
该函数用于删除BLE扫描。
函数原型：
ql_errcode_bt_e ql_ble_delete_scaning(uint8_t actv_idx, ble_cmd_cb_t callback)
参数：
actv_idx：[In] BLE活动序号，通常对应
ql_ble_create_scaning()创建的BLE活动。callback：[In] 删除扫描命令的回调函数。该回调函数暂不支持，可设置为NULL。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_update_param
该函数用于更新连接参数。
函数原型：
ql_errcode_bt_e ql_ble_update_param(uint8_t conn_idx, uint16_t intv_min, uint16_t intv_max,uint16_t latency, uint16_t sup_to, ble_cmd_cb_t callback)
参数：
conn_idx：[In] 连接索引。
intv_min：[In] 连接间隔最小值。范围：6~3200；单位：1.25毫秒。对应的时间范围：7.5毫秒~4秒。
intv_max：[In] 连接间隔最大值。范围：6~3200；单位：1.25毫秒。对应的时间范围：7.5毫秒~4秒。
latency：[In] 服务器可忽略的连接间隔的数目。需满足：(1 +
latency)*intv_max*2*1.25 <sup_to*10。sup_to：[In] 连接超时时间。范围：10~3200；单位：10毫秒。对应的时间范围：100毫秒~32秒。
callback：[In] 更新连接参数命令的回调函数。该回调函数暂不支持，可设置为NULL。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_gatts_disconnect
该函数用于服务器主动断开与客户端的连接。
函数原型：
ql_errcode_bt_e ql_ble_gatts_disconnect(uint8_t conn_idx, ble_cmd_cb_t callback)
参数：
conn_idx：[In] 连接索引。
callback：[In] 服务器主动断开与客户端连接命令的回调函数。该回调函数暂不支持，可设置为NULL。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_gatt_mtu_changes
该函数用于更改MTU大小。
函数原型：
ql_errcode_bt_e ql_ble_gatt_mtu_changes(uint8_t conn_idx,uint16_t mtu_size,ble_cmd_cb_t callback)
参数：
conn_idx：[In] 连接索引。
mtu_size：[In] 更新的MTU大小；单位：字节。
callback：[In] 更改MTU大小命令的回调函数。该回调函数暂不支持，可设置为NULL。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_gatt_mtu_get
该函数用于获取MTU大小。
函数原型：
uint16_t ql_ble_gatt_mtu_get(uint8_t conn_idx)
参数：
conn_idx：
[In] 连接索引。
返回值：
MTU的字节数。
ql_ble_create_conn
该函数用于创建连接。
函数原型：
ql_errcode_bt_e ql_ble_create_conn(uint8_t actv_idx,unsigned short con_interval,unsigned short con_latency,unsigned short sup_to,ble_cmd_cb_t callback)
参数：
actv_idx：[In] 通过
ql_ble_get_idle_actv_idx_handle()获取的空闲BLE活动序号。con_interval：[In] 连接间隔。单位：1.25毫秒。
con_latency：[In] 服务器可忽略的连接间隔的数目。需满足：(1 +
con_latency)*max_interval*2*1.25 <sup_to*10。sup_to：[In] 连接超时时间。单位：10毫秒。
callback：[In] 创建连接命令的回调函数。该回调函数暂不支持，可设置为NULL。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_set_connect_dev_addr
该函数用于设置待连接的BLE设备地址。
函数原型：
ql_errcode_bt_e ql_ble_set_connect_dev_addr(unsigned char actv_idx,struct ql_bd_addr *bdaddr,unsigned char addr_type)
参数：
actv_idx：[In] BLE活动序号，通常对应
ql_ble_create_conn()创建的BLE活动。bdaddr：[In] 连接的对端设备的MAC地址。详见ql_bd_addr。
addr_type：[In] 对端设备地址类型。
0公共地址1随机地址
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_bd_addr
MAC地址结构体定义如下：
struct ql_bd_addr
{
uint8_t addr[BD_ADDR_LEN];
}
参数：
| 类型 | 参数 | 描述 |
|---|---|---|
| uint8_t | addr |
目标BLE设备的MAC地址，长度为6字节。 |
ql_ble_gattc_register_discovery_callback
该函数用于客户端注册发现服务器服务的回调函数。
函数原型：
ql_errcode_bt_e ql_ble_gattc_register_discovery_callback(app_sdp_callback cb)
参数：
cb：
[In] 发现服务器服务的回调函数；详见app_sdp_callback。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
app_sdp_callback
该函数为用于发现服务器服务的回调函数，用于上报服务发现结果。
函数原型：
typedef void (*app_sdp_callback)(unsigned char conidx,uint16_t chars_val_hdl,unsigned char uuid_len,unsigned char *uuid)
参数：
conidx：[Out] 连接索引。
chars_val_hdl：[Out] 服务句柄。
uuid_len：[Out] UUID长度；单位：字节。
uuid：[Out] UUID值。
备注
服务器服务的句柄和UUID会依次通过该回调函数返回，用户可存储使用。
ql_ble_gattc_register_event_recv_callback
该函数用于客户端注册事件接收回调函数。
函数原型：
ql_errcode_bt_e ql_ble_gattc_register_data_recv_callback(app_sdp_charac_callback cb)
参数：
cb：
[In] 事件接收回调函数；详见app_sdp_charac_callback。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
app_sdp_charac_callback
该函数为事件接收回调函数，用于客户端接收服务端所上报的事件。
函数原型：
typedef void (*app_sdp_charac_callback)(CHAR_TYPE type, uint8 conidx,uint16_t hdl, uint16_t len, uint8 *data)
参数：
type：[Out] 事件类型；详见CHAR_TYPE。
conidx：[Out] 连接索引。
hdl：[Out] 服务句柄。
len：[Out] 数据长度；单位：字节。
data：[Out] 数据。
CHAR_TYPE
事件类型枚举定义如下：
typedef enum{
CHARAC_NOTIFY,
CHARAC_INDICATE,
CHARAC_READ,
CHARAC_READ_DONE,
CHARAC_WRITE_DONE,
}CHAR_TYPE
成员：
| 成员 | 描述 |
|---|---|
CHARAC_NOTIFY |
接收到服务器通过通知方式发送的数据 |
CHARAC_INDICATE |
接收到服务器通过指示方式发送的数据 |
CHARAC_READ |
读数据事件 |
CHARAC_READ_DONE |
读数据完成事件 |
CHARAC_WRITE_DONE |
写数据完成事件 |
备注
此枚举定义位于
ql_kernel/driver/ble_5_x_rw/ble_pub/app/api/app_sdp.h路径中。
ql_ble_start_conn
该函数用于发起连接。
函数原型：
ql_errcode_bt_e ql_ble_start_conn(uint8_t actv_idx,ble_cmd_cb_t callback)
参数：
actv_idx：[In] BLE活动序号，通常对应
ql_ble_create_conn()创建的BLE活动。callback：[In] 发起连接命令的回调函数。该回调函数暂不支持，可设置为NULL。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_stop_conn
该函数用于停止连接。
函数原型：
ql_errcode_bt_e ql_ble_stop_conn(uint8_t actv_idx,ble_cmd_cb_t callback)
参数：
actv_idx：[In] BLE活动序号，通常对应
ql_ble_create_conn()创建的BLE活动。callback：[In] 停止连接命令的回调函数。该回调函数暂不支持，可设置为NULL。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_gattc_disconnect
该函数用于客户端主动断开与服务器的连接。
函数原型：
ql_errcode_bt_e ql_ble_gattc_disconnect(uint8_t conn_idx, uint8_t reason)
参数：
conn_idx：[In] 连接索引。
reason：[In] 连接断开的原因。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_gattc_read_service_data_by_handle_req
该函数用于客户端通过服务句柄读取服务器数据。
函数原型：
ql_errcode_bt_e ql_ble_gattc_read_service_data_by_handle_req(uint8_t conidx,uint16_t handle,ble_cmd_cb_t callback)
参数：
conidx：[In] 连接索引。
handle：[In] 指定服务句柄。
callback：[In] 通过服务句柄读取数据命令的回调函数。该回调函数暂不支持，可设置为NULL。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_gattc_write_service_data_req
该函数用于客户端通过服务句柄写数据至服务器。
函数原型：
ql_errcode_bt_e ql_ble_write_service_data_req(uint8_t conidx,uint16_t handle,uint16_t data_len,uint8_t *data,ble_cmd_cb_t callback)
参数：
conidx：[In] 连接索引。
handle：[In] 指定服务的句柄。
data_len：[In] 数据长度；单位：字节。
data：[In] 数据。
callback：[In] 通过服务句柄写数据命令的回调函数。该回调函数暂不支持，可设置为NULL。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_gatts_send_ntf_value
该函数用于服务器通过通知方式发送数据至客户端。
函数原型：
ql_errcode_bt_e ql_ble_gatts_send_ntf_value(uint32_t len, uint8_t *buf, uint16_t prf_id,uint16_t att_idx)
参数：
len：[In] 数据长度；单位：字节。
buf：[In] 数据。
prf_id：[In] 服务ID号。
att_idx：[In] 一般为添加服务时通过具有notification特征值属性权限的对应特征值序号。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_gatts_send_ind_value
该函数用于服务器通过指示方式发送数据至客户端。
函数原型：
ql_errcode_bt_e ql_ble_gatts_send_ind_value(uint32_t len, uint8_t *buf, uint16_t prf_id, uint16_t att_idx)
参数：
len：[In] 数据长度；单位：字节。
buf：[In] 数据。
prf_id：[In] 服务ID号。
att_idx：[In] 一般为添加服务时通过具有indication特征值属性权限的对应特征值序号。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_address_get
该函数用于获取BLE MAC地址。
函数原型：
ql_errcode_bt_e ql_ble_address_get(uint8_t *mac_addr)
参数：
mac_addr：
[Out] BLE MAC地址。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_gattc_ntf_enable
该函数用于启用指定特征句柄的通知。
函数原型：
ql_errcode_bt_e ql_ble_gattc_ntf_enable(uint8_t conidx,uint16_t handle,bool ntf)
参数：
conidx：[In] 连接索引。
handle：[In] 服务表中的特征值句柄。
ntf：[In] 启用或禁用指定特征句柄的通知。
0禁用1启用
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_gattc_all_service_discovery
该函数用于客户端发现服务器的所有服务。
函数原型：
ql_errcode_bt_e ql_ble_gattc_all_service_discovery(uint8_t conidx)
参数：
conidx：
[In] 连接索引。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_security_param_init
该函数用于配置安全配对参数。
函数原型：
ql_errcode_bt_e ql_ble_security_param_init(ql_ble_security_param_t *param)
参数：
param：
[In] 安全配对参数；详见ql_ble_security_param_t。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_security_param_t
安全配对参数的结构体定义如下：
typedef struct
{
bool ble_secure_conn;
ql_ble_io_cap_e io_cap;
bool bond_auth;
uint32_t password;
}ql_ble_security_param_t
参数：
| 类型 | 参数 | 描述 |
|---|---|---|
| bool | ble_secure_conn |
启用或禁用安全连接模式。0 禁用1 启用 |
ql_ble_io_cap_e |
io_cap |
设备输入/输出能力；详见ql_ble_io_cap_e。 |
| bool | bond_auth |
启用或禁用绑定设备时的身份验证。 |
| uint32_t | password |
配对密码；范围：000000~999999。 |
ql_ble_io_cap_e
设备输入/输出能力枚举定义如下：
typedef enum
{
QL_BLE_IO_CAP_DISPLAY_ONLY = 0x00,
QL_BLE_IO_CAP_DISPLAY_YES_NO = 0x01,
QL_BLE_IO_CAP_KEYBOARD_ONLY = 0x02,
QL_BLE_IO_CAP_NO_INPUT_NO_OUTPUT = 0x03,
QL_BLE_IO_CAP_KEYBOARD_DISPLAY = 0x04,
}ql_ble_io_cap_e
成员：
| 成员 | 描述 |
|---|---|
QL_BLE_IO_CAP_DISPLAY_ONLY |
仅显示000000~999999范围内的数字。 |
QL_BLE_IO_CAP_DISPLAY_YES_NO |
显示Yes/No按钮。 |
QL_BLE_IO_CAP_KEYBOARD_ONLY |
仅能输入000000~999999范围内的数字。 |
QL_BLE_IO_CAP_NO_INPUT_NO_OUTPUT |
无输入无显示。 |
QL_BLE_IO_CAP_KEYBOARD_DISPLAY |
可输入000000~999999范围内的数字，并显示该范围内的数字。 |
ql_ble_security_req
该函数用于发送安全连接请求。
函数原型：
ql_errcode_bt_e ql_ble_security_req(uint8_t conidx)
参数：
conidx：
[In] 连接索引。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_bond_delete_all
该函数用于删除所有绑定的BLE设备信息。
函数原型：
ql_errcode_bt_e ql_ble_bond_delete_all(void)
参数：
无
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_delete_specified_bound_device
该函数用于删除指定的绑定的BLE设备。
函数原型：
ql_errcode_bt_e ql_ble_delete_specified_bound_device(uint8_t idx)
参数：
idx：
[In] 绑定设备的索引。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_get_random_number
该函数用于获取硬件随机值。
函数原型：
int ql_ble_get_random_number(void)
参数：
无
返回值：
硬件随机值。
ql_ble_get_idle_conn_idx_handle
该函数用于获取空闲BLE连接的索引。
函数原型：
uint8_t ql_ble_get_idle_conn_idx_handle(void)
参数：
无
返回值：
空闲BLE连接的索引。
ql_ble_get_bonded_devices
该函数用于获取绑定的BLE设备信息。
函数原型：
ql_errcode_bt_e ql_ble_get_bonded_devices(uint8_t *bonded_total, ql_ble_bonded_device *bonded_device)
参数：
bonded_total：[Out] 绑定设备的总数。
bonded_device：[Out] 绑定设备信息；详见ql_ble_bonded_device。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_bonded_device
绑定设备信息的结构定义如下：
typedef struct
{
uint8_t idx;
uint8_t peer_addr_type;
uint8_t peer_addr[6];
}ql_ble_bonded_device
参数：
| 类型 | 参数 | 描述 |
|---|---|---|
| uint8_t | idx |
绑定设备的索引。 |
| uint8_t | peer_addr_type |
对端设备BLE地址类型。0 公共地址1 随机地址 |
| uint8_t | peer_addr |
对端设备BLE地址。 |
ql_ble_is_device_bonded
该函数用于判断对端BLE设备是否为绑定过的设备。
函数原型：
ql_errcode_bt_e ql_ble_is_device_bonded(uint8_t peer_addr_type, uint8_t *peer_addr)
参数：
peer_addr_type：[In] 对端设备BLE地址类型。
0公共地址1随机地址
peer_addr：[In] 对端设备BLE地址。
返回值：
函数执行结果码；详见ql_errcode_bt_e。
ql_ble_set_device_name
该函数用于设置BLE设备名称。
函数原型：
uint8_t ql_ble_set_device_name(uint8_t* name , uint8_t len)
参数：
name：[In] 设备名称。
len：[In] 设备名称的长度；单位：字节。
返回值：
设备名称的实际长度。
ql_ble_get_device_name
该函数用于获取BLE设备名称。
函数原型：
uint8_t ql_ble_get_device_name(uint8_t* name, uint32_t buf_len)
参数：
name：[Out] 设备名称。
buf_len：[In] 设备名称的长度；单位：字节。
返回值：
设备名称的实际长度。
示例
本章节主要介绍如何在应用中使用上述BLE API以及进行简单的BLE数据收发的调试。用户只需在ql_application/quectel_demo/quectel_demo_config.h中使能CFG_ENABLE_QUECTEL_BLE_PERIPHERA或CFG_ENABLE_QUECTEL_BLE_CENTRAL即可运行BLE
demo程序。
BLE API的示例代码文件为ql_ble_demo.c，位于ql_application/quectel_demo目录下，用户可自行查看完整示例。
BLE GATT服务器
演示步骤
步骤一：调用如下函数注册BLE事件回调函数。
ql_errcode_bt_e ql_ble_set_notice_cb(ble_notice_cb_t func)
步骤二：调用如下函数添加BLE服务。
ql_errcode_bt_e ql_ble_create_db (struct ql_ble_db_cfg* ble_db_cfg)
步骤三：调用如下函数获取空闲的BLE活动序号。
uint8_t ql_ble_get_idle_actv_idx_handle(void)
步骤四：调用如下函数获取BLE活动状态。
ql_actv_state_t app_ble_actv_state_get(uint8_t actv_idx)
步骤五：调用如下函数开启BLE广播。
ql_errcode_bt_e ql_ble_adv_start(uint8_t actv_idx, struct adv_param *adv, ble_cmd_cb_t callback)
步骤六：服务器与客户端连接后，服务器接收到客户端发送的数据可调用如下函数将数据回传至客户
端。
ql_ble_gatts_send_ntf_value(w_req->len , w_req->value, w_req->prf_id , QL_DEMO_IDX_FF03_VAL_VALUE)
代码示例
定义BLE服务：
BLE事件回调函数示例：
设置BLE事件回调函数并初始化BLE：
设置广播参数、广播数据并开启广播：
服务器接收数据并回传数据至客户端：
结果如下：
BLE GATT客户端
演示步骤
步骤一：调用如下函数注册BLE事件回调函数。
ql_errcode_bt_e ql_ble_set_notice_cb(ble_notice_cb_t func)
步骤二：调用如下函数初始化BLE。
ql_errcode_bt_e ql_ble_init(void)
步骤三：调用如下函数获取空闲的BLE活动序号。
uint8_t ql_ble_get_idle_actv_idx_handle(void)
步骤四：调用如下函数获取BLE活动状态。
ql_actv_state_t app_ble_actv_state_get(uint8_t actv_idx)
步骤五：调用如下函数开启BLE扫描。
ql_errcode_bt_e ql_ble_scan_start(uint8_t actv_idx, struct scan_param *scan, ble_cmd_cb_t callback)
步骤六：调用如下函数停止BLE扫描。
ql_errcode_bt_e ql_ble_stop_scaning(uint8_t actv_idx, ble_cmd_cb_t callback)
步骤七：调用如下函数创建连接活动。
ql_errcode_bt_e ql_ble_create_conn(uint8_t con_idx,unsigned short con_interval,unsigned short con_latency,unsigned short sup_to,ble_cmd_cb_t callback)
步骤八：调用如下函数开始连接。
ql_errcode_bt_e ql_ble_start_conn(uint8_t con_idx,ble_cmd_cb_t callback)
代码示例
设置BLE事件回调函数并初始化BLE：
设置扫描参数并开启扫描：
在回调函数返回的BLE_5_REPORT_ADV事件中可获取扫描结果，即周围设备的广播信息。使用app_demo_ble_adv_report_deal()解析出目标BLE设备（广播名为"test"的设备）的地址及地址类型，扫描到该目标设备后即停止广播：
创建连接活动并进行连接：
服务器接收数据并回传数据至客户端：
结果如下：
附录 参考文档及术语缩写
参考文档：
| 文档名称 |
|---|
| Quectel_FC41D&FCM100D&FCM740D&FLMx40D_QuecOpen(SDK)_快速开发指导 |
术语缩写：
| 缩写 | 英文全称 | 中文全称 |
|---|---|---|
| AP | Access Point | 接入点 |
| API | Application Programming Interface | 应用程序接口 |
| BLE | Bluetooth Low Energy | 蓝牙低功耗 |
| GATT | Generic Attribute Profile | 通用属性协议 |
| ID | Identifier | 标识符 |
| IoT | Internet of Things | 物联网 |
| MAC | Medium Access Control | 媒体访问控制 |
| MTU | Maximum Transmission Unit | 最大传输单元 |
| RTOS | Real Time Operating System | 实时操作系统 |
| SDK | Software Development Kit | 软件开发工具包 |
| SDP | Service Discovery Protocol | 服务发现协议 |
| USB | Universal Serial Bus | 通用串行总线 |
| UUID | Universally Unique Identifier | 通用唯一识别码 |