The header file for local upgrade related functions is dji_upgrade.h. This document describes the key information and usage of the structure and function prototypes in the dji_upgrade.h file.

Notice： dji_upgrade.h can be used only for payloads developed by X-Port. If payloads are developed by SkyPort, please usedji_gimbal.h。

Catalog

• Definition, Enum and Struct
  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

• Function
  DjiUpgrade_Init
  DjiUpgrade_EnableLocalUpgrade
  DjiUpgrade_RegHandler
  DjiUpgrade_PushUpgradeState

Definition, Enum and Struct

typedef enum E_DjiFirmwareTransferType

typedef enum {
    /*!
     * @brief FTP firmware transfer type.
     * @note This transfer type only support linux platform and use network port. Users need to deploy FTP service on
     * payload. The ftp user info used to transfer upgrade firmware is :
     * username:dji_payload_ftp
     * password:DJi_#$31
     * You can get guide about FTP service deployment on https://developer.dji.com/payload-sdk/documentation
     */
    DJI_FIRMWARE_TRANSFER_TYPE_FTP = 0,
    /*!
     * @brief DCFTP firmware transfer type.
     * @details DCFTP (DJI Common File Transfer Protocol) is a private protocol used to transfer file on DJI Product.
     * Users can get file data by command callbacks, see :: T_DjiUpgradeDcftpFileTransferOpt.
     * @note This transfer type is used to support RTOS platform or payload don't have network port. The transfer speed
     * is very slow compare to FTP because it uses low speed transfer channel.
     */
    DJI_FIRMWARE_TRANSFER_TYPE_DCFTP,
} E_DjiFirmwareTransferType;

typedef enum E_DjiUpgradeStage

typedef enum {
    DJI_UPGRADE_STAGE_IDLE = 0, /*!< Idle stage means not in upgrade mode. */
    DJI_UPGRADE_STAGE_ONGOING = 3, /*!< Ongoing stage means payload is upgrading. */
    DJI_UPGRADE_STAGE_DEVICE_REBOOT = 6, /*!< Device reboot stage means device is rebooting. */
    DJI_UPGRADE_STAGE_END = 4, /*!< End Stage means upgrade finish and reporting upgrade result to the terminal APP. */
} E_DjiUpgradeStage;

typedef enum E_DjiUpgradeEndState

typedef enum {
    DJI_UPGRADE_END_STATE_SUCCESS = 1, /*!< Upgrade success. */
    DJI_UPGRADE_END_STATE_UNKNOWN_ERROR = 2, /*!< Upgrade failure due to unknown reason. */
} E_DjiUpgradeEndState;

typedef struct T_DjiFirmwareVersion

typedef struct {
    uint8_t majorVersion; /*!< The major version of firmware, the range is 0 ~ 99. */
    uint8_t minorVersion; /*!< The minor version of firmware, the range is 0 ~ 99. */
    uint8_t modifyVersion; /*!< The modify version of firmware, the range is 0 ~ 99. */
    uint8_t debugVersion; /*!< The debug version of firmware, the range is 0 ~ 99. */
} T_DjiFirmwareVersion;

typedef struct T_DjiUpgradeOngoingInfo

typedef struct {
    uint8_t upgradeProgress; /*!< The upgrade progress, the range is 0 ~ 100. */
} T_DjiUpgradeOngoingInfo;

typedef struct T_DjiUpgradeRebootInfo

typedef struct {
    uint8_t rebootTimeout; 
} T_DjiUpgradeRebootInfo;

typedef struct T_DjiUpgradeEndInfo

typedef struct {
    E_DjiUpgradeEndState upgradeEndState;    
} T_DjiUpgradeEndInfo;

typedef struct T_DjiUpgradeFtpFileTransferInfo

typedef struct {
    uint32_t port; 
} T_DjiUpgradeFtpFileTransferInfo;

typedef struct T_DjiUpgradeFileInfo

typedef struct {
    uint32_t fileSize; /*! The size of file. */
    char fileName[DJI_FILE_NAME_SIZE_MAX]; /*! The name of file. */
} 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

function DjiUpgrade_Init

Function:Initialise upgrade module

product：all

T_DjiReturnCode DjiUpgrade_Init(const T_DjiUpgradeConfig *upgradeConfig);

Return
The details for the return code please refer to: DjiErrorCode

function DjiUpgrade_EnableLocalUpgrade

Function:Enable local upgrade mode.

product：all

T_DjiReturnCode DjiUpgrade_EnableLocalUpgrade(void);

Return
The details for the return code please refer to: DjiErrorCode

function DjiUpgrade_RegHandler

Function:Register the handler for upgrade process.

product：all

T_DjiReturnCode DjiUpgrade_RegHandler(const T_DjiUpgradeHandler *upgradeHandler);

Parameter
upgradeHandler：pointer to structure of handler functions for upgrade process.
Return
The details for the return code please refer to: DjiErrorCode

function DjiUpgrade_PushUpgradeState

Function:Push upgrade state to terminal app.

product：all

T_DjiReturnCode DjiUpgrade_PushUpgradeState(const T_DjiUpgradeState *upgradeState);

Parameter
upgradeState：upgrade state in upgrade process.
Return
The details for the return code please refer to: DjiErrorCode