5.6 遥测数据订阅（fc_subscription）

• 基本功能介绍

• 主要代码文件

• sample代码实现

• 开发注意事项

5.6 遥测数据订阅

5.6.1 基本功能介绍

SDK中的遥测数据是指DJI飞行器状态等信息，以及飞行器上传感器的相关数据，比如飞行器速度、姿态，GPS坐标，高度等。OSDK端口和PSDK端口均支持遥测数据订阅，不同的端口订阅到的数据源基本一样，但其用途可因负载功能自行订阅读取。无人机在飞行过程中，其飞行信息和传感器信息都是在动态变更，采用订阅的方式，无人机将会以一定的频率推送到SDK端，在一定程度上可以理解为SDK实时获取相关遥测数据，在OSDK端可以实时调整控制策略，PSDK端口实时将相关数据记录或者融合到负载设备。

旧版本OSDK还支持使用广播方式，对SDK端来说两种方式是一样的，都是飞机端将遥测数据以一定的频率发布出来。但随着版本迭代，OSDK逐渐使用订阅方式取代了广播方式，新版本PSDK 3.x开始已经将广播方式移除。但M300无人机OSDK依旧支持广播，广播和订阅均通过串口通道传输。为避免广播包占用带宽，建议在使用PSDK 3.0开发时，在DJI Assistant2上OSDK界面将各数据均设置为不发送。详见DJI无人机与调参仿真软件 -- DJI Assistant2 OSDK界面部分。PSDK端口各版本仅支持订阅方式。

PSDK 3.0支持订阅的主要数据包整理如下，订阅的数据由飞控发出，格式固定，具体数据定义可参考PSDK lib头文件。

5.6.2 主要代码文件

fc_subscription/

├── test_fc_subscription.c

└── test_fc_subscription.h

PSDK lib头文件：

dji_fc_subscription.h

5.6.3 sample代码实现

FcSubscription功能入口

1. OSDK通过widget进入

DjiTest_FcSubscriptionRunSample(void)

2. PSDK通过宏打开

#ifdef CONFIG_MODULE_SAMPLE_FC_SUBSCRIPTION_ON
    returnCode = DjiTest_FcSubscriptionStartService();
    if (returnCode != DJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS) {
        USER_LOG_ERROR("data subscription sample init error\n");
    }
#endif

两者内部的调用的lib API一致，应用端无需区分PSDK端口还是OSDK端口，此版本PSDK 3.x中的消息订阅已经高度封装，API也较为简单，主要在其数据格式及定义。结合DjiTest_FcSubscriptionRunSample将lib API提炼出来如下：

USER_LOG_INFO("--> Step 1: Init fc 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;
    }
​
    USER_LOG_INFO("--> Step 2: Subscribe the topics of quaternion, velocity and gps position");
    djiStat = DjiFcSubscription_SubscribeTopic(DJI_FC_SUBSCRIPTION_TOPIC_QUATERNION, DJI_DATA_SUBSCRIPTION_TOPIC_10_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;
    }
​
    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;
    }
​
    USER_LOG_INFO("--> Step 3: Get latest value of the subscribed topics in the next 20s\r\n");
​
    for (int i = 0; i < 20; ++i) {
        osalHandler->TaskSleepMs(1000 / FC_SUBSCRIPTION_TASK_FREQ);
        djiStat = DjiFcSubscription_GetLatestValueOfTopic(DJI_FC_SUBSCRIPTION_TOPIC_VELOCITY,
                                                          (uint8_t *) &velocity,
                                                          sizeof(T_DjiFcSubscriptionVelocity),
                                                          &timestamp);
        ...
    }        

初始化

/**
 * @brief Initialise data subscription module in blocking mode. This function has to be called before subscribing any
 * data, to initialize run environment of data subscription module, if need to subscribe data from aircraft.
 * @note Max execution time of this function is slightly larger than 500ms.
 * @note This function has to be called in user task, rather than main() function, and after scheduler being started.
 * @return Execution result.
 */
T_DjiReturnCode DjiFcSubscription_Init(void);

API简介：

• 初始化订阅模块，在调用订阅相关API之前需先调用此API。

• 对应DjiFcSubscription_DeInit为反初始化，无需使用订阅模块时需要调用，释放订阅数据占用的相关资源。

TOPIC订阅

/**
 * @brief Subscribe a topic in blocking mode. Before subscribing any data from aircraft, DjiFcSubscription_Init()
 * function has to be called.
 * @details User can subscribe a topic by specifying topic name, push frequency and callback function used to receive
 * data of topic (if needed). After subscribing successfully, the user can call
 * DjiFcSubscription_GetLatestValueOfTopic() function to get the latest data of the topic have been
 * subscribed and the corresponding timestamp when aircraft sends the data out, and the callback function will be called to
 * push data of the topic and corresponding timestamp if the callback function is specified.
 * @note Max execution time of this function is slightly larger than 1200ms.
 * @note Topic to be subscribed can not have been subscribed, that is, one topic can not be subscribed repeatedly.
 * @note User must ensure that types of subscription frequency of all topics have been subscribed is less than or
 * equal to 4. Otherwise, the subscribing topic will fail.
 * @note User must ensure that the data length sum of all topics of the same subscription frequency is less than or equal to 242.
 * @param topic: topic name to be subscribed.
 * @param frequency: subscription frequency of topic to be subscribed. Subscription frequency can not beyond max
 * frequency limitation of the topic and must be the value of enum E_DjiFcSubscriptionTopicFreq. And, subscription
 * frequency has to be larger than 0. Users can find max frequency of topics in data subscription part of documentation
 * on developer website (developer.dji.com).
 * @param callback: callback function used to receive data of topic to be subscribed. If the callback function is not needed,
 * this item can be set as NULL.
 * @return Execution result.
 */
T_DjiReturnCode DjiFcSubscription_SubscribeTopic(E_DjiFcSubscriptionTopic topic,
                                                 E_DjiDataSubscriptionTopicFreq frequency,
                                                 DjiReceiveDataOfTopicCallback callback);

API简介：

• 指定TOPIC发起数据订阅，在init之后调用。一个TOPIC不能重复订阅，所有订阅TOPIC的频率不能超过4种，且设定的参数频率不能超过该TOPIC支持的最大频率值。数据订阅项是通过串口通信通道，所有订阅项数据长度总和不能超过242KB。

参数：

• topic，遥测数据的标志，对应基本功能介绍中的订阅项TOPIC

• frequency，订阅topic时指定发布的频率，此频率不能超过对应topic支持的最大频率

• callback，获取订阅数据值的回调函数。当有数据发布过来时，将触发此回调。需要注意回调函数执行会影响底层数据更新，如果频率太高用下面的GetLatestValue主动读取。不需使用回调上抛时，直接将此参数设置为NULL即可。

读取订阅数值

除用回调被动获取订阅数值外，还可以使用API主动读取订阅数值。

/**
 * @brief Get the latest data value and timestamp in aircraft time system when sending the data from aircraft of specified
 * topic. If the specified topic has not been subscribed successfully, this function will return the error code.
 * @note After calling this function, user need transfer type of data pointer that pointer to data of topic to
 * corresponding data structure pointer for getting every item of the topic conveniently.
 * @param topicName: topic name to be gotten value.
 * @param data: pointer to memory space used to store data of the topic. The memory space used to store data of topic
 * have to have been allocated correctly and should ensure its size is equal to data structure size corresponding to
 * the topic, otherwise, this function will not be able to return data and timestamp (return error code).
 * @param dataSizeOfTopic: the size of memory space used to store data of topic. Normally, this size is equal to data
 * structure size corresponding to the topic. If this size is not equal to the size of the memory space, may cause memory
 * overflow event
 * @param timestamp: pointer to memory space used to store timestamps. The memory space used to store timestamps
 * have to have been allocated correctly, and should ensure its size is equal to data structure size of timestamp,
 * otherwise, this function will not be able to return data and timestamp (return error code) or even cause memory
 * overflow event. If the user does not need timestamp information, can fill in NULL.
 * @return Execution result.
 */
T_DjiReturnCode DjiFcSubscription_GetLatestValueOfTopic(E_DjiFcSubscriptionTopic topic,
                                                        uint8_t *data, uint16_t dataSizeOfTopic,
                                                        T_DjiDataTimestamp *timestamp);

API简介：

• 获取指定TOPIC的最新发布数据。获取数据前，需要先通过DjiFcSubscription_SubscribeTopic发起订阅。

参数：

• topic，指定读取数据的TOPIC

• data，存放数据的内存块，传入指针参数。

• dataSizeOfTopic，存放数据的内存块大小，通常与TOPIC定义的数据结构保持一致即可。

• timestamp，用于存放读取该数据值对应的时间戳，时间戳包括毫米和微秒。

/**
 * @brief Timestamp data structure.
 */
typedef struct {
    uint32_t millisecond; /*!< Millisecond. */
    uint32_t microsecond; /*!< Microsecond. */
} T_DjiDataTimestamp;

5.6.4 开发注意事项

1. 数据订阅功能在PSDK端口和OSDK端口都是通过串口通道实现，其订阅项数据量不能超过波特率带宽。

2. 同一个TOPIC不能重复订阅。

3. 要先发起订阅后才能去读取对应的TOPIC数据。

4. 订阅设置频率不能超过TOPIC支持的最大频率值，最大频率值是飞控和传感器发布效率固定的，SDK不能更改这个最大值。