消息订阅
PSDK 消息订阅相关功能的头文件为psdk_data_subscription.h
,本文档描述了psdk_data_subscription.h
文件中结构体和函数原型的关键信息和使用方法。
目录
枚举
E_PsdkDataSubscriptionTopicName
E_PsdkDataSubscriptionDataHealthFlag
E_PsdkDataSubscriptionPositionSolutionProperty
E_PsdkDataSubscriptionGpsFixState
E_PsdkDataSubscriptionFlightStatus结构体
T_PsdkDataSubscriptiontTimestamp
T_PsdkDataSubscriptionQuaternion
T_PsdkDataSubscriptionVelocity
T_PsdkDataSubscriptionPositionFused
T_PsdkDataSubscriptionGpsDetail
T_PsdkDataSubscriptionRtkPosition
T_PsdkDataSubscriptionBatteryInfo函数原型
ReceiveDataOfTopicCallback
PsdkDataSubscription_Init
PsdkDataSubscription_DeInit
PsdkDataSubscription_RegTopicSync
PsdkDataSubscription_AntiRegTopicSync
PsdkDataSubscription_GetValueOfTopicWithTimestamp
宏定义
- 融合高度(单位:m)
typedef psdk_f32_t T_PsdkDataSubscriptionAltitudeFused;
- 相对高度(单位:m)
typedef psdk_f32_t T_PsdkDataSubscriptionHeightRelative;
- GPS 日期,格式为:yyyymmdd
typedef uint32_t T_PsdkDataSubscriptionGpsDate;
- GPS 时间,格式为:hhmmss
typedef uint32_t T_PsdkDataSubscriptionGpsTime;
- GPS 位置 x=经度, y=纬度, z=高度, 单位:度*10-7 (经度,纬度), mm (海拔高度)
typedef T_PsdkVector3d T_PsdkDataSubscriptionGpsPosition;
- GPS 速度,单位为:cm/s
typedef T_PsdkVector3f T_PsdkDataSubscriptionGpsVelocity;
- GPS 信号的等级。GPS 信号优劣等级由低到高依次是0~5。
typedef uint8_t T_PsdkDataSubscriptionGpsSignalLevel;
- RTK 速度,单位:cm/s
typedef T_PsdkVector3f T_PsdkDataSubscriptionRtkVelocity;
- RTK 偏航角度,单位:度
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
功能:接收订阅数据 | product:all |
用于接收订阅数据的函数原型。
说明: 为防止接收订阅数据的函数阻塞PSDK 的线程或造成死循环,请勿以阻塞的方式在回调函数中获取无人机订阅数据。
typedef T_PsdkReturnCode (*ReceiveDataOfTopicCallback)(const uint8_t *data, uint16_t dataSize,
const T_PsdkDataSubscriptiontTimestamp *timestamp);
data:指向订阅项的指针,如需获取订阅项中的每一条信息,请将此指针的类型转换为该指针对应的数据结构
dataSize:指向用于存储订阅项的空间,其空间大小与订阅项的长度相同
timestamp:存储某订阅项对应的时间戳
返回值
根据程序执行的情况输出对应的返回值,详情请参见:PsdkErrorCode
function PsdkDataSubscription_Init
功能:消息订阅模块初始化 | product:all |
消息订阅功能初始化,并开始执行消息订阅功能。
说明
- 在使用消息订阅功能订阅无人机上的信息前,请先使用本接口初始化消息订阅功能;
- 请勿在main()函数中调用本接口,请在用户线程中调用本接口,启动调度器后,该接口将正常运行;
- 本接口执行时间可能会超过 500ms。
T_PsdkReturnCode PsdkDataSubscription_Init(void);
返回值
根据程序执行的情况输出对应的返回值,详情请参见:PsdkErrorCode
function PsdkDataSubscription_DeInit
功能:释放消息订阅功能 | product:all |
释放消息订阅功能。在无需使用消息订阅功能时,可调用本接口释放消息订阅功能。
说明: 释放消息订阅功能后,无人机中被占用的资源也将释放。
T_PsdkReturnCode PsdkDataSubscription_DeInit(void);
返回值
根据程序执行的情况输出对应的返回值,详情请参见:PsdkErrorCode
function PsdkDataSubscription_RegTopicSync
功能:使用消息订阅功能 | product:all |
在阻塞模式下使用消息订阅功能。
说明
- 在使用消息订阅功能订阅无人机上的信息前,请先指定订阅频率和订阅项,通过构造并注册回调函数,获取无人机最新产生的订阅项的数据信息及其对应的时间;消息订阅成功后,可调用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 |
调用该接口必须指定在订阅数据项时填入的频率与回调函数。如果频率或回调函数不正确,取消订阅操作将失败,并且接口返回错误。
说明
- 本接口执行时间可能会超过 600ms;
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