Payload SDK

PSDK API 文档概览
PSDK Core
PSDK Core
PSDK 版本信息
PSDK Typedef
PSDK 错误码
PSDK 负载信息
PSDK 跨平台移植
PSDK 基础功能
信息管理
消息订阅
日志管理
电源管理
数据通道
数据传输
SDK 互联互通
时间同步
本地升级
应用实践
自定义控件
精准定位
负载协同
X-Port 控制
标准负载功能
云台功能
相机功能

消息订阅

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