BS2X指导资料
前言¶
BS2XV100通过API（Application Programming Interface）向开发者提供接入和使用低功耗蓝牙的相关接口，包括GAP广播、连接以及GATT服务注册、服务发现等，其他协议相关接口将在后续增量发布。
与本文档对应的产品版本如下。
本文档主要适用以下工程师：
技术支持工程师
软件开发工程师
在本文中可能出现下列标志，它们所代表的含义如下。
更新“BLE passkey接口”章节内容。 |
||
|
||
|
||
概述¶
BS2XV100通过API（Application Programming Interface）面向开发者提供BLE功能的开发和应用接口，包括GAP、GATT server和GATT client接口。
各组件功能说明如下：
GAP：通用访问协议（Generic Access Profile），包含蓝牙本地设置和低功耗蓝牙的发现和连接接口。
GATT：通用属性协议（Generic Attribute Profile），包含服务注册、服务发现等功能相关接口。
说明： 该文档描述各个模块功能的基本流程和API接口描述。
错误码返回值如表 错误码所示。
表 1 错误码
异常断连原因如表2所示：
表 2 断连原因
GAP接口¶
概述¶
GAP实现蓝牙设备开关控制、设备信息管理、广播管理、主动连接和断开连接等功能。
开发流程¶
打开蓝牙设备开关是使用蓝牙功能的首要条件，蓝牙启动后可进行设备信息管理，包括获取与设置本地设备名称、获取本地设备地址、获取配对信息、获取远端设备名称/设备类型/接收信号强度等。
当蓝牙设备需要被动与对端设备建立连接时，可设置广播参数并启动广播等待对端连接；当蓝牙设备需要主动与对端设备建立连接时，可向对端发起主动连接；当对端地址已知时，用户可直接向对端发起主动连接；当对端地址未知时，可打开蓝牙设备的扫描功能，获取正在广播的设备信息，并向对端发起主动连接；当蓝牙设备处于连接状态时，可获取设备连接信息；当蓝牙设备不需要与对端设备保持连接时，可主动断开连接。
GAP提供的接口如表1所示。
表 1 GAP接口描述
|
NV_STORE_SMP_KEYS_ENCRYPT：0，加密保存； |
GAP开发的具体编程实例可参考application/samples/bt。
GAP开发的典型流程：
Slave：
调用gap_ble_register_callbacks注册用户回调函数。
调用enable_ble，打开蓝牙开关。
调用gap_ble_set_local_addr，设置本地蓝牙地址。
调用gap_ble_set_local_name，设置本地设备名称。
调用gap_ble_set_adv_param，设置广播参数
调用gap_ble_set_adv_data，设置广播数据
调用gap_ble_start_adv，启动广播。
Master：
调用gap_ble_register_callbacks注册用户回调函数。
调用enable_ble，打开蓝牙开关。
调用gap_ble_set_local_addr，设置本地蓝牙地址。
调用gap_ble_set_local_name，设置本地设备名称。
调用gap_ble_set_scan_parameters，设置扫描参数
调用gap_ble_start_scan，启动扫描
调用gap_connect_remote_device，连接到目标设备。
调用gap_ble_pair_remote_device，与目标设备配对
设置passkey：
调用gap_ble_set_local_passkey设置passkey值
调用gap_ble_set_sec_param设置安全参数
调用gap_ble_passkey_entry输入passkey
用户指定保存NV配对信息：
基于auth_complete_cb回调获取配对信息
调用ble_set_nv_pair_keys指定编号存储配对信息至nv
获取配对状态返回值如表2所示。
表 2 获取配对状态返回值说明
BLE passkey接口¶
表 1 BLE Passkey接口描述
BLE Passkey鉴权典型开发流程如下：
gap_ble_set_sec_param设置安全参数，两端设备会根据安全参数选择对应的鉴权方式。
连接端调用gap_connect_remote_device发起连接，并确保连接完成。
连接完成后，调用配对发起接口：gap_ble_pair_remote_device，该接口在G、T节点均可调用。
若设备配置为显示设备（IO能力为：只展示或展示并可以选择Yes或者No），则该设备只会收到passkey_notify_cb回调，此时该设备需要将数据显示，passkey在当前设备上由协议栈生成随机6位数字。
若设备配置为输入设备（IO能力为：只支持键盘或支持键盘和展示），则该设备只会收到passkey_req_cb回调，此时该设备需要用户输入对端设备显示的passkey。
输入设备调用gap_ble_passkey_entry输入接口成功后，等待配对完成。
注意事项：
1、调用gap_ble_pair_remote_device时，即加密配对流程中，不要进行其他业务（重点“服务发现”业务），否则可能导致配对失败。
2、连接参数（连接间隔，延时周期）设置太大会导致配对时间过长。
注意事项¶
本产品只作为低功耗蓝牙设备工作时，最多只支持八路低功耗蓝牙连接，同时作为低功耗蓝牙设备和星闪设备工作时，一共支持八路连接。
若扫描不到设备，请先检查设备是否已在配对设备列表中，或者设备是否已与其他设备配对（此情况下需要先清除设备端配对信息）。
若需要配对密钥在nv中加密存储，需要打开宏CONFIG_NV_SUPPORT_ENCRYPT。在配置界面Middleware->Utils->勾选nv_support encrypt。并在使能协议之前设置配对密钥在nv的保存方式为加密保存，此设置对蓝牙和星闪同时生效。
GATT server接口¶
概述¶
GATT是一个基于蓝牙GAP连接的发送和接收数据的通用规范，支持在两个蓝牙设备间进行数据传输。
开发流程¶
GATT server主要接收对端设备的命令和请求，给对端设备发送响应、指示或者通知。
GATT server提供的接口如表1所示。
表 1 GATT server接口描述
GATT server开发具体编程实例可参考application/samples/bt。
GATT server开发的典型流程：添加服务和特征及描述信息并启动服务。
调用gatts_register_callbacks，注册GATT server用户回调函数。
调用enable_ble，打开蓝牙开关。
调用gatts_register_server，创建一个server。
调用gatts_add_service，根据UUID创建service。
调用gatts_add_characteristic，对创建的服务添加特征值。
调用gatts_add_descriptor，对服务中的特征添加描述信息。
调用gatts_start_service，启动service。
启动广播，等待对端连接。
被对端使能为“可通知”后，调用gatts_notify_indicate或gatts_notify_indicate_by_uuid向对端发起特征值通知。
GATT client接口¶
概述¶
GATT是一个基于蓝牙GAP连接的发送和接收数据的通用规范，支持在两个蓝牙设备间进行数据传输。
开发流程¶
GATT client主要给对端发送命令和请求，接收对端回复的响应、指示和通知。
GATT client提供的接口如表1所示。
表 1 GATT client接口描述
GATT client开发的具体编程实例可参考application/samples/bt。
GATT client开发的典型流程：连接对端设备，发现对端设备的服务，读写对端特征值，订阅对端的通知或者指示。
调用gattc_register_callbacks，注册GATT client用户回调函数。
调用enable_ble，打开蓝牙开关。
调用gattc_register_client，创建一个client。
递归调用gattc_discovery_service，gattc_discovery_character和gattc_discovery_descriptor，获取对端的属性数据库。
调用gattc_write_req或gattc_write_cmd将关注的对端特征的客户端特征配置写为0x0001或0x0002，设置为前者时可收到关注特征的特征通知，设置为后者时可收到关注特征的特征指示。
调用相应读写接口操作GATT server的特征和描述符。