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

### 该页内容

- 前言
- 射频功率配置说明
  - 产线TX测试功率
    - BLE/SLE GFSK TX
      - 功率档位说明
    - SLE PSK TX
      - 功率档位说明
  - 定制化最大功率
    - NV存储定制化功率
      - NV介绍
      - 定制化NV结构
      - NV的读写
      - 读NV接口
      - 写NV接口
    - 应用NV配置
  - RT201 FEM 配置说明
  - Sample广播功率
    - SLE广播
      - SLE广播参数结构
      - 广播功率配置
    - BLE广播
      - BLE广播参数结构

# 前言

概述

本文档详细的描述了BS2X各种场景下功率调整方式以及具体的操作指导，同时提供了常见的注意事项。

读者对象

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

- 技术支持工程师

- 软件开发工程师

符号约定

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

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

修改记录

文档版本 | 发布日期 | 修改说明
--- | --- | ---
04 | 2025-08-07 | 更新“BLE广播参数结构”小节内容。
03 | 2025-01-14 | 更新“定制化NV结构”小节内容。
02 | 2024-09-13 | 更新“定制化NV结构”小节内容。
01 | 2024-05-22 | 第一次正式版本发布。

# 射频功率配置说明

## 产线TX测试功率

### BLE/SLE GFSK TX

#### 功率档位说明

BS2X BLE/SLE GFSK定义了0~5一共6个功率档位，最大档位是5档，默认为6dBm。每往下一档递减2dB。

档位 | 参数描述
--- | ---
5 | 6dBm
4 | 4dBm
3 | 2dBm
2 | 0dBm
1 | -2dBm
0 | -4dBm

> 说明： 产测BLE测试模式常发（非信令）的功率为上电默认的最大功率档位，只能通过配置“最大功率”修改（详见“定制化最大功率”），不能通过指令参数调整功率档位。

测试模式SLE GFSK调制的功率调整可通过修改AT指令第二个参数实现。

1M GFSK测试模式TX：

    AT+SLETX=0,5,255,0,0,0,0,0,0,50

第二个参数为5，说明此时发射功率为最大档6dBm。

### SLE PSK TX

#### 功率档位说明

BS2X SLE PSK定义了0~5共6个功率档位，最大档位是5档，默认为2dBm。每往下一档递减2dB。

档位 | 参数描述
--- | ---
5 | 2dBm
4 | 0dBm
3 | -2dBm
2 | -4dBm
1 | -6dBm
0 | -8dBm

测试模式SLE PSK 调制的功率调整可通过修改AT指令第二个参数实现。

1M QPSK测试模式TX：

AT+SLETX=0,5,255,0,0,2,2,3,2,50

第二个参数为5，说明此时发射功率为最大档2dBm。

phy和帧类型、导频、编码等参数配置请参见《BS2XV100 射频 AT测试指南》。

## 定制化最大功率

### NV存储定制化功率

由于产品特性差异，sdk开发者可根据需求修改BLE TX和SLE TX信号的最大功率，修改后，产线测试和商用版本实际业务场景的最大功率将被定制化，即最大档位（5档）的实际功率变为定制化的功率，之后的4-0档依次递减2dB。

由于实际影响功率的寄存器配置会在下电后清零，因此需要把功率配置保存在非易失性内存（Non-Volatile Memory）中。

注意：通过修改NV配置最大功率影响整个芯片的射频TX，即包括产线测试的TX信号强度和实际业务的最大档位发射信号强度。

#### NV介绍

NV全称Non-Volatile Memory ，即非易失性内存。BS2X的NV是一块flash memory。

#### 定制化NV结构

#define BTH_BLE_NV_RESERVED_ID 0xE

NV结构体使用预留的ID为0xE的结构

    typedef struct {            /* Keys that indexes by addr */
        uint8_t reserve[BTH_BLE_RESERVE_LEN];
    } bth_ble_nv_reserved_struct_t;
    "bth_reserve_struct": {
        "key_id": "0xE",
        "key_status": "alive",
        "structure_type": "bth_ble_nv_reserved_struct_t",
        "attributions": 1,
        "value": [
        [
        01, 02, 63, 24, 36, 0, 8, 05, 0, 0, 0, 0, 0, 0, 0, 0,
        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
        ]
        ]
    },

目前已使用的字节如下：

序号 | 字节偏移 | 含义解释
--- | --- | ---
1、2 | 0~1 Byte | 定制化使能flag， bit[0]：BLE、SLE GFSK功率enable。 bit[1]：SLE PSK功率enable。
3 | 2 Byte | BLE、SLE GFSK最大功率 取值范围：[-12, 6] 单位：dBm *高功率场景：配置7或8，实际功率可达到8dBm左右。
4 | 3 Byte | SLE PSK 最大功率 取值范围：[-16, 2] 单位：dBm 注意：高功率场景：BLE字段配置7或8，SLE实际功率可达到4dBm左右。（SLE字段不需要修改，默认2dBm）

例如：修改BLE和SLE GFSK调制信号的功率最大值为2dBm（默认最大6dBm），以及修改SLE PSK调制的最大功率为-2dBm（默认最大2dBm）需要修改以下几点：

- 第三字节的6改为2（十进制），第四字节2改为-2（十进制，负数直接写-号）。

- 第一字节的bit[0]写1，即使能BLE功率的配置；bit[1]写1，即使能SLE PSK调制的功率配置，合起来，第一字节的低两bit位拉高，即0b00000011，第一字节写成3（十进制）。

注意：以上两个修改缺一不可，通过接口修改NV时，也需要修改第一字节的flag标志位。

#### NV的读写

NV只能根据结构体ID整块读写，不能单独读取几个字节。 写NV时需要先整块读出，可根据偏移修改部分内容后写回。

#### 读NV接口

errcode_t uapi_nv_read(uint16_t key, uint16_t kvalue_max_length, uint16_t *kvalue_length, uint8_t *kvalue);

uapi_nv_read | 读取指定NV数据项的值，默认不获取key的属性值。
key | 要读取的NV项的key ID，用于索引。
kvalue_max_length | 允许存储数据的最大长度，单位：Byte。
*kvalue_length | 实际读取到的数据长度（读取以四字节对齐）。
*kvalue | 指向保存读取数据的buffer的指针。

使用实例：

    uint16_t key = TEST_KEY;
    uint16_t key_len= test_len;
    uint16_t real_len= 0;
    uint8_t *read_value = uapi_malloc(key_len);
    if (uapi_nv_read(key, key_len, &real_len, read_value) != ERRCODE_SUCC) {
        /* ERROR PROCESS */
        uapi_free(read_value);
        return ERRCODE_FAIL;
    }
    /* APP PROCESS */
    uapi_free(read_value);
    return ERRCODE_SUCC;

#### 写NV接口

errcode_t uapi_nv_write(uint16_t key, const uint8_t *kvalue, uint16_t kvalue_length);

uapi_nv_write | 写入NV数据项，默认属性Normal，无回调函数。
key | 要写入的NV项的key ID，用于索引。
*kvalue | 指向要写入的NV项的值的指针。
kvalue_length | 写入数据的长度，单位：Byte。

使用实例：

写入默认Normal类型NV。

    uint8_t *test_nv_value;  /* 要写入的NV value保存在test_nv_value中 */
    uint32_t test_len = 15;  /* 长度为test_len ，例中为15*/
    uint16_t key = TEST_KEY; /* TEST_KEY 为该Key的ID*/
    uint16_t key_len= test_len;
    uint8_t *write_value = uapi_malloc(key_len);
    (void)memcpy_s(write_value, key_len, test_nv_value, key_len);
    errcode_t nv_ret_value = uapi_nv_write(key, write_value, key_len);
    if (nv_ret_value != ERRCODE_SUCC) {
        /* ERROR PROCESS */
        uapi_free(wrt_value);
        return ERRCODE_FAIL;
    }
    /* APP PROCESS */
    uapi_free(wrt_value);
    return ERRCODE_SUCC;

### 应用NV配置

上电时，调用读NV接口把功率配置读出，配置到实际生效的寄存器中，应用代码sdk不可见。

## RT201 FEM 配置说明

> 说明： 本章仅供前端使用RT201型号的FEM模组的产品参考。

NV结构参见“定制化NV结构”章节。

其中控制RT201 FEM使能的字节为第7个字节，写1表示版本带FEM配置。

除了修改app.json , 还提供AT指令”AT+FEMENABLE=1” ”AT+FEMENABLE=0”来使能和关闭FEM配置，AT指令发送后需重新上下电生效。

## Sample广播功率

SDK开发sample时，需要手动配置广播参数，其中广播功率的大小也可以通过参数配置。

### SLE广播

#### SLE广播参数结构

如图announce_tx_power为广播功率参数，取值范围[20,-127]。

> 说明： 取值范围的单位是dBm，实际广播发送功率最大值取决于第二章定制化最大功率的配置，如果没有定制，则默认为6dBm。

#### 广播功率配置

实际功率档位为当前配置的功率向下最接近的档位功率。

例如：announce_tx_power配置为18，实际发出的广播功率就是最大档位6dBm。如果配置的值小于-4，则直接返回0，也就是最低档位，实际发出功率为-4dBm。

### BLE广播

#### BLE广播参数结构

实际功率档位为当前配置的功率向下最接近的档位功率。

例如：tx_power配置为10，实际发出的广播功率则为最大档位6dBm。如果配置的值小于-4，则直接返回0，也就是最低档位，实际发出功率为-4dBm。