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

### 该页内容

- 前言
- 编译&测试
  - 编译说明
  - 测试说明
- 系统状态管理
  - 系统状态
  - 接口说明
  - 状态机原理
    - 概述
    - 详细介绍
  - 使用配置说明
- 用户指南

# 前言

概述

本文档详细介绍了BS2XV100 低功耗sample的使用方法，旨在方便用户开发。用户在实际开发中可以完全重新写一套状态管理的代码，也可以利用该sample进行拓展开发。

BS2X系列包含BS21/BS22/BS26，本文档以BS21为例。

读者对象

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

- 技术支持工程师

- 软件开发工程师

符号约定

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

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

修改记录

文档版本 | 发布日期 | 修改说明
--- | --- | ---
04 | 2025-08-07 | 更新“详细介绍”章节内容。
03 | 2025-05-30 | 更新“用户指南”章节内容。
02 | 2025-01-14 | 更新“用户指南”章节内容。
01 | 2024-05-15 | 第一次正式版本发布。
00B01 | 2024-03-01 | 第一次临时版本发布。

# 编译&测试

## 编译说明

1. 打开IDE工具目录，双击env_start.bat打开终端命令行。

2. 命令行进到SDK对应路径。

3. 执行“python build.py”。

   输入bs21-pm序号回车即执行编译。

4. 去SDK目录下tools\pkg\fwpkg\bs21取镜像包烧录即可。

## 测试说明

1. 烧录bs21-pm对应镜像。

2. 搜索并连接蓝牙“BS21-pm-demo”（pm_ble_server_adv.c中配置）。

3. 系统会根据宏 DURATION_MS_OF_WORK_TO_STANDBY 设置的时间进入保连。

4. 系统会根据宏 DURATION_MS_OF_STANDBY_TO_SLEEP 设置的时间进入睡眠。

5. 系统会根据宏 PM_SAMPLE_GPIO_NUM 设置的管脚拉低时唤醒，之后重复步骤3和步骤4。

# 系统状态管理

## 系统状态

低功耗sample中将系统状态划分为工作（work）、待机（standby）和睡眠（sleep），状态切换如图1所示。

图 1 系统状态机

1. 工作空闲一段时间进待机（保连）状态

2. 待机（保连）空闲一段时间进深睡状态

3. 待机（保连）状态唤醒后进入工作状态

4. 深睡状态唤醒后进入工作状态

> 说明： 待机（standby）态时系统也会进睡眠，只是在此sample中“待机”时蓝牙未断连，“睡眠”时蓝牙断连了。 如果用户不需要“保连”或者“断连”，那么系统只需进入“待机”态即可，用户只需在状态转移回调函数中实现相应功能即可。

## 接口说明

- 注册低功耗状态管理接口：errcode_t uapi_pm_state_trans_handler_register(pm_state_trans_handler_t *handler);

      typedef struct pm_state_trans_handler {
          pm_state_trans_func_t work_to_standby;  /* 工作态转换到待机状态（如interval调大） */
          pm_state_trans_func_t standby_to_sleep; /* 工作态转换到深睡状态（如断连、关广播） */
          pm_state_trans_func_t standby_to_work;  /* 待机态转换到工作状态（如interval调小） */
          pm_state_trans_func_t sleep_to_work;    /* 深睡态转换到工作状态（如开广播） */
      } pm_state_trans_handler_t;

- 设置低功耗状态转移的时间：errcode_t uapi_pm_set_state_trans_duration(uint32_t work_to_standby, uint32_t standby_to_sleep);

  - work_to_standby：从工作到待机的时间，单位：ms。

  - standby_to_sleep：从待机到睡眠的时间，单位：ms。

- 重置工作状态接口（重置工作到待机的计时器）：errcode_t uapi_pm_work_state_reset(void);

- 低功耗唤醒处理接口（在外设唤醒的时候调用以切换到工作状态）：errcode_t uapi_pm_wkup_process(uintptr_t arg);

## 状态机原理

### 概述

由《BS2XV100 低功耗 开发指南》中的介绍可以知道，睡眠管理模块在LiteOs的IDLE线程中被调用到，满足睡眠条件系统则进睡眠。

图 1 睡眠条件

其中一个条件是“不存在睡眠否决票”，系统状态机入口中有投了一个睡眠否决票，如图2所示。

图 2 pm_sys初始化

睡眠管理接口判定存在否决票则不进睡眠，在“适当”的时候将该否决票移除掉，则系统就可以进睡眠。

对于BS2X的产品形态来说，一般要控制系统“何时”进入保连态、“何时”进入睡眠态，所以这里必然要有一个“定时器”。

低功耗sample中利用OsTick实现了这一计时功能（当然，用户也可以用软Timer或者周期性线程实现）。

### 详细介绍

pm_sys_entry初始化时，创建了一线程，即pm_sys_task，该线程由消息触发进入：

以下场景会写消息队列：

1. “工作->待机”或者“待机->睡眠”定时时间到，如下：

2. 由“待机”态或“睡眠”态唤醒时，主动切换到“工作”态，如下：

状态切换时会调用用户由 uapi_pm_state_trans_handler_register 接口注册的状态切换回调函数，用户需在此回调函数中实现，BT保连、断连、唤醒回连等参数配置。

此外，系统在睡眠时（standby或sleep），用户需在相应回调函数中注册唤醒源，在唤醒时需对用户所使用的外设进行恢复。

示例见：application/samples/products/lowpower/lowpower.c

> 说明： BS2XV100睡眠时CPU和绝大多数外设会下电，唤醒后SDK中有对CPU和部分通用外设进行恢复，用户自己初始化的外设需要在状态机管理接口中自行恢复。 详情见《BS2XV100低功耗 开发指南》。

## 使用配置说明

图 1 KConfig配置

- KConfig中打开宏①，即可开启pm_sys这块驱动，之后使用2.2章节中的接口说明即可。

- KConfig中打开宏②，即可开启pm_sys的消息队列功能，建议打开。

- KConfig中修改宏③，即可调整消息队列栈空间大小，默认2K。

> 说明： 消息队列可以起到缓冲、异步、解耦等作用，这里更适合消息队列的使用，但是消息队列使用了线程，增加了一部分空间。理论上，非内存紧缺的情况下，强烈建议使用消息队列。 非消息队列的方式虽然节省了一些空间，但是很多软件处理是直接放在中断中进行的，这里软件处理时间长可能会导致其他中断被阻塞。 此外，消息队列的方式可扩展性也更强，用户在后续拓展开发时也更方便添加新的实例或节点。

# 用户指南

1. 低功耗sample提供了一种业务状态机管理的方法，这一层代码属于业务逻辑，本应由用户自行实现。SDK中通过该sample向用户演示了一套状态管理示例方法，旨在方便用户开发。用户在实际开发中可以完全重新写一套状态管理的代码，也可以利用该sample进行拓展开发。

2. 低功耗sample功能比较简单，用户在实际使用时，如果要基于该sample进行开发，肯定要进行适当拓展的。

3. 低功耗sample中使用的BT相关的接口仅提供参考，后续客户有扩展功能开发，请参考协议说明。

4. 低功耗sample旨在演示低功耗管理/开发方法，仅借用BLE接口作了个演示，用户实际开发时也会涉及到SLE场景以及BLE和SLE共存场景，在此无法提供这一开发指导。

5. 用户在开发拓展之前可以先基于此sample简单做个功耗测试，以对功耗情况有个大概了解。

6. pm_sys定时状态机任务优先级被设定为最低的30，如需使用请注意任务优先级关系，不建议将其他任务的优先级设置为30。

> 说明： uapi_pm_work_state_reset 用来重置计时器，不重置的话到了“work_to_standby”的设定时间，系统就会进入待机，该sample中在 PM_SAMPLE_GPIO_NUM 拉低时调用该接口进行定时器重置。用户实际使用场景可能会更加复杂，有时可能无法及时调用该接口重置定时器。 在用户实际使用时，除了 uapi_pm_work_state_reset 接口，也可以灵活使用 uapi_pm_set_state_trans_duration 接口，该接口会控制“work_to_standby”和“standby_to_sleep”的定时器时间，灵活设置该时间也可以达到控制“不进睡眠”和“何时进睡眠”的效果。