消息订阅

2022-07-25

PSDK 消息订阅相关功能的头文件为psdk_data_subscription.h,本文档描述了psdk_data_subscription.h 文件中结构体和函数原型的关键信息和使用方法。

目录

宏定义

  • 融合高度(单位: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