PSDK 消息订阅相关功能的头文件为psdk_data_subscription.h
,本文档描述了psdk_data_subscription.h
文件中结构体和函数原型的关键信息和使用方法。
目录
宏定义
typedef psdk_f32_t T_PsdkDataSubscriptionAltitudeFused;
|
typedef psdk_f32_t T_PsdkDataSubscriptionHeightRelative;
|
typedef uint32_t T_PsdkDataSubscriptionGpsDate;
|
typedef uint32_t T_PsdkDataSubscriptionGpsTime;
|
- GPS 位置 x=经度, y=纬度, z=高度, 单位:度*10-7 (经度,纬度), mm (海拔高度)
typedef T_PsdkVector3d T_PsdkDataSubscriptionGpsPosition;
|
typedef T_PsdkVector3f T_PsdkDataSubscriptionGpsVelocity;
|
- GPS 信号的等级。GPS 信号优劣等级由低到高依次是0~5。
typedef uint8_t T_PsdkDataSubscriptionGpsSignalLevel;
|
typedef T_PsdkVector3f T_PsdkDataSubscriptionRtkVelocity;
|
typedef int16_t T_PsdkDataSubscriptionRtkYaw;
|
- RTK 位置信息(RTK 位置解的状态),详情请参见E_PsdkDataSubscriptionPositionSolutionProperty
typedef uint8_t T_PsdkDataSubscriptionRtkPositionInfo;
|
- RTK 偏航信息(RTK 偏航角解状态),详情请参见E_PsdkDataSubscriptionPositionSolutionProperty
typedef uint8_t T_PsdkDataSubscriptionRtkYawInfo;
|
- 无人机飞行状态,详情请参见:E_PsdkDataSubscriptionFlightStatus
typedef uint8_t T_PsdkDataSubscriptionFlightStatus;
|
枚举
typedef enum E_PsdkDataSubscriptionTopicName
PSDK 支持用户订阅的订阅项,其中包括
- 姿态四元数
- 速度
- 融合海拔高度
- 相对高度
- 融合位置
- 飞行状态
- 电池信息
- GPS 日期
- GPS 时间
- GPS 位置
- GPS 速度
- GPS 信息
- GPS 信号等级
- RTK 位置
- RTK 速度
- RTK 航向角
- RTK 位置属性
- RTK 航向角属性
typedef enum { @brief 无人机四元数,提供飞机机身框架(FRD)到地面框架(NED)的旋转信息。有关四元数数据的说明请参见:T_PsdkDataSubscriptionQuaternion @note 该四元数遵循 Hamilton convention(右手坐标系,即q0 = w, q1 = x, q2 = y, q3 = z). | 角度 | 单位 | 精度 | 说明 | |--------------|------|---------- -|----------------------| | 俯仰角, 横滚角 | 度 | <1 | NON-AHRS 模式 | | 偏航角 | 度 | <3 | 指南针校准良好并精确对准 | | RTK 偏航角 | 度 | 1.2 | 1米基线且RTK航向FIX模式 | PSDK_DATA_SUBSCRIPTION_TOPIC_QUATERNION = 0,
@brief 地球中心坐标系(ground-fixed NEU frame)下的无人机速度,有关无人机速度的结构体请参见:T_PsdkDataSubscriptionVelocity. @note 请注意,此数据不遵循常规的右手参考系规则。 @details 该速度数据是飞机的融合输出。 原始输出基于右手NED坐标系,但在发布之前,z轴速度的符号被翻转。 因此,如果您希望获得NED坐标系中的速度,只需翻转z轴值的符号即可。 | 轴 | 单位 | 精度|-----------------------------------------------------------------| | vgx, vgy | m/s | 使用GNSS导航时约为5cm/s, 使用视觉里程计于1米高度处约为3cm/s | | vgz | m/s | 在稳定空气中仅气压计被使用时10cm/s, 使用视觉里程计于1米高度且基线8cm时3cm/s | PSDK_DATA_SUBSCRIPTION_TOPIC_VELOCITY,
@brief 无人机融合海拔高度(以海平面为0 米)详情请参见 T_PsdkDataSubscriptionAltitudeFused PSDK_DATA_SUBSCRIPTION_TOPIC_ALTITUDE_FUSED,
@brief 无人机的融合相对高度,详情请参见:T_PsdkDataSubscriptionHeightRelative @details 无人机通过超声波获得无人机相对于地面的垂直高度 @warning 受无人机飞行高度的影响,通过超声波传感器获取无人机的相对高度可能会有误差 PSDK_DATA_SUBSCRIPTION_TOPIC_HEIGHT_RELATIVE,
@brief 无人机融合位置信息,详情请参见:T_PsdkDataSubscriptionPositionFused @warning 若GPS 的信号较弱,无人机的经纬度值将不会被更新,但海拔高度可能会更新 @note 为跟踪GPS 卫星的覆盖范围,预测GPS 的信号,请订阅T_PsdkDataSubscriptionPositionFused::visibleSatelliteNumber | 轴 | 单位 | 位置传感器 | 精度 | |------|------|-----------------|------------------------------------| | x, y | m | GPS | <3m(在无遮挡的空旷区域) | | z | m | GPS | <5m(在无遮挡的空旷区域) | PSDK_DATA_SUBSCRIPTION_TOPIC_POSITION_FUSED,
@brief GPS 数据,详情请参见:T_PsdkDataSubscriptionGpsDate PSDK_DATA_SUBSCRIPTION_TOPIC_GPS_DATE,
@brief GPS 时间,详情请参见:T_PsdkDataSubscriptionGpsTime PSDK_DATA_SUBSCRIPTION_TOPIC_GPS_TIME,
@brief GPS 位置,详情请参见:T_PsdkDataSubscriptionGpsPosition @details | 轴 | 精度 | |------|--------------------------------------------------| | x, y | <3m(在无遮挡的空旷区域) | | z | <5m(在无遮挡的空旷区域) | PSDK_DATA_SUBSCRIPTION_TOPIC_GPS_POSITION,
@brief GPS 速度,详情请参见:T_PsdkDataSubscriptionGpsVelocity PSDK_DATA_SUBSCRIPTION_TOPIC_GPS_VELOCITY,
@brief GPS 详情,其中包括GPS 的状态等,详情请参见:T_PsdkDataSubscriptionGpsDetail PSDK_DATA_SUBSCRIPTION_TOPIC_GPS_DETAILS,
@brief GPS 信号等级,提供GPS 信号的质量信息,详情请参见:T_PsdkDataSubscriptionGpsSignalLevel PSDK_DATA_SUBSCRIPTION_TOPIC_GPS_SIGNAL_LEVEL,
@brief RTK 位置,详情请参见:T_PsdkDataSubscriptionRtkPosition @details | Axis | Accuracy | |------|----------------------------------| | x, y | 卫星精度和校准状态较好时约为2cm | | z | 卫星精度和校准状态较好时约为3cm | PSDK_DATA_SUBSCRIPTION_TOPIC_RTK_POSITION,
@brief RTK 速度,详情请参见:T_PsdkDataSubscriptionRtkVelocity PSDK_DATA_SUBSCRIPTION_TOPIC_RTK_VELOCITY,
@brief RTK 偏航角度,详情请参见:T_PsdkDataSubscriptionRtkYaw @details 该订阅项为无人机1号天线到2号天线的向量的偏航角,即RTK 偏航值与无人机的偏航角相差90度 PSDK_DATA_SUBSCRIPTION_TOPIC_RTK_YAW,
@brief RTK 位置的状态,详情请参见:T_PsdkDataSubscriptionRtkPositionInfo PSDK_DATA_SUBSCRIPTION_TOPIC_RTK_POSITION_INFO,
@brief RTK 偏航角状态,详情请参见:T_PsdkDataSubscriptionRtkYawInfo PSDK_DATA_SUBSCRIPTION_TOPIC_RTK_YAW_INFO,
@brief 无人机飞行状态,详情请参见:T_PsdkDataSubscriptionFlightStatus PSDK_DATA_SUBSCRIPTION_TOPIC_STATUS_FLIGHT,
@brief 无人机电池信息,详情请参见:T_PsdkDataSubscriptionBatteryInfo PSDK_DATA_SUBSCRIPTION_TOPIC_BATTERY_INFO,
所有可订阅的主题的数量 PSDK_DATA_SUBSCRIPTION_TOPIC_TOTAL_NUMBER, } E_PsdkDataSubscriptionTopicName;
|
typedef enum E_PsdkDataSubscriptionDataHealthFlag
订阅数据的健康状态
typedef enum { PSDK_DATA_SUBSCRIPTION_DATA_NOT_HEALTH = 0, 订阅数据不可用 PSDK_DATA_SUBSCRIPTION_DATA_HEALTH = 1, 订阅数据有效且可用 } E_PsdkDataSubscriptionDataHealthFlag;
|
typedef enum E_PsdkDataSubscriptionPositionSolutionProperty
位置解属性
typedef enum { PSDK_DATA_SUBSCRIPTION_POSITION_SOLUTION_PROPERTY_NOT_AVAILABLE = 0, 位置解数据不可用 PSDK_DATA_SUBSCRIPTION_POSITION_SOLUTION_PROPERTY_FIX_POSITION = 1, 位置由FIX POSITION命令指定 PSDK_DATA_SUBSCRIPTION_POSITION_SOLUTION_PROPERTY_FIX_HEIGHT_AUTO = 2, 位置由FIX HEIGHT / AUTO命令指定 PSDK_DATA_SUBSCRIPTION_POSITION_SOLUTION_PROPERTY_INSTANTANEOUS_DOPPLER_COMPUTE_VELOCITY = 8, 速度由即时多普勒信息导出 PSDK_DATA_SUBSCRIPTION_POSITION_SOLUTION_PROPERTY_SINGLE_PNT_SOLUTION = 16, 单点位置解 PSDK_DATA_SUBSCRIPTION_POSITION_SOLUTION_PROPERTY_PSEUDORANGE_DIFFERENTIAL_SOLUTION = 17, 伪距差分解 PSDK_DATA_SUBSCRIPTION_POSITION_SOLUTION_PROPERTY_SBAS_CORRECTION_CALCULATED = 18, SBAS定位 PSDK_DATA_SUBSCRIPTION_POSITION_SOLUTION_PROPERTY_KALMAN_FILTER_WITHOUT_OBSERVATION_PROPAGATED = 19, 由一个没有新观测值的卡尔曼滤波器输出 PSDK_DATA_SUBSCRIPTION_POSITION_SOLUTION_PROPERTY_OMNISTAR_VBS_POSITION = 20, OmniSTAR VBS 位置 (L1 sub-metre) PSDK_DATA_SUBSCRIPTION_POSITION_SOLUTION_PROPERTY_FLOAT_L1_AMBIGUITY = 32, L1浮点解 PSDK_DATA_SUBSCRIPTION_POSITION_SOLUTION_PROPERTY_FLOAT_IONOSPHERIC_FREE_AMBIGUITY = 33, 消电离层浮点解 PSDK_DATA_SUBSCRIPTION_POSITION_SOLUTION_PROPERTY_FLOAT_SOLUTION = 34, 窄巷浮点解 PSDK_DATA_SUBSCRIPTION_POSITION_SOLUTION_PROPERTY_L1_AMBIGUITY_INT = 48, L1固定解 PSDK_DATA_SUBSCRIPTION_POSITION_SOLUTION_PROPERTY_WIDE_LANE_AMBIGUITY_INT = 49, 宽巷固定解 PSDK_DATA_SUBSCRIPTION_POSITION_SOLUTION_PROPERTY_NARROW_INT = 50, 窄巷固定解 } E_PsdkDataSubscriptionPositionSolutionProperty;
|
typedef enum E_PsdkDataSubscriptionGpsFixState
GPS 定位状态
typedef enum { PSDK_DATA_SUBSCRIPTION_GPS_FIX_STATE_NO_FIX = 0, GPS 未获取到定位信息 PSDK_DATA_SUBSCRIPTION_GPS_FIX_STATE_DEAD_RECKONING_ONLY = 1, GPS推算得到 GPS 位置 PSDK_DATA_SUBSCRIPTION_GPS_FIX_STATE_2D_FIX = 2, 包含纬度/经度(或X / Y)的水平位置已定位 PSDK_DATA_SUBSCRIPTION_GPS_FIX_STATE_3D_FIX = 3, 包含纬度/经度/海拔(或X / Y / Z)的水平和垂直位置已定位 PSDK_DATA_SUBSCRIPTION_GPS_FIX_STATE_GPS_PLUS_DEAD_RECKONING = 4, GPS推测计算位置 PSDK_DATA_SUBSCRIPTION_GPS_FIX_STATE_TIME_ONLY_FIX = 5, 仅时间信息有效 } E_PsdkDataSubscriptionGpsFixState;
|
typedef enum E_PsdkDataSubscriptionFlightStatus
无人机飞行状态
typedef enum { PSDK_DATA_SUBSCRIPTION_FLIGHT_STATUS_STOPED = 0, 无人机在地面上且电机静止 PSDK_DATA_SUBSCRIPTION_FLIGHT_STATUS_ON_GROUND = 1, 无人机在地面上,但电机仍在转动 PSDK_DATA_SUBSCRIPTION_FLIGHT_STATUS_IN_AIR = 2, 无人机在空中 } E_PsdkDataSubscriptionFlightStatus;
|
数据结构
typedef struct T_PsdkDataSubscriptiontTimestamp
时间戳
typedef struct { uint32_t millisecond; 毫秒 uint32_t microsecond; 微秒 } T_PsdkDataSubscriptiontTimestamp;
|
typedef struct T_PsdkDataSubscriptionQuaternion
四元数
typedef struct Quaternion { psdk_f32_t q0; w, 使用弧度制 (转换为旋转矩阵或欧拉角) psdk_f32_t q1; x, 使用弧度制 (转换为旋转矩阵或欧拉角) psdk_f32_t q2; y, 使用弧度制 (转换为旋转矩阵或欧拉角) psdk_f32_t q3; z, 使用弧度制 (转换为旋转矩阵或欧拉角) } T_PsdkDataSubscriptionQuaternion;
|
typedef struct T_PsdkDataSubscriptionVelocity
速度
typedef struct Velocity { 速度数值 T_PsdkVector3f data; 健康状态,该值可为:E_PsdkDataSubscriptionDataHealthFlag 中的任意值 uint8_t health : 1; 保留 uint8_t reserve : 7; } T_PsdkDataSubscriptionVelocity;
|
typedef struct T_PsdkDataSubscriptionPositionFused
融合位置
typedef struct PositionFused { psdk_f64_t longitude; 经度(单位:度) psdk_f64_t latitude; 纬度(单位:度) psdk_f64_t altitude; 纬度,WGS 84 参考椭球系, 单位:米 uint16_t visibleSatelliteNumber; 可见卫星数 } T_PsdkDataSubscriptionPositionFused;
|
typedef struct T_PsdkDataSubscriptionGpsDetail
GPS 详细信息
typedef struct GpsDetail { psdk_f32_t hdop; 水平面精度因子,<1:ideal极好, 1-2:excellent较好, 2-5:good好, 5-10:moderate普通, 10-20:fair差, >20:poor较差 psdk_f32_t pdop; 3D位置精度因子,<1:ideal极好, 1-2:excellent较好, 2-5:good好, 5-10:moderate普通, 10-20:fair差, >20:poor较差 psdk_f32_t fixState; GPS 定位状态,详情请参见:E_PsdkDataSubscriptionGpsFixState. psdk_f32_t vacc; 垂直位置精度(mm),越低越好 psdk_f32_t hacc; 水平位置精度(mm),越低越好 psdk_f32_t sacc; 速度精度(cm/s),越低越好 uint32_t gpsSatelliteNumberUsed; 用于定位的GPS卫星数。 uint32_t glonassSatelliteNumberUsed; 用于定位的GLONASS卫星数。 uint16_t totalSatelliteNumberUsed; 用于定位的卫星总数 uint16_t gpsCounter; 发送GPS数据的累计次数。 } T_PsdkDataSubscriptionGpsDetail;
|
typedef struct T_PsdkDataSubscriptionRtkPosition
RTK 位置信息
typedef struct PositionData { psdk_f64_t longitude; 经度,单位:度 psdk_f64_t latitude; 维度,单位:度 psdk_f32_t hfsl; 海平面以上的高度, 单位:米 } T_PsdkDataSubscriptionRtkPosition;
|
typedef struct T_PsdkDataSubscriptionBatteryInfo
电池的信息
typedef struct BatteryInfo { uint32_t capacity; 电池容量,单位:mAh int32_t voltage; 电池电压, 单位:mV int32_t current; 当前电流,单位:mA uint8_t percentage; 电池剩余电量比例,单位:1% } T_PsdkDataSubscriptionBatteryInfo;
|
函数原型
typedef function ReceiveDataOfTopicCallback
用于接收订阅数据的函数原型。
说明: 为防止接收订阅数据的函数阻塞PSDK 的线程或造成死循环,请勿以阻塞的方式在回调函数中获取无人机订阅数据。
typedef T_PsdkReturnCode (*ReceiveDataOfTopicCallback)(const uint8_t *data, uint16_t dataSize, const T_PsdkDataSubscriptiontTimestamp *timestamp);
|
参数
data:指向订阅项的指针,如需获取订阅项中的每一条信息,请将此指针的类型转换为该指针对应的数据结构
dataSize:指向用于存储订阅项的空间,其空间大小与订阅项的长度相同
timestamp:存储某订阅项对应的时间戳
返回值
根据程序执行的情况输出对应的返回值,详情请参见:PsdkErrorCode
function PsdkDataSubscription_Init
消息订阅功能初始化,并开始执行消息订阅功能。
说明
- 在使用消息订阅功能订阅无人机上的信息前,请先使用本接口初始化消息订阅功能;
- 请勿在main()函数中调用本接口,请在用户线程中调用本接口,启动调度器后,该接口将正常运行;
- 本接口执行时间可能会超过 500ms。
T_PsdkReturnCode PsdkDataSubscription_Init(void);
|
返回值
根据程序执行的情况输出对应的返回值,详情请参见:PsdkErrorCode
function PsdkDataSubscription_DeInit
释放消息订阅功能。在无需使用消息订阅功能时,可调用本接口释放消息订阅功能。
说明: 释放消息订阅功能后,无人机中被占用的资源也将释放。
T_PsdkReturnCode PsdkDataSubscription_DeInit(void);
|
返回值
根据程序执行的情况输出对应的返回值,详情请参见:PsdkErrorCode
function PsdkDataSubscription_RegTopicSync
在阻塞模式下使用消息订阅功能。
说明
- 在使用消息订阅功能订阅无人机上的信息前,请先指定订阅频率和订阅项,通过构造并注册回调函数,获取无人机最新产生的订阅项的数据信息及其对应的时间;消息订阅成功后,可调用PsdkDataSubscription_GetValueOfTopicWithTimestamp() 接口获得订阅项最新的数据和相应的时间戳(注册回调函数后,回调函数将获得订阅项的数据和该数据对应的时间戳);
- 本接口执行时间可能会超过 1200ms;
- 每个订阅项仅可被订阅一次,不可被重复订阅。
T_PsdkReturnCode PsdkDataSubscription_RegTopicSync(E_PsdkDataSubscriptionTopicName topic, uint16_t frequency,ReceiveDataOfTopicCallback callback);
|
参数
topic:订阅项的名称
frequency:订阅项的频率,该频率不可超过最大订阅频率限制;最多支持订阅4类频率,如最多支持订阅10Hz、20Hz、50Hz、100Hz,4类频率,且相同订阅频率的主题的数据长度总和须小于或等于242。;订阅频率不能小于或等于0
callback:用于接收订阅数据的回调函数,则该参数可为空
返回值
根据程序执行的情况输出对应的返回值,详情请参见:PsdkErrorCode
function PsdkDataSubscription_AntiRegTopicSync
功能:以阻塞模式取消订阅数据项 |
product:all |
调用该接口必须指定在订阅数据项时填入的频率与回调函数。如果频率或回调函数不正确,取消订阅操作将失败,并且接口返回错误。
说明
T_PsdkReturnCode PsdkDataSubscription_AntiRegTopicSync(E_PsdkDataSubscriptionTopicName topic, uint16_t frequency, ReceiveDataOfTopicCallback callback);
|
参数
topic:需要取消订阅的数据项名称
frequency:订阅时填入的订阅频率
callback:订阅时填入的回调函数
返回值
根据程序执行的情况输出对应的返回值,详情请参见:PsdkErrorCode
function PsdkDataSubscription_GetValueOfTopicWithTimestamp
功能:获取最新的数据和时间戳 |
product:all |
获取无人机上订阅项最新的数据和时间戳,订阅失败时,该接口将返回错误码。
说明: 调用本接口时,请指定订阅项,以及相应的数据。
T_PsdkReturnCode PsdkDataSubscription_GetValueOfTopicWithTimestamp(E_PsdkDataSubscriptionTopicName topicName, uint8_t *data, uint16_t dataSizeOfTopic, T_PsdkDataSubscriptiontTimestamp *timestamp);
|
参数
topicName:订阅项的名称
data:请正确地指向用于存储订阅项数据的存储空间,否则,本接口将返回错误码
dataSizeOfTopic:请正确地指向用于存储订阅项数据的存储空间,正常情况下,该数值与订阅项的长度相同,否则可能会导致内存溢出等问题
timestamp:请正确地指向用于存储时间戳的内存空间,否则,本接口将返回错误码或出现内存溢出等问题,若无需获取时间戳,则该参数可为空
返回值
根据程序执行的情况输出对应的返回值,详情请参见:PsdkErrorCode