The latest version of the Android system provided by Digi enables you to update the firmware of the ConnectCore 6 device from the Android system itself. See Update the Android firmware to learn how to perform the firmware update through the Android settings. If you prefer, you can add the firmware update functionality to an Android application using the firmware update service provided by Digi.
With the Firmware update API you can perform a firmware update of the system from an Android application, install new applications and wipe the user and data partitions. In the Digi APIx javadoc documentation you can find a complete list of the available methods in this API.
Unless noted, all Firmware update API methods require the com.digi.android.permission.FIRMWARE_UPDATE permission.
If your application does not have the com.digi.android.permission.FIRMWARE_UPDATE permission it will not have access to any Firmware update service feature. |
First of all, a new FirmwareUpdateManager object must be instantiated by passing the Android Application Context.
import android.app.Activity;
import android.os.Bundle;
import com.digi.android.firmwareupdate.FirmwareUpdateManager;
public class FirmwareUpdateSampleActivity extends Activity {
FirmwareUpdateManager firmwareUpdateManager;
[...]
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Instantiate the FirmwareUpdateManager manager object.
firmwareUpdateManager = new FirmwareUpdateManager(this);
[...]
}
[...]
}
Install an application
One of the features provided by the Firmware update service is to install an Android application. Use the installApplication(String, boolean) method of the FirmwareUpdateManager with the full path of the APK to install. This method also offers the possibility of rebooting the module after the application installation.
Method | Description |
---|---|
installApplication(String, boolean) |
Installs the application represented by the given APK full path |
The installApplication(String, boolean) method may fail for the following reasons:
-
The provided application path is null throwing a NullPointerException.
-
There is an error installing the application throwing an IOException.
import com.digi.android.firmwareupdate.FirmwareUpdateManager;
[...]
FirmwareUpdateManager firmwareUpdateManager = [...];
[...]
// Install the application located at '/storage/emulated/0/MyApplication.apk'.
// Do not restart the device after application installation.
firmwareUpdateManager.installApplication("/storage/emulated/0/MyApplication.apk", false);;
This method will not ask for permission to install the application, as the installation process is performed by the Android Firmware update service. |
Install an update package
The main purpose of this Firmware update service is to install an update package to update the Android system.
A firmware update process follows these steps when it is triggered:
-
Check update package location. Firmware update is always performed from the cache partition of the device. If the update package is not located there, it is copied.
-
Verification of update package. If verification is enabled, the cryptographic signature of the package is verified against the provided certificates.
-
Update process.
-
Device reboots into recovery mode. The kernel and system in the recovery partition are booted instead of the kernel in the boot partition.
-
Recovery binary is started by init. It finds command-line arguments in /cache/recovery/command that point it to the update package.
-
Data is pulled from the package and used to update the boot, system and vendor partitions. One of the new files on the system partition contains the contents of the new recovery partition.
-
Device reboots normally.
-
The newly updated boot partition is loaded, and it mounts and starts the newly updated system partition.
-
As part of normal startup, the system checks the contents of the recovery partition against the desired contents (previously stored as a file in /system). They are different, so the recovery partition is reprogrammed with the desired contents. On subsequent boots, the recovery partition already contains the new contents, so no reprogram is necessary.
-
The system update is complete!
To generate an update package for your device, follow the steps in Create an update package. |
To update your Android system using an update package, use the installUpdatePackage(String, listener, boolean, String) method with the following parameters:
-
updatePackagePath: Full path of the update package to install.
-
listener: An object implementing the IFirmwareUpdateListener interface to receive firmware update progress information, cannot be null. See Listen for firmware update events for more information.
-
verify: Boolean parameter indicating if the update package signature must be verified.
Package signature is verified using the given certificates zip file in deviceCertsZipFile parameter. If this parameter is not provided, the default system certificates file is used. -
deviceCertsZipFile: Full path to the zip file of certificates whose public keys will be accepted. Verification succeeds if the package is signed by the private key corresponding to any public key in this file. May be null to use the system default file, /system/etc/security/otacerts.zip. This parameter only applies if verify is true.
Method | Description |
---|---|
installUpdatePackage(String, listener, boolean, String) |
Installs the given update package |
This installUpdatePackage(String, listener, boolean, String) may fail if the provided update package path or listener are null throwing a NullPointerException.
import com.digi.android.firmwareupdate.FirmwareUpdateManager;
[...]
FirmwareUpdateManager firmwareUpdateManager = [...];
MyFirmwareUpdateListener myFirmwareUpdateListener = [...];
[...]
// Install the '/storage/udisk1/ota_update_package.zip' update package.
// Listen to firmware events and do not verify the package.
firmwareUpdateManager.installUpdatePackage("/storage/udisk1/ota_update_package.zip", myFirmwareUpdateListener, false, null);
The module is restarted during the firmware update process. You can get events produced during the process with the IFirmwareUpdateListener provided in the method. |
Listen for firmware update events
The firmware update process generates some events that can be get and processed in your application. To make your application aware of these events, create your own Firmware update listener by implementing the IFirmwareUpdateListener interface.
import com.digi.android.firmwareupdate.IFirmwareUpdateListener;
class MyFirmwareUpdateListener implements IFirmwareUpdateListener {
@Override
void updatePackageCopyStarted() {
}
@Override
void updatePackageCopyFinished() {
}
@Override
void verifyStarted() {
}
@Override
void verifyProgress(int progress) {
}
@Override
void verifyFinished() {
}
@Override
void updateStarted() {
}
@verride
void onError(String error) {
}
}
The IFirmwareUpdateListener interface defines the following methods to handle the events generated during a firmware update process:
Method | Description |
---|---|
updatePackageCopyStarted() |
Notifies that the update package copy operation started |
updatePackageCopyFinished() |
Notifies that the update package copy operation finished |
verifyStarted() |
Notifies that the update package verification started |
verifyProgress(int) |
Notifies about the update package verification progress and provides the progress percentage |
verifyFinished() |
Notifies that the update package verification finished |
updateStarted() |
Notifies that the update process started and the device is about to reboot |
onError(String) |
Notifies any firmware update error and provides the error message |
Depending on the parameters provided in the installUpdatePackage method and the location of the update package, some events are not generated:
-
Check update package location.
-
If the package is not in the cache partition, copy it to the cache partition.
-
updatePackageCopyStarted() notification is fired when the copy process starts.
-
updatePackageCopyFinished() notification is fired when the copy process ends.
-
-
If the package is in the cache partition, copy notifications are not fired.
-
-
Verification of update package.
-
If verify parameter is set to true in the installUpdatePackage(String, listener, boolean, String), verify the update package signature.
-
verifyStarted() notification is fired when the verification stars.
-
verifyProgress(int) notifies about the verification progress.
-
verifyFinished() notification is fired when the verification ends.
-
-
If verify parameter is set to false in the installUpdatePackage(String, listener, boolean, String), verification notifications are not fired.
-
-
Update the system.
-
updateStarted() notification is fired when the update process starts.
-
onError(String) notification is fired if any error occurs at any stage of the firmware update process.
This listener is a mandatory parameter of the installUpdatePackage(String, listener, boolean, String) method. See Install an update package for more information. |
Wipe partitions
The latest feature you can find inside the Firmware update service is functionality to wipe some of the Android system partitions. These are the data and cache partitions, where you have full access and can read and write files. Use any of the following methods to start a wipe process:
Method | Description |
---|---|
wipeCache() |
Wipes the cache (/cache) partition |
wipeCache(String) |
Wipes the cache (/cache) partition providing a 'reason' message |
wipeUserData() |
Wipes the user data (/data) and cache (/cache) partitions |
wipeUserData(String) |
Wipes the user data (/data) and cache (/cache) partitions providing a 'reason' message |
wipeUserData(String, boolean) |
Wipes the user data (/data) and cache (/cache) partitions providing a 'reason' message. It also allows for a shutdown instead of reset |
These methods may fail if there is any error preparing for the wipe process throwing an IOException.
import com.digi.android.firmwareupdate.FirmwareUpdateManager;
[...]
FirmwareUpdateManager firmwareUpdateManager = [...];
[...]
// Wipe the cache partition and provide a reason message.
firmwareUpdateManager.wipeCache("I'm sorry for your cache");
import com.digi.android.firmwareupdate.FirmwareUpdateManager;
[...]
FirmwareUpdateManager firmwareUpdateManager = [...];
[...]
// Wipe the user data and cache partitions and provide a reason message.
firmwareUpdateManager.wipeData("I'm extremely sorry for your data and cache");
The device is restarted in order to perform the wipe operation. The wipeUserData(String, boolean) method shutdowns the device, instead of rebooting it, if the shutdown parameter is true.