This is the header file for "psdk_upgrade.c", defining the structure and (exported) function prototypes.

Catalog

• Enum
  E_PsdkPayloadFirmwareTransferType
  E_PsdkUpgradeStage
  E_PsdkUpgradeEndState

• Structure
  T_PsdkPayloadFirmwareVersion
  T_PsdkUpgradeOngoingInfo
  T_PsdkUpgradeRebootInfo
  T_PsdkUpgradeEndInfo
  T_PsdkUpgradeFtpFileTransferInfo
  T_PsdkUpgradeFileInfo
  T_PsdkUpgradeDcftpFileTransferOpt
  T_PsdkPayloadFirmwareTransferInfo
  T_PsdkUpgradeState
  T_PsdkUpgradeConfig
  T_PsdkUpgradeHandler

• Function
  PsdkUpgrade_Init
  PsdkUpgrade_EnableLocalUpgrade
  PsdkUpgrade_RegHandler
  PsdkUpgrade_PushUpgradeState

Enum

typedef enum E_PsdkPayloadFirmwareTransferType

DCFTP (DJI Common File Transfer Protocol) is DJI's unique file transfer protocol. By calling the specified interface, you can obtain the required files. For details, please refer to: T_PsdkUpgradeDcftpFileTransferOpt.

NOTE

• Only the payload developed based on the Linux platform supports developers to transfer the required upgraded firmware through the network port and the FTP protocol.
• When developers use FTP protocol to transfer firmware, they need to deploy corresponding FTP servers for payload.
• Account and password when using FTP to transfer the firmware of the payload: username: psdk_payload_ftp; password: DJi _ # $ 31.
• Payload that use RTOS or have no network port can use this method to transfer firmware.

typedef enum {
    PSDK_PAYLOAD_FIRMWARE_TRANSFER_TYPE_FTP = 0, FTP firmware transfer type
    PSDK_PAYLOAD_FIRMWARE_TRANSFER_TYPE_DCFTP,   DCFTP firmware transfer type.
} E_PsdkPayloadFirmwareTransferType;

typedef enum E_PsdkUpgradeStage

The state of the payload's upgrade

typedef enum {
    PSDK_UPGRADE_STAGE_IDLE = 0,       Idle stage means not in upgrade mode. 
    PSDK_UPGRADE_STAGE_ONGOING = 3,    Ongoing stage means payload is upgrading. 
    PSDK_UPGRADE_STAGE_DEVICE_REBOOT = 6,  Device reboot stage means device is rebooting. 
    PSDK_UPGRADE_STAGE_END = 4,            End Stage means upgrade finish and reporting upgrade result to the terminal APP. 
} E_PsdkUpgradeStage;

typedef enum E_PsdkUpgradeEndState

The finished state of the payload's upgrade

typedef enum {
    PSDK_UPGRADE_END_STATE_SUCCESS = 1,        Upgrade success. 
    PSDK_UPGRADE_END_STATE_UNKNOWN_ERROR = 2,  Upgrade failure due to unknown reason. 
} E_PsdkUpgradeEndState;

Structure

typedef struct T_PsdkPayloadFirmwareVersion

The firmware version of payload

NOTE

• majorVersion = AA, minorVersion = BB, modifyVersion = CC, debugVersion = DD。
• DJI Assistant 2 will display the version format: AA.BB.CC.DD

typedef struct {
    uint8_t majorVersion;       majorVersion：0 ~ 99. 
    uint8_t minorVersion;       minorVersion：0 ~ 99. 
    uint8_t modifyVersion;      modifyVersion：0 ~ 99. 
    uint8_t debugVersion;       debugVersion：0 ~ 99. 
} T_PsdkPayloadFirmwareVersion;

typedef struct T_PsdkUpgradeOngoingInfo

The upgrade progress

typedef struct {
    uint8_t upgradeProgress;       The upgrade progress:0 ~ 100. 
} T_PsdkUpgradeOngoingInfo;

typedef struct T_PsdkUpgradeRebootInfo

The timeout value of rebooting device

typedef struct {
    uint8_t rebootTimeout;       The timeout value of rebooting device. unit: s
} T_PsdkUpgradeRebootInfo;

typedef struct T_PsdkUpgradeEndInfo

The upgrade end state

typedef struct {
    E_PsdkUpgradeEndState upgradeEndState;       The upgrade end state 
} T_PsdkUpgradeEndInfo;

typedef struct T_PsdkUpgradeFtpFileTransferInfo

FTP port used to transfer file, default is 21

typedef struct {
    uint32_t port;       FTP port used to transfer file, default is 21
} T_PsdkUpgradeFtpFileTransferInfo;

typedef struct T_PsdkUpgradeFileInfo

The information of file

typedef struct {
    uint32_t fileSize;                           The information of file.
    char fileName[PSDK_FILE_NAME_SIZE_MAX];      The name of file 
} T_PsdkUpgradeFileInfo;

typedef struct T_PsdkUpgradeDcftpFileTransferOpt

Prototype of callback function used to transfer file in DCFTP:

• Start to transfer the file
• transfer file data
• finish file transfer

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_PsdkReturnCode (*start)(const T_PsdkUpgradeFileInfo *fileInfo);

      @brief Prototype of callback function used to transfer the firmware file's data.
      @details After start transfer, this callback function will be called several times
       to transfer the data sequentially.
      @param data: pointer to memory space used to store the data.
      @param dataLen: the data length of the firmware's file.
      @return Execution result.
      T_PsdkReturnCode (*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_PsdkReturnCode (*finish)(const uint8_t md5[PSDK_MD5_BUFFER_LEN]);
} T_PsdkUpgradeDcftpFileTransferOpt;

typedef struct T_PsdkPayloadFirmwareTransferInfo

The information of the firmware transfer

typedef struct {
    E_PsdkPayloadFirmwareTransferType transferType;     The firmware transfer type for upgrade.
    T_PsdkUpgradeFtpFileTransferInfo ftpTransferInfo;   If transferType is PSDK_PAYLOAD_FIRMWARE_TRANSFER_TYPE_FTP, need support ftpTransferInfo. 
    T_PsdkUpgradeDcftpFileTransferOpt dcftpFileTransferOpt;    If transferType is PSDK_PAYLOAD_FIRMWARE_TRANSFER_TYPE_DCFTP, need support dcftpFileTransferOpt.
} T_PsdkPayloadFirmwareTransferInfo;

typedef struct T_PsdkUpgradeState

The state information of the upgrade stage

typedef struct {
           
    E_PsdkUpgradeStage upgradeStage;                   The upgrade stage in upgrade process.  

    union {
        T_PsdkUpgradeOngoingInfo upgradeOngoingInfo;   If upgradeStage is PSDK_UPGRADE_STAGE_ONGOING,
                                                       need support upgradeOngoingInfo.
        T_PsdkUpgradeRebootInfo upgradeRebootInfo;     If upgradeStage is PSDK_UPGRADE_STAGE_DEVICE_REBOOT,
                                                       need support upgradeRebootInfo.
        T_PsdkUpgradeEndInfo upgradeEndInfo;           If upgradeStage is PSDK_UPGRADE_STAGE_END, need support 
                                                       upgradeEndInfo.
    };
} T_PsdkUpgradeState;

typedef struct T_PsdkUpgradeConfig

The update information of the payload in updated state

typedef struct {
    T_PsdkPayloadFirmwareVersion currentFirmwareVersion;     The current firmware version of payload.
    T_PsdkPayloadFirmwareTransferInfo firmwareTransferInfo;  The firmware transfer info of payload. 
} T_PsdkUpgradeConfig;

typedef struct T_PsdkUpgradeHandler

Please construct the callback function of the upgrade:

• Enter upgrade mode
• Verify the transmitted firmware information
• Start to upgrade the firmware
• Complete firmware upgrade

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_PsdkReturnCode (*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_PsdkReturnCode (*CheckFirmware)(void);

       @brief Prototype of callback function used to start firmware upgrade.
       @note After start upgrade, the upgrade stage need change to ::PSDK_UPGRADE_STAGE_ONGOING
       @return Execution result.
       T_PsdkReturnCode (*StartUpgrade)(void);

       @brief Prototype of callback function used to finish firmware upgrade.
       @note After call finish upgrade, the upgrade stage need change from ::PSDK_UPGRADE_STAGE_END to ::PSDK_UPGRADE_STAGE_IDLE
       @return Execution result. 
       T_PsdkReturnCode (*FinishUpgrade)(void);
} T_PsdkUpgradeHandler;

Function

function PsdkUpgrade_Init

Function:Initialise upgrade module

product：all

Initialise upgrade module, and user should call this function before using upgrade features.

T_PsdkReturnCode PsdkUpgrade_Init(const T_PsdkUpgradeConfig *upgradeConfig);

Parameter
upgradeConfig：upgrade init configuration.
Return
The details for the return code please refer to：PsdkErrorCode

function PsdkUpgrade_EnableLocalUpgrade

Function:Enable local upgrade mode.

product：all

Enable local upgrade mode. After enable local upgrade mode, DJI Assistant 2 will display payload upgrade interface. Users can choose firmware file to upgrade payload.

T_PsdkReturnCode PsdkUpgrade_EnableLocalUpgrade(void);

Return

The details for the return code please refer to：PsdkErrorCode

function PsdkUpgrade_RegHandler

Function:Register the handler for upgrade process.

product：all

Register the handler for upgrade process.

T_PsdkReturnCode PsdkUpgrade_RegHandler(const T_PsdkUpgradeHandler *upgradeHandler);

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

function PsdkUpgrade_PushUpgradeState

Function:Push upgrade state

product：all

Push upgrade state to terminal App like Mobile App.

NOTE

• When start upgrade, you need push upgrade state until finish upgrade. The upgrade state push logic is :

1. StartUpgrade callback called;
2. The upgrade stage change to PSDK_UPGRADE_STAGE_ONGOING. Push upgrade state upgradeOngoingInfo when upgradeOngoingInfo changed;
3. After upgrade ongoing, change upgrade stage to PSDK_UPGRADE_STAGE_DEVICE_REBOOT and push upgrade state upgradeRebootInfo;
4. Device reboot;
5. After device reboot, change upgrade stage to PSDK_UPGRADE_STAGE_END and continuous push upgrade state upgradeEndInfo (recommended 1Hz);
6. FinishUpgrade Callback called, stop push upgrade state. The upgrade process finished.

T_PsdkReturnCode PsdkUpgrade_PushUpgradeState(const T_PsdkUpgradeState *upgradeState);

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