前言

概述

SP31V100通过API（Application Programming Interfaces）向开发者提供使用SLP的相关接口，本文档详细介绍SLP的API和开发流程。

产品版本

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

产品名称	产品版本
SP31	V100

读者对象

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

• 技术支持工程

• 软件开发工程师

符号约定

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

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

修改记录

文档版本	发布日期	修改说明
03	2025-06-24	更新“错误码”小节内容。 更新“功能”小节内容。 新增“降成本适配”小节内容。
02	2025-04-23	更新“错误码”小节内容。 更新“功能”小节内容。
01	2024-07-29	第一次正式版本发布。 更新“错误码”小节内容。 更新“SLP接口”小节内容。
00B01	2024-07-04	第一次临时版本发布。

概述

SP31V100通过API（Application Programming Interface）面向开发者提供SLP功能的开发和应用接口。

错误码

SLP接口调用完成或SLP业务执行过程中遇到异常会上报错误码，用户可通过错误码排查问题，错误码分为以下三个级别：

INFO：表示接口执行成功；

WARNING：提示类错误；典型的出现场景是状态重复切换；该错误不影响正常功能，可忽略或者用于排查冗余的代码流程；

ERROR：严重错误，可能会导致业务启动失败，需要排查原因避免此类错误的出现。

表 1 SLP错误码（ErrcodeSlpClient）

序号	定义	实际数值	描述	常见产生原因	级别
1	ERRCODE_SLPC_SUCCESS	0	执行成功	正常执行	INFO
2	ERRCODE_SLPC_MALLOC_FAILED	0x80009600	申请动态内存失败错误码	内存不足，或者内存申请过程出现异常	ERROR
3	ERRCODE_SLPC_MEMCPY_FAILED	0x80009601	内存拷贝失败错误码	内存拷贝过程异常	ERROR
4	ERRCODE_SLPC_SEND_PAYLOAD_FAILED	0x80009602	发送负载失败错误码	没有注册发送函数接口	ERROR
5	ERRCODE_SLPC_RECV_PAYLOAD_FAILED	0x80009603	接收负载失败错误码	检测到一段时间没有收到测量值消息的时候会上报该错误码，此时业务内部会执行重启测距流程进行自恢复。若周期性的上报该错误码表示流程业务异常，无法恢复，需要排查原因，如：窄带通信流程异常、对端slp加载失败等	WARNING/ERROR
6	ERRCODE_SLPC_POWER_ON_FAILED	0x80009604	上电加载失败错误码	上电加载过程出现异常	ERROR
7	ERRCODE_SLPC_POWERD_ON	0x80009605	SLP已经上电加载错误码	SLP已经上电，又收到了上电命令	WARNGING
8	ERRCODE_SLPC_INCORRECT_PARAM	0x80009606	参数设置失败错误码	测距启动命令里的参数/本机属性参数 设置不正确	ERROR
9	ERRCODE_GET_SESSION_KEY_FAILED	0x80009607	会话密钥获取失败错误码	没有从窄带获取到会话密钥	ERROR
10	ERRCODE_SLPC_QUEUE_WRITE_FAILED	0x80009608	消息队列写入失败错误码	消息队列已满，再次写入会失败	ERROR
11	ERRCODE_SLPC_START_RANGING_FAILED	0x80009609	启动测距失败错误码	SLP还没上电时，发送了测距启动命令， 或者切换窄带时钟失败	ERROR
12	ERRCODE_SLPC_SET_LOCAL_ATT_FAILED	0x8000960A	设置本机属性失败错误码	设置本机属性的消息为空消息	ERROR
13	ERRCODE_SLPC_ALREADY_IN_RANGING	0x8000960B	已经在测距中错误码	已经启动测距了，又收到了测距启动命令	WARNGING
14	ERRCODE_SLPC_ALREADY_STOP_RANGING	0x8000960C	已经停止测距错误码	测距已经停止了，又收到了停止测距的命令	WARNGING
15	ERRCODE_SLPC_ALREADY_PAUSE_RANGING	0x8000960D	已经暂停测距错误码	测距已经暂停了，又收到了暂停测距的命令	WARNGING
16	ERRCODE_SLPC_ALREADY_SLEEP	0x8000960E	已经在睡眠中错误码	已经睡眠了，又收到了睡眠的命令	WARNGING
17	ERRCODE_SLPC_STATE_ERROR	0x8000960F	slp状态错误错误码	在收到继续测距命令时，测距状态不是暂停测距	WARNGING
18	ERRCODE_SLPC_LOCAL_IMU_READ_DATA	0x80009610	本端imu读数据异常错误码	本端IMU读数异常	ERROR
19	ERRCODE_SLPC_PEER_IMU_READ_DATA	0x80009611	对端imu读数据异常错误码	对端IMU读数异常	ERROR
20	ERRCODE_SLPC_POWERING_ON	0x80009612	SLP正在上电中错误码	SLP正在上电加载中，又收到了上电命令	WARNGING
21	ERRCODE_SLPC_POWERING_OFF	0x80009613	SLP在下电中错误码	SLP正在下电中，又收到了下电命令	WARNGING
22	ERRCODE_SLPC_POWERD_OFF	0x80009614	SLP已经下电错误码	SLP已下电， 又收到了下电命令	WARNGING
23	ERRCODE_SLPC_MAX	0x800097FF	SLP错误码最大值		-

SLP接口

• 功能

• RF Switch配置

• 开发流程

功能

表 1 SLP接口描述

接口名称	描述	参数说明	返回信息说明
SlpTask	SLP线程主函数	-	-
SlpPowerOnCommand	SLP上电命令，完成SLP加载	-	错误码
SlpStartRangingCommand	SLP启动测距命令	codeLen：前导码长度； syncCodeIdx：sync段的码字索引值； syncSymNum：sync段的符号数量； ctsSegNum：cts域中segment段的数量； ctsSegSymNum：一个segment段中的符号数量； gapBaseSymNum：gap段基准的符号数量； ctsCpLen：cts段中cp长度； secMode：安全模式； encryptMode：加密模式； sessionKeyMode：会话密钥模式； sessionKeyIdx：会话密钥索引值，会话密钥模式是宽带共享密钥时有效，取值范围0~15； chIdx：通道号； usageMode：SLP使用模式； slpRangingMode：SLP测距模式； multiNodeMode：SLP多节点模式； rangingRoundUsage：SLP测距轮用法； mrSource：slp测量值请求源； rangingFreq：测距频率，最高频率100Hz，遥控器场景取值：1~20Hz； validRoundNum：有效测距轮数，取值范围：0~255，其中0表示无限轮； aoxDirection：测角方向； firstAoxAntDis：第一测角帧天线间距 单位：nm； nbSyncMode：窄带同步模式； deviceNum：参与测距的设备个数，取值：2； sessionId：会话标识符，随机值，每次启动测距，值不同； txPower：TX功率码字； deviceAddr：设备地址列表，第1个是测距发起者的地址。	错误码
SlpStopRangingCommand	SLP停止测距：SLP不工作	-	错误码
SlpPauseRangingCommand	SLP暂停测距：宽窄带的通信关闭	-	错误码
SlpContinueRangingCommand	SLP继续测距：宽窄带通信恢复	-	错误码
SlpPowerOffCommand	SLP下电	-	错误码
SlpSleepCommand	SLP睡眠	-	错误码
SlpSetLocalAttCommand	设置本机特性	localAddr：本机地址； screenParam：屏幕参数。 rfSwParam：RF switch参数	错误码
SlpRecvPayload	SLP接收负载	payload：负载指针； payloadLen：SLP负载长度，取值范围[0, 255]。	错误码
SlpRegisterSendPayloadCallback	注册SLP发送负载回调	cbk：发送负载的回调函数	错误码
SlpRegisterReportCallbacks	注册SLP上报结果回调函数	func：回调函数，包括： SlpReportCursorCallback rptCursorCbk：SLP上报光标和IMU原始数据回调函数 SlpReportRangingCallback rptRangingCbk：SLP上报测距结果回调函数 SlpReportErrcodeCallback rptErrcodeCbk：SLP上报错误码回调函数 SlpReportCirCallback rptCirCbk：slp上报cir回调函数 SlpReportVersionCallback rptVersionCbk：slp上报版本号回调函数 SlpReportCfoCallback rptCfoCbk：slp上报cfo和当前帧的cfo阈值	错误码
SlpRegisterCommandCallbacks	注册SLP命令回调	func：上层命令回调函数，包括： SlpPowerOnCallback powerOnCbk：SLP上电命令回调函数； SlpStartRangingCallback startRangingCbk：SLP启动测距命令回调函数； SlpStopRangingCallback stopRangingCbk：SLP停止测距回调函数； SlpPauseRangingCallback pauseRangingCbk：SLP暂停测距回调函数； SlpContinueRangingCallback continueRangingCbk：SLP继续测距回调函数； SlpPowerOffCallback powerOffCbk：SLP下电命令回调函数； SlpSleepCallback sleepCbk：slp睡眠命令回调函数； SlpEnCirReportCallback enCirReportCbk：slp打开cir上报命令回调函数； SlpDisCirReportCallback disCirReportCbk：slp关闭cir上报命令回调函数 SlpSetLocalAttCallback setLocalAttCbk：SLP设置本机属性回调函数。	错误码
SlpClickDebounceCommand	按键消抖命令	state：按键状态信息，0表示释放，1表示按下	错误码
SlpSetCursorSpeedCommand	动态切换光标灵敏度命令	mode：速度模式	错误码

RF Switch配置

• 接口说明

• 参数配置示例

接口说明

芯片使用ANT_SW_CTRL_0~ANT_SW_CTRL_5共6个管脚控制RF Switch的射频链路切换，用户可根据前端硬件设计进行配置，使用接口参考表1

表 1 RF Switch配置接口说明

接口	描述	参数	参数描述
SlpSetLocalAttCommand	设置本地参数	rfSwParam	RF Switch参数配置
SlpRfSwParam	射频开关参数配置结构体	pwrCtrl	射频开关电源是否独立控制，类型：bool true: 需要拉高nb_wakeup_ctrl管脚上电RF Switch false: RF Switch 默认上电,，软件不需要控制
		antSwCtrlEn	射频开关控制管脚使能，类型：SlpRfSwBit bit0~bit5对应ant_sw_ctrl0~ant_sw_ctrl5控制管脚 1: 开启 0: 关闭
		ant0Code	天线0的射频开关切换配置码字，类型：SlpAntSwCode 天线0定义：遥控器按键朝上并指向电视时左侧的天线
		ant1Code	天线1的射频开关切换配置码字，类型：SlpAntSwCode 天线1定义：遥控器按键朝上并指向电视时右侧的天线
		ant2Code	当前未使用
SlpAntSwCode	射频链路切换码字结构体	tx	天线发送信号时的码字，类型：SlpRfSwBit
		rx	天线接收信号时的码字，类型：SlpRfSwBit
SlpRfSwBit	射频开关控制码字	ctrl0~ctrl5	类型：uint8_t bit0~bit5对应ant_sw_ctrl0~ant_sw_ctrl5的控制 1：开启/拉高 0：关闭/拉低

参数配置示例

电视指向参考设计板的射频链路参数配置可参考表1

表 1 参考设计板RF Switch配置参数

参考设计板类型	pwrCtrl	antSwCtrlE	ant0Code		ant1Code		ant2Code
			TX	RX	TX	RX	TX	RX
RCU	false	0b000011	0b000010	0b000001	0x0	0b000000	0x0	0x0
Dongle	false	0b000001	0b000000	0b000001	0x0	0x0	0x0	0x0

开发流程

以Air Mouse场景为例，仅涉及SLP接口的开发说明，具体编程实例可参考application/samples/products/air_mouse。

Air Mouse侧：

1. 调用SlpRegisterCommandCallbacks，注册SLP命令回调函数。

2. 调用SlpSetLocalAttCommand，设置本机特性。

3. 调用SlpRegisterReportCallbacks，注册坐标上报回调函数。

4. 调用SlpRegisterSendPayloadCallback，注册SLP发送payload函数。

5. SLE连接配对成功，调用SlpPowerOnCommand，加载SLP。

6. 调用SlpStartRangingCommand，启动SLP测距。

7. 在交互过程中，调用SlpRecvPayload，接收对端发来的payload。

8. 如果想让SLP睡眠，调用SlpSleepCommand。如果需要唤醒，则再次调用SlpStartRangingCommand，启动SLP测距。

9. 如果SLE断连，调用SlpPowerOffCommand，SLP下电。

Dongle侧：

1. 调用SlpRegisterCommandCallbacks，注册SLP命令回调函数。

2. 调用SlpSetLocalAttCommand，设置本机特性。

3. 调用SlpRegisterSendPayloadCallback，注册SLP发送payload函数。

4. 调用SlpRegisterCommandCallbacks，注册命令回调函数。

5. SLE连接配对成功，调用SlpPowerOnCommand，加载SLP。

6. 在交互过程中，调用SlpRecvPayload，接收对端发来的payload。

7. 如果想让SLP睡眠，调用SlpSleepCommand。dongle侧是受控方，由mouse侧负责唤醒，通过再次发送SlpStartRangingCommand命令。

8. 如果SLE断连，调用SlpPowerOffCommand，SLP下电。

以air mouse场景为例，对应的SLP工作时序图，如图1所示。

图 1 air mouse sample中SLP工作流程

降成本适配

• SLE

• SLP

SLE

1. 蜂鸣器和按键矩阵适配。

2. 原uart h0 tx管脚sle的hso log，改为按键。

3. 原adc en 管脚改为按键。

SLP

1. 遥控器slp power on管脚已给触摸使用，tiot中操作power on管脚的都要去掉；dongle侧保持原样。

2. slp power ctrl管脚反向，拉低上电，拉高下电，遥控器和dongle均需要改动。

3. dongle打开ldo供电。

缩略语

A
ADDR	Address	地址
ANT	Antenna	天线
AOX	AOA（angle of arrival）/AOD（angle of departure）	到达角/出发角的统称
API	Application Programming Interface	应用编程接口
C
CBK	Callback	回调
CHIDX	Channel Index	通道号
CTSCPLEN	CTS Cylic Prefix Length	CTS 循环前缀长度
CTS	CIR Training Sequence	信道冲激响应（CIR）训练序列
D
DIS	Distance	距离
I
ID	Index	索引
IDX	Index	索引
F
FREQ	Frequency	频率
M
MRSOURCE	Measurement Request Source	slp测量值请求源
N
NB	Narrow Band	窄带
R
RPT	Report	上报
S
SECMODE	Security Mode	安全模式
SEG	Segment	段
SLP	Sychronous Link Positioning	星闪高精定位
SLPC	SLP Client	SLP客户端
SW	Switch	开关
SYNCSYMNUM	Sync Symbol Number	sync段的符号数量