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

目录

• 枚举
  E_PsdkPayloadFirmwareTransferType
  E_PsdkUpgradeStage
  E_PsdkUpgradeEndState

• 结构体
  T_PsdkPayloadFirmwareVersion
  T_PsdkUpgradeOngoingInfo
  T_PsdkUpgradeRebootInfo
  T_PsdkUpgradeEndInfo
  T_PsdkUpgradeFtpFileTransferInfo
  T_PsdkUpgradeFileInfo
  T_PsdkUpgradeDcftpFileTransferOpt
  T_PsdkPayloadFirmwareTransferInfo
  T_PsdkUpgradeState
  T_PsdkUpgradeConfig
  T_PsdkUpgradeHandler

• 函数原型
  PsdkUpgrade_Init
  PsdkUpgrade_EnableLocalUpgrade
  PsdkUpgrade_RegHandler
  PsdkUpgrade_PushUpgradeState

枚举

typedef enum E_PsdkPayloadFirmwareTransferType

使用FTP 协议传输固件或DCFTP 协议传输固件。DCFTP (DJI Common File Transfer Protocol) 是DJI 独有的文件传输协议，通过调用指定的接口，即可获得所需的文件，详情请参见：T_PsdkUpgradeDcftpFileTransferOpt。

说明

• 仅基于Linux 平台开发的负载设备支持开发者通过网口，使用FTP 协议传输所需升级的固件；
• 开发者使用FTP 协议传输固件时，需为负载设备部署相应的FTP 服务器；
• 使用FTP 协议传输负载设备的固件时的账号和密码：username为psdk_payload_ftp，密码为password:DJi_#$31；
• 使用RTOS 或没有网口的负载设备可使用该方式传输固件。

typedef enum {
    PSDK_PAYLOAD_FIRMWARE_TRANSFER_TYPE_FTP = 0, 使用FTP 协议传输固件
    PSDK_PAYLOAD_FIRMWARE_TRANSFER_TYPE_DCFTP,   使用DCFTP 协议传输固件
} E_PsdkPayloadFirmwareTransferType;

typedef enum E_PsdkUpgradeStage

负载设备的升级状态

typedef enum {
    PSDK_UPGRADE_STAGE_IDLE = 0,            负载设备未进入升级状态 
    PSDK_UPGRADE_STAGE_ONGOING = 3,         负载设备正在升级中 
    PSDK_UPGRADE_STAGE_DEVICE_REBOOT = 6,   负载设备正在重启中 
    PSDK_UPGRADE_STAGE_END = 4,             负载设备升级结束 
} E_PsdkUpgradeStage;

typedef enum E_PsdkUpgradeEndState

负载设备升级结束的状态

typedef enum {
    PSDK_UPGRADE_END_STATE_SUCCESS = 1,         负载设备升级成功 
    PSDK_UPGRADE_END_STATE_UNKNOWN_ERROR = 2,   由于未知原因导致负载设备升级失败 
} E_PsdkUpgradeEndState;

结构体

typedef struct T_PsdkPayloadFirmwareVersion

固件版本声明

说明

• majorVersion = AA, minorVersion = BB, modifyVersion = CC, debugVersion = DD；
• DJI Assistant 2 将以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

升级进度

typedef struct {
    uint8_t upgradeProgress;       升级进度：0 ~ 100. 
} T_PsdkUpgradeOngoingInfo;

typedef struct T_PsdkUpgradeRebootInfo

负载设备重启状态

typedef struct {
    uint8_t rebootTimeout;       设备重启超时时间，单位：s 
} T_PsdkUpgradeRebootInfo;

typedef struct T_PsdkUpgradeEndInfo

负载设备升级结束状态

typedef struct {
    E_PsdkUpgradeEndState upgradeEndState;       负载设备升级结束 
} T_PsdkUpgradeEndInfo;

typedef struct T_PsdkUpgradeFtpFileTransferInfo

FTP 文件传输信息

typedef struct {
    uint32_t port;       FTP 文件传输端口，默认为21 
} T_PsdkUpgradeFtpFileTransferInfo;

typedef struct T_PsdkUpgradeFileInfo

固件文件的信息

typedef struct {
    uint32_t fileSize;                           固件文件的大小 
    char fileName[PSDK_FILE_NAME_SIZE_MAX];      固件文件的名称 
} T_PsdkUpgradeFileInfo;

typedef struct T_PsdkUpgradeDcftpFileTransferOpt

以DCFTP 的方式传输固件文件，请根据本结构体中的函数构造以DCFTP 的方式传输固件文件 相关功能的回调函数，其中包括：

• 开始传输固件文件
• 传输固件文件
• 完成固件文件传输

typedef struct {
    @brief 开始传输固件文件的回调函数
    @param fileInfo: 固件文件的信息
    @return 执行结果
    T_PsdkReturnCode (*start)(const T_PsdkUpgradeFileInfo *fileInfo);
      
    @brief 传输固件文件数据的回调函数。开始传输固件文件数据后，将多次调用该回调函数有序传输固件文件
    @param data: 指向固件文件数据的指针
    @param dataLen: 固件文件数据长度
    @return 执行结果
    T_PsdkReturnCode (*transfer)(const uint8_t *data, uint16_t dataLen);
      
    @brief 完成固件文件传输的回调函数
    @param md5: 固件文件的MD5 值，用于校验传输文件的准确性
    @return 执行结果
    T_PsdkReturnCode (*finish)(const uint8_t md5[PSDK_MD5_BUFFER_LEN]);
} T_PsdkUpgradeDcftpFileTransferOpt;

typedef struct T_PsdkPayloadFirmwareTransferInfo

固件文件传输信息

typedef struct {
    E_PsdkPayloadFirmwareTransferType transferType;           固件升级方式 
    T_PsdkUpgradeFtpFileTransferInfo ftpTransferInfo;         通过FTP 升级 
    T_PsdkUpgradeDcftpFileTransferOpt dcftpFileTransferOpt;   通过DCFTP 升级 
} T_PsdkPayloadFirmwareTransferInfo;

typedef struct T_PsdkUpgradeState

负载设备固件升级时的状态信息

typedef struct {
           
    E_PsdkUpgradeStage upgradeStage;                   固件升级时的不同状态 

    union {

        T_PsdkUpgradeOngoingInfo upgradeOngoingInfo;    固件升级中 
               
        T_PsdkUpgradeRebootInfo upgradeRebootInfo;      负载设备重启中 
        T_PsdkUpgradeEndInfo upgradeEndInfo;            固件升级结束 
    };
} T_PsdkUpgradeState;

typedef struct T_PsdkUpgradeConfig

负载设备升级配置信息

typedef struct {
    T_PsdkPayloadFirmwareVersion currentFirmwareVersion;       负载设备当前的版本信息 
    T_PsdkPayloadFirmwareTransferInfo firmwareTransferInfo;    固件传输信息 
} T_PsdkUpgradeConfig;

typedef struct T_PsdkUpgradeHandler

负载设备本地升级，请根据本结构体中的函数构造负载设备本地升级相关功能的回调函数，其中包括：

• 进入升级模式
• 校验已传输的固件信息
• 开始升级固件
• 完成固件升级

typedef struct {
    @brief 进入升级模式的回调函数
    @param waitTime: 进入升级模式的等待时间，单位：s。在该时间内，开发者可以做升级准备工作，如关闭其他系统服务，擦除升级固件存储区中的数据等。
    @return 执行结果
    T_PsdkReturnCode (*EnterUpgradeMode)(uint16_t *waitTime);
      
    @brief 校验已传输的固件的回调函数
    @details 在该回调函数中，开发者可验证固件的签名信息或解压固件文件
    @return 执行结果
    T_PsdkReturnCode (*CheckFirmware)(void);
      
    @brief 开始升级固件的回调函数
    @note 开始升级固件后，请更改固件升级的状态 ::PSDK_UPGRADE_STAGE_ONGOING
    @return 执行结果
    T_PsdkReturnCode (*StartUpgrade)(void);
      
    @brief 完成固件升级的回调函数
    @note 负载设备的固件升级完成后，请更改固件升级的状态为 ::PSDK_UPGRADE_STAGE_END
    @return 执行结果
    T_PsdkReturnCode (*FinishUpgrade)(void);
} T_PsdkUpgradeHandler;

函数原型

function PsdkUpgrade_Init

功能：本地升级模块初始化

product：all

在使用本地升级功能前，请先初始化升级模块。

T_PsdkReturnCode PsdkUpgrade_Init(const T_PsdkUpgradeConfig *upgradeConfig);

参数
upgradeConfig：设置本地升级初始化信息
返回值
根据程序执行的情况输出对应的返回值，详情请参见：PsdkErrorCode

function PsdkUpgrade_EnableLocalUpgrade

功能：开启本地升级模式

product：all

开启本地升级模式，开启本地升级模式后，DJI Assistant 2 将会显示负载设备的升级界面，用户可选择所需的固件文件升级负载设备。

T_PsdkReturnCode PsdkUpgrade_EnableLocalUpgrade(void);

返回值

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

function PsdkUpgrade_RegHandler

功能：获取负载设备升级进度

product：all

注册获取负载设备升级进度的回调函数。

T_PsdkReturnCode PsdkUpgrade_RegHandler(const T_PsdkUpgradeHandler *upgradeHandler);

参数
upgradeHandler：指向升级进度的结构体
返回值
根据程序执行的情况输出对应的返回值，详情请参见：PsdkErrorCode

function PsdkUpgrade_PushUpgradeState

功能：发送升级状态

product：all

向DJI Pilot 或基于MSDK 开发的移动端App 推送升级状态。

说明 在负载设备升级的过程中，开发者需要向DJI Pilot 或基于MSDK 开发的移动端App 推送升级状态：

1. 调用StartUpgrade 回调函数开始升级；
2. 负载设备开始升级时，需改变升级状态为PSDK_UPGRADE_STAGE_ONGOING，并推送正在升级的信息；
3. 负载设备升级结束后，需改变升级状态为PSDK_UPGRADE_STAGE_DEVICE_REBOO 并推送升级状态 upgradeRebootInfo；
4. 负载设备重启；
5. 负载设备重启结束后，需改变负载设备的升级状态并推送升级结束状态 PSDK_UPGRADE_STAGE_END (推荐使用 1Hz 推送负载设备的升级状态)；
6. 调用FinishUpgrade 回调函数，停止推送升级状态，完成负载设备的升级。

T_PsdkReturnCode PsdkUpgrade_PushUpgradeState(const T_PsdkUpgradeState *upgradeState);

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