HiSpark编程指南

- 调测资料
  - SDK Sample使用指南
    - 前言
    - 概述
    - Sample框架
    - 外设 Sample
    - SLE UART Sample
    - SLE UART DMA Sample
    - SLE Mouse Sample
    - SLE amic vdt with dongle
    - SLE microphone
    - SLE measure dis
    - BLE Lowpower Sample
    - BLE UART Sample
    - BLE Keyboard Sample
    - BLE SLE TAG Sample
    - BLE Mouse Sample
    - USB Keyboard Sample
    - USB Mouse Sample
    - USB AMIC VDT Sample
    - RCU
    - 多连接
    - air mouse
    - SLE MOUSE with Dongle
    - SLE OTA dongle
    - game mouse
    - BLE UUID
    - 缩略语
  - SDK二次开发网络安全注意事项
    - 前言
    - 产品安全解决方案
    - 结论
  - SDK开发环境搭建用户指南
    - 前言
    - 开发环境搭建
    - 编译SDK
    - 新建APP
  - 内存维测指导书
    - 前言
    - 简介
    - 内存维测功能
  - 射频AT测试指南
    - 前言
    - 射频测试AT指令
    - AT指令组包示例
    - 注意事项
  - 维测指导书
    - 前言
    - 概述
    - 日志说明
    - 日志分析
    - 问题定位
    - 典型案例
    - 常见问题FAQ
- 软件资料
  - AT命令使用指南
    - 前言
    - 指令说明
    - 通用AT指令
    - BT业务AT指令
    - 新增AT指令方法
  - DFU升级APK开发指南
    - 前言
    - 功能特性
    - 系统框架
    - 工程文件部署
    - 界面实现
    - 升级界面Fragment实现
    - 关于界面Fragment实现
    - 应用清单AndroidManifest
  - DFX软件开发指南
    - 前言
    - DIAG维测功能
    - 死机诊断
    - Dump解析
  - EFUSE使用指南
    - 前言
    - 概述
    - 使用软件接口读写EFUSE
    - 使用BurnTool烧写EFUSE
  - NFC TAG软件开发指导书
    - 前言
    - 概述
    - 开发指导
  - NV存储用户指南
    - 前言
    - NV简介
    - NV编译预置
    - NV API指南
    - 定制化NV结构使用介绍
    - 通过NV自定义传输数据最大长度
  - Release notes
    - 1.0.18版本描述文件
    - 1.0.17版本描述文件
    - 1.0.16版本描述文件
  - SDK开发指南
    - 前言
    - 概述
    - 系统接口
  - SDK接口变更说明书
    - 前言
    - BLE SDK接口变更说明
  - SP31 SLP使用指南
    - 开源版本
  - USB HID复合设备开发指南
    - 前言
    - 概述
    - 实现方式
  - 代码框架说明
    - 前言
    - SDK模块框架
    - SDK目录结构
    - SDK目录说明
  - 低功耗FAQ
    - 前言
    - 系统无法睡眠
    - IO无法唤醒系统
    - 唤醒后外设异常
    - 低功耗导致OTA升级异常
    - 功耗比预期高
    - 锁中断导致BT业务阻塞
    - 概率性狗超时
    - 供电模式&软件配置
    - 提前唤醒时间问题
  - 低功耗sample使用指南
    - 前言
    - 编译&测试
    - 系统状态管理
    - 用户指南
  - 低功耗开发指南
    - 前言
    - 低功耗概述
    - 低功耗方案
    - 开发指引
    - 功耗优化
    - 常见问题
  - 功率配置说明书
    - 前言
    - 射频功率配置说明
  - 升级方案使用指南
    - 前言
    - 概述
    - 升级包制作
    - 升级包传输
    - 升级包保存
    - 升级包本地升级
    - FAQ
  - 快速入门指南
    - 前言
    - 文档目录
    - 环境搭建
    - 基础功能开发
    - 调优
    - 特性开发
    - 测试报告
  - 星闪应用层SLE-Link协议
    - 前言
    - 概述
    - SLE Frame格式定义
    - 服务接口定义
    - 交互流程示例
  - 星闪软件开发指导书
    - 前言
    - 概述
    - Device Discovery接口
    - Connection Manager接口
    - SSAP Server接口
    - SSAP client接口
    - Low Latency接口
    - Transmission Manager接口
    - SLE Passkey接口
    - SLE Channel Map 接口
  - 红外学习使用指南
    - 前言
    - 红外学习方式
    - 通过比较器进行红外学习
    - 使用指南
  - 蓝牙软件开发指导书
    - 前言
    - 概述
    - GAP接口
    - GATT server接口
    - GATT client接口
  - 设备驱动开发指南
    - 前言
    - Pinctrl
    - GPIO
    - UART
    - SPI
    - I2C
    - ADC
    - DMA
    - PWM
    - WDT
    - Timer
    - Systick
    - TCXO
    - Flash
    - SFC
    - QDEC
    - KEYSCAN
    - PDM
    - USB_HID
    - USB_DFU
    - I2S
    - TRNG
    - 附：MIDDLEWARE
  - 音频编解码开发指导书
    - 前言
    - 概述
    - Audio Encoder
    - Audio Decoder
    - 调试与功能
- 工具资料
  - BurnTool工具使用指导书
    - 前言
    - BurnTool工具简介
    - 操作指南
    - FAQ
  - HiSpark Studio使用指南
    - 前言
    - 工具简介
    - 开发环境搭建
    - 工程管理
    - 工程配置
    - 编译运行
    - 软件包烧录
    - 栈分析和镜像分析
    - 工程调试
    - 串口控制台工具
    - Kconfig配置
    - GUI工程创建与使用
    - 高阶分析功能使用
    - 常见错误

### 该页内容

- 前言
- 概述
- GAP接口
  - 概述
  - 开发流程
  - BLE passkey接口
  - 注意事项
- GATT server接口
  - 概述
  - 开发流程
- GATT client接口
  - 概述
  - 开发流程

# 前言

概述

BS2XV100通过API（Application Programming Interface）向开发者提供接入和使用低功耗蓝牙的相关接口，包括GAP广播、连接以及GATT服务注册、服务发现等，其他协议相关接口将在后续增量发布。

产品版本

与本文档对应的产品版本如下。

产品名称 | 产品版本
--- | ---
BS2X | V100

读者对象

本文档主要适用以下工程师：

- 技术支持工程师

- 软件开发工程师

符号约定

在本文中可能出现下列标志，它们所代表的含义如下。

符号 | 说明
--- | ---
| 表示如不避免则将会导致死亡或严重伤害的具有高等级风险的危害。
| 表示如不避免则可能导致死亡或严重伤害的具有中等级风险的危害。
| 表示如不避免则可能导致轻微或中度伤害的具有低等级风险的危害。
| 用于传递设备或环境安全警示信息。如不避免则可能会导致设备损坏、数据丢失、设备性能降低或其它不可预知的结果。 “须知”不涉及人身伤害。
| 对正文中重点信息的补充说明。 “说明”不是安全警示信息，不涉及人身、设备及环境伤害信息。

修改记录

文档版本 | 发布日期 | 修改说明
--- | --- | ---
06 | 2025-11-07 | 更新“GAP接口”的“开发流程”章节内容。 更新“GAP接口”的“注意事项”章节内容。
05 | 2025-08-07 | 更新“BLE passkey接口”章节内容。
04 | 2025-01-14 | 更新“GAP接口”的“注意事项”章节内容。 更新“GATT server接口”的“开发流程”章节内容。
03 | 2024-09-13 | 更新“概述”章节内容。 更新“GAP接口”的“开发流程”章节内容。 更新“GATT server接口”的“开发流程”章节内容。
02 | 2024-08-02 | 更新“GAP接口”的“开发流程”章节内容。
01 | 2024-05-15 | 第一次正式版本发布。
00B02 | 2024-01-08 | 更新“GAP接口”的“注意事项”章节内容。
00B01 | 2023-09-27 | 第一次临时版本发布。

# 概述

BS2XV100通过API（Application Programming Interface）面向开发者提供BLE功能的开发和应用接口，包括GAP、GATT server和GATT client接口。

各组件功能说明如下：

- GAP：通用访问协议（Generic Access Profile），包含蓝牙本地设置和低功耗蓝牙的发现和连接接口。

- GATT：通用属性协议（Generic Attribute Profile），包含服务注册、服务发现等功能相关接口。

> 说明： 该文档描述各个模块功能的基本流程和API接口描述。

返回值

错误码返回值如表 错误码所示。

表 1 错误码

序号 | 定义 | 实际数值 | 描述
--- | --- | --- | ---
1 | ERRCODE_BT_SUCCESS | 0x0 | 执行成功错误码。
2 | ERRCODE_BT_FAIL | 0x80006000 | 执行失败错误码。
3 | ERRCODE_BT_NOT_READY | 0x80006001 | 执行状态未就绪错误码。
4 | ERRCODE_BT_MALLOC_FAIL | 0x80006002 | 内存不足错误码。
5 | ERRCODE_BT_MEMCPY_FAIL | 0x80006003 | 内存拷贝错误错误码。
6 | ERRCODE_BT_BUSY | 0x80006004 | 繁忙无法响应错误码。
7 | ERRCODE_BT_DONE | 0x80006005 | 执行完成错误码。
8 | ERRCODE_BT_UNSUPPORTED | 0x80006006 | 不支持错误码。
9 | ERRCODE_BT_PARAM_ERR | 0x80006007 | 无效参数错误码。
10 | ERRCODE_BT_STATE_ERR | 0x80006008 | 状态错误。
11 | ERRCODE_BT_UNHANDLED | 0x80006009 | 未处理错误码。
12 | ERRCODE_BT_AUTH_FAIL | 0x8000600A | 鉴权失败错误码。
13 | ERRCODE_BT_RMT_DEV_DOWN | 0x8000600B | 远端设备关闭错误码。
14 | ERRCODE_BT_AUTH_REJECTED | 0x8000600C | 鉴权被拒错误码。
15 | ERRCODE_BT_KEY_MISSING | 0x8000600F | 密钥丢失错误码

断连原因

异常断连原因如表2所示：

表 2 断连原因

序号 | 定义 | 实际数值 | 描述
--- | --- | --- | ---
1 | BLE_DISCONNECT_UNKNOWN | 0x00 | 未知原因断连
2 | BLE_DISCONNECT_BY_PIN_OR_KEY_MISSING | 0x06 | pin或key丢失导致断连
3 | BLE_DISCONNECT_BY_CONNECT_TIMEOUT | 0x08 | 连接超时断连
4 | BLE_DISCONNECT_BY_REMOTE_USER | 0x13 | 远端用户断连
5 | BLE_DISCONNECT_BY_LOCAL_HOST | 0x16 | 本端host断连。
6 | BLE_DISCONNECT_BY_MIC_ERROR | 0x3D | MIC error 断连
7 | BLE_ESTABLISH_CONNECT_FAIL | 0x3E | 建连异常

# GAP接口

## 概述

GAP实现蓝牙设备开关控制、设备信息管理、广播管理、主动连接和断开连接等功能。

## 开发流程

使用场景

打开蓝牙设备开关是使用蓝牙功能的首要条件，蓝牙启动后可进行设备信息管理，包括获取与设置本地设备名称、获取本地设备地址、获取配对信息、获取远端设备名称/设备类型/接收信号强度等。

当蓝牙设备需要被动与对端设备建立连接时，可设置广播参数并启动广播等待对端连接；当蓝牙设备需要主动与对端设备建立连接时，可向对端发起主动连接；当对端地址已知时，用户可直接向对端发起主动连接；当对端地址未知时，可打开蓝牙设备的扫描功能，获取正在广播的设备信息，并向对端发起主动连接；当蓝牙设备处于连接状态时，可获取设备连接信息；当蓝牙设备不需要与对端设备保持连接时，可主动断开连接。

功能

GAP提供的接口如表1所示。

表 1 GAP接口描述

接口名称 | 描述 | 入参说明 | 返回信息说明
--- | --- | --- | ---
enable_ble | 使能BLE。 | - | 接口返回值：错误码。
disable_ble | 去使能BLE。 | - | 接口返回值：错误码。
gap_ble_set_local_addr | 设置本地设备地址。 | addr 本地设备地址。 | 接口返回值：错误码。
gap_ble_get_local_addr | 获取本地设备地址。 | [out]addr 本地设备地址。 | 本地设备地址存储在入参mac中； 接口返回值：错误码。
gap_ble_set_local_name | 设置本地设备名称。 | local_name：本地设备名称指针； length：本地设备名称长度(最大值：32)。 | 接口返回值：错误码。
gap_ble_set_local_appearance | 设置本地设备appearance。 | appearance：本地设备外貌（参考对外头文件gap_ble_appearance_type_t） | 接口返回值：错误码。
gap_ble_get_local_name | 获取本地设备名称。 | local_name：本地设备名称指针； length：本地设备名称长度。 | 本地设备名称存储在入参local_name中； 接口返回值：错误码。
gap_ble_get_paired_devices_num | 获取BLE配对设备数量。 | number：配对设备数量指针。 | 配对设备数量存储在入参number中； 接口返回值：错误码。
gap_ble_get_paired_devices | 获取BLE配对设备。 | number：配对设备数量指针； addr：配对设备地址指针。 | 配对设备数量存储在入参number中； 配对设备地址存储在入参addr中； 接口返回值：错误码。
gap_ble_get_pair_state | 获取BLE设备的配对状态。 | addr：对端设备地址。 [out] status 配对设备状态. | 接口返回值：配对状态（GAP_PAIR_NONE、GAP_PAIR_PAIRING、GAP_PAIR_PAIRED）。
gap_ble_remove_all_pairs | 删除所有配对设备。 | - | 接口返回值：错误码。
gap_ble_remove_pair | 删除配对设备 | addr：配对设备地址。 | 接口返回值：错误码。
gap_ble_disconnect_remote_device | 断开BLE设备连接。 | addr：对端设备地址。 | 接口返回值：错误码。
gap_ble_connect_remote_device | 与设备建立ACL连接。 | addr：对端设备地址。 | 接口返回值：错误码。
gap_ble_pair_remote_device | 与已连接设备进行配对。 | addr：对端设备地址。 | 接口返回值：错误码。
gap_ble_connect_param_update | 连接参数更新。 | params：待更新连接参数。 | 接口返回值：错误码。
gap_ble_set_adv_data | 设置BLE广播数据。 | adv_id：广播id； data：设备的广播数据（长度＜31时为普通广播，＞31时为拓展广播）。 | 接口返回值：错误码。
gap_ble_set_adv_param | 设置广播参数。 | adv_id：广播id； param：设备广播的配置参数。 注：使用板端地址发送广播时，param中own_addr应设置成全0。 | 接口返回值：错误码。
gap_ble_start_adv | 启动BLE广播。 | adv_id：广播id； | 接口返回值：错误码。
gap_ble_stop_adv | 停止BLE广播。 | adv_id：广播id。 | 接口返回值：错误码。
gap_ble_set_scan_parameters | 设置扫描参数。 | param：设置的扫描参数。 | 接口返回值：错误码。
gap_ble_start_scan | 启动扫描。 | - | 接口返回值：错误码。
gap_ble_stop_scan | 停止扫描。 | - | 接口返回值：错误码。
gap_ble_register_callbacks | 注册BLE GAP回调。 | func：用户回调函数。 | 接口返回值：错误码。
bth_ota_init | 初始化bth ota通道。 注：在收到ble使能成功的回调之后调用。 | - | 接口返回值：错误码。
ble_update_local_latency | 设置本端latency。 | conn_handle：连接id type：参照枚举sle_update_latency_type_t latency：0xFFFF未更新，其他值更新latency | 接口返回值：错误码。
gap_ble_set_data_length | 设置数据长度参数 | conn_handle：连接id maxtxoctets：最大字节数(27-251) maxtxtime：最大发送时间(328-2120) | 接口返回值：错误码。
gap_ble_set_local_passkey | 设置本地Passkey | enable：是否开启使用用户自定义Passkey tk：通行码值(不得＞999999) | 接口返回值：错误码。
gap_ble_passkey_entry | 通行码输入函数 | conn_id：连接ID tk：通行码值(同上) | 接口返回值：错误码
gap_ble_set_sec_param | 设置安全参数 | param：安全参数 | 接口返回值：错误码
ble_set_nv_pair_keys |  | key：配对信息 own_addr：本端地址 peer_addr：对端地址 index：nv中存储编号，取值0~7（包含7） | 接口返回值：错误码
gap_ble_set_nv_store_smp_keys_mode | 设置配对密钥在nv的保存方式 | is_encrypted：是否加密保存（ NV_STORE_SMP_KEYS_ENCRYPT：0，加密保存； NV_STORE_SMP_KEYS_PLAINTEXT：1，明文保存 ） | 接口返回值：错误码

开发流程

GAP开发的具体编程实例可参考application/samples/bt。

GAP开发的典型流程：

Slave：

1. 调用gap_ble_register_callbacks注册用户回调函数。

2. 调用enable_ble，打开蓝牙开关。

3. 调用gap_ble_set_local_addr，设置本地蓝牙地址。

4. 调用gap_ble_set_local_name，设置本地设备名称。

5. 调用gap_ble_set_adv_param，设置广播参数

6. 调用gap_ble_set_adv_data，设置广播数据

7. 调用gap_ble_start_adv，启动广播。

Master：

1. 调用gap_ble_register_callbacks注册用户回调函数。

2. 调用enable_ble，打开蓝牙开关。

3. 调用gap_ble_set_local_addr，设置本地蓝牙地址。

4. 调用gap_ble_set_local_name，设置本地设备名称。

5. 调用gap_ble_set_scan_parameters，设置扫描参数

6. 调用gap_ble_start_scan，启动扫描

7. 调用gap_connect_remote_device，连接到目标设备。

8. 调用gap_ble_pair_remote_device，与目标设备配对

设置passkey：

1. 调用gap_ble_set_local_passkey设置passkey值

2. 调用gap_ble_set_sec_param设置安全参数

3. 调用gap_ble_passkey_entry输入passkey

用户指定保存NV配对信息：

1. 基于auth_complete_cb回调获取配对信息

2. 调用ble_set_nv_pair_keys指定编号存储配对信息至nv

返回值

获取配对状态返回值如表2所示。

表 2 获取配对状态返回值说明

序号 | 定义 | 实际数值 | 描述
--- | --- | --- | ---
1 | GAP_PAIR_NONE | 1 | 未配对。
2 | GAP_PAIR_PAIRING | 2 | 配对中。
3 | GAP_PAIR_PAIRED | 3 | 已配对。

## BLE passkey接口

表 1 BLE Passkey接口描述

接口描述 | 描述 | 参数说明 | 返回信息说明
--- | --- | --- | ---
passkey_req_cb | 请求通行码回调函数 | conn_id：BLE连接ID。 | -
passkey_notify_cb | 通知通行码回调函数 | conn_id：BLE连接ID； passkey：通行码数据指针； len：通行码数据长度。 | -
gap_ble_passkey_entry | 通行码输入。 | conn_id：BLE连接ID； passkey：转为数字的通信码数据。 | 成功：ERRCODE_BT_SUCCESS； 失败：对应错误码。

开发流程

BLE Passkey鉴权典型开发流程如下：

1. gap_ble_set_sec_param设置安全参数，两端设备会根据安全参数选择对应的鉴权方式。

2. 连接端调用gap_connect_remote_device发起连接，并确保连接完成。

3. 连接完成后，调用配对发起接口：gap_ble_pair_remote_device，该接口在G、T节点均可调用。

4. 若设备配置为显示设备（IO能力为：只展示或展示并可以选择Yes或者No），则该设备只会收到passkey_notify_cb回调，此时该设备需要将数据显示，passkey在当前设备上由协议栈生成随机6位数字。

5. 若设备配置为输入设备（IO能力为：只支持键盘或支持键盘和展示），则该设备只会收到passkey_req_cb回调，此时该设备需要用户输入对端设备显示的passkey。

6. 输入设备调用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接口描述

接口名称 | 描述 | 入参说明 | 返回信息说明
--- | --- | --- | ---
gatts_register_server | Gatt server注册。根据传入的UUID注册server，回调函数返回server接口ID。 注：目前只支持注册一个GATT server。 | app_uuid：应用UUID指针； server_id：服务端ID指针。 | 服务端ID存储在server_id中； 接口返回值：错误码。
gatts_unregister_server | 注销gatt服务端。 | server_id：服务器ID。 | 接口返回值：错误码。
gatts_add_service | 添加service。 | server_id：服务器ID； service_uuid：服务UUID； is_primary：是否是首要服务。 | 接口返回值：错误码。
gatts_add_characteristic | 添加characteristic到指定的service。 | server_id：服务器ID； service_handle：服务句柄； character：特征信息。 | 接口返回值：错误码。
gatts_add_descriptor | 添加descriptor到对应的characteristic。 包含当前Characteristic的描述信息、配置信息、表示格式信息等。 | server_id：服务器ID； service_handle：服务句柄； descriptor：描述符信息。 | 接口返回值：错误码。
gatts_add_service_sync | 添加一个gatt服务同步接口，服务句柄同步返回。 | server_id：服务器ID； service_uuid：服务UUID； is_primary：是否是首要服务； handle：服务句柄指针。 | 服务句柄存储在handle中； 接口返回值：错误码。
gatts_add_characteristic_sync | 添加一个gatt特征同步接口，特征句柄同步返回。 | server_id：服务器ID； service_handle：服务UUID； character：GATT特征； result：特征句柄指针。 | 特征句柄存储在 result中； 接口返回值：错误码。
gatts_add_descriptor_sync | 添加一个gatt特征描述符同步接口，特征描述符句柄同步返回。 | server_id：服务器ID； service_handle：服务UUID； descriptor：特征描述符； handle：特征描述符句柄指针。 | 特征描述符句柄存储在handle中； 接口返回值：错误码。
gatts_start_service | 启动service。 | server_id：服务器ID； service_handle：服务句柄。 | 接口返回值：错误码。
gatts_delete_all_services | 删除所有GATT服务。 | server_id：服务器ID； | 接口返回值：错误码。
gatts_send_response | 用户发送响应。 | server_id：服务器ID； conn_id：连接ID； param：响应参数。 | 接口返回值：错误码。
gatts_notify_indicate | 给远端client发送indication/notification。 | server_id：服务器ID； conn_id：连接ID； param：通知或指示参数。 | 接口返回值：错误码。
gatts_notify_indicate_direct_send | 向对端发送通知或指示,不更新Character值 | server_id：服务器ID； conn_id：连接ID； param：通知或指示参数。 | 接口返回值：错误码。
gatts_notify_indicate_by_uuid | 按照UUID给远端client发送indication/notification。 | server_id：服务器ID； conn_id：连接ID； param：通知或指示参数。 | 接口返回值：错误码。
gatts_set_mtu_size | 在连接之前设置服务端接收mtu。 | server_id：服务器ID； mtu_size：服务端接收mtu值。 | 接口返回值：错误码。
gatts_register_callbacks | 注册GATT server回调函数。 | func：用户回调函数。 | 接口返回值：错误码。

开发流程

GATT server开发具体编程实例可参考application/samples/bt。

GATT server开发的典型流程：添加服务和特征及描述信息并启动服务。

1. 调用gatts_register_callbacks，注册GATT server用户回调函数。

2. 调用enable_ble，打开蓝牙开关。

3. 调用gatts_register_server，创建一个server。

4. 调用gatts_add_service，根据UUID创建service。

5. 调用gatts_add_characteristic，对创建的服务添加特征值。

6. 调用gatts_add_descriptor，对服务中的特征添加描述信息。

7. 调用gatts_start_service，启动service。

8. 启动广播，等待对端连接。

9. 被对端使能为“可通知”后，调用gatts_notify_indicate或gatts_notify_indicate_by_uuid向对端发起特征值通知。

# GATT client接口

## 概述

GATT是一个基于蓝牙GAP连接的发送和接收数据的通用规范，支持在两个蓝牙设备间进行数据传输。

## 开发流程

使用场景

GATT client主要给对端发送命令和请求，接收对端回复的响应、指示和通知。

功能

GATT client提供的接口如表1所示。

表 1 GATT client接口描述

接口名称 | 描述 | 入参说明 | 返回信息说明
--- | --- | --- | ---
gattc_register_client | 注册GATT client。 | app_uuid：应用UUID； client_id：客户端ID指针。 | 客户端id存储在client_id中 接口返回值：错误码。
gattc_unregister_client | 取消注册GATT client。 | client_id：客户端ID。 | 接口返回值：错误码。
gattc_discovery_service | 发现服务。 | client_id：客户端ID； conn_id：连接ID； uuid：服务UUID。 | 接口返回值：错误码。
gattc_discovery_character | 发现特征。 | client_id：客户端ID； conn_id：连接ID； param：发现的特征参数。 | 接口返回值：错误码。
gattc_discovery_descriptor | 发现特征描述符。 | client_id：客户端ID； conn_id：连接ID； character_handle：特征声明句柄。 | 接口返回值：错误码。
gattc_read_req_by_handle | 发起按照句柄读取请求。 | client_id：客户端ID； conn_id：连接ID； handle：句柄。 | 接口返回值：错误码。
gattc_read_req_by_uuid | 发起按照UUID读取请求。 | client_id：客户端ID； conn_id：连接ID； param：按照UUID读取请求参数。 | 接口返回值：错误码。
gattc_write_req | 发起写请求。 | client_id：客户端ID； conn_id：连接ID； param：写请求参数。 | 接口返回值：错误码。
gattc_write_cmd | 发起写命令。 | client_id：客户端ID； conn_id：连接ID； param：写命令参数。 | 接口返回值：错误码。
gattc_exchange_mtu_req | 发送交换mtu请求。 | client_id：客户端ID； conn_id：连接ID； mtu_size：客户端接收mtu。 | 接口返回值：错误码。
gattc_register_callbacks | 注册GATT client回调函数。 | func：用户回调函数。 | 接口返回值：错误码。

开发流程

GATT client开发的具体编程实例可参考application/samples/bt。

GATT client开发的典型流程：连接对端设备，发现对端设备的服务，读写对端特征值，订阅对端的通知或者指示。

1. 调用gattc_register_callbacks，注册GATT client用户回调函数。

2. 调用enable_ble，打开蓝牙开关。

3. 调用gattc_register_client，创建一个client。

4. 递归调用gattc_discovery_service，gattc_discovery_character和gattc_discovery_descriptor，获取对端的属性数据库。

5. 调用gattc_write_req或gattc_write_cmd将关注的对端特征的客户端特征配置写为0x0001或0x0002，设置为前者时可收到关注特征的特征通知，设置为后者时可收到关注特征的特征指示。

6. 调用相应读写接口操作GATT server的特征和描述符。