HCM111Z QuecOpen(SDK) BLE开发指导

2025-12-16

Edit this page

引言

移远通信HCM111Z模块支持QuecOpen®方案；QuecOpen®是一种嵌入式开发平台，可简化IoT应用的软件设计和开发过程。

本文档适用于SDK构建环境的QuecOpen®方案，主要介绍在QuecOpen®方案下，HCM111Z模块的低功耗蓝牙（BLE）API和相关示例。

低功耗蓝牙API

头文件

低功耗蓝牙API的头文件为ql_ble.h，位于SDK包的components/quectel_api/ql_include目录下。若无特别说明，本文档所涉及头文件均在该目录下。

函数概览

函数	说明
`ql_ble_create_db()`	初始化BLE并自定义BLE服务
`ql_ble_set_notice_cb()`	注册BLE事件回调函数
`ql_ble_set_dev_name()`	设置本地名称
`ql_ble_address_get()`	获取BLE的MAC地址
`ql_ble_set_adv_param()`	设置广播参数
`ql_ble_set_adv_data()`	设置广播数据
`ql_ble_set_scan_rsp_data()`	设置扫描响应数据
`ql_ble_start_advertising()`	开启BLE广播
`ql_ble_stop_advertising()`	停止BLE广播
`ql_ble_start_scaning()`	开启BLE扫描
`ql_ble_stop_scaning()`	停止BLE扫描
`ql_ble_update_param()`	更新连接参数
`ql_ble_set_connect_dev_addr()`	设置待连接的BLE设备地址
`ql_ble_start_conn()`	发起连接
`ql_ble_disconnect()`	主动断开连接
`ql_ble_get_connect_num()`	获取已连接的链路数量
`ql_ble_link_rssi_report()`	使能/禁止获取连接链路RSSI
`ql_ble_gatt_init()`	初始化GATT参数
`ql_ble_gatt_mtu_changes()`	更新MTU值
`ql_ble_gattc_all_service_discovery()`	中心设备发现外围设备的所有服务
`ql_ble_gattc_ntf_ind_enable()`	中心设备使能外围设备的通知或指示
`ql_ble_gattc_write_data_req()`	中心设备向外围设备以请求的方式写数据
`ql_ble_gattc_write_data_with_handle()`	中心设备向外围设备指定的特征值句柄以请求的方式写数据
`ql_ble_gattc_write_data_cmd()`	中心设向外围设备以命令的方式写数据
`ql_ble_gatts_send_ntf_value()`	外围设备通过通知的方式发送数据至中心设备
`ql_ble_gatts_send_ind_value()`	外围设备通过指示方式发送数据至中心设备
`ql_ble_security_param_init()`	设置安全特性参数
`ql_ble_bond_num_max()`	设置最大绑定设备数量
`ql_ble_bond_delete_all()`	删除所有已绑定设备的信息
`ql_ble_get_bond_status()`	获取当前连入设备的绑定状态
`ql_ble_pairing_req()`	发送配对请求
`ql_ble_security_req()`	发送安全连接请求
`ql_ble_enc_req()`	发送加密请求

函数详解

ql_ble_create_db

该函数用于初始化BLE并自定义BLE服务。

函数原型

ql_errcode_bt_e ql_ble_create_db(ql_ble_gatt_service_t *service, uint8_t *svc_id)

参数

service：
[In] BLE服务列表；详见 ql_ble_gatt_service_t。

svc_id：
[Out] BLE服务ID。

返回值

结果码；详见 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_gatt_service_t

BLE服务列表结构体定义如下：

typedef struct {
  const ql_ble_gatt_attribute_t *p_att_tb;
  uint8_t att_nb;
  ql_ble_gatt_msg_handler_t gatt_msg_handler;
} ql_ble_gatt_service_t

参数

类型	参数	描述
ql_ble_gatt_attribute_t	`p_att_tb`	BLE服务属性列表；详见 ql_ble_gatt_attribute_t。
uint8_t	`att_nb`	属性列表数量。
ql_ble_gatt_msg_handler_t	`gatt_msg_handler`	回调函数；详见 ql_ble_gatt_msg_handler_t。

ql_ble_gatt_attribute_t

BLE服务属性列表结构体定义如下：

typedef struct {
  ql_ble_gatt_uuid_t uuid;
  uint16_t prop;
  uint16_t max_size;
  uint8_t *p_data;
} ql_ble_gatt_attribute_t

参数

类型	参数	描述
ql_ble_gatt_uuid_t	`uuid`	UUID；详见 ql_ble_gatt_uuid_t。
uint16_t	`prop`	权限设置
uint16_t	`max_size`	属性的最大字节数
uint8_t	`*p_data`	属性数据指针

ql_ble_gatt_uuid_t

UUID结构体定义如下：

typedef struct {
  uint8_t size;
  uint8_t p_uuid[16];
} ql_ble_gatt_uuid_t

参数

类型	参数	描述
uint8_t	`size`	UUID长度，可为2字节或16字节。
uint8_t	`p_uuid`	UUID值；2字节或16字节的数组。

ql_ble_gatt_msg_handler_t

该函数为BLE服务回调函数。

函数原型

typedef uint16_t (*ql_ble_gatt_msg_handler_t)(void *p_msg)

参数

p_msg：
[In] BLE GATT消息。详见 ql_ble_gatt_msg_t。

ql_ble_gatt_msg_t

BLE GATT消息结构体定义如下：

typedef struct {
  ql_ble_gatt_msg_evt_t msg_evt;
  uint8_t conn_idx;
  uint8_t svc_id;
  uint16_t att_idx;
  uint16_t handle;
  union {
    ql_ble_gatt_msg_hdl_t msg;
    ql_ble_gatt_op_cmp_t op;
  } param;
} ql_ble_gatt_msg_t

参数

类型	参数	描述
ql_ble_gatt_msg_evt_t	`msg_evt`	BLE GATT消息事件；详见 ql_ble_gatt_msg_evt_t。
uint8_t	`conn_idx`	连接索引。
uint8_t	`svc_id`	BLE服务ID。
uint16_t	`att_idx`	服务表中的属性索引。
uint16_t	`handle`	外围设备服务中的属性句柄编号。
ql_ble_gatt_msg_hdl_t	`msg`	GATT消息的长度和数据指针；详见 ql_ble_gatt_msg_hdl_t。
ql_ble_gatt_op_cmp_t	`op`	GATT操作类型，包括读取、写入、通知和指示；详见 ql_ble_gatt_op_cmp_t。

ql_ble_gatt_msg_evt_t

BLE GATT消息事件枚举定义如下：

typedef enum {
  QL_BLE_GATTC_MSG_READ_REQ,
  QL_BLE_GATTC_MSG_WRITE_REQ,
  QL_BLE_GATTC_MSG_ATT_INFO_REQ,
  QL_BLE_GATTC_MSG_NTF_REQ,
  QL_BLE_GATTC_MSG_IND_REQ,
  QL_BLE_GATTC_MSG_READ_IND,
  QL_BLE_GATTC_MSG_CMP_EVT,
  QL_BLE_GATTC_MSG_LINK_CREATE,
  QL_BLE_GATTC_MSG_LINK_LOST,
  QL_BLE_GATTC_MSG_SVC_REPORT,
  QL_BLE_GATTC_MSG_HANDLE_ERROR = 0x80,
} ql_ble_gatt_msg_evt_t

成员

成员	描述
`QL_BLE_GATTC_MSG_READ_REQ`	读数据请求
`QL_BLE_GATTC_MSG_WRITE_REQ`	写数据请求
`QL_BLE_GATTC_MSG_ATT_INFO_REQ`	属性信息请求
`QL_BLE_GATTC_MSG_NTF_REQ`	收到来自GATT客户端的通知数据
`QL_BLE_GATTC_MSG_IND_REQ`	收到来自GATT客户端的指示数据
`QL_BLE_GATTC_MSG_READ_IND`	读数据请求应答
`QL_BLE_GATTC_MSG_CMP_EVT`	消息完成事件
`QL_BLE_GATTC_MSG_LINK_CREATE`	建立链接
`QL_BLE_GATTC_MSG_LINK_LOST`	链接丢失
`QL_BLE_GATTC_MSG_SVC_REPORT`	接收到外围设备BLE服务信息的报告
`QL_BLE_GATTC_MSG_HANDLE_ERROR`	应用程序无法正确处理消息

ql_ble_gatt_msg_hdl_t

BLE GATT消息结构体定义如下：

typedef struct {
  uint16_t msg_len;
  uint8_t *p_msg_data;
} ql_ble_gatt_msg_hdl_t

参数

类型	参数	描述
uint16_t	`msg_len`	消息长度
uint8_t	`*p_msg_data`	消息数据

ql_ble_gatt_op_cmp_t

GATT操作类型结构体定义如下：

typedef struct {
  uint8_t operation;
  uint8_t status;
  void * arg;
} ql_ble_gatt_op_cmp_t

参数

类型	参数	描述
uint8_t	`operation`	操作类型
uint8_t	`status`	操作状态
void	`* arg`	参数指针

ql_ble_set_notice_cb

该函数用于注册BLE事件回调函数。

函数原型

ql_errcode_bt_e ql_ble_set_notice_cb(ql_ble_notice_cb callback)

参数

callback：
[In] BLE事件回调函数；详见 ble_notice_cb_t。

返回值

结果码；详见 ql_errcode_bt_e。

ble_notice_cb_t

该函数为BLE事件回调函数。

函数原型

typedef void (*ql_ble_notice_cb)(ql_ble_notify_e notice, void *param)

参数

notice：
[In] BLE事件类型；详见 ble_notice_t。

param：
[In] BLE事件参数。

ble_notice_t

BLE事件枚举定义如下：

typedef enum {
  QL_BLE_STACK_OK = 0,
  QL_BLE_REPORT_ADV_EVENT,
  QL_BLE_MTU_CHANGE_EVENT,
  QL_BLE_CONNECT_EVENT,
  QL_BLE_DISCONNECT_EVENT,
  QL_BLE_INIT_CONNECT_EVENT,
  QL_BLE_ADV_STOP_EVENT,
  QL_BLE_SCAN_STOP_EVENT,
  QL_BLE_CONN_PARAM_UPDATE_EVENT,
  QL_BLE_LINK_RSSI_EVENT,
  QL_BLE_SEC_MASTER_AUTH_REQ,
  QL_BLE_SEC_MASTER_ENCRYPT,
  QL_BLE_SEC_SLAVE_ENCRYPT,
} ql_ble_notify_e

成员

成员	描述
`QL_BLE_STACK_OK`	BLE协议栈准备就绪
`QL_BLE_REPORT_ADV_EVENT`	扫描结果返回事件
`QL_BLE_MTU_CHANGE_EVENT`	MTU更改事件
`QL_BLE_CONNECT_EVENT`	模块作为外围设备与中心设备建立连接事件
`QL_BLE_DISCONNECT_EVENT`	连接断开事件
`QL_BLE_INIT_CONNECT_EVENT`	模块作为中心设备与外围设备建立连接事件
`QL_BLE_ADV_STOP_EVENT`	广播停止事件
`QL_BLE_SCAN_STOP_EVENT`	扫描停止事件
`QL_BLE_CONN_PARAM_UPDATE_EVENT`	连接参数更新事件
`QL_BLE_LINK_RSSI_EVENT`	获取连接链路的RSSI值
`QL_BLE_SEC_MASTER_AUTH_REQ`	中心设备从外围设备获得身份验证请求
`QL_BLE_SEC_MASTER_ENCRYPT`	中心设备链路加密
`QL_BLE_SEC_SLAVE_ENCRYPT`	外围设备链路加密

ql_ble_set_dev_name

该函数用于设置本地名称。

函数原型

ql_errcode_bt_e ql_ble_set_dev_name(uint8_t *name, uint8_t name_len)

参数

name：
[In] 设备名。

name_len：
[In] 设备名长度；最大值：26字节。

返回值

结果码；详见 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_set_adv_param

该函数用于设置广播参数。

函数原型

ql_errcode_bt_e ql_ble_set_adv_param(ql_ble_adv_param_t *adv_param)

参数

adv_param：
[In] 广播参数。详见 ql_ble_adv_param_t。

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_adv_param_t

广播参数结构体定义如下：

typedef struct {
  ql_ble_adv_mode_e mode;
  ql_ble_addr_type_e addr_type;
  ql_ble_adv_mac_addr_t peer_addr;
  ql_ble_phy_e phy;
  uint16_t adv_intv_min;
  uint16_t adv_intv_max;
  ql_ble_adv_channel_e channel;
  ql_ble_adv_filter_e filter;
  uint8_t adv_sid;
  uint16_t per_adv_intv_min;
  uint16_t per_adv_intv_max;
  ql_ble_adv_disc_mode_e disc_mode;
} ql_ble_adv_param_t

参数

类型	参数	描述
ql_ble_adv_mode_e	`mode`	广播模式；详见 ql_ble_adv_mode_e。
ql_ble_addr_type_e	`addr_type`	广播地址类型；详见 ql_ble_addr_type_e。
ql_ble_adv_mac_addr_t	`peer_addr`	外围设备地址；详见 ql_ble_adv_mac_addr_t。
ql_ble_phy_e	`phy`	广播的物理层类型；详见 ql_ble_phy_e。
uint16_t	`adv_intv_min`	广播间隔最小值；范围：32~16384；单位：0.625毫秒。对应的时间范围：20毫秒~10.24秒。
uint16_t	`adv_intv_max`	广播间隔最大值；范围：32~16384；单位：0.625毫秒。对应的时间范围：20毫秒~10.24秒。
ql_ble_adv_channel_e	`channel`	广播通道；详见 ql_ble_adv_channel_e。
ql_ble_adv_filter_e	`filter`	广播过滤类型；详见 ql_ble_adv_filter_e。
uint8_t	`adv_sid`	广播索引，仅适用于扩展广播和周期广播；范围：0~0xF。
uint16_t	`per_adv_intv_min`	外围设备广播间隔最小值。范围：32~16384；单位：0.625毫秒。对应的时间范围：20毫秒~10.24秒。
uint16_t	`per_adv_intv_max`	外围设备广播间隔最大值。范围：32~16384；单位：0.625毫秒。对应的时间范围：20毫秒~10.24秒。
ql_ble_adv_disc_mode_e	`disc_mode`	广播可发现类型；详见 ql_ble_adv_disc_mode_e。

ql_ble_adv_mode_e

广播模式枚举定义如下：

typedef enum {
  QL_BLE_ADV_MODE_UNDIRECT = 0x01,
  QL_BLE_ADV_MODE_DIRECT = 0x02,
  QL_BLE_ADV_MODE_NON_CONN_NON_SCAN = 0x03,
  QL_BLE_ADV_MODE_NON_CONN_SCAN = 0x04,
  QL_BLE_ADV_MODE_HDC_DIRECT = 0x05,
  QL_BLE_ADV_MODE_BEACON = 0x06,
  QL_BLE_ADV_MODE_CUSTOM = 0x07,
  QL_BLE_ADV_MODE_EXTEND_CONN_UNDIRECT = 0x11,
  QL_BLE_ADV_MODE_EXTEND_CONN_DIRECT = 0x12,
  QL_BLE_ADV_MODE_EXTEND_NON_CONN_SCAN = 0x13,
  QL_BLE_ADV_MODE_EXTEND_NON_CONN_SCAN_DIRECT = 0x14,
  QL_BLE_ADV_MODE_EXTEND_NON_CONN_NON_SCAN = 0x15,
  QL_BLE_ADV_MODE_EXTEND_NON_CONN_NON_SCAN_DIRECT = 0x16,
  QL_BLE_ADV_MODE_PER_ADV_UNDIRECT = 0x21,
  QL_BLE_ADV_MODE_PER_ADV_DIRECT = 0x22,
} ql_ble_adv_mode_e

成员

成员	描述
`QL_BLE_ADV_MODE_UNDIRECT`	可连接可扫描广播
`QL_BLE_ADV_MODE_DIRECT`	直接广播
`QL_BLE_ADV_MODE_NON_CONN_NON_SCAN`	不可连接不可扫描广播
`QL_BLE_ADV_MODE_NON_CONN_SCAN`	不可连接可扫描广播
`QL_BLE_ADV_MODE_HDC_DIRECT`	可连接不可扫描广播
`QL_BLE_ADV_MODE_BEACON`	Beacon广播
`QL_BLE_ADV_MODE_CUSTOM`	自定义类型
`QL_BLE_ADV_MODE_EXTEND_CONN_UNDIRECT`	扩展广播模式，可连接可扫描广播
`QL_BLE_ADV_MODE_EXTEND_CONN_DIRECT`	扩展广播模式，直接广播
`QL_BLE_ADV_MODE_EXTEND_NON_CONN_SCAN`	扩展广播模式，不可连接可扫描广播
`QL_BLE_ADV_MODE_EXTEND_NON_CONN_SCAN_DIRECT`	扩展广播模式，不可连接可扫描的直接广播
`QL_BLE_ADV_MODE_EXTEND_NON_CONN_NON_SCAN`	扩展广播模式，不可连接不可扫描广播
`QL_BLE_ADV_MODE_EXTEND_NON_CONN_NON_SCAN_DIRECT`	扩展广播模式，不可连接不可扫描广播的直接广播
`QL_BLE_ADV_MODE_PER_ADV_UNDIRECT`	同步广播模式，非直接广播
`QL_BLE_ADV_MODE_PER_ADV_DIRECT`	同步广播模式，直接广播

ql_ble_addr_type_e

广播地址类型枚举定义如下：

typedef enum {
  QL_BLE_ADDR_TYPE_PUBLIC = 0,
  QL_BLE_ADDR_TYPE_PRIVATE,
  QL_BLE_ADDR_TYPE_RANDOM_RESOVABLE,
  QL_BLE_ADDR_TYPE_RANDOM_NONE_RESOVABLE,
} ql_ble_addr_type_e

成员

成员	描述
`QL_BLE_ADDR_TYPE_PUBLIC`	公共地址
`QL_BLE_ADDR_TYPE_PRIVATE`	私有地址
`QL_BLE_ADDR_TYPE_RANDOM_RESOVABLE`	可解析的随机地址
`QL_BLE_ADDR_TYPE_RANDOM_NONE_RESOVABLE`	不可解析的随机地址

ql_ble_adv_mac_addr_t

外围设备地址类型结构体定义如下：

typedef struct {
  uint8_t addr[6];
  uint8_t addr_type;
} ql_ble_adv_mac_addr_t

参数

类型	参数	描述
uint8_t	`addr`	地址。6字节的数组。
uint8_t	`addr_type`	地址类型。0=public/1=private random。

ql_ble_phy_e

广播物理层类型枚举定义如下：

typedef enum {
  QL_BLE_PHY_ANY = 0,
  QL_BLE_PHY_1MBPS = 1,
  QL_BLE_PHY_2MBPS = 2,
  QL_BLE_PHY_CODED = 3,
} ql_ble_phy_e

成员

成员	描述
`QL_BLE_PHY_ANY`	没有首选的类型
`QL_BLE_PHY_1MBPS`	1 Mbps
`QL_BLE_PHY_2MBPS`	2 Mbps
`QL_BLE_PHY_CODED`	CODED类型

ql_ble_adv_channel_e

广播通道枚举定义如下：

typedef enum {
  QL_BLE_ADV_CHAN_37 = 0x01,
  QL_BLE_ADV_CHAN_38 = 0x02,
  QL_BLE_ADV_CHAN_39 = 0x04,
  QL_BLE_ADV_CHAN_ALL = 0X07,
} ql_ble_adv_channel_e

成员

成员	描述
`QL_BLE_ADV_CHAN_37`	广播通道37
`QL_BLE_ADV_CHAN_38`	广播通道38
`QL_BLE_ADV_CHAN_39`	广播通道39
`QL_BLE_ADV_CHAN_ALL`	所有通道

ql_ble_adv_filter_e

广播过滤类型枚举定义如下：

typedef enum {
  QL_BLE_ADV_ALLOW_SCAN_ANY_CON_ANY = 0x00,
  QL_BLE_ADV_ALLOW_SCAN_WLST_CON_ANY = 0x01,
  QL_BLE_ADV_ALLOW_SCAN_ANY_CON_WLST = 0x02,
  QL_BLE_ADV_ALLOW_SCAN_WLST_CON_WLST = 0x03,
} ql_ble_adv_filter_e

成员

成员	描述
`QL_BLE_ADV_ALLOW_SCAN_ANY_CON_ANY`	任意设备可扫描可连接
`QL_BLE_ADV_ALLOW_SCAN_WLST_CON_ANY`	任意设备可连接，只允许白名单中设备扫描
`QL_BLE_ADV_ALLOW_SCAN_ANY_CON_WLST`	任意设备可扫描，只允许白名单中设备连接
`QL_BLE_ADV_ALLOW_SCAN_WLST_CON_WLST`	只允许白名单中的设备扫描和连接

ql_ble_adv_disc_mode_e

广播可发现类型枚举定义如下：

typedef enum {
  QL_BLE_ADV_DISC_MODE_GEN_DISC = 0,
  QL_BLE_ADV_DISC_MODE_LIM_DISC = 1,
  QL_BLE_ADV_DISC_MODE_NON_DISC = 2,
  QL_BLE_ADV_DISC_MODE_MAX = 3,
} ql_ble_adv_disc_mode_e

成员

成员	描述
`QL_BLE_ADV_DISC_MODE_GEN_DISC`	通用可发现模式
`QL_BLE_ADV_DISC_MODE_LIM_DISC`	限制可发现模式
`QL_BLE_ADV_DISC_MODE_NON_DISC`	不可发现模式
`QL_BLE_ADV_DISC_MODE_MAX`	可发现模式最大值

ql_ble_set_adv_data

该函数用于设置广播数据。

函数原型

ql_errcode_bt_e ql_ble_set_adv_data(uint8_t *adv_buff, uint16_t adv_len)

参数

adv_buff：
[In] 广播数据，需按照BLE广播数据规则写入。

adv_len：
[In] 广播数据长度；单位：字节。

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_set_scan_rsp_data

该函数用于设置扫描响应数据。

函数原型

ql_errcode_bt_e ql_ble_set_scan_rsp_data(uint8_t *scan_rsp, uint16_t scan_rsp_len)

参数

scan_rsp：
[In] 扫描响应数据。需按照BLE广播数据规则写入。

scan_rsp_len：
[In] 扫描响应数据长度；单位：字节。

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_start_advertising

该函数用于开启BLE广播。

函数原型

ql_errcode_bt_e ql_ble_start_advertising(uint16_t duration)

参数

duration：
[In] 广播持续时间；单位：10毫秒。0表示不主动停止广播。

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_stop_advertising

该函数用于停止BLE广播。

函数原型

ql_errcode_bt_e ql_ble_stop_advertising(void)

参数

无

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_start_scaning

该函数用于开启BLE扫描。

函数原型

ql_errcode_bt_e ql_ble_start_scaning(uint16_t scan_intv, uint16_t scan_wd, uint8_t dup_filt, ql_ble_phy_e phy)

参数

scan_intv：
[In] 扫描间隔。范围：18~4096；单位：0.625毫秒。对应的时间范围：11.25毫秒~2560毫秒。

scan_wd：
[In] 扫描窗口。范围：17~4096；单位：0.625毫秒。对应的时间范围：10.625毫秒~2560毫秒。

dup_filt：
[In] 是否开启重复广播包过滤。1：关闭，2：开启。

phy：
[In] 广播物理层类型。详见 ql_ble_phy_e。

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_stop_scaning

该函数用于停止BLE扫描。

函数原型

ql_errcode_bt_e ql_ble_stop_scaning(void)

参数

无

返回值

结果码；详见 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)

参数

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秒。

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_set_connect_dev_addr

该函数用于设置待连接的BLE设备地址。

函数原型

ql_errcode_bt_e ql_ble_set_connect_dev_addr(ql_ble_adv_mac_addr_t *addr)

参数

addr：
[In] 连接的外围设备的MAC地址。详见 ql_ble_adv_mac_addr_t。

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_start_conn

该函数用于发起连接。

函数原型

ql_errcode_bt_e ql_ble_start_conn(uint16_t intv_min, uint16_t intv_max, uint16_t latency, uint16_t sup_to)

参数

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秒。

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_disconnect

该函数用于主动断开连接。

函数原型

ql_errcode_bt_e ql_ble_disconnect(uint8_t conidx)

参数

conidx：
[In] 连接索引。

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_get_connect_num

该函数用于获取已连接的链路数量。

函数原型

int ql_ble_get_connect_num(void)

参数

无

返回值

链路数量。

ql_ble_link_rssi_report

该函数用于使能/禁止获取连接链路的RSSI。

函数原型

ql_errcode_bt_e ql_ble_link_rssi_report(bool enable)

参数

enable：
[In] 使能/禁止获取连接链路的RSSI。使能后获取到的RSSI将通过QL_BLE_LINK_RSSI_EVENT事件通知应用层。

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_gatt_init

该函数用于初始化GATT参数。

函数原型

ql_errcode_bt_e ql_ble_gatt_init(ql_gatt_client_t *p_client)

参数

p_client：
[In] GATT参数。详见 ql_gatt_client_t。

返回值

结果码；详见 ql_errcode_bt_e。

ql_gatt_client_t

GATT参数结构体定义如下：

typedef struct {
  const ql_ble_gatt_uuid_t *p_att_tb;
  uint8_t att_nb;
  uint8_t att_tb_initialized;
  ql_ble_gatt_msg_handler_t gatt_msg_handler;
} ql_gatt_client_t

参数

类型	参数	描述
ql_ble_gatt_uuid_t	`p_att_tb`	UUID。详见 ql_ble_gatt_uuid_t。
uint8_t	`att_nb`	属性值数量。
uint8_t	`att_tb_initialized`	属性初始化标志
ql_ble_gatt_msg_handler_t	`gatt_msg_handler`	回调函数。详见 ql_ble_gatt_msg_handler_t。

ql_ble_gatt_mtu_changes

该函数用于更新MTU值。

函数原型

ql_errcode_bt_e ql_ble_gatt_mtu_changes(uint8_t conn_idx, uint16_t mtu_size)

参数

conn_idx：
[In] 连接索引。

mtu_size：
[In] MTU值。最大值：247。

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_gattc_all_service_discovery

该函数用于模块作为中心设备发现外围设备的所有服务，发现结果由QL_BLE_GATTC_MSG_ATT_INFO_REQ事件返回。

函数原型

ql_errcode_bt_e ql_ble_gattc_all_service_discovery(uint8_t conidx)

参数

conidx：
[In] 连接索引。

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_gattc_ntf_ind_enable

该函数用于模块作为中心设备使能外围设备的通知或指示。

函数原型

ql_errcode_bt_e ql_ble_gattc_ntf_ind_enable(uint8_t conidx, uint8_t att_idx, bool ntf, bool ind)

参数

conidx：
[In] 连接索引。

att_idx：
[In] 服务列表中的属性索引。

ntf：
[In] 是否使能通知。

ind：
[In] 是否使能指示。

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_gattc_write_data_req

该函数用于模块作为中心设备向外围设备以请求的方式写数据。

函数原型

ql_errcode_bt_e ql_ble_gattc_write_data_req(uint8_t conidx, uint8_t att_idx, uint8_t *data, uint16_t data_len)

参数

conidx：
[In] 连接索引。

att_idx：
[In] 服务列表中的属性索引。

data：
[In] 数据。

data_len：
[In] 数据长度；单位：字节。

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_gattc_write_data_req_with_handle

该函数用于模块作为中心设备向外围设备指定的特征值句柄以请求的方式写数据。

函数原型

ql_errcode_bt_e ql_ble_gattc_write_data_req_with_handle(uint8_t conidx, uint16_t handle, uint8_t *data, uint16_t data_len)

参数

conidx：
[In] 连接索引。

handle：
[In] 外围设备服务句柄。

data：
[In] 数据。

data_len：
[In] 数据长度；单位：字节。

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_gattc_write_data_cmd

该函数用于模块作为中心设向外围设备以命令的方式写数据。

函数原型

ql_errcode_bt_e ql_ble_gattc_write_data_cmd(uint8_t conidx, uint8_t att_idx, uint8_t *data, uint16_t data_len)

参数

conidx：
[In] 连接索引。

att_idx：
[In] 服务列表中的属性索引。

data：
[In] 数据。

data_len：
[In] 数据长度；单位：字节。

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_gattc_write_data_with_handle

该函数用于模块作为中心设备向外围设备指定句柄以命令的方式写数据。

函数原型

ql_errcode_bt_e ql_ble_gattc_write_data_with_handle(uint8_t conidx, uint16_t handle, uint8_t *data, uint16_t data_len)

参数

conidx：
[In] 连接索引。

handle：
[In] 外围设备服务句柄。

data：
[In] 数据。

data_len：
[In] 数据长度；单位：字节。

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_gatts_send_ntf_value

该函数用于模块作为外围设备通过通知的方式发送数据至中心设备。

函数原型

ql_errcode_bt_e ql_ble_gatts_send_ntf_value(uint8_t con_idx, uint8_t svc_id, uint8_t att_idx, uint8_t *data, uint16_t len)

参数

con_idx：
[In] 连接索引。

svc_id：
[In] BLE服务ID。

att_idx：
[In] 服务列表中的属性索引。

data：
[In] 数据。

len：
[In] 数据长度；单位：字节。

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_gatts_send_ind_value

该函数用于模块作为外围设备通过指示方式发送数据至中心设备。

函数原型

ql_errcode_bt_e ql_ble_gatts_send_ind_value(uint8_t con_idx, uint8_t svc_id, uint8_t att_idx, uint8_t *data, uint16_t len)

参数

con_idx：
[In] 连接索引。

svc_id：
[In] BLE服务ID。

att_idx：
[In] 服务列表中的属性索引。

data：
[In] 数据。

len：
[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 mitm;
  bool ble_secure_conn;
  ql_ble_io_cap_e io_cap;
  ql_ble_pair_mode_e pair_init_mode;
  bool bond_auth;
  uint32_t password;
} ql_ble_security_param_t

参数

类型	参数	描述
bool	`mitm`	启用/禁用防中间人攻击模式。
bool	`ble_secure_conn`	启用/禁用安全连接模式。
ql_ble_io_cap_e	`io_cap`	输入输出能力类型；详见 ql_ble_io_cap_e。
ql_ble_pair_mode_e	`pair_init_mode`	配对模式类型；详见 ql_ble_pair_mode_e。
bool	`bond_auth`	启用/禁用绑定认证。
uint32_t	`password`	配对密码；范围0~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`	只有显示能力。
`QL_BLE_IO_CAP_DISPLAY_YES_NO`	可以显示"是/否"的选项，并且可以选择"是/否"。
`QL_BLE_IO_CAP_KEYBOARD_ONLY`	仅有键盘输入能力。
`QL_BLE_IO_CAP_NO_INPUT_NO_OUTPUT`	无键盘输入能力和显示能力，Justwork模式。
`QL_BLE_IO_CAP_KEYBOARD_DISPLAY`	有键盘输入能力和显示能力。

ql_ble_pair_mode_e

配对模式类型枚举定义如下：

typedef enum {
  QL_BLE_PAIRING_MODE_NO_PAIRING = 0x00,
  QL_BLE_PAIRING_MODE_WAIT_FOR_REQ = 0x01,
  QL_BLE_PAIRING_MODE_INITIATE = 0x02,
} ql_ble_pair_mode_e

成员

成员	描述
`QL_BLE_PAIRING_MODE_NO_PAIRING`	不允许配对
`QL_BLE_PAIRING_MODE_WAIT_FOR_REQ`	等待配对请求
`QL_BLE_PAIRING_MODE_INITIATE`	发起配对请求

ql_ble_bond_num_max

该函数用于设置最大绑定设备数量。

函数原型

ql_errcode_bt_e ql_ble_bond_num_max(uint8_t max_dev_num)

参数

max_dev_num：
[In] 最大绑定数量。范围0~20。

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_bond_delete_all

该函数用于删除所有已绑定设备的信息。

函数原型

ql_errcode_bt_e ql_ble_bond_delete_all(void)

参数

无

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_get_bond_status

该函数用于获取当前连入设备的绑定状态。

函数原型

bool ql_ble_get_bond_status(void)

参数

无

返回值

绑定状态。
False 未绑定
True 已绑定

ql_ble_pairing_req

该函数用于发送配对请求。

函数原型

ql_errcode_bt_e ql_ble_pairing_req(uint8_t conidx)

参数

conidx：
[In] 连接索引。

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_security_req

该函数用于发送安全连接请求。

函数原型

ql_errcode_bt_e ql_ble_security_req(uint8_t conidx)

参数

conidx：
[In] 连接索引。

返回值

结果码；详见 ql_errcode_bt_e。

ql_ble_enc_req

该函数用于发送加密请求。

函数原型

ql_errcode_bt_e ql_ble_enc_req(uint8_t conidx)

参数

conidx：
[In] 连接索引。

返回值

结果码；详见 ql_errcode_bt_e。

示例

本章节主要介绍如何在应用程序中使用上述BLE API以及进行简单的BLE数据收发的调试。

BLE API的工程示例如下，用户可自行查看完整示例。

BLE外设功能的工程示例位于quectel_demo/ql_ble_peripheral_demo路径下。
BLE中心设备功能的工程示例位于quectel_demo/ql_ble_central_demo路径下。
BLE HID设备功能的工程示例位于quectel_demo/ql_ble_hid_demo路径下。
BLE多连接设备功能的工程示例位于quectel_demo/ql_ble_multi_demo路径下。

BLE外设功能

初始化BLE外围设备，代码示例如下。

void simple_peripheral_init(void)
{
    // 设置本地蓝牙名称
    uint8_t local_name[] = "Simple Peripheral";
    ql_ble_set_dev_name(local_name, sizeof(local_name));

    #if 0 //是否需要安全连接
    ql_ble_security_param_t param = {
        .mitm = false,
        .ble_secure_conn = false,
        .io_cap = QL_BLE_IO_CAP_NO_INPUT_NO_OUTPUT,
        .pair_init_mode = QL_BLE_PAIRING_MODE_WAIT_FOR_REQ,
        .bond_auth = true,
        .password = 0,
    };
    ql_ble_security_param_init(&param);
    ql_ble_bond_num_max(8);
    #endif

    ql_ble_set_notice_cb(ql_ble_demo_notice);

    //获取蓝牙MAC地址
    uint8_t mac_addr[6] = {0};
    ql_ble_address_get(mac_addr);
    ql_debug("Local BDADDR: 0x%2X%2X%2X%2X%2X%2X\\r\\n", 
             mac_addr[0], mac_addr[1], mac_addr[2], 
             mac_addr[3], mac_addr[4], mac_addr[5]);

    // 添加蓝牙服务
    sp_gatt_add_service();
}

添加BLE服务，代码示例如下

void sp_gatt_add_service(void)
{
    //simple_profile_att_table为蓝牙服务的定义表，用户可自行调整
    simple_profile_svc.p_att_tb = simple_profile_att_table;
    simple_profile_svc.att_nb = SP_IDX_NB;

    //sp_gatt_msg_handler为此服务的数据通信回调函数
    simple_profile_svc.gatt_msg_handler = (void *)sp_gatt_msg_handler;

    //添加此服务
    ql_ble_create_db(&simple_profile_svc, &sp_svc_id);
}

BLE服务添加完成后，生成QL_BLE_STACK_OK事件，之后再设置广播参数并开启广播，代码示例如下。

case QL_BLE_STACK_OK:
{
    sp_start_adv();
} break;

设置广播参数和广播数据之后开启广播，代码示例如下。

static void sp_start_adv(void)
{
    //设置广播参数
    ql_ble_adv_param_t param;
    param.mode = QL_BLE_ADV_MODE_UNDIRECT;
    param.addr_type = QL_BLE_ADDR_TYPE_PUBLIC;
    param.channel = QL_BLE_ADV_CHAN_ALL;
    param.filter = QL_BLE_ADV_ALLOW_SCAN_ANY_CON_ANY;
    param.adv_intv_min = 400;
    param.adv_intv_max = 400;
    ql_ble_set_adv_param(&param);

    // 设置广播数据及广播应答数据
    ql_ble_set_adv_data(adv_data, sizeof(adv_data));
    ql_ble_set_scan_rsp_data(scan_rsp_data, sizeof(scan_rsp_data));

    // 开始广播
    ql_debug("Start advertising...\\r\\n");
    ql_ble_start_advertising(0);
}

打开nRF_connect，开启扫描，结果如下。

扫描结果

中心设备发送数据给外围设备，外围设备收到数据后返回数据至中心设备，如下图所示。

数据收发测试

数据接收及回发的代码示例如下：

else if (p_msg->att_idx == SP_IDX_CHAR2_VALUE)
{
    //接收数据打印
    ql_debug("char2_recv:");
    ql_debug_hex(p_msg->param.msg.p_msg_data, p_msg->param.msg.msg_len);

    //发送"HCM111Z send"给中心设备
    ql_ble_gatts_send_ntf_value(p_msg->conn_idx, sp_svc_id, SP_IDX_CHAR1_VALUE, 
                               (uint8_t *)"HLM111Z send", strlen("HLM111Z send"));
}

BLE中心设备功能

本示例中，需使用*BLE外设功能*中的外围设备作为测试设备。

初始化BLE GATT客户端，代码示例如下。

void simple_central_init(void)
{
    //设置本地名称
    uint8_t local_name[] = "Simple Central";
    ql_ble_set_dev_name(local_name, sizeof(local_name));

    //设置事件回调
    ql_ble_set_notice_cb(ql_ble_demo_notice);

    //获取设备MAC地址
    uint8_t mac_addr[6] = {0};
    ql_ble_address_get(mac_addr);
    ql_debug("Local BDADDR: 0x%2X%2X%2X%2X%2X%2X\\r\\n", 
             mac_addr[0], mac_addr[1], mac_addr[2], 
             mac_addr[3], mac_addr[4], mac_addr[5]);

    #if 0
    ql_ble_security_param_t param = {
        .mitm = false, // dont use PIN code during bonding
        .ble_secure_conn = false, //not enable security encryption
        .io_cap = QL_BLE_IO_CAP_NO_INPUT_NO_OUTPUT, //ble device has neither output nor input ability,
        .pair_init_mode = QL_BLE_PAIRING_MODE_WAIT_FOR_REQ, //need bond
        .bond_auth = true, //need bond auth
        .password = 0,
    };
    ql_ble_security_param_init(&param);
    //enable bond manage module, which will record bond key and peer service info into flash.
    ql_ble_bond_num_max(8);
    #endif

    //初始化GATT客户端参数
    ql_gatt_client_t client;
    #if 1
    client.p_att_tb = client_att_tb;
    client.att_nb = 2;
    #else
    client.p_att_tb = NULL;
    client.att_nb = 0;
    #endif
    client.gatt_msg_handler = (void *)simple_central_msg_handler;
    ql_ble_gatt_init(&client);
}

初始化BLE GATT客户端后，生成QL_BLE_STACK_OK事件，之后设置扫描参数并开启蓝牙扫描，代码示例如下。

case QL_BLE_STACK_OK:
{
    ql_debug("[ql]QL_BLE_STACK_OK\\r\\n");
    simple_central_start_scan();
} break;

设置扫描参数并开启扫描，代码示例如下。

static void simple_central_start_scan(void)
{
    // Start Scanning
    ql_ble_start_scaning(32, 20, 0, QL_BLE_PHY_1MBPS);
}

开启扫描后生成QL_BLE_REPORT_ADV_EVENT事件，通过该事件选出将要连接的设备。

case QL_BLE_REPORT_ADV_EVENT:
{
    ql_ble_recv_adv_t *adv_report = (ql_ble_recv_adv_t *)param;

    //打印出完整的广播数据
    ql_debug("adv_type:%02x, rssi:%d, addr_type:%d\\r\\n", 
             adv_report->adv_type, adv_report->rssi, adv_report->adv_addr_type);
    ql_debug("content:");
    ql_debug_hex(adv_report->data, adv_report->data_len);

    char scan_name[] = "Simple_Peripheral";

    //过滤出广播名为"Simple_Peripheral"的设备
    if (strstr((char *)adv_report->data, scan_name) != NULL)
    {
        //停止扫描
        ql_ble_stop_scaning();
        ql_debug("content:");
        ql_debug_hex(adv_report->data, adv_report->data_len);

        //从扫描结果中记录MAC地址信息
        ql_ble_adv_mac_addr_t addr;
        memcpy(addr.addr, adv_report->adv_addr, 6);
        addr.addr_type = adv_report->adv_addr_type;

        //设置连接参数并发起连接
        ql_ble_set_connect_dev_addr(&addr);
        ql_ble_start_conn(12, 12, 0, 300);
    }
} break;

设备连接后生成QL_BLE_INIT_CONNECT_EVENT事件，之后发起发现外围设备服务的操作。

case QL_BLE_INIT_CONNECT_EVENT:
{
    ql_ble_conn_ind_t *conn_ind = (ql_ble_conn_ind_t *)param;

    //发现外围设备服务
    ql_ble_gattc_all_service_discovery(conn_ind->conn_idx);
} break;

发现外围设备服务完成后，生成QL_BLE_GATTC_MSG_CMP_EVT事件，操作项为GATT_OP_PEER_SVC_DISC_END。

case QL_BLE_GATTC_MSG_CMP_EVT:
{
    ql_debug("[ql]GATT Operation : %d\\r\\n", p_msg->param.op.operation);

    if(p_msg->param.op.operation == GATT_OP_PEER_SVC_DISC_END)
    {
        //服务发现完成
        ql_debug("peer svc discovery done\\r\\n");
        #if 0
        ql_ble_gattc_add_uuid(p_msg->conn_idx, client_att_tb, 2, handles)
        #endif
    }
    else if(p_msg->param.op.operation == GATT_OP_PEER_SVC_REGISTERED)
    {
        uint16_t att_handles[2];
        memcpy(att_handles, p_msg->param.op.arg, 4);
        ql_debug_hex((uint8_t *)att_handles, 4);

        #if 0
        handles[0] = att_handles[0];
        handles[1] = att_handles[1];
        #endif

        //对外围设备进行通知使能
        ql_debug("ql_ble_gattc_ntf_ind_enable\\r\\n");
        ql_ble_gattc_ntf_ind_enable(p_msg->conn_idx, 0, 1, 0);

        //写数据到外围设备
        ql_debug("ql_ble_gattc_write_data_cmd\\r\\n");
        uint8_t send_data[10] = {0x09,0x08,0x07,0x06,0x05,0x04,0x03,0x02,0x01,0x00};
        ql_ble_gattc_write_data_cmd(p_msg->conn_idx, 1, send_data, 10);
    }
} break;

写数据到外围设备成功后，外围设备将发送"HCM111Z send"数据到中心设备，之后生成QL_BLE_GATTC_MSG_NTF_REQ事件。

case QL_BLE_GATTC_MSG_NTF_REQ: //receive notification data from peer device
{
    ql_debug_hex(p_msg->param.msg.p_msg_data, p_msg->param.msg.msg_len); //printf received ntf data
}
break;

BLE HID设备功能

BLE HID设备指带有HID服务的外围设备，由于集成HID服务，BLE HID设备可与手机自动回连。本示例还添加了设备信息服务、电量服务及OTA升级服务。

初始化BLE HID设备，代码示例如下。

void hid_device_init(void)
{
    // 设置本地设备名称
    uint8_t local_name[] = "BLE HID KBD MICE";
    ql_ble_set_dev_name(local_name, sizeof(local_name));

    //设置安全特性参数
    ql_ble_security_param_t param = {
        .mitm = true,
        .ble_secure_conn = false,
        .io_cap = QL_BLE_IO_CAP_NO_INPUT_NO_OUTPUT,
        .pair_init_mode = QL_BLE_PAIRING_MODE_WAIT_FOR_REQ,
        .bond_auth = true,
        .password = 123456,
    };
    ql_ble_security_param_init(&param);

    //设置保存配对信息设备数最大为8个
    ql_ble_bond_num_max(8);

    //设置事件回调
    ql_ble_set_notice_cb(ql_ble_demo_notice);

    //获取蓝牙MAC地址
    uint8_t mac_addr[6] = {0};
    ql_ble_address_get(mac_addr);
    ql_debug("Local BDADDR: 0x%2X%2X%2X%2X%2X%2X\\r\\n", 
             mac_addr[0], mac_addr[1], mac_addr[2], 
             mac_addr[3], mac_addr[4], mac_addr[5]);

    //添加设备信息服务
    dis_gatt_add_service();

    //添加电量服务
    batt_gatt_add_service();

    //添加HID服务
    hid_gatt_add_service();

    //添加OTA服务
    ota_gatt_add_service();
}

BLE HID设备初始化完成后生成QL_BLE_STACK_OK事件，之后设置广播参数并开启蓝牙广播，代码示例如下。

case QL_BLE_STACK_OK:
{
    hid_start_adv();
} break;

设置广播参数并开启广播，代码示例如下。

void hid_start_adv(void)
{
    // 设置广播参数
    ql_ble_adv_param_t param;
    param.mode = QL_BLE_ADV_MODE_UNDIRECT;
    param.addr_type = QL_BLE_ADDR_TYPE_PUBLIC;
    param.channel = QL_BLE_ADV_CHAN_ALL;
    param.filter = QL_BLE_ADV_ALLOW_SCAN_ANY_CON_ANY;
    param.adv_intv_min = 80;
    param.adv_intv_max = 80;
    ql_ble_set_adv_param(&param);

    // 设置广播数据和扫描应答数据
    ql_ble_set_adv_data(adv_data, sizeof(adv_data));
    ql_ble_set_scan_rsp_data(scan_rsp_data, sizeof(scan_rsp_data));

    //开启广播
    ql_ble_start_advertising(0);
}

打开手机蓝牙，点击HID设备名进行连接，如下图所示。

HID设备连接

关闭手机蓝牙再重新打开手机蓝牙，HID设备将自动连接，如下图所示。

HID设备自动重连

术语缩写

缩写	英文全称	中文全称
API	Application Programming Interface	应用程序接口
BLE	Bluetooth Low Energy	蓝牙低功耗
GATT	Generic Attribute Profile	通用属性协议
HID	Human Interface Device	人体学接口设备
ID	Identifier	标识符
IoT	Internet of Things	物联网
MAC	Medium Access Control	媒体访问控制
MTU	Maximum Transmission Unit	最大传输单元
OTA	Over-the-air programming	空中编程
SDK	Software Development Kit	软件开发工具包
UUID	Universally Unique Identifier	通用唯一识别码

硬件设计

通用 API 开发指南

ShortRange

HCM111Z QuecOpen(SDK) BLE开发指导

引言

低功耗蓝牙API

头文件

函数概览

函数详解

ql_ble_create_db

ql_errcode_bt_e

ql_ble_gatt_service_t

ql_ble_gatt_attribute_t

ql_ble_gatt_uuid_t

ql_ble_gatt_msg_handler_t

ql_ble_gatt_msg_t

ql_ble_gatt_msg_evt_t

ql_ble_gatt_msg_hdl_t

ql_ble_gatt_op_cmp_t

ql_ble_set_notice_cb

ble_notice_cb_t

ble_notice_t

ql_ble_set_dev_name

ql_ble_address_get

ql_ble_set_adv_param

ql_ble_adv_param_t

ql_ble_adv_mode_e

ql_ble_addr_type_e

ql_ble_adv_mac_addr_t

ql_ble_phy_e

ql_ble_adv_channel_e

ql_ble_adv_filter_e

ql_ble_adv_disc_mode_e

ql_ble_set_adv_data

ql_ble_set_scan_rsp_data

ql_ble_start_advertising

ql_ble_stop_advertising

ql_ble_start_scaning

ql_ble_stop_scaning

ql_ble_update_param

ql_ble_set_connect_dev_addr

ql_ble_start_conn

ql_ble_disconnect

ql_ble_get_connect_num

ql_ble_link_rssi_report

ql_ble_gatt_init

ql_gatt_client_t

ql_ble_gatt_mtu_changes

ql_ble_gattc_all_service_discovery

ql_ble_gattc_ntf_ind_enable

ql_ble_gattc_write_data_req

ql_ble_gattc_write_data_req_with_handle

ql_ble_gattc_write_data_cmd

ql_ble_gattc_write_data_with_handle

ql_ble_gatts_send_ntf_value

ql_ble_gatts_send_ind_value

ql_ble_security_param_init

ql_ble_security_param_t

ql_ble_io_cap_e

ql_ble_pair_mode_e

ql_ble_bond_num_max

ql_ble_bond_delete_all

ql_ble_get_bond_status

ql_ble_pairing_req

ql_ble_security_req

ql_ble_enc_req

示例

BLE外设功能

BLE中心设备功能

BLE HID设备功能

术语缩写