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工程创建与使用
    - 高阶分析功能使用
    - 常见错误

### 该页内容

- 前言
- 概述
  - 错误码
- Device Discovery接口
  - 概述
  - 开发流程
  - 注意事项
- Connection Manager接口
  - 概述
  - 开发流程
- SSAP Server接口
  - 概述
  - 开发流程
- SSAP client接口
  - 概述
  - 开发流程
- Low Latency接口
  - 概述
  - 开发流程
- Transmission Manager接口
  - 概述
  - 开发流程
- SLE Passkey接口
  - 概述
  - 开发流程
- SLE Channel Map 接口
  - 概述
  - 开发流程

# 前言

概述

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

产品版本

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

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

读者对象

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

- 技术支持工程

- 软件开发工程师

符号约定

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

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

修改记录

文档版本 | 发布日期 | 修改说明
--- | --- | ---
06 | 2025-11-07 | 更新“SLE Passkey接口”章节内容的“开发流程”章节内容。 新增“SLE Channel Map 接口”章节内容。
05 | 2025-05-30 | 更新“错误码”章节内容。
04 | 2025-01-24 | 新增“SLE Passkey接口”章节内容。
03 | 2024-09-13 | 更新“错误码”章节内容。 更新“Connection Manager接口”的“开发流程”章节内容。 更新“SSAP Server接口”的“开发流程”章节内容。
02 | 2024-08-02 | 更新“Connection Manager接口”的“开发流程”章节内容。
01 | 2024-05-15 | 第一次正式版本发布。 新增“Transmission Manager接口”章节内容。
00B04 | 2024-04-25 | 更新“Connection Manager接口”章节内容。
00B03 | 2024-01-08 | 更新“Device Discovery接口”的“注意事项”章节内容。
00B02 | 2023-12-08 | 更新“Connection Manager接口”的“开发流程”章节内容。
00B01 | 2023-09-27 | 第一次临时版本发布。

# 概述

BS2XV100通过API（Application Programming Interface）面向开发者提供SLE功能的开发和应用接口，包括Device Discovery, Connection Manager, SSAP等。

各组件功能说明如下：

- Device Discovery：星闪设备发现协议，包括设备管理、设备公开和设备发现接口。

- Connection Manager：星闪连接管理协议，包括设备连接、配对相关接口。

- SSAP：星闪服务交互协议（SparkLink Service Access Protocol），包含服务注册、服务发现、属性数据读写等功能相关接口。

- Low Latency：低时延初始化和低时延数据收发接口。

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

## 错误码

SLE SDK使用错误码指示用户当前任务执行结果，如表1所示。

表 1 错误码

序号 | 定义 | 实际数值 | 描述
--- | --- | --- | ---
1 | ERRCODE_SLE_SUCCESS | 0 | 执行成功错误码。
2 | ERRCODE_SLE_CONTINUE | 0x80006000 | 继续执行错误码。
3 | ERRCODE_SLE_DIRECT_RETURN | 0x80006001 | 直接返回错误码。
4 | ERRCODE_SLE_NO_ATTATION | 0x80006002 | -
5 | ERRCODE_SLE_PARAM_ERR | 0x80006003 | 参数错误错误码。
6 | ERRCODE_SLE_FAIL | 0x80006004 | 执行失败错误码。
7 | ERRCODE_SLE_TIMEOUT | 0x80006005 | 执行超时错误码。
8 | ERRCODE_SLE_UNSUPPORTED | 0x80006006 | 参数不支持错误码。
9 | ERRCODE_SLE_GETRECORD_FAIL | 0x80006007 | 获取当前记录失败错误码。
10 | ERRCODE_SLE_POINTER_NULL | 0x80006008 | 指针为空错误码。
11 | ERRCODE_SLE_NO_RECORD | 0x80006009 | 无记录返回错误码。
12 | ERRCODE_SLE_STATUS_ERR | 0x8000600a | 状态错误错误码。
13 | ERRCODE_SLE_NOMEM | 0x8000600b | 内存不足错误码。
14 | ERRCODE_SLE_AUTH_FAIL | 0x8000600c | 认证失败错误码。
15 | ERRCODE_SLE_AUTH_PKEY_MISS | 0x8000600d | PIN码或密钥丢失致认证失败错误码。
16 | ERRCODE_SLE_RMT_DEV_DOWN | 0x8000600e | 对端设备关闭错误码。
17 | ERRCODE_SLE_PAIRING_REJECT | 0x8000600f | 配对拒绝错误码。
18 | ERRCODE_SLE_BUSY | 0x80006010 | 系统繁忙错误码。
19 | ERRCODE_SLE_NOT_READY | 0x80006011 | 系统未准备好错误码。
20 | ERRCODE_SLE_CONN_FAIL | 0x80006012 | 连接失败错误码。
21 | ERRCODE_SLE_OUT_OF_RANGE | 0x80006013 | 越界错误码。
22 | ERRCODE_SLE_MEMCPY_FAIL | 0x80006014 | 拷贝失败错误码。
23 | ERRCODE_SLE_MALLOC_FAIL | 0x80006015 | 内存申请失败错误码。

断连原因

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

表 2 断连原因

序号 | 定义 | 实际数值 | 描述
--- | --- | --- | ---
1 | SLE_DISCONNECT_UNKNOWN | 0x00 | 未知原因断连。
2 | SLE_DISCONNECT_BY_PIN_OR_KEY_MISSING | 0x05 | pin或key丢失导致断连。
3 | SLE_DISCONNECT_BY_CONNECT_TIMEOUT | 0x07 | 连接超时断连。
5 | SLE_D ISCONNECT_BY_REMOTE_USER | 0x10 | 远端用户断连。
6 | SLE_DISCONNECT_BY_LOCAL_HOST | 0x11 | 本端host断连。
7 | SLE_DISCONNECT_BY_MIC_ERROR | 0x1B | MIC error断连。
8 | SLE_ESTABLISH_CONNECT_FAIL | 0x1C | 建连异常。

# Device Discovery接口

## 概述

Device Discovery接口是星闪设备发现协议的软件实现，主要功能有SLE设备开关、设备管理、设备公开和设备发现。

## 开发流程

使用场景

打开SLE设备开关是使用SLE功能的首要条件，SLE启动后可进行设备信息管理，包括获取与设置本地设备名称、获取与设置本地设备地址和设置本地设备外观。

- 当SLE设备需要进行设备公开时，可先设置设备公开参数、设备公开数据，然后使能设备公开。

- 当SLE设备需要进行设备发现时，可先设置设备发现参数，然后使能设备发现，并通过回调函数观察发现到的设备公开数据包。

功能

Device Discovery提供的接口如表1所示。

表 1 Device Discovery接口描述

接口名称 | 描述 | 参数说明 | 返回信息说明
--- | --- | --- | ---
enable_sle | 使能SLE。 | - | 接口返回值：错误码。
disable_sle | 去使能SLE。 | - | 接口返回值：错误码。
sle_set_local_addr | 设置本地设备地址。 | addr：本地设备地址。 | 接口返回值：错误码。
sle_get_local_addr | 获取本地设备地址。 | addr：[out]本地设备地址。 | 接口返回值：错误码。
sle_set_local_name | 设置本地设备名称。 | name：本地设备名称； len：本地设备名称长度。 | 接口返回值：错误码。
sle_get_local_name | 获取本地设备名称。 | name：[out]本地设备名称； len：[inout]入参时为用户预留内存大小，出参时为本地设备名称长度。 | 接口返回值：错误码。
sle_set_announce_data | 设置设备公开数据。 | announce_id：设备公开ID； data：设备公开数据。 | 接口返回值：错误码。
sle_set_announce_param | 设置设备公开参数。 | announce_id：设备公开ID； data：设备公开参数。 | 接口返回值：错误码。
sle_start_announce | 开始设备公开。 | announce_id：设备公开ID。 | 接口返回值：错误码。
sle_stop_announce | 停止设备公开。 | announce_id：设备公开ID。 | 接口返回值：错误码。
sle_set_seek_param | 设置设备发现参数。 | param：设备发现参数。 | 接口返回值：错误码。
sle_start_seek | 开始设备发现。 | - | 接口返回值：错误码。
sle_stop_seek | 停止设备发现。 | - | 接口返回值：错误码。
sle_announce_seek_register_callbacks | 注册设备公开和设备发现回调函数。 | func：用户回调函数。 | 接口返回值：错误码。

开发流程

Device Discovery开发的典型流程如下，具体编程实例可参考application/samples/bt。

Terminal Node：

1. 调用enable_sle，打开SLE开关。

2. 调用sle_announce_seek_register_callbacks，注册设备公开和设备发现回调函数。

3. 调用sle_set_local_addr，设置本地设备地址。

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

5. 调用sle_set_announce_param，设置设备公开参数

6. 调用sle_set_announce_data，设置设备公开数据

7. 调用sle_start_announce，启动设备公开。

Grant Node：

1. 调用enable_sle，打开SLE开关。

2. 调用sle_announce_seek_register_callbacks，注册设备公开和设备发现回调函数。

3. 调用sle_set_local_addr，设置本地设备地址。

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

5. 调用sle_set_seek_param，设置设备发现参数。

6. 调用sle_start_seek，启动设备发现，并在回调函数中获得正在进行设备公开的设备信息。

## 注意事项

- BS2XV100产品只作为SLE设备工作时，最多只支持八路连接，同时作为BLE和SLE设备工作时，一共支持八路连接。

- 若扫描不到设备，请先检查设备是否已在配对设备列表中，或者设备是否已与其他设备配对（此情况下需要先清除设备端配对信息）。

# Connection Manager接口

## 概述

Connection Manager接口是星闪连接管理协议的软件实现，主要功能有连接、配对和读远端设备RSSI值。

## 开发流程

使用场景

当设备需要与对端设备建立连接时，可向对端设备发起连接请求。在连接过程中，设备可读取远端设备RSSI值，当设备需要更新连接参数时，可向对端设备发起连接参数更新请求，当设备需要与对端设备配对时，可向对端设备发起配对请求。在配对过程中，可获取当前本端设备与指定对端设备的配对状态。设备可获取当前配对设备数量以及当前配对设备信息链表，当前的链路角色。

功能

Connection Manager提供的接口如表1所示。

表 1 Connection Manager接口描述

接口名称 | 描述 | 参数说明 | 返回信息说明
--- | --- | --- | ---
sle_connect_remote_device | 向对端设备发起连接请求。 | addr：对端设备地址。 | 接口返回值：错误码。
sle_disconnect_remote_device | 向对端设备发起断连请求。 | addr：对端设备地址。 | 接口返回值：错误码。
sle_update_connect_param | 连接参数更新。 | params：连接参数 | 接口返回值：错误码。
sle_pair_remote_device | 向对端设备发起配对请求。 （目前星闪鉴权流程仅支持免输入模式） | addr：对端设备地址。 | 接口返回值：错误码。
sle_remove_paired_remote_device | 与对端设备取消配对。 | addr：对端设备地址。 | 接口返回值：错误码。
sle_remove_all_pairs | 取消与所有对端设备的配对。 | - | 接口返回值：错误码。
sle_get_paired_devices_num | 获取配对设备数量。 | number：[out]配对设备数量。 | 接口返回值：错误码。
sle_get_paired_devices | 获取配对设备信息。 | addr：[out]设备地址链表； number：[inout]入参时为用户预留内存大小，出参时为设备数量。 | 接口返回值：错误码。
sle_get_pair_state | 获取配对状态。 | addr：设备地址； state：[out]配对状态。 | 接口返回值：错误码。
sle_get_connect_role | 获取链路角色。 | conn_id: 连接id； role: [out]链路角色。 | 接口返回值：错误码。
sle_read_remote_device_rssi | 读对端设备RSSI值。 | conn_id：连接id。 | 接口返回值：错误码。
sle_set_phy_param | 更新星闪phy参数。 | conn_id：连接id; param：phy更新的配置参数。 | 接口返回值：错误码。
sle_connection_register_callbacks | 注册连接管理回调函数。 | func：用户回调函数。 | 接口返回值：错误码。

开发流程

Connection Manager开发的典型流程如下，具体编程实例可参考application/samples/bt。

Terminal Node：

1. 调用enable_sle，打开SLE开关。

2. 调用sle_announce_seek_register_callbacks，注册设备公开和设备发现回调函数。

3. 调用sle_connection_register_callbacks，注册连接管理回调函数。

4. 调用sle_set_local_addr，设置本地设备地址。

5. 调用sle_set_local_name，设置本地设备名称。

6. 调用sle_set_announce_param，设置设备公开参数

7. 调用sle_set_announce_data，设置设备公开数据

8. 调用sle_start_announce，启动设备公开。

Grant Node：

1. 调用enable_sle，打开SLE开关。

2. 调用sle_announce_seek_register_callbacks，注册设备公开和设备发现回调函数。

3. 调用sle_connection_register_callbacks，注册连接管理回调函数。

4. 调用sle_set_local_addr，设置本地设备地址。

5. 调用sle_set_local_name，设置本地设备名称。

6. 调用sle_set_seek_param，设置设备发现参数。

7. 调用sle_start_seek，启动设备发现，并在回调函数中获得正在进行设备公开的设备信息。

8. 调用sle_connect_remote_device，向对端设备发起连接请求。

9. 调用sle_pair_remote_device，向对端设备发起配对请求。

10. 调用sle_get_paired_devices_num，获取当前配对设备数量。

11. 调用sle_get_paired_devices，获取当前配对设备信息。

12. 调用sle_get_pair_state，获取配对状态。

13. 调用sle_get_connect_role，获取链路角色。

# SSAP Server接口

## 概述

SSAP是SLE发送和接收数据的通用规范，支持在两个SLE设备间进行数据传输。

## 开发流程

使用场景

SSAP Server主要接收对端的请求和命令，向对端发送响应、通知和指示。

功能

SSAP Server提供的接口如表1所示。

表 1 SSAP Server接口描述

接口名称 | 描述 | 参数说明 | 返回信息说明
--- | --- | --- | ---
ssaps_register_server | 注册SSAP server。 注：目前只支持注册一个SSAP server。 | app_uuid：应用UUID指针； server_id：[out] server id指针。 | 接口返回值：错误码。
ssaps_unregister_server | 注销SSAP server。 | server_id：server id。 | 接口返回值：错误码。
ssaps_add_service | 添加服务。 | server_id：server id； service_uuid：服务UUID； is_primary：是否是首要服务。 | 接口返回值：错误码。
ssaps_add_property | 添加特征。 | server_id：server id； service_handle：服务句柄； property：特征信息。 | 接口返回值：错误码。
ssaps_add_descriptor | 添加特征描述符。 | server_id：server id； service_handle：服务句柄； property_handle：特征句柄； descriptor：描述符信息。 | 接口返回值：错误码。
ssaps_add_service_sync | 添加服务同步接口，服务句柄同步返回。 | server_id：server id； service_uuid：服务UUID； is_primary：是否是首要服务； handle：[out]服务句柄指针。 | 接口返回值：错误码。
ssaps_add_property_sync | 添加特征同步接口，特征句柄同步返回。 | server_id：server id； service_handle：服务句柄； property：特征； handle：[out]特征句柄指针。 | 接口返回值：错误码。
ssaps_add_descriptor_sync | 添加特征描述符同步接口，特征描述符句柄同步返回。 | server_id：server id； service_handle：服务句柄； property_handle：特征句柄； descriptor：特征描述符； | 接口返回值：错误码。
ssaps_start_service | 启动服务。 | server_id：server id； service_handle：服务句柄。 | 接口返回值：错误码。
ssaps_delete_all_services | 删除所有服务。 | server_id：server id。 | 接口返回值：错误码。
ssaps_send_response | 发送响应。 | server_id：server id； conn_id：连接ID； param：响应参数。 | 接口返回值：错误码。
ssaps_notify_indicate | 给对端发送通知或指示。 | server_id：server id； conn_id：连接ID； param：通知或指示参数。 | 接口返回值：错误码。
ssaps_notify_indicate_by_uuid | 按照uuid给对端发送通知或指示。 | server_id：server id； conn_id：连接ID； param：通知或指示参数。 | 接口返回值：错误码。
ssaps_set_info | 在连接之前设置 server信息。 | server_id：server id； info： server信息。 | 接口返回值：错误码。
ssaps_register_callbacks | 注册SSAP server回调函数。 | func：用户回调函数。 | 接口返回值：错误码。

开发流程

SSAP server开发的典型流程：注册SSAP server，注册本端属性数据库，接收对端的请求和命令，向对端发送通知和指示，具体编程实例可参考application/samples/bt。

1. 调用enable_sle，打开SLE开关。

2. 调用ssaps_register_callbacks，注册SSAP server回调。

3. 调用sle_announce_seek_register_callbacks，注册设备公开和设备发现回调函数。

4. 调用ssaps_register_server，创建一个server实体。

5. 调用ssaps_add_service_sync、ssaps_add_property_sync、ssaps_add_descriptor_sync和ssaps_start_service注册本端属性数据库，每一个服务及其内容添加完成后调用ssaps_start_service启动服务。

6. 调用sle_set_local_addr，设置本地设备地址。

7. 调用sle_set_local_name，设置本地设备名称。

8. 调用sle_set_announce_param，设置设备公开参数。

9. 调用sle_set_announce_data，设置设备公开数据。

10. 调用sle_start_announce，启动设备公开。

11. 连接建立。

12. 接收对端设备的读写请求，当对端设备读写需要授权的特征或描述符时，调用ssaps_send_response向对端发送响应并修改本端特征值。

13. 当某个特征的客户端特征配置描述符为0x0001时，在特征值变化时调用ssaps_notify_indicate向对端设备发送通知，当某个特征的客户端特征配置描述符为0x0002时，在特征值变化时调用ssaps_notify_indicate向对端设备发送指示。

# SSAP client接口

## 概述

SSAP是SLE发送和接收数据的通用规范，支持在两个SLE设备间进行数据传输。

## 开发流程

使用场景

SSAP Client主要向对端发送请求和命令，接收对端的响应、通知和指示。

功能

SSAP Client提供的接口如表1所示。

表 1 SSAP Client接口描述

接口名称 | 描述 | 参数说明 | 返回信息说明
--- | --- | --- | ---
ssapc_register_client | 注册SSAP client。 注：目前只支持注册一个SSAP client。 | app_uuid：应用UUID指针； client_id：[out] client id指针。 | 接口返回值：错误码。
ssapc_unregister_client | 注销SSAP client。 | client_id：client id。 | 接口返回值：错误码。
ssapc_find_structure | 查找对端服务、特征和描述符。 | client_id：client id； conn_id：连接ID； param：查找参数。 | 接口返回值：错误码。
ssapc_read_req_by_uuid | 向对端发送按照uuid读取请求。 | client_id：client id； conn_id：连接ID； param：读取参数。 | 接口返回值：错误码。
ssapc_read_req | 向对端发送读取请求。 | client_id：client id； conn_id：连接ID； handle：句柄； type：类型。 | 接口返回值：错误码。
ssapc_write_req | 向对端发送写请求。 | client_id：client id； conn_id：连接ID； param：写参数。 | 接口返回值：错误码。
ssapc_write_cmd | 向对端发送写命令。 | client_id：client id； conn_id：连接ID； param：写参数。 | 接口返回值：错误码。
ssapc_exchange_info_req | 向对端发送交换信息请求。 | client_id：client id； conn_id：连接ID； param：交换信息参数。 | 接口返回值：错误码。
ssapc_register_callbacks | 注册SSAP client回调函数。 | func：用户回调函数。 | 接口返回值：错误码。

开发流程

SSAP Client开发的典型流程：注册SSAP Client，查找对端属性数据库，向对端发送请求和命令，接收对端的通知和指示，具体编程实例可参考application/samples/bt。

SSAP Server：

1. 调用enable_sle，打开SLE开关。

2. 调用ssaps_register_callbacks，注册SSAP server回调。

3. 调用sle_announce_seek_register_callbacks，注册设备公开和设备发现回调函数。

4. 调用ssaps_register_server，创建一个server实体。

5. 调用ssaps_add_service_sync、ssaps_add_property_sync、ssaps_add_descriptor_sync和ssaps_start_service注册本端属性数据库，每一个服务及其内容添加完成后调用ssaps_start_service启动服务。

6. 调用sle_set_local_addr，设置本地设备地址。

7. 调用sle_set_local_name，设置本地设备名称。

8. 调用sle_set_announce_param，设置设备公开参数。

9. 调用sle_set_announce_data，设置设备公开数据。

10. 调用sle_start_announce，启动设备公开。

11. 连接建立。

12. 接收对端设备的读写请求，当对端设备读写需要授权的特征或描述符时，调用ssaps_send_response向对端发送响应并修改本端特征值。

13. 当某个特征的客户端特征配置描述符为0x0001时，在特征值变化时向对端设备发送通知，当某个特征的客户端特征配置描述符为0x0002时，在特征值变化时向对端设备发送指示。

SSAP Client：

1. 调用enable_sle，打开SLE开关。

2. 调用ssapc_register_callbacks，注册SSAP client回调。

3. 调用sle_announce_seek_register_callbacks，注册设备公开和设备发现回调函数。

4. 调用ssapc_register_client，创建一个client实体。

5. 递归调用ssapc_find_structure查找对端属性数据库。

6. 如果关注对端某个特征，可调用ssapc_write_req或ssapc_write_cmd将该特征的客户端特征配置描述符写为0x0001或0x0002，前者可使能对端特征通知，后者可使能对端特征指示。

7. 调用读接口ssapc_read_req和写接口ssapc_write_req操作对端属性数据库。

# Low Latency接口

## 概述

Low Latency模块使用星闪协议以极低时延在服务端和客户端之间进行数据传输。

## 开发流程

使用场景

Low Latency模块的功能是开关服务端和客户端的低时延通道，在服务端发送传感器内数据，在客户端侧接收客户端数据。

功能

Low Latency提供的接口如表1所示。

表 1 Low Latency接口描述

接口名称 | 描述 | 参数说明 | 返回信息说明
--- | --- | --- | ---
sle_low_latency_mouse_enable | 打开低时延鼠标。 | - | 接口返回值：错误码。
sle_low_latency_dongle_enable | 打开低时延dongle。 | - | 接口返回值：错误码。
sle_low_latency_mouse_register_callbacks | 注册低时延鼠标回调函数。 | mouse_cbk：鼠标数据回调函数。 | 接口返回值：错误码。
sle_low_latency_set | 设置低时延速率，打开或关闭低时延。 | conn_id：连接ID； enable：是否打开低时延； rate：速率。 | 接口返回值：错误码。
sle_low_latency_dongle_register_callbacks | 注册低时延dongle回调函数。 | dongle_cbk：dongle数据回调函数。 | 接口返回值：错误码。

开发流程

Low Latency开发的典型流程如下：

Dongle：

1. 调用sle_low_latency_dongle_register_callbacks，注册dongle数据回调函数。

2. 调用sle_low_latency_dongle_enable接口，打开dongle低时延通道。

3. 调用sle_low_latency_set设置低时延速率。

4. 接收鼠标数据。

鼠标：

1. 调用sle_low_latency_mouse_register_callbacks，注册鼠标数据回调函数。

2. 调用sle_low_latency_mouse_enable接口，打开鼠标低时延通道。

3. 移动鼠标。

# Transmission Manager接口

## 概述

Transmission Manager模块负责SLE的数据发送，保障了数据成功传输到底层。

## 开发流程

使用场景

Transmission Manager模块实时监控了底层缓冲区数量，数据包因为底层发送繁忙没有发出去时，就会上报发送繁忙通知。

功能

Transmission Manager提供的接口如表1所示。

表 1 Transmission Manager接口描述

接口描述 | 描述 | 参数说明 | 返回信息说明
--- | --- | --- | ---
send_data_cb | SLE发送数据繁忙回调勾子。 | - | -
sle_transmission_register_callbacks | 注册SLE传输管理回调函数。 | func：用户回调函数。 | 接口返回值：错误码。

开发流程

Transmission Manager典型开发流程如下：

SERVER端：

1. 调用sle_transmission_register_callbacks，注册SLE传输管理回调函数。

2. 每次发包前，根据回调勾子反馈的系统忙闲状态，若是空闲状态，继续高速发包；若是流控状态，减小发包速率；若是繁忙状态，停止发包。

# SLE Passkey接口

## 概述

星闪配对有多种鉴权方式可以选择，passkey鉴权是其中之一，passkey鉴权提供了防中间人攻击能力，安全性相对免输入鉴权有提升。

## 开发流程

使用场景

发起星闪配对后，根据用户设置的IO（Input Output）能力决策的鉴权方式决策鉴权方式，当满足条件时，协议栈能够自动协商为passkey鉴权。

功能

SLE提供的passkey相关接口如SLE Passkey接口描述如表1所示。

表 1 SLE Passkey接口描述

接口描述 | 描述 | 参数说明 | 返回信息说明
--- | --- | --- | ---
passkey_req_cb | SLE配对发起后，passkey请求回调勾子。 | conn_id：SLE连接ID。 | -
passkey_notify_cb | SLE配对发起后，passkey确认回调勾子。 | conn_id：SLE连接ID； passkey：通行码数据指针； len：通行码数据长度。 | -
sle_passkey_entry | 通行码输入。 | conn_id：SLE连接ID； passkey：转为数字的通信码数据。 | 成功：ERRCODE_SLE_SUCCESS； 失败：对应错误码。

SLE提供的安全参数设置接口如SLE安全参数设置接口描述如表2所示。

表 2 SLE安全参数设置接口描述

接口描述 | 描述 | 参数说明 | 返回信息说明
--- | --- | --- | ---
sle_set_sec_param | SLE设置安全参数。 | sec_params：SLE安全参数，包含IO能力、配对绑定地址、配对防中间人攻击、地址隐私使能。 | 成功：ERRCODE_SLE_SUCCESS； 失败：对应错误码。

SLE协议提供的IO能力和鉴权方式对应关系如SLE鉴权方式决策描述如表3所示。

表 3 SLE鉴权方式决策描述

- | G节点IO能力
- | 只展示 | 展示，并且可以选择Yes或者No | 只支持键盘 | 没有输入输出 | 支持键盘和展示
T节点IO能力 | 只展示 | 免输入 | 免输入 | Passkey通行码鉴权 | 免输入 | Passkey通行码鉴权
展示，并且可以选择Yes或者No | 免输入 | - | Passkey通行码鉴权 | 免输入 | -
只支持键盘 | Passkey通行码鉴权 | Passkey通行码鉴权 | - | 免输入 | -
没有输入输出 | 免输入 | 免输入 | 免输入 | 免输入 | 免输入
支持键盘和展示 | Passkey通行码鉴权 | - | - | 免输入 | -

IO能力定义参考枚举：sle_io_ability_t

开发流程

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

1. 初始化SLE协议栈之后，互联的两个设备必须调用安全参数设置接口，配置双方设备的IO能力、防中间人攻击标识。

   配对决策使用passkey鉴权时，需将防中间人攻击标识置为：SLE_PAIRING_DEFEND_MITM，双方设备的IO能力按照表SLE鉴权方式决策描述进行设置。

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

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

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

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

6. 输入设备调用passkey输入接口成功后，等待配对完成，典型时长2s~4s。

SLE配对，选择Passkey鉴权异常处理如SLE Passkey异常处理描述，如表4所示。

表 4 SLE Passkey异常处理描述

异常情形 | 异常处理 | 异常影响或措施
--- | --- | ---
passkey输入超时 | 当输入设备端，超过30s没有调用passkey输入接口时，协议栈断开连接。 | 断开后可以重新发起配对
passkey输入错误 | 当输入设备端，输入的passkey值和显示设备不一致时，协议栈直接断开连接。 | 断开后可以重新发起配对

SLE配对，选择Passkey鉴权时，显示设备可选设置默认显示的passkey：

1. 初始化SLE协议栈后，调用安全参数设置接口。

2. 连接端发起连接，连接成功。

3. 显示设备（IO能力：只展示或展示并可以选择Yes或者No）在连接成功后，调用sle_passkey_entry接口设置显示端默认passkey。

4. 任意设备调用配对发起接口，发起配对。

5. 输入设备（IO能力为：只支持键盘或支持键盘和展示）上收到请求后，输入默认passkey。

6. 等待配对完成。

若需要配对密钥在nv中加密存储，需要打开宏CONFIG_NV_SUPPORT_ENCRYPT。在配置界面Middleware->Utils->勾选nv_support encrypt。并在使能协议之前设置配对密钥在nv的保存方式为加密保存，这个设置对蓝牙和星闪同时生效。接口请参考《BS2X100 蓝牙软件开发 指导书》中的gap_ble_set_nv_store_smp_keys_mode。

# SLE Channel Map 接口

## 概述

星闪跳频支持用户自定义跳频信道。

## 开发流程

使用场景

SLE Channel Map 接口典型使用场景是对wifi占用信道进行避让，如wifi为20M，使用信道6，推荐对2427-2447信道进行避让。

如下图，WiFi在2.4g频段被分为14个交叠的、错列的20MHz信道，信道编码从1到14，邻近的信道之间存在一定的重叠范围。

为了提高无线终端无线网络速率，可以增加射频的信道工作带宽。如果把两个20MHz信道捆绑在一起成为40MHz信道，其中一个是主信道，一个是从信道。如果主信道的中心频率高于从信道的中心频率，则为40MHz-，反之则为40MHz+。在2.4G中，两个绑定的信道间隔为4（如1,5；2,6）。

功能

SLE Channel Map提供的接口如表1所示。

表 1 SLE Channel Map接口描述

接口描述 | 描述 | 参数说明 | 返回信息说明
--- | --- | --- | ---
sle_channel_map | 设置Host信道偏好。 广播信道不受此接口影响。 | channel_map: 信道偏好，长度为10的数组，其中每个bit表示当前信道能否使用。 | 接口返回值：错误码。

对于2.4GHz频段，不同带宽信道对应的射频信道中心频率和射频信道号如表2规定。channel_map为一个长度为十的数组，其中每个bit表示当前信道能否使用，字节内信道按照从低到高的顺序，1代表可用，0代表不可用，如数组第二字节为0x03，代表2410，2411信道可用。如果感知周围特定信道收到干扰，可通过 SLE Channel Map 接口规避使用受干扰信道。

表 2 2400MHz频段不同带宽信道对应的射频信道中心频率和射频信道号

射频信道号 | 物理信道号 | 射频信道中心频率(MHz) | 信道带宽 | 射频信道号 | 物理信道号 | 射频信道中心频率(MHz) | 信道带宽
1MHz | 2MHz | 4MHz | 1MHz | 2MHz | 4MHz
0 | 76 | 2402 | Y1 | - | - | 40 | 38 | 2442 | Y | Y | -
1 | 0 | 2403 | Y | - | - | 41 | 39 | 2443 | Y | - | -
2 | 1 | 2404 | Y | Y | - | 42 | 40 | 2444 | Y | Y |
3 | 2 | 2405 | Y | - | Y | 43 | 41 | 2445 | Y |  | Y
4 | 3 | 2406 | Y | Y | - | 44 | 42 | 2446 | Y | Y | -
5 | 4 | 2407 | Y | - | - | 45 | 43 | 2447 | Y | - | -
6 | 5 | 2408 | Y | Y |  | 46 | 44 | 2448 | Y | Y | -
7 | 6 | 2409 | Y |  | Y | 47 | 45 | 2449 | Y | - | Y
8 | 7 | 2410 | Y | Y | - | 48 | 46 | 2450 | Y | Y | -
9 | 8 | 2411 | Y | - | - | 49 | 47 | 2451 | Y | - | -
10 | 9 | 2412 | Y | Y | - | 50 | 48 | 2452 | Y | Y | -
11 | 10 | 2413 | Y | - | Y | 51 | 49 | 2453 | Y | - | Y
12 | 11 | 2414 | Y | Y | - | 52 | 50 | 2454 | Y | Y | -
13 | 12 | 2415 | Y | - | - | 53 | 51 | 2455 | Y | - | -
14 | 13 | 2416 | Y | Y | - | 54 | 52 | 2456 | Y | Y | -
15 | 14 | 2417 | Y | - | Y | 55 | 53 | 2457 | Y | - | Y
16 | 15 | 2418 | Y | Y | - | 56 | 54 | 2458 | Y | Y | -
17 | 16 | 2419 | Y | - | - | 57 | 55 | 2459 | Y | - | -
18 | 17 | 2420 | Y | Y | - | 58 | 56 | 2460 | Y | Y | -
19 | 18 | 2421 | Y | - | Y | 59 | 57 | 2461 | Y | - | Y
20 | 19 | 2422 | Y | Y | - | 60 | 58 | 2462 | Y | Y | -
21 | 20 | 2423 | Y | - | - | 61 | 59 | 2463 | Y | - | -
22 | 77 | 2424 | Y1 | - | - | 62 | 60 | 2464 | Y | Y | -
23 | 21 | 2425 | Y | - | - | 63 | 61 | 2465 | Y | - | Y
24 | 22 | 2426 | Y | Y | - | 64 | 62 | 2466 | Y | Y | -
25 | 23 | 2427 | Y | - | - | 65 | 63 | 2467 | Y | - | -
26 | 24 | 2428 | Y | Y | - | 66 | 64 | 2468 | Y | Y | -
27 | 25 | 2429 | Y | - | Y | 67 | 65 | 2469 | Y | - | Y
28 | 26 | 2430 | Y | Y | - | 68 | 66 | 2470 | Y | Y | -
29 | 27 | 2431 | Y | - | - | 69 | 67 | 2471 | Y | - | -
30 | 28 | 2432 | Y | Y | - | 70 | 68 | 2472 | Y | Y | -
31 | 29 | 2433 | Y | - | Y | 71 | 69 | 2473 | Y | - | Y
32 | 30 | 2434 | Y | Y | - | 72 | 70 | 2474 | Y | Y | -
33 | 31 | 2435 | Y | - | - | 73 | 71 | 2475 | Y | - | -
34 | 32 | 2436 | Y | Y | - | 74 | 72 | 2476 | Y | Y | -
35 | 33 | 2437 | Y | - | Y | 75 | 73 | 2477 | Y | - | Y
36 | 34 | 2438 | Y | Y | - | 76 | 74 | 2478 | Y | Y | -
37 | 35 | 2439 | Y | - | - | 77 | 75 | 2479 | Y | - | -
38 | 36 | 2440 | Y | Y | - | 78 | 78 | 2480 | Y1 | - | -
39 | 37 | 2441 | Y | - | Y | - | - | - | - | - | -

注1：射频信道号0，22和78对应1MHz信道为广播信道，物理信道号76，77和78对应1MHz信道为广播信道。

开发流程

SLE Channel Map典型开发流程如下：

CLIENT端：

1. 当上报连接成功时调用sle_channel_map，设置信道偏好。