消息订阅

2022-08-30
暂无评分

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
最近修改: 8/30/2022, 9:59:01 AM
若您对文档有意见或疑惑,点击可快速反馈,我们会与您联系。