Payload SDK

Data Subscription

2024-07-11
No Rating
Github Edit open in new window

Overview

The information management function of PSDK includes information acquisition and message subscription functions. The payload device developed based on PSDK has the information acquisition function, which can actively obtain information such as the model of the drone, the location where the payload device is mounted, and the Mobile App used by the user. Loading different configuration files is convenient for users to use the payload device. The payload device with message subscription function can record the data information subscribed by the user, which is convenient for the user to realize a wider range of applications.

Basic concepts

Access to information

Information acquisition means that the payload device can actively acquire and record the data information on the drone, such as the drone model, hardware platform type, and the mounting position of the payload device.

Note: Install the payload device developed with PSDK on the drone, and the correct data information of the drone can be obtained only after 5s of booting and initialization.

After the payload device developed with PSDK is initialized, the following information can be obtained:

  • Basic information: drone model, hardware platform type, and payload mounting location
  • Mobile App information: the system language of the App and the screen type of the App

Data subscription

Various components on the drone will generate a large amount of data information in real time according to the actual flight status of the drone and will be pushed to other modules by the drone. The user can specify the data information to be subscribed by using the payload device with the message subscription function.

The following figures show the positions of the RTK and GPS modules on the Matrice 300 RTK and Matrice 350 RTK aircraft.

M300M350

Subscription Process

After subscribing to the data item, the payload device can obtain the subscription information. The specific process is shown in Figure 1. Message subscription.

Figure 1. Message subscription

Subscription Topics

Subscribable data information is shown at Table. Drone Subscription Topics.

Note: If you want search the topics in the code project, please replace the "*_" to "DJI_FC_SUBSCRIPTION_TOPIC_QUATERNION". For example, *_QUATERNION should be extended to DJI_FC_SUBSCRIPTION_TOPIC_QUATERNION.

Table. Drone Subscription Topics

Data Subscription TopicM300 RTKMatrice 30/30TMavic 3E/3TMatrice 3D/3TDFlycart 30M350 RTKMatrice 4T
Attitude quaternion
*_QUATERNION		Maximum 200HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 200HzMaximum 50Hz
Acceleration relative to the ground
*_ACCELERATION_GROUND		Maximum 200HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 200HzMaximum 50Hz
Acceleration relative to the drone
*_ACCELERATION_BODY		Maximum 200HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 200HzMaximum 50Hz
Original acceleration
*_ACCELERATION_RAW		Maximum 400HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 400HzMaximum 50Hz
Speed
*_VELOCITY		Maximum 200HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 200HzMaximum 50Hz
Fusion angular volecity
*_ANGULAR_RATE_FUSIONED		Maximum 200HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 200HzMaximum 50Hz
Original angular volecity
*_ANGULAR_RATE_RAW		Maximum 400HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 400HzMaximum 50Hz
Fused altitude
*_ALTITUDE_FUSED		Maximum 200HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 200HzMaximum 50Hz
Altitude of barometer
*_ALTITUDE_BAROMETER		Maximum 200HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 200HzMaximum 50Hz
Home point altitude
*_ALTITUDE_OF_HOMEPOINT		Maximum 1HzMaximum 50HzMaximum 5HzMaximum 5HzMaximum 5HzMaximum 1HzMaximum 5Hz
Fusion height relative to the ground
*_HEIGHT_FUSION		Maximum 100HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 100HzMaximum 50Hz
Height relative to the ground
*_HEIGHT_RELATIVE		Maximum 200Hz----Maximum 200Hz-
Coordinate of fused position
*_POSITION_FUSED		Maximum 200Hz----Maximum 200Hz-
GPS date(year/month/day)
*_GPS_DATE		Maximum 5HzMaximum 50HzMaximum 5HzMaximum 5HzMaximum 5HzMaximum 5HzMaximum 5Hz
GPS time(hour/miniute/second)
*_GPS_TIME		Maximum 5HzMaximum 50HzMaximum 5HzMaximum 5HzMaximum 5HzMaximum 5HzMaximum 5Hz
GPS position
*_GPS_POSITION		Maximum 5HzMaximum 50HzMaximum 5HzMaximum 5HzMaximum 5HzMaximum 5HzMaximum 5Hz
GPS velocity
*_GPS_VELOCITY		Maximum 5HzMaximum 50HzMaximum 5HzMaximum 5HzMaximum 5HzMaximum 5HzMaximum 5Hz
GPS inofrmation
*_GPS_DETAILS		Maximum 5HzMaximum 50HzMaximum 5HzMaximum 5HzMaximum 5HzMaximum 5HzMaximum 5Hz
GPS signal level
*_GPS_SIGNAL_LEVEL		Maximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50Hz
RTK position
*_RTK_POSITION		Maximum 5HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 5HzMaximum 50Hz
RTK velocity
*_RTK_VELOCITY		Maximum 5HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 5HzMaximum 50Hz
RTK yaw angle
*_RTK_YAW		Maximum 5HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 5HzMaximum 50Hz
RTK position information
*_RTK_POSITION_INFO		Maximum 5HzMaximum 50HzMaximum 5HzMaximum 5HzMaximum 5HzMaximum 5HzMaximum 5Hz
RTK yaw information
*_RTK_YAW_INFO		Maximum 5HzMaximum 50HzMaximum 5HzMaximum 5HzMaximum 5HzMaximum 5HzMaximum 5Hz
Compass information
*_COMPASS		Maximum 100HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 100HzMaximum 50Hz
RC stick information
*_RC		Maximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50Hz
Gimbal angle
*_GIMBAL_ANGLES		Maximum 50Hz50Hz Only50Hz Only50Hz Only50Hz OnlyMaximum 50Hz50Hz Only
Gimbal status
*_GIMBAL_STATUS		Maximum 50Hz----Maximum 50Hz-
Flight status
*_STATUS_FLIGHT		Maximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50Hz
Flight mode status
*_STATUS_DISPLAYMODE		Maximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50Hz
Landing gear status
*_STATUS_LANDINGGEAR		Maximum 50Hz----Maximum 50Hz-
Motor starting error code
*_STATUS_MOTOR_START_ERROR		Maximum 50Hz-Maximum 5HzMaximum 5HzMaximum 5HzMaximum 50HzMaximum 5Hz
Battery information
*_BATTERY_INFO		Maximum 50Hz----Maximum 50Hz-
Device controlling information
*_CONTROL_DEVICE		Maximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50Hz
Firmware clock synchronization
*_HARD_SYNC		Maximum 400HzMaximum 50Hz---Maximum 400Hz-
GPS controlling level
*_GPS_CONTROL_LEVEL		Maximum 50HzMaximum 50Hz---Maximum 50Hz-
RC information with flag
*_RC_WITH_FLAG_DATA		Maximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50Hz
ESC data
*_ESC_DATA		Maximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50Hz
RTK connection status
*_RTK_CONNECT_STATUS		Maximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50Hz
Gimbal controlling mode
*_GIMBAL_CONTROL_MODE		Maximum 50Hz----Maximum 50Hz-
Flight abnormal information
*_FLIGHT_ANOMALY		Maximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50Hz
Cartesian coordinates position
*_POSITION_VO		Maximum 200HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 200HzMaximum 50Hz
Obstacle avoidance data
*_AVOID_DATA		Maximum 100HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 100HzMaximum 50Hz
Home point setting status
*_HOME_POINT_SET_STATUS		Maximum 50HzMaximum 50HzMaximum 5HzMaximum 5HzMaximum 5HzMaximum 50HzMaximum 5Hz
Home point information
*_HOME_POINT_INFO		Maximum 50HzMaximum 50HzMaximum 5HzMaximum 5HzMaximum 5HzMaximum 50HzMaximum 5Hz
Three gimbal information
(Corresponding to M300 RTK and M350 RTK, three gimbals above and below the drone)
*_THREE_GIMBAL_DATA		Maximum 50Hz----Maximum 50Hz-
Information of battery 1
*_BATTERY_SINGLE_INFO_INDEX1		Maximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50HzMaximum 50Hz
Information of battery 2
*_BATTERY_SINGLE_INFO_INDEX2		Maximum 50HzMaximum 50Hz---Maximum 50Hz-

Subscription Rules

  • The supported frequencies of subscrption topics are 1Hz, 5Hz, 10Hz, 50Hz, 100Hz, 200Hz and 400Hz. Range of each topic is different. Each topic supports repetitve subscription.
  • When specifying the subscription frequency, the subscription frequency of any parameter cannot be less than or equal to 0, and the sum of the data lengths of topics with the same subscription frequency must be less than or equal to 242.

Note: When using the simulator in DJI Assistant 2 to simulate the working state of the payload device, the simulator will cannot obtain the sensor raw data such as GPS information and RTK information, but developers can subscribe to such as fusion location, Fusing fused data such as altitude or relative altitude.

Use the Message Subscription Feature

PSDK supports subscription to the data information pushed by the drone through registration callback and interface call:

  • Obtain the data information of the latest subscription item generated by the drone and its corresponding time by calling DjiFcSubscription_GetLatestValueOfTopic().
  • Specify the subscription frequency and subscription items by calling the DjiFcSubscription_SubscribeTopic interface, and obtain the data information of the latest subscription items generated by the drone and the corresponding time by constructing and registering the callback function.

Note: Use the subscription function to synchronize the data received by the subscription item with the time of the drone system when the data is generated. This time is not currently supported and the time on the payload device.

Message Subscription Function Module Initialization

If a payload developed with PSDK needs to subscribe to the status information on the drone, it needs to call DjiFcSubscription_Init() to initialize the message subscription module.

djiStat = DjiFcSubscription_Init();
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
    USER_LOG_ERROR("init data subscription module error.");
    return DJI_ERROR_SYSTEM_MODULE_CODE_UNKNOWN;
}

Get the Information on the Drone by Constructing the Callback Function

  1. Construct callback function Receive the information pushed by the drone by constructing a callback function.

Note: To avoid memory stamping events, the type of the data address must be cast to the pointer type in the subscription data structure.

static T_DjiReturnCode DjiTest_FcSubscriptionReceiveQuaternionCallback(const uint8_t *data, uint16_t dataSize, const T_DjiDataTimestamp *timestamp)
{
    T_DjiFcSubscriptionQuaternion *quaternion = (T_DjiFcSubscriptionQuaternion *) data;
    dji_f64_t pitch, yaw, roll;

    USER_UTIL_UNUSED(dataSize);

    pitch = (dji_f64_t) asinf(-2 * quaternion->q1 * quaternion->q3 + 2 * quaternion->q0 * quaternion->q2) * 57.3;
    roll = (dji_f64_t) atan2f(2 * quaternion->q2 * quaternion->q3 + 2 * quaternion->q0 * quaternion->q1, -2 * quaternion->q1 * quaternion->q1 - 2 * quaternion->q2 * quaternion->q2 + 1) * 57.3;
    yaw = (dji_f64_t) atan2f(2 * quaternion->q1 * quaternion->q2 + 2 * quaternion->q0 * quaternion->q3, -2 * quaternion->q2 * quaternion->q2 - 2 * quaternion->q3 * quaternion->q3 + 1) * 57.3;

    if (s_userFcSubscriptionDataShow == true) {
        USER_LOG_INFO("receive quaternion data.");

        USER_LOG_INFO("timestamp: millisecond %u microsecond %u.", timestamp->millisecond,
                      timestamp->microsecond);
        USER_LOG_INFO("quaternion: %f %f %f %f.\r\n", quaternion->q0, quaternion->q1, quaternion->q2, quaternion->q3);
        USER_LOG_INFO("euler angles: pitch = %.2f roll = %.2f yaw = %.2f.", pitch, yaw, roll);
        DjiTest_WidgetLogAppend("pitch = %.2f roll = %.2f yaw = %.2f.", pitch, yaw, roll);
    }

    return DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS;
}
  1. Register callback function
    The registration callback function receives the data information generated by the drone and pushed to the outside world. The following code subscribes the drone's "drone flight speed" and "drone GPS coordinates" at a frequency of 1Hz, as shown in Figure 2. Subscription results (1) shown.

Note: When using the subscription function to subscribe to the data information on the drone, the subscription frequency can only be a submultiple of the "maximum subscription frequency".

djiStat = DjiFcSubscription_SubscribeTopic(DJI_FC_SUBSCRIPTION_TOPIC_QUATERNION, DJI_DATA_SUBSCRIPTION_TOPIC_1_HZ,
                                           DjiTest_FcSubscriptionReceiveQuaternionCallback);
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
    USER_LOG_ERROR("Subscribe topic quaternion error.");
    return DJI_ERROR_SYSTEM_MODULE_CODE_UNKNOWN;
}

Figure 2. Subscription results (1)

Get Info on Drone in Thread Function

Non callback method to start the subscription. The callback parameter is set to NULL.

djiStat = DjiFcSubscription_SubscribeTopic(DJI_FC_SUBSCRIPTION_TOPIC_VELOCITY, DJI_DATA_SUBSCRIPTION_TOPIC_1_HZ,
                                               NULL);
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
    USER_LOG_ERROR("Subscribe topic velocity error.");
    return DJI_ERROR_SYSTEM_MODULE_CODE_UNKNOWN;
}

djiStat = DjiFcSubscription_SubscribeTopic(DJI_FC_SUBSCRIPTION_TOPIC_GPS_POSITION, DJI_DATA_SUBSCRIPTION_TOPIC_1_HZ,
                                               NULL);
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
  	USER_LOG_ERROR("Subscribe topic gps position error.");
    return DJI_ERROR_SYSTEM_MODULE_CODE_UNKNOWN;
}

Obtain the information pushed by the drone through the data subscription thread function and print it on the terminal. The following code subscribes the latest drone flight speed and drone GPS coordinates generated by the drone at a frequency of 1Hz, as well as the corresponding time of the data, as shown in Figure 3. Subscription result (2).

djiStat = DjiFcSubscription_GetLatestValueOfTopic(DJI_FC_SUBSCRIPTION_TOPIC_VELOCITY,
                                                  (uint8_t *) &velocity,
                                                  sizeof(T_DjiFcSubscriptionVelocity),
                                                  &timestamp);
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
    USER_LOG_ERROR("get value of topic velocity error.");
} else {
    USER_LOG_INFO("velocity: x = %f y = %f z = %f healthFlag = %d.", velocity.data.x, velocity.data.y,
                  velocity.data.z, velocity.health);
}

djiStat = DjiFcSubscription_GetLatestValueOfTopic(DJI_FC_SUBSCRIPTION_TOPIC_GPS_POSITION,
                                                  (uint8_t *) &gpsPosition,
                                                  sizeof(T_DjiFcSubscriptionGpsPosition),
                                                  &timestamp);
if (djiStat != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
    USER_LOG_ERROR("get value of topic gps position error.");
} else {
    USER_LOG_INFO("gps position: x = %d y = %d z = %d.", gpsPosition.x, gpsPosition.y, gpsPosition.z);
}

Figure 3. Subscription results (2)

How was your reading experience of our documentation?
If you have any comments or confusion about our documentation, you can click here to give feedback and we will get back to you as soon as possible.