资料说明成果sdk user

1、Saber SDK 用户手册文档编号 UM0002Rev 1.112020 年 11 月北京原子人科技Saber SDK User ManualINFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH ATOM ROBOTICS PRODUCTS. NO LICENSE,EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN

2、ATOMS TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, ATOM ASSUMES NO LIABILITY WHATSOEVER, AND ATOM DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF ATOM PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMEN

3、T OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.ATOM ROBOTICS may make changes to specifications and product descriptions at any time, without notice.Designers must not rely on the absence or characteristics of any features or instructions marked "" or"undefined."

4、 ATOM ROBOTICS reserves these for future definition and shall have no responsibility whatsoever fors or incompatibilities arising from future changes to them.The ATOM ROBOTICS SDK may contain design defects or errors known as errata, which may cause the product to deviate from published specificatio

5、ns. Current characterized errata are available on request.Contact your local ATOM ROBOTICS sales office or your distributor to obtain the latest specifications and before placing your product order.ATOM ROBOTICS, include any ATOM ROBOTICS trademarks which are used in this document and the ATOMROBOTI

6、CS logo are trademarks or registered trademarks of ATOM ROBOTICS Co.,and other countries.*Other names and brands may be claimed as the property of others. or its subsidiariesCopyright © 2019, ATOM ROBOTICS Co.,.s.2 of 283Atom RoboticsUM0002Content11.11.21.31.41.522.12.2关于本文15目标15目标用户15范围和局限性15缩

7、写词、缩略语和术语16文档格式17SDK 概述18SDK 安装18SDK 结构182.2.1Examples 示例文件夹192.2.2Linux 文件夹202.2.3Windows 文件夹202.2.4ROS 文件夹2133.13.2系统结构22概述22设备系统状态233.2.1WAKEUP 状态233.2.23.2.3CONFIG 状态24MEASURE 状态243.2.43.2.5SELFTEST 状态24MAG_CAL 状态243.344.14.2数据包的多样性24协议描述28通用消息结构28头部字段294.2.14.2.24.2.34.2.44.2.54.2.6Preamble129P

8、reamble229MADDR30CID30MID31PL(有效载荷长度)313 of 283Atom RoboticsUM0002Saber SDK User Manual4.2.7SLP(超长数据包)314.34.44.54.6Atom BCC(Atom 异或校验)32TAIL 尾部字段33Saber 数据配置结构33Saber 数据包结构344.6.1温度354.6.2原始数据(Acc/Gyro/Mag)354.6.34.6.4校准数据(Acc/Gyro/Mag)36Kalman 滤波数据(Acc/Gyro/Mag)374.6.5磁力偏差数据374.6.6气压计原始数据374.6.7Ka

9、lman 滤波的气压计数据384.6.84.6.9Gnss PVT 数据38Gnss Satellites 数据394.6.104.6.11. 40四欧拉角414.6.12余弦矩阵414.6.134.6.14度42. 42线性速度4.6.15. 42位移4.6.16. 42升沉4.6.17. 42高度4.6.184.6.19. 43经度纬度轮速计数据434.6.204.6.21数据包编号43操作系统参考时间434.6.22采样间隔时间444.6.234.6.24状态字44Saber 数据包 PID454.7坐标系定义454 of 283Atom RoboticsUM00024.855.1NME

10、A 协议46API 接口49枚举定义495.1.1模式 ID495.2宏定义495.2.1Saber 类名称495.2.2操作类515.2.35.2.4设备信息类51传感器配置类525.2.5算法引擎类545.2.6通信配置类565.2.7主机配置类575.2.8固件升级类595.35.45.55.6ATR_OpenCom(const char *ucComNo, unsigned long ulBaudrate = 115200)59ATR_CloseCom(const char *openComNo)60ATR_Init()61ATR_RegisterCallback(CallbackFu

11、nction pFunction, unsigned char classID, unsigned char mID). 62ATR_DeRegisterCallback(u8 classID, u8 mID)63ATR_WakeUpHostCmdAck ()63ATR_SwitchModeReq(char mode)64ATR_SystemResetReq()65ATR_ConfigurationWriteToFlashReq()66ATR_ConfigurationLoadFromFlashReq()67ATR_LoadFactoryConfigurationReq()68ATR_GetF

12、WVersionReq()68ATR_GetProductVersionReq()70ATR_GetVendorInfoReq()715.75.85.95.105.115.125.135.145.155.165.175.185.195.205.215.225.235.245.255.265.275.285.29ATR_GlStatusReq()73ATR_GetDeviceInfoReq()74ATR_SetModuleIDReq(u8 id)76ATR_GetModuleIDReq()77ATR_SetAcceleroMeterScaleReq(u8 *acc, u8 dataLen)78A

13、TR_GetAcceleroMeterScaleReq()79ATR_SetAcceleroMeterCoeffReq(u8 *acc, u8 dataLen)81ATR_GetAcceleroMeterCoeffReq()82ATR_SetGyroscopeScaleReq(u8 *gyro, u8 dataLen)83ATR_GetGyroscopeScaleReq()84ATR_SetMagnetoMeterCoeffReq(u8 *mag, u8 dataLen)86ATR_GetMagnetoMeterCoeffReq()87ATR_SetMagnetoMeterSensorCali

14、brateReq(u8 *onOrOff, u8 dateLen)895 of 283Atom RoboticsUM0002Saber SDK User Manual5.305.315.325.335.345.355.365.375.385.395.405.415.425.435.445.455.465.475.485.495.505.515.525.535.545.555.565.575.585.595.605.615.625.635.6466.16.2ATR_SetMux2Req(u8 *onOrOff, u8 dataLen)90ATR_GetMux2Req()91ATR_SetAcc1

15、DEKFParamReq(u8 *KFP, u8 dataLen)92ATR_GetAcc1DEKFParamReq()94ATR_SetGyro1DEKFParamReq(u8 *KFP, u8 dataLen)95ATR_GetGyro1DEKFParamReq()97ATR_SetMag1DEKFParamReq(u8 *KFP, u8 dataLen)98ATR_GetMag1DEKFParamReq()100ATR_SetEngineFusionModeReq(u8 *setMode, u8 dataLen)101ATR_GetEngineFusionModeReq()103ATR_

16、SetPacketUpdateRateReq(u8 *setRate, u8 dataLen)104ATR_GetPacketUpdateRateReq()105ATR_SetGyroThresholdReq(u8 *pdata, u8 dataLen)107ATR_GetGyroThresholdReq()108ATR_SetYawOffsetReq(u8 *data, u8 datalen)110ATR_SetAttitudeOffsetReq(u8 *data, u8 dataLen)111ATR_SetReferenceOffsetReq(u8 *data, u8 dataLen)11

17、1ATR_ClearOffsetReq (u8 *data, u8 dataLen)112ATR_SetComPortParamReq(u8 *para, u8 datalen)113ATR_GetComPortParamReq()115ATR_SetComPortParamHandshakeReq()117ATR_SetDrdyConfigReq(u8* pData, u8 dataLen)118ATR_GetDrdyConfigReq()119ATR_SetGpioConfigReq(u8* pData, u8 dataLen)121ATR_GetGpioConfigReq()122ATR

18、_SetSyncOutConfigReq(u8 *pData, u8 dataLen)124ATR_GetSyncOutConfigReq()125ATR_SetDataPacketConfigReq(u8* pData, u8 dataLen)126ATR_GetDataPacketConfigReq()127ATR_RegisterDownLoadCallback(DownloadCallbackFunction pFunction)128ATR_DownloadFirmware_new(char *filename)130ATR_GetVersion(char *version_Buf)

19、130ATR_DebugSwitch(bool onOrOff)131ATR_GetScenarioReq()132ATR_SetScenarioReq(u8* pData, u8 dataLen)133底层通信协议接口135概述135操作类1356.2.16.2.26.2.36.2.46.2.5WakeUpHost135WakeUpHostAck135SwitchToConfigMode136SwitchToConfigModeAck136SwitchToMeasureMode1376 of 283Atom RoboticsUM00026.2.66.2.76.2.86.2.96.2.106.

20、2.116.2.126.2.136.2.14SwitchToMeasureModeAck137SystemReset138SystemResetAck138ConfigurationWriteToFlash138ConfigurationWriteToFlashAck139ConfigurationLoadFromFlash139ConfigurationLoadFromFlashAck140LoadFactoryConfiguration140LoadFactoryConfigurationAck1416.3设备信息类1416.3.16.3.26.3.36.3.46.3.56.3.66.3.

21、76.3.86.3.96.3.106.3.116.3.126.3.136.3.14GetFWVersion141RespFWVersion141GetProductVersion142RespProductVersion142GetVendorInfo143RespVendorInfo143GlStatus144RespAllStatus144GetDeviceInfo148RespDeviceInfo149SetModuleID149ModuleIDAck150GetModuleID150RespModuleID1516.4传感器配置类1516.4.16.4.26.4.36.4.46.4.5

22、6.4.6SetAccelerometerScale151AccelerometerScaleAck152GetAccelerometerScale153RespAccelerometerScale153SetAccelerometerCoeff154AccelerometerCoeffAck1557 of 283Atom RoboticsUM0002Saber SDK User Manual6.4.76.4.86.4.96.4.106.4.116.4.126.4.136.4.146.4.156.4.166.4.176.4.186.4.196.4.206.4.216.4.226.4.236.4

23、.24GetAccelerometerCoeff155RespAccelerometerCoeff156SetGyroscopeScale157GyroscopeScaleAck158GetGyroscopeScale158RespGyroscopeScale159SetMagnetometerCoeff159MagnetometerCoeffAck160GetMagnetometerCoeff160RespMagnetometerCoeff161SetMagnetometerCalibrate162MagnetometerCalibrateAck162MagCalPacket163MagCa

24、lMessage164SetMux2165Mux2Ack166GetMux2167RespMux21676.5算法引擎类1686.5.16.5.26.5.36.5.46.5.56.5.66.5.76.5.86.5.96.5.106.5.11SetACC1DEKFParam168ACC1DEKFParamAck169GetACC1DEKFParam170RespACC1DEKFParam170SetGYRO1DEKFParam171GYRO1DEKFParamAck171GetGYRO1DEKFParam172RespGYRO1DEKFParam172SetMAG1DEKFParam173MAG

25、1DEKFParamAck173GetMAG1DEKFParam1748 of 283Atom RoboticsUM00026.5.126.5.136.5.146.5.156.5.166.5.176.5.186.5.196.5.206.5.216.5.226.5.236.5.246.5.256.5.266.5.276.5.286.5.296.5.306.5.316.5.326.5.336.5.346.5.356.5.366.5.376.5.386.5.396.5.406.5.416.5.42RespMAG1DEKFParam174SetEngineFusionMode175EngineFusi

26、onModeAck176GetEngineFusionMode176RespEngineFusionMode177SetPacketUpdateRate177PacketUpdateRateAck178GetPacketUpdateRate178RespPacketUpdateRate179SetGyroThreshold179GyroThresholdACK180GetGyroThreshold180RespGyroThreshold181SetYawOffSet181SetYawOffSetAck182SetAttitudeOffSet182SetAttitudeOffSetAck183S

27、etReferenceOffSet183SetReferenceOffSetAck184SetDistanceOffSet184SetDistanceOffSetAck185SetVelocityOffSet185SetVelocityOffSetAck186SetStartYaw186SetStartYawAck186SetTempCoefCfg187SetTempCoefCfgAck187GetTempCoefCfg188GetTempCoefCfgAck188SetBARO1DEKFParam189BARO1DEKFParamAck1899 of 283Atom RoboticsUM00

28、02Saber SDK User Manual6.5.436.5.446.5.456.5.466.5.476.5.486.5.496.5.506.5.516.5.526.5.536.5.546.5.556.5.566.5.576.5.586.5.596.5.606.5.616.5.626.5.636.5.646.5.656.5.666.5.67GetBARO1DEKFParam190RespBARO1DEKFParam190GetPreOffSet191GetPreOffSetAck191SetPreOffSet191SetPreOffSetAck192ClearOffset194ClearO

29、ffsetAck194OdometerPacket195SetScenario195SetScenarioAck196GetScenario197RespGetScenario197SetCoordinatesMode198SetCoordinatesModeAck199GetCoordinatesMode200RespGetCoordinatesMode200SetSelfTestMode201SetSelfTestModeAck202GetSelfTestMode203RespGetSelfTestMode203SetEngineParam203SetEngineParamAck204Ge

30、tEngineParam205GetEngineParamAck2066.6通讯配置类2076.6.16.6.26.6.36.6.4SetComPortParam207ComPortParamAck209GetComPortParam210RespComPortParam21010 of 283Atom RoboticsUM00026.6.56.6.6SetComPortParamHandshake212ComPortParamHandshakeAck2126.7主机配置类2136.7.16.7.26.7.36.7.46.7.56.7.66.7.76.7.86.7.96.7.106.7.116

31、.7.126.7.136.7.146.7.156.7.166.7.176.7.186.7.196.7.206.7.216.7.226.7.236.7.246.7.256.7.266.7.276.7.28SaberDatapacket213SetDrdyConfig213DrdyConfigAck214GetDrdyConfig215RespDrdyConfig215SetGpioConfig216GpioConfigAck217GetGpioConfig218RespGpioConfig218SetSyncOutConfig219SetSyncOutConfigAck220GetSyncOut

32、Config221GetSyncOutConfigAck221SetDataPacketConfig222DataPacketConfigAck223GetDataPacketConfig223RespDataPacketConfig223SetGNSSOutputMode224SetGNSSOutputModeAck224GetGNSSOutputMode225RespGNSSOutputMode225SetGNSSParameters226SetGNSSParametersAck226GetGNSSParameters227RespGNSSParameters227SetAntOffSet

33、228SetAntOffSetAck229GetAntOffSet22911 of 283Atom RoboticsUM0002Saber SDK User Manual6.7.296.7.306.7.316.7.326.7.33GetAntOffSetAck230SetGNSSMode230SetGNSSModeAck231GetGNSSMode231GetGNSSModeAck2326.8固件更新类2326.8.16.8.26.8.36.8.4FirmwareUpdateReq232FirmwareUpdateReqAck233FirmwareUpdatePacket233Firmware

34、UpdatePacketAck23477.17.27.37.47.5示例代码235概述235SDK AutoProtocolDemo236SDK MeasureDataDemo237SDK DownloadFirmware239Low-Level MeasureDataDemo 说明2407.5.17.5.2Windows/STM32-Uart/Linux240STM32 IIC and SPI2507.6Low-Level Download 底层说明2567.6.17.6.27.6.3SwitchToConfigMode256FirmwareUpdateReq257FirmwareUpdat

35、ePacket25788.18.28.38.48.58.68.78.899.19.29.39.4命令速查表258概述258操作类258设备信息类259传感器配置类260算法引擎类262通讯配置类265主机配置类266固件更新类268消息响应机制269概述269WAKEUP 状态269MEASURE 状态269SELFTEST 状态27012 of 283Atom RoboticsUM00029.59.610MAG_CAL 状态271CONFIG 状态271Saber 返回码278历史版本280FiguresFigure 1 Saber SDK 目录结构19Figure 2 Saber 应用结构

36、23Figure 3 系统状态转换流程图23Figure 4 通用消息结构28Figure 5 头结构29Figure 6 CID 结构31Figure 7 MID 结构31Figure 8 有效载荷和超长数据包结构32Figure 9 Saber 数据配置结构34Figure 10 Saber 数据包结构35Figure 11 Saber 状态定义145Figure 12 初始化自检正常流程147Figure 13 初始化自检失败恢复流程148Figure 14 SDK AutoProtocolDemo 运行示例237Figure 15 SDK MeasureDataDemo 运行示例239

37、Figure 16 SDK DownloadFirmware 在Windows 下运行示例240Figure 17 UART 例程流程图241Figure 18 Wait Ack 流程图243Figure 19 IIC and SPI 例程流程图253Figure 20 IICMessage 流程254Figure 21 IIC 获取Measure 数据流程254Message 流程255Figure 22 IIC and SPI with DRDY13 of 283Atom RoboticsUM0002Saber SDK User ManualFigure 23 IIC and SPI wi

38、th DRDY 获取Measure 数据流程256TablesTable 1 Saber C1/C2/C2G/C3/C3G/C4/C6/B6 数据包列表27Table 2 GNSS PVT Data39Table 3 Saber 数据包PID45Table 4 类名称和类 ID51Table 5 操作类下的消息列表51Table 6 设备信息类下的消息列表52Table 7 传感器配置类下的消息列表53Table 8 算法引擎类下的消息列表56Table 9 通信配置类下的消息列表57Table 10 主机配置类下的消息列表58Table 11 固件升级来下的消息列表59Table 12 自检

39、配置与状态表202Table 13 SDK 例程矩阵235Table 14 Low Level 例程矩阵236Table 15 Saber 返回码279Table 16 历史版本28314 of 283Atom RoboticsUM00021 关于本文1.1目标Saber C 系列是标准的工业级惯导，与此同时它集成了我们专有的算法引擎BosonEngineTM，对于工业用户来说，Saber C 系列是一款集高性能与低成本于一体的产品。本手册专为来自北京原子人科技的 Saber提供关于软件架构和 API 协议进行连接的方法和细节，相关的说明。手册描述了使用 Atom 通信协议与 Saber并提供

40、了来自 SDK(软件开发工具包)的示例代码。1.2目标用户目标用户是来自于人领域或其他对惯性导航有工业级需求的软件设计和开发，如：VR/AR，人，无人机，运动跟踪，自动驾驶，物联网等。本文档也可用于指导正在使用 ATOM进行硬件设计和调试的工程师。1.3范围和局限性从用户的角度来看本文可分为如下几部分：······功能和模块的基本介绍，以便更好地理解 Saber C 系列演示软件结构以便让用户了解如何在工作模式下正确的配置引擎列出所有 API 协议并给出相应的解释介绍一种通过底层协议进行通信的方法对软件开发工具包(SDK)进行描述并且

41、附上示例代码加以解释一些必要的硬件信息15 of 283Atom RoboticsUM0002Saber SDK User Manual本文总结了软件领域的所有技术方面问题，旨在让用户能够轻松高效地将 Saber 模组集成到各种应用场景中。如果有细节未涉及，请公司官网：,或者发邮件给我们：contactatom-缩写词、缩略语和术语1.4INSInertial Navigation SystemIMUInertial Measurement UnitVRUVertical Reference UnitAHRSAttitude & Heading Reference SystemVRVi

42、rtual RealityARAugmented RealityUAVUnmanned Aerial VehicleDCMDirection Cosine MatrixMISCMiscellaneousSDKSoftware Development KitBosonEngineTMThe name of Saber EngineHzHertz16 of 283Atom RoboticsUM0002专业术语描述DRDYData ready1.5文档格式正文格式：字体文字：“1.5文档格式”状态：WAKEUP命令格式：WakeUpHost例程格式：#define FULL_SCALE 32768特

43、殊名称：BosonEngineTM17 of 283Atom RoboticsUM0002Saber SDK User Manual2 SDK 概述2.1SDK 安装Saber SDK是一套软件开发工具，专为在特定软件包、软件框架和硬件平台的开发环境下开发的开发提供便捷的技术指导，以便与Saber进行通信。我们开发了一个名为“SaberSDK_Setup_需要安装SDK，安装程序如下：.exe”的专业SDK安装包。首先，用户在使用之前1. 打开SDK文件夹并双击可执行文件“SaberSDK_Release_Setup_2. 点击“next”直到安装完成。.exe”。2.2SDK 结构提供的SD

44、K是单个可执行文件。安装完成后，在安装路径下有一个名为“AtomRobotics”的文件夹，其中包含以下子文件夹：18 of 283Atom RoboticsUM0002Figure 1 Saber SDK 目录结构2.2.1 Examples 示例文件夹Exmaples 示例文件夹包含：Low-Level文件夹：- Linux_Demo：Linux平台Demo，由ubuntu 14.04系统编译和运行。包括：o MeasureDataDemo文件夹中为Linux环境下获取测量数据例程。o DownLoad_Firmware文件夹中为Linux环境下实现Atom Robotics模组更新FW的

45、例程。- Windows_Demo：Windows平台Demo，由VS2013环境编译运行，包括：o MeasureDataDemo文件夹中为windows下获取模组的测量数据例程。o DownLoad_Firmware文件夹中为windows下实现Atom Robotics模组更新FW的例程。- STM32_Demo：STM32平台Demo，由IAR7或者8在Windows10系统上编译并在STM32F411环境下运行，包括：o DownLoad_Firmware文件夹中为实现Atom Robotics模组更新FW的例程。o MeasureDataDemo文件夹，分为下面几个工程：§

46、; STM32 Uart版，由IAR在Windows10系统上编译并在STM32F411环境下运行，演示了如何利用Uart去使用Atom Robotics的底层协议与设备通信。§ STM32 IIC版，由IAR在Windows10系统上编译并在STM32F411环境下运行，此版本分为两个子版本，使用DRDY和不使用DRDY版本，演示了如何利用IIC去使用Atom Robotics的底层协议与设备通信。§ STM32 SPI版，由IAR在Windows10系统上编译并在STM32F411环境下运行，此版本为使用DRDY的版本（SPI只能使用DRDY进行通信），演示了如何利用S

47、PI去使用Atom Robotics的底层协议与设备通信。SDK文件夹：19 of 283Atom RoboticsUM0002Saber SDK User Manual- Linux_SDK_Demo：Linux平台Demo，包括：o AutoProtocolDemo文件夹中有X86, X64, ARM环境下，调用SDK实现与Atom Robotics设备的协议通信例程。o DownLoad_Firmware文件夹中有X86, X64, ARM环境下，调用SDK实现为Atom Robotics模组更新的例程。- Windows_SDK_Demo：Windows平台Demo，包括：o Auto

48、ProtocolDemo文件夹中为windows下VS2013环境下，调用SDK实现与Atom Robotics设备的协议通信例程。o DownLoad_Firmware文件夹中为windows下VS2013环境下，调用SDK实现为Atom Robotics模组更新的例程。o MeasureDataDemo文件夹中为windows下VS2013环境下，调用SDK实现与Atom Robotics设备的测量数据获取例程。2.2.2 Linux 文件夹Linux文件夹包括Linux环境下SDK的二进制库文件：- PC-X86：Atom Robotics发布了基于32位桌面操作系统(Ubuntu 16

49、.04)的Linux SDK，经过测试，支持GCC-7.3.0、GCC-5、GCC-5.4.0、GCC-4.8版本。- PC-X64：Atom Robotics发布了基于64位桌面操作系统(Ubuntu 18.04)的Linux SDK，同样支持GCC-7.3.0、GCC-5、GCC-5.4.0、GCC-4.8版本。- ARM：Atom Robotics发布了基于ARM两种交叉编译环境(arm-none-linux-gnueabi-gcc、gcc-linaro-4.9.4-2017.1)的Linux SDK。2.2.3 Windows 文件夹Windows文件夹包括Windows环境下SDK的

50、二进制库文件：- X64：Atom Robotics发布了基于64位桌面操作系统的Windows SDK。- X86：Atom Robotics发布了基于32位桌面操作系统的Windows SDK。20 of 283Atom RoboticsUM00022.2.4 ROS 文件夹ROS文件夹包含：- catkin_ws文件夹是ROS和模组通信的例程。- ROS版本为Kinetic Kame，环境为 Ubuntu 16.04，64位操作系统ROS例程使用方法：打开新终端进入catkin_ws；创建工作空间，将imu_publish中的源码放入对应工作空间中；详细步骤参考ReadMe.txt；运行命令catkin_make编译产生可执行文件“imu”；