Firmware update

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  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.

Note 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.

Instantiating the FirmwareUpdateManager 

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.

Installing an application 

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);

Note 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:

1. 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.
2. Verification of update package.
   
   If verification is enabled, the cryptographic signature of the package is verified against the provided certificates.
3. Update process.

Note 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.

Note 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.

Installing an update package 

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);

Note 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. In order to make your application aware of these events, create your own Firmware update listener by implementing the IFirmwareUpdateListener interface.

Firmware update listener 

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:

1. Check update package location.

• If the package is not in the cache partition, copy it to the cache partition.

1. updatePackageCopyStarted() notification is fired when the copy process starts.
2. updatePackageCopyFinished() notification is fired when the copy process ends.

• If the package is in the cache partition, copy notifications are not fired.

2. Verification of update package.

• If verify parameter is set to true in the installUpdatePackage(String, listener, boolean, String), verify the update package signature.

1. verifyStarted() notification is fired when the verification stars.
2. verifyProgress(int) notifies about the verification progress.
3. 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.

3. 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.

Note 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.

Wiping cache partition 

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");

Wiping cache and data partitions

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.