本地升级相关功能的头文件为dji_upgrade.h，本文档描述了dji_upgrade.h 文件中结构体和函数原型的关键信息和使用方法。

说明： 仅使用X-Port 开发的负载设备可使用dji_upgrade.h，若使用SkyPort 开发负载设备，请使用dji_gimbal.h。

目录

• 宏定义、枚举与结构体
  E_DjiFirmwareTransferType
  E_DjiUpgradeStage
  E_DjiUpgradeEndState
  T_DjiFirmwareVersion
  T_DjiUpgradeOngoingInfo
  T_DjiUpgradeRebootInfo
  T_DjiUpgradeEndInfo
  T_DjiUpgradeFtpFileTransferInfo
  T_DjiUpgradeFileInfo
  T_DjiUpgradeDcftpFileTransferOpt
  T_DjiFirmwareTransferInfo
  T_DjiUpgradeState
  T_DjiUpgradeConfig
  T_DjiUpgradeHandler

• 函数原型
  DjiUpgrade_Init
  DjiUpgrade_EnableLocalUpgrade
  DjiUpgrade_RegHandler
  DjiUpgrade_PushUpgradeState

宏定义、枚举与结构体

typedef enum E_DjiFirmwareTransferType

X-Port 角度限制类型

typedef enum {  
    DJI_FIRMWARE_TRANSFER_TYPE_FTP = 0,  FTP固件传输类型
    DJI_FIRMWARE_TRANSFER_TYPE_DCFTP,  DCFTP固件传输类型
} E_DjiFirmwareTransferType;

typedef enum E_DjiUpgradeStage

角度限制的数据结构

typedef enum {
    DJI_UPGRADE_STAGE_IDLE = 0, /*!< 空闲阶段意味着不处于升级模式。 */
    DJI_UPGRADE_STAGE_ONGOING = 3, /*!< 正在进行的阶段意味着负载正在升级。*/
    DJI_UPGRADE_STAGE_DEVICE_REBOOT = 6, /*!< 设备重启阶段意味着设备正在重启。 */
    DJI_UPGRADE_STAGE_END = 4, /*!< 结束阶段是指升级完成并向终端APP报告升级结果。 */
} E_DjiUpgradeStage;

typedef enum E_DjiUpgradeEndState

typedef enum {
    DJI_UPGRADE_END_STATE_SUCCESS = 1, /*!< 升级成功 */
    DJI_UPGRADE_END_STATE_UNKNOWN_ERROR = 2, /*!< 升级失败 */
} E_DjiUpgradeEndState;

typedef struct T_DjiFirmwareVersion

typedef struct {
    uint8_t majorVersion; /*!< major 固件版本， 范围为 0 ~ 99. */
    uint8_t minorVersion; /*!< minor 固件版本， 范围为 0 ~ 99. */
    uint8_t modifyVersion; /*!< modify 固件版本， 范围为 0 ~ 99. */
    uint8_t debugVersion; /*!< debug 固件版本， 范围为 0 ~ 99. */
} T_DjiFirmwareVersion;

typedef struct T_DjiUpgradeOngoingInfo

typedef struct {
    uint8_t upgradeProgress; /*!< 升级进程，范围为 0 ~ 100. */
} T_DjiUpgradeOngoingInfo;

typedef struct T_DjiUpgradeRebootInfo

typedef struct {
    uint8_t rebootTimeout; /*!< 重启设备的timeout时间， unit: s */
} T_DjiUpgradeRebootInfo;

typedef struct T_DjiUpgradeEndInfo

typedef struct {
    E_DjiUpgradeEndState upgradeEndState; /*!< 升级结束状态 */
} T_DjiUpgradeEndInfo;

typedef struct T_DjiUpgradeFtpFileTransferInfo

typedef struct {
    uint32_t port; /*!< FTP接口用于传输文件，默认为 21 */
} T_DjiUpgradeFtpFileTransferInfo;

typedef struct T_DjiUpgradeFileInfo

typedef struct {
    uint32_t fileSize; /*! 文件大小*/
    char fileName[DJI_FILE_NAME_SIZE_MAX]; /*! 文件名 */
} T_DjiUpgradeFileInfo;

typedef struct T_DjiUpgradeDcftpFileTransferOpt

typedef struct {
    /**
      * @brief Prototype of callback function used to start file transfer.
      * @param fileInfo: the file info about the file to be transferred.
      * @return Execution result.
      */
    T_DjiReturnCode (*start)(const T_DjiUpgradeFileInfo *fileInfo);
    /**
      * @brief Prototype of callback function used to transfer file data.
      * @details After start transfer, this callback function will be called several times to transfer file data sequentially.
      * @param data: pointer to memory space used to store file data.
      * @param dataLen: the data length of data.
      * @return Execution result.
      */
    T_DjiReturnCode (*transfer)(const uint8_t *data, uint16_t dataLen);
    /**
      * @brief Prototype of callback function used to finish file transfer.
      * @param md5: the md5 value of file, used to check the correctness of the file transfer .
      * @return Execution result.
      */
    T_DjiReturnCode (*finish)(const uint8_t md5[DJI_MD5_BUFFER_LEN]);
} T_DjiUpgradeDcftpFileTransferOpt;

typedef struct T_DjiFirmwareTransferInfo

typedef struct {
    /*! The firmware transfer type for upgrade. */
    E_DjiFirmwareTransferType transferType;

    /*! If transferType is DJI_FIRMWARE_TRANSFER_TYPE_FTP, need support ftpTransferInfo. */
    T_DjiUpgradeFtpFileTransferInfo ftpTransferInfo;
    /*! If transferType is DJI_FIRMWARE_TRANSFER_TYPE_DCFTP, need support dcftpFileTransferOpt. */
    T_DjiUpgradeDcftpFileTransferOpt dcftpFileTransferOpt;
} T_DjiFirmwareTransferInfo;

typedef struct T_DjiUpgradeState

typedef struct {
    /*! The upgrade stage in upgrade process. */
    E_DjiUpgradeStage upgradeStage;

    union {
        /*! If upgradeStage is DJI_UPGRADE_STAGE_ONGOING, need support upgradeOngoingInfo. */
        T_DjiUpgradeOngoingInfo upgradeOngoingInfo;
        /*! If upgradeStage is DJI_UPGRADE_STAGE_DEVICE_REBOOT, need support upgradeRebootInfo. */
        T_DjiUpgradeRebootInfo upgradeRebootInfo;
        /*! If upgradeStage is DJI_UPGRADE_STAGE_END, need support upgradeEndInfo. */
        T_DjiUpgradeEndInfo upgradeEndInfo;
    };
} T_DjiUpgradeState;

typedef struct T_DjiUpgradeConfig

typedef struct {
    T_DjiFirmwareVersion currentFirmwareVersion; /*!< The current firmware version of payload. */
    T_DjiFirmwareTransferInfo firmwareTransferInfo; /*!< The firmware transfer info of payload. */
} T_DjiUpgradeConfig;

typedef struct T_DjiUpgradeHandler

typedef struct {
    /**
      * @brief Prototype of callback function used to enter upgrade mode.
      * @param waitTime: the wait time for enter upgrade mode. The terminal APP will wait these time before do other
      * upgrade actions. You can use this time to prepare for firmware upgrade in other task, such as clean firmware
      * store area. unit: s
      * @return Execution result.
      */
    T_DjiReturnCode (*EnterUpgradeMode)(uint16_t *waitTime);
    /**
      * @brief Prototype of callback function used to check transferred firmware.
      * @details You can verify signature and decrypt firmware in this callback function.
      * @return Execution result.
      */
    T_DjiReturnCode (*CheckFirmware)(void);
    /**
      * @brief Prototype of callback function used to start firmware upgrade.
      * @note After start upgrade, the upgrade stage need change to ::DJI_UPGRADE_STAGE_ONGOING
      * @return Execution result.
      */
    T_DjiReturnCode (*StartUpgrade)(void);
    /**
      * @brief Prototype of callback function used to finish firmware upgrade.
      * @note After call finish upgrade, the upgrade stage need change from ::DJI_UPGRADE_STAGE_END to ::DJI_UPGRADE_STAGE_IDLE
      * @return Execution result.
      */
    T_DjiReturnCode (*FinishUpgrade)(void);
} T_DjiUpgradeHandler;

函数原型

function DjiUpgrade_Init

功能：升级模块初始化

product：all

初始化升级模块，用户在使用升级功能前应调用该函数。

T_DjiReturnCode DjiUpgrade_Init(const T_DjiUpgradeConfig *upgradeConfig);

返回值
根据程序执行的情况输出对应的返回值，详情请参见：DjiErrorCode

function DjiUpgrade_EnableLocalUpgrade

功能：启动本地升级模块

product：all

开启本地升级模式后，DJI Assistant 2 将显示负载升级界面。 用户可以选择固件文件来升级有效载荷。

T_DjiReturnCode DjiUpgrade_EnableLocalUpgrade(void);

返回值
根据程序执行的情况输出对应的返回值，详情请参见：DjiErrorCode

function DjiUpgrade_RegHandler

功能：注册升级过程的处理程序。

product：all

T_DjiReturnCode DjiUpgrade_RegHandler(const T_DjiUpgradeHandler *upgradeHandler);

参数
upgradeHandler：指向升级过程的处理函数结构的指针
返回值
根据程序执行的情况输出对应的返回值，详情请参见：DjiErrorCode

function DjiUpgrade_PushUpgradeState

功能：向终端App推送升级状态

product：all

T_DjiReturnCode DjiUpgrade_PushUpgradeState(const T_DjiUpgradeState *upgradeState);

参数
upgradeState：升级过程中的升级状态
返回值
根据程序执行的情况输出对应的返回值，详情请参见：DjiErrorCode