Firmware Upgrade Tutorial
Firmware Upgrade Tutorial
1. Overview
The MSDK firmware upgrade feature supports checking connected upgradable device modules (controller devices, aircraft devices). After obtaining upgradable information, developers can download corresponding upgrade firmware to perform upgrades and can also listen to information during the upgrade process.
2. Upgrade Check
2.1 Checking if there is a new version for the aircraft and controller
Example code as follows:
OTAUpgradeManger.getInstance().detectDeviceUpdateInfo()
2.2 Version Information Callback Listener
/**
* Upgrade version information reporting
*/
interface UpgradeVersionListener {
/**
* APP upgrade notification
*/
fun onAppUpgrade(manual:Boolean, needUpgrade: Boolean, bean: CheckResponseBean?){}
/**
* Device upgrade notification
*/
fun onDeviceUpgrade(beanMap: HashMap<String, CheckResponseBean.Data>){}
/**
* Whether entering upgrade mode was successful
*/
fun onEnterUpgradeMode(success: Boolean){}
/**
* Whether exiting upgrade mode was successful
*/
fun onExitUpgradeMode(success: Boolean){}
}
2.3 Downloading the Upgrade Package
Example code as follows:
OTAUpgradeManger.getInstance()
.downloadFile(remoterBean.pkg_url, 0, object : FileTransmitListener<File> {
override fun onSuccess(result: File?) {
// download succcess
}
override fun onProgress(sendLength: Long, totalLength: Long, speed: Long) {
// progress
}
override fun onFailed(code: IAutelCode?, msg: String?) {
// download failed
}
})
3. Upgrade Process
3.1 Entering Upgrade Mode
Example code:
For aircraft upgrades, it's necessary to switch to upgrade mode.
Entering upgrade mode
OTAUpgradeManger.getInstance().switchUpgradeMode(true)
Exiting upgrade mode
OTAUpgradeManger.getInstance().switchUpgradeMode(false)
3.2 Upgrading Devices
3.2.1 Initializing the Upgrade Manager
First upgrade the aircraft then the controller, example code as follows:
Upgrading the Controller:
val deviceId = remoteDevice.getDeviceNumber()
UpgradeManager(deviceId).init(UpgradeClientTypeEnum.CLIENT_TYPE_GND)
Upgrading the Aircraft:
val deviceId = droneDevice.getDeviceNumber()
UpgradeManager(deviceId).init(UpgradeClientTypeEnum.CLIENT_TYPE_SKY)
3.2.2 Starting the Upgrade Flow
After preparing the upgrade package, you can start upgrading the device.
Example code as follows:
UpgradeManager.startUpgradeFlow(file: File, md5: String?)
(Note: No MD5 is needed for encrypted packages, currently MD5 verification is not performed either)
3.2.3 Listening for Upgrade Progress Status
Register an upgrade process listener, example code as follows:
UpgradeManager.registerUpgradeListener(listener:UpgradeListener)
4.Sample Acquisition
Refer to OTAFirmwareUpgradeFragment in the Sample
5.Interface Description
5.1 Upgrade Progress Listener
interface UpgradeListener {
/**
* Upgrade flow report
*/
fun onUpgradeFlowChange(deviceId: Int, flowState: UpgradeFlowEnum){}
/**
* Status report during upgrade flow
*/
fun onUpgradeStateChange(deviceId: Int, state: UpgradeErrorStateEnum)
/**
* Upload OTA package progress report
*/
fun onUploadPackageProgress(deviceId: Int, totalLength:Long, sendLength:Long, progress: Int, speed: Long )
/**
* Report upgrade progress after executing upgrade
*/
fun onUpgradeProgress(deviceId: Int, progress: Int)
/**
* Final upgrade result
*/
fun onUpgradeResult(deviceId: Int, resultBean: UpgradeResultBean)
}
5.2 Upgrade Flow
/**
* Upgrade flow status
*/
enum class UpgradeFlowEnum {
GENERATE_FILE_MD5, //Generate OTA file MD5
CHECK_UPGRADE_CONDITION, //Check upgrade conditions
CHECK_UPGRADE_STATE, //Check current upgrade state
UPGRADE_ENTER, //Enter upgrade state
UPGRADE_HIGH_SPEED, //Switch to high-speed mode
NOTIFY_SINGLE_UPGRADE, //Notify single device to enter upgrade state in network
UPGRADE_NORMAL_SPEED, //Switch to normal speed mode
UPGRADE_UPLOAD, //Upload file
UPGRADE_MD5_VERIFY, //Upload complete, notify upgrade service to verify file integrity
UPGRADE_EXECUTING, //Upgrade execution in progress
UNKNOWN; // Unknown status
}
5.3 Upgrade Flow Errors
/**
* Upgrade flow error report
*/
enum class UpgradeErrorStateEnum {
UPGRADE_UNKNOWN_DEVICE_CLIENT, //Unknown upgrade device type, incorrect type passed during initialization
UPGRADE_DEVICE_DISCONNECT, //Upgrade device disconnected
UPGRADE_DEVICE_NOT_EXIST, //Upgrade device does not exist, device not found by Id
OTA_FILE_ERROR, //OTA file check failed: does not exist, abnormal length, unreadable
UPGRADE_CONDITION_ERROR, //Check upgrade conditions failed
UPGRADE_MODE_ENTER_ERROR, //Enter upgrade mode failed
UPGRADE_HIGH_SPEED_ERROR, //Switch to high-speed mode failed
UPGRADE_NORMAL_SPEED_ERROR, //Switch to normal speed mode failed
ENTER_SINGLE_UPGRADE_ERROR, //Network Enter single-device upgrade mode failed
CHECK_SINGLE_UPGRADE_STATUS_ERROR, //Network Check single-device upgrade mode failed
UPGRADE_UPLOAD_ERROR, //Upload file failed
UPGRADE_TRANSFER_PROGRESS_ERROR, //Notify upgrade service progress failed
UPGRADE_MD5_ERROR, //Upgrade file MD5 verification failed
UPGRADE_EXECUTE_ERROR, //Upgrade execution failed
UPGRADE_STATE_ERROR; //After reaching maximum time, upgrade state is incorrect
UPGRADE_STATE_ERROR_FOR_IDLE; //Final state query results in IDLE, considered failure; (generally indicates that the upgrade service abnormally restarted during the upgrade, unable to confirm final success or failure)
}
5.4 Final Upgrade Result
/**
* Upgrade result message
* Copyright: Autel Robotics
*/
data class UpgradeResultBean(
/**
* Upgrade error, see ERROR_TYPE_E enumeration
*/
var errCode: UpgradeErrorTypeEnum = UpgradeErrorTypeEnum.UPGRADE_ERR_NONE,
/**
* Error description
*/
var errDesc: String = "",
/**
* Response result 1-success 2-error
*/
var result: ResponseResultEnum = ResponseResultEnum.UNKNOWN,
)
5.4.1 ErrorCode Enumeration
/**
* Response result enumeration
* Copyright: Autel Robotics
*/
public enum class UpgradeErrorTypeEnum(var value: Int) {
/**
* Unknown error
*/
CODE_UNKNOWN(-100),
/**
* Upgrade timeout
*/
UPGRADE_TIME_OUT (-101),
/**
* Upgrade upload file failed
*/
UPGRADE_UPLOAD_ERROR (-102),
/**
* Upgrade download file failed
*/
UPGRADE_DOWNLAOD_ERROR (-103),
/**
* Retry count reached
*/
UPGRADE_REPEAT_ERROR (-104),
/**
* Parsing failed
*/
PROTO_RESPONSE_PARSE_ERROR(-1),
/**
* Empty response data
*/
PROTO_RESPONSE_EMPTY_DATA(-2),
/**
* Response timeout
*/
PROTO_RESPONSE_TIMEOUT(-3),
/**
* Response code error
*/
RESPONSE_CODE_ERROR(-4),
/**
* Device disconnected
*/
DEVICE_DISCONNECTED(-5),
/**
* Duplicate request
*/
REPEAT_REQUEST(-6),
/**
* Success
*/
UPGRADE_ERR_NONE(0),
/**
* In flight
*/
UPGRADE_ERR_FLY (1),
/**
* In upgrading
*/
UPGRADE_ERR_BUSY (2),
/**
* MD5 error
*/
UPGRADE_ERR_MD5 (3),
/**
* File does not exist
*/
UPGRADE_ERR_EXIST (4),
/**
* Low battery
*/
UPGRADE_ERR_LOBAT (5),
/**
* Model mismatch
*/
UPGRADE_ERR_MODEL (6),
/**
* Not enough space to upgrade
*/
UPGRADE_ERR_SPACE (7),
/**
* Error header of pkg, like CRC error
*/
UPGRADE_ERR_HEAD (8),
/**
* Error signature, untrusted firmware
*/
UPGRADE_ERR_SIGN (9),
/**
* Error firmware size, not match header
*/
UPGRADE_ERR_SIZE (10),
/**
* Package error
*/
UPGRADE_ERR_PACKAGE (11),
/**
* Error major version, not match firmware
*/
UPGRADE_ERR_VERSION (12),
/**
* Lower than the current version, need force flag
*/
UPGRADE_ERR_LVERSION (13),
/**
* Refuse upgrade request, errDesc for more details
*/
UPGRADE_ERR_REFUSE (14),
/**
* Special error of every pkg, use errDesc for details
*/
UPGRADE_ERR_SPECIAL (15);
}
5.4.2 Response Result
/**
* Response result enumeration
* Copyright: Autel Robotics
*/
enum class ResponseResultEnum(var value: Int) {
/**
* Result response of upgrade finish
*/
FINISH(0),
/**
* Result response of upgrade success
*/
SUCCESS(1),
/**
* Result response of upgrade failure
*/
ERROR(2),
UNKNOWN(3);
}