ALLPCB
Preface
In embedded systems device management, OTA (Over-The-Air) updates are a core capability for remote maintenance and feature iteration. This article, based on an Ubuntu system environment, analyzes the updateEngine OTA solution. It covers configuration, command usage, practical examples, and troubleshooting to provide developers with a practical operational guide.
1. Configure recovery to support updateEngine
OTA updates require entering recovery mode to perform the update, so ensure the recovery filesystem includes the updateEngine executable.
To use updateEngine for OTA updates, enable the relevant features when building recovery. For Ubuntu, add the following parameters to the recovery configuration:
BR2_PACKAGE_RECOVERY=y # Enable core update functionalityBR2_PACKAGE_RECOVERY_USE_UPDATEENGINE=y # Enable new update engine, if not set the original update flow is usedBR2_PACKAGE_RECOVERY_UPDATEENGINEBIN=y # Build the new update engine binaryBR2_PACKAGE_RECOVERY_NO_UI=y # Disable UIThe key option is USE_UPDATEENGINE to select the new update framework, ensuring subsequent commands can call updateEngine to perform updates.
The updateEngine tool for Ubuntu should be built from source.
2. updateEngine command reference
updateEngine supports remote network updates and local firmware updates. Its parameters are flexible and can be combined as needed. Core usage is as follows.
2.1 Network update: fetch image from remote server
updateEngine --image_url=http://192.168.0.190/recovery/update.img \ --misc=update \ --savepath=/userdata/update.img \ --reboot &- --image_url: remote firmware URL (HTTP/HTTPS supported);
- --misc=update: set update mode;
- --savepath: local path to save the firmware (recommended /userdata/update.img to match recovery mount path and avoid search failures);
- --reboot: automatically reboot after saving to enter recovery mode to complete subsequent steps.
2.2 Local update: use an already downloaded image
Local update does not require network transfer. It reads the image specified by --image_url from a local path. Other parameters are the same as the network update.
2.3 Optional parameters
- --version_url: version file URL (remote or local), used to compare with /etc/version RK_VERSION before updating. If omitted, no version check is performed;
- --partition: specify the partition to update (default 0x3FFC00). Cannot update parameter or loader partitions;
- --savepath: defaults to /tmp/update.img if omitted, but /userdata/update.img is recommended to avoid read failures in recovery mode;
- --reboot: optional. If automatic reboot is not desired, omit this parameter and enter recovery mode manually.
2.4 Full update flow
The updateEngine process can be divided into six core steps. Logs from RK3568 help to understand and locate each stage:
- Version check (optional): if --version_url is specified, compare the remote version file with local /etc/version to determine whether an update is needed;
- Firmware acquisition: download (network) or read (local) the image from --image_url and save it to --savepath;
- Update recovery partition: in normal mode, update the recovery partition first to prepare for recovery-mode operations;
- Reboot trigger: automatically reboot the device via --reboot;
- Recovery-mode update: once in recovery mode, execute updates on the partition list specified by --partition;
- Final reboot: after a successful update, automatically reboot back into the normal system.
3. Partition update logic
updateEngine mainly provides partition update and misc writing functionality. Supported command options include:
***update_engine: Version V1.1.0***--misc=now A/B mode: Setting the current partition to bootable.--misc=other A/B mode: Setting another partition to bootable.--misc=update Recovery mode: Setting the partition to be upgraded.--misc=wipe_userdata Format data partition.--update Upgrade mode.--partition=0x3FFC00 Set the partition to be upgraded.Example: the default 0x3FFC00 corresponds to a combined update of "uboot + trust + boot + recovery + rootfs + oem + uboot_a/b + boot_a/b + system_a/b", covering the main core partitions.
4. Examples: updating individual partitions
4.1 Update kernel only (boot partition)
updateEngine --image_url=http://192.168.0.190/recovery/update.img \ --misc=update \ --savepath=/userdata/update.img \ --partition=0x80000 \ --reboot &Principle: 0x80000 corresponds to the boot partition. The image is written directly without entering recovery mode.
Log signature: you will see "write boot to /dev/block/by-name/boot" and MD5 verification success messages.
4.2 Update u-boot or other low-level partitions
updateEngine --image_url=http://192.168.0.190/recovery/update.img \ --misc=update \ --savepath=/userdata/update.img \ --partition=0x200000 \ --reboot &Note: u-boot is a critical boot partition. Ensure firmware compatibility after updating to avoid device boot failures.
4.3 Update rootfs (synchronize recovery update)
updateEngine--image_url=http://192.168.0.190/recovery/update.img \ --misc=update \ --savepath=/userdata/update.img \ --partition=0x60000 \ # 0x20000(rootfs)+0x40000(recovery) combined value --reboot &Special note: rootfs is the running filesystem. Writing it directly can cause instability. Update the recovery partition in sync and perform the update via recovery mode for a safe operation.
Summary
updateEngine provides a flexible and efficient OTA update capability for the system. With appropriate configuration, precise partition selection, and a standardized operation flow, it can perform full-scenario updates from kernel to filesystem. This article covered the configuration basics and practical examples so developers can adjust parameters according to actual requirements to implement a device update solution.
