前言

概述

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

产品版本

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

产品名称

产品版本

SP31

V100

读者对象

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

  • 技术支持工程

  • 软件开发工程师

概述

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

错误码

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

INFO：表示接口执行成功；

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

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

表 1 SLP错误码

序号

定义

实际数值

描述

常见产生原因

级别

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

接收负载失败错误码

接收对端发送的数据失败，一般说明对端发送数据异常

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_UART_BUFFER_TOO_SMALL

0x80009615

UART缓冲区过小错误码

buffer设置过小

ERROR

24

ERRCODE_SLPC_UART_SEND_FAIL

0x80009616

UART发送失败

UART发送失败

ERROR

25

ERRCODE_SLPC_NB_CFO_LOSS

0x80009617

窄带CFO丢失

窄带CFO丢失

WARNGING

-

ERRCODE_SLPC_MAX

0x800097FF

SLP错误码最大值

-

-

接口

通用

线程主函数

表 1 SLP线程主函数

接口名称

描述

参数说明

返回信息说明

备注

SlpTask

SLP线程主函数

-

-

-

设置UART缓冲区

表 1 设置UART缓冲区接口

接口名称

描述

参数说明

返回信息说明

备注

SlpSetUartBuffer

设置UART缓冲区

info：缓冲区参数

错误码

-

上电

表 1 上电接口

接口名称

描述

参数说明

返回信息说明

备注

SlpPowerOnCommand

上电命令，完成SLP加载

-

错误码

-

SlpPowerOnCallback

上电命令执行结果回调

-

错误码

-

下电

表 1 下电接口

接口名称

描述

参数说明

返回信息说明

备注

SlpPowerOffCommand

下电

-

错误码

-

SlpPowerOffCallback

下电命令执行结果回调

-

错误码

-

设置本机属性

表 1 设置本机属性接口

接口名称

描述

参数说明

返回信息说明

备注

SlpSetLocalAttCommand

设置本机属性
  • localAddr：本机地址

    addr：slp设备地址

  • screenParam：屏幕参数

    cursorSpeed：光标灵敏度参数

    clickTremorPrevSens：点击防抖灵敏度参数

    width：屏幕宽度，单位：mm

    height：屏幕高度，单位：mm

    dongleAntPoseOffset：dongle天线位置相对屏幕中心左右偏移量，偏左边设置为负值，偏右边设置为正值，单位：mm

  • rfSwParam：射频开关控制参数

    pwrCtrl：slp射频开关电源是否独立控制

    antSwCtrlEn：slp射频开关控制管脚使能

    ant0Code：天线0切换码字

    ant1Code：天线1切换码字

    ant2Code：天线2切换码字

错误码

-

SlpSetLocalAttCallback

设置本机属性命令执行结果回调

-

错误码

-

负载收发

表 1 负载收发接口

接口名称

描述

参数说明

返回信息说明

备注

SlpRecvPayload

SLP接收负载

payload：负载指针；

payloadLen：SLP负载长度，取值范围[0, 255]。

错误码

-

SlpRegisterSendPayloadCallback

注册SLP发送负载回调

cbk：发送负载的回调函数

错误码

-

注册命令完成结果回调

表 1 命令完成结果回调注册接口

接口名称

描述

参数说明

返回信息说明

备注

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设置本机属性回调函数。

错误码

-

注册上报结果回调函数

表 1 上报结果回调函数注册接口

接口名称

描述

参数说明

返回信息说明

备注

SlpRegisterReportCallbacks

注册SLP上报结果回调函数

func：回调函数，包括：

  • SlpReportCursorCallback rptCursorCbk：SLP上报光标回调函数；
  • SlpReportRangingCallback rptRangingCbk：SLP上报测距结果回调函数；
  • SlpReportErrcodeCallback rptErrcodeCbk：SLP上报错误码回调函数；
  • SlpReportCirCallback rptCirCbk：slp上报cir回调函数
  • SlpReportVersionCallback rptVersionCbk：slp上报版本号回调函数
  • SlpReportCfoCallback rptCfoCbk：slp上报CFO和当前帧的CFO阈值

错误码

-

启动测距

表 1 启动测距接口

接口名称

描述

参数说明

返回信息说明

备注

SlpStartRangingCommand

启动测距命令

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个是测距发起者的地址。

错误码

-

SlpStartRangingCallback

启动测距命令执行结果回调

-

错误码

-

停止测距

表 1 停止测距接口

接口名称

描述

参数说明

返回信息说明

备注

SlpStopRangingCommand

停止测距：SLP不工作

-

错误码

   

SlpStopRangingCallback

停止测距命令执行结果回调

-

错误码

-

暂停测距

表 1 暂停测距接口

接口名称

描述

参数说明

返回信息说明

备注

SlpPauseRangingCommand

暂停测距：宽窄带的通信关闭

-

错误码

-

SlpPauseRangingCallback

暂停测距命令执行结果回调

-

错误码

-

继续测距

表 1 继续测距接口

接口名称

描述

参数说明

返回信息说明

备注

SlpContinueRangingCommand

继续测距：宽窄带通信恢复

-

错误码

-

SlpContinueRangingCallback

继续测距命令执行结果回调

-

错误码

-

睡眠

表 1 睡眠接口

接口名称

描述

参数说明

返回信息说明

备注

SlpSleepCommand

睡眠

-

错误码

-

SlpSleepCallback

睡眠命令执行结果回调

-

错误码

-

产测

注册产测结果上报回调

表 1 产测结果上报回调注册接口

接口名称

描述

参数说明

返回信息说明

备注

SlpRegisterFactoryReportCallbacks

注册产测结果上报回调

产测数据上报回调

错误码

-

设置产测模式

表 1 产测模式设置接口

接口名称

描述

参数说明

返回信息说明

备注

SlpSetFactoryTestMode

设置产测模式

产测模式

错误码

测角校准模式需要在dongle侧设置

测距测角校准

表 1 测距测角校准接口

接口名称

描述

参数说明

返回信息说明

备注

SlpReportOriginDataCallback

测距测角校准数据上报回调

-

测距测角校准数据

-

IMU检测

表 1 IMU检测接口

接口名称

描述

参数说明

返回信息说明

备注

SlpEnableImuDetectionCommand

开启IMU检测

是否更新零偏值。

true：是；

false：否。

错误码

-

SlpDisableImuDetectionCommand

关闭IMU检测

-

错误码

-

SlpReportFactoryImuDataCallback

IMU产测数据上报的回调函数

IMU产测数据。

错误码

-

SlpReportGyroZeroOffsetCallback

陀螺仪零偏校准值结果上报回调函数

offset：GYRO零偏值

updateNv：是否更新NV值，true。

  • true：是；
  • false：否。

-

-

读写板级时延

表 1 读写本端时延校准值NV接口

接口名称

描述

参数说明

返回信息说明

备注

SlpReadBoardAntTrxTimeDelay

读取时延校准值NV

时延校准值

错误码

-

SlpWriteBoardAntTrxTimeDelay

写入时延校准值指NV

-

时延校准值

-

表 2 读写对端时延校准值NV接口

接口名称

描述

参数说明

返回信息说明

备注

SlpReadTrxDelayFromOnb

从对端NV中读取时延校准值

时延校准值

错误码

设备需要建链

SlpReportFactoryTrxDelayCallback

板级+天线时延校准结果上报函数

-

时延校准值

设备需要建链

SlpWriteGyroZeroOffset

向对端NV中写入时延校准值

时延校准值

错误码

设备需要建链

读写测角校准参数

表 1 从NV中读写本端测角校准参数接口

接口名称

描述

参数说明

返回信息说明

备注

SlpReadAoxCaliPara

读取测角校准值

测角校准值

错误码

-

SlpWriteAoxCaliPara

写入测角校准值

-

测角校准值

-

表 2 从NV中读写对端测角校准参数接口

接口名称

描述

参数说明

返回信息说明

备注

SlpReadAoxCaliParaFromOnb

从对端NV中读取测角校准值

-

错误码

设备需要建链

SlpReportAoxCaliParaCallback

测角校准值上报函数

-

测角校准值

设备需要建链

SlpWriteAoxCaliPara2Onb

向对端NV中写入测角校准值

测角校准值

错误码

设备需要建链

读写陀螺仪零偏值

表 1 从NV中读写陀螺仪零偏值接口

接口名称

描述

参数说明

返回信息说明

备注

SlpReadGyroZeroOffset

向NV中写入陀螺仪零偏值

陀螺仪零偏值

错误码

-

SlpWriteGyroZeroOffset

从NV中读取陀螺仪零偏值

陀螺仪零偏值

错误码

-

读写TX功率码字

表 1 从NV中读写TX功率码字值接口

接口名称

描述

参数说明

返回信息说明

备注

SlpReadTxPower

读取TX功率码字

功率码字值

错误码

-

SlpWriteTxPower

写入TX功率码字

-

功率码字值

-

读写三天线校准参数

表 1 从NV中读写三天线校准参数接口

接口名称

描述

参数说明

返回信息说明

备注

SlpReadTriAntAoxCaliPara

读取三天线校准参数

三天线校准参数

错误码

-

SlpWriteTriAntAoxCaliPara

写入三天线校准参数

三天线校准参数

错误码

-

维测

读取版本号

表 1 版本号读取接口

接口名称

描述

参数说明

返回信息说明

备注

SlpReadVersionCommand

读取软件版本号

-

错误码

-

SlpReportVersionCallback

版本号读取结果回调
  • narrowBand：窄带软件版本号
  • wideBand：宽带软件版本号
  • capability：版本支持特性
  • chipId：芯片ID
  • imuType：IMU类型

-

-

设置日志打印级别

表 1 日志打印级别设置接口

接口名称

描述

参数说明

返回信息说明

备注

SlpSetLogLevel

设置日志打印级别

日志打印级别

错误码

-

芯片温度读取

表 1 SLP温度读取接口

接口名称

描述

参数说明

返回信息说明

备注

SlpReadTsensorCommand

读取SLP芯片温度命令

-

错误码

-

SlpReportTsensorCallback

温度上报回调

-

温度

-

CIR上报功能

表 1 CIR上报功能接口

接口名称

描述

参数说明

返回信息说明

备注

SlpEnCirReportCommand

开启CIR数据上报命令

-

错误码

-

SlpEnCirReportCallback

开启命令执行结果回调

-

错误码

-

SlpReportCirCallback

数据上报

cir上报结果

错误码

-

SlpDisCirReportCommand

关闭CIR数据上报

-

错误码

-

SlpDisCirReportCallback

关闭命令执行结果回调

-

错误码

-

芯片 DIE ID 读取

表 1 芯片 DIE ID 读取接口

接口名称

描述

参数说明

返回信息说明

备注

SlpReadDieIdCommand

读取芯片DIE ID 命令

-

错误码

仅在上电后可调用

SlpReportDieIdCallback

DIE ID结果上报回调函数

DIE ID数据

错误码

-

AT命令注册

表 1 AT命令注册接口

接口名称

描述

参数说明

返回信息说明

备注

SlpAtRegister

AT命令注册

-

错误码

-

SLP支持的AT指令请详见《Sample 使用指南》中“AT命令”章节。

开发流程

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

RCU侧：

  1. 调用SlpSetUartBuffer，设置UART缓冲区。

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

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

  4. 调用SlpRecvPayload，注册SLP接收payload函数。

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

  6. 调用SlpRegisterReportCallbacks，注册结果上报回调。

  7. 调用SlpSetTransformParam，设置坐标系转换参数

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

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

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

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

  12. 如果SLE断连，调用SlpPowerOffCommand，本端SLP下电，对端slp进入低功耗状态。

Dongle侧：

  1. 调用SlpSetUartBuffer，设置UART缓冲区。

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

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

  4. 调用SlpRecvPayload，注册SLP接收payload函数。

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

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

  7. 调用SlpRegisterReportCallbacks，注册结果上报回调函数。

  8. 调用SlpSetInstParam，设置安装参数。

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

  10. SlpReportCursorCallback接口会持续上报光标结果。

  11. SlpReportRangingCallback接口会持续上报测距测角值结果。

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

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

图 1 air mouse sample中SLP工作简易流程
https://cloudmodeling.tools.huawei.com/draw?id=ee1eea2ec89e41ef85af4b166e9ed81b

缩略语

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

Identification

唯一编码

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客户端

SYNCSYMNUM

Sync Symbol Number

sync段的符号数量