The firmware update process requires an OTA package to update your system. See Create a signed OTA package if you don’t have one already generated.

Use the signed OTA package to update Android:

  1. Generate the OTA configuration file

  2. Update Android with OTA package

A/B System updates

A/B updates were introduced in Android 7.1. The A/B system keeps redundant copies of system, boot, vendor, and other vendor-specific partitions and can apply an update to the currently unused partition while the system is running. A/B system updates, also known as seamless updates, ensure a workable booting system remains on the disk during an over-the-air (OTA) update in case of failure.

The recovery partition is no longer used since it was very similar to boot partition. However, the boot partition now contains recovery ramdisk to retain old functionality.

A/B system updates use two sets of partitions referred to as slots (normally slot A and slot B). The system runs from the current slot while the partitions in the unused slot are not accessed by the running system during normal operation. The current slot is bootable when the system is running, but the other slot may have an old (still correct) version of the system, a newer version, or invalid data.

Updates are applied while your device is still running, since they are applied to the inactive slot. Once they are applied, a reboot is required and your inactive slot is marked as the active and bootable slot. If it boots successfully, it’s marked as successful so you keep using it from that point on. If the system is not able to boot after seven attempts, the bootloader marks the slot as unbootable and marks your old, untouched slot as the active/bootable slot again.

A/B Update

For more information about A/B system updates, read Android documentation chapter A/B (Seamless) System Updates

Streamed/Non-streamed updates

One of the advantages of the new A/B firmware update system is that the OTA package can be directly streamed from a web server and applied on-the-fly to the inactive partition. This means that no additional space is required in the device to download and store the update package. Applying an update from a local OTA file in the device (non-streamed update) is still possible.

Streamed updates require a web server with range requests support in order to download OTA zip file fragments. Otherwise, the streaming update will fail.

JSON OTA configuration file

An A/B system update requires specific configuration, including the type of update to execute (streamed/non-streamed), the location of the OTA zip file (local or hosted), whether to verify metadata, and a description of the OTA zip file contents. Because of these requirements, the operation is triggered by a JSON configuration file with the required inputs.

The structure of this configuration file is:

{
    "__name": "name of the update",
    "__url": "https:// or file:// uri to update package (zip, xz, ...). Depends on stream/non-stream update",
    "__ab_install_type": "NON_STREAMING (update from a local file) - STREAMING (update from a hosted file)",
    "name": "SAMPLE-cake-release BUILD-12345",
    "url": "file:///data/my-sample-ota-builds-dir/ota-001.zip",
    "ab_install_type": "NON_STREAMING",
    "ab_streaming_metadata": {
        "__": "streaming_metadata is required only for streaming update",
        "__property_files": "name, offset and size of files",
        "__authorization": "it will be sent to OTA package server as value of HTTP header - Authorization",
        "property_files": [
            {
                "__filename": "name of the file in package",
                "__offset": "defines beginning of the file in package",
                "__size": "size of the file in package",
                "filename": "payload.bin",
                "offset": 531,
                "size": 5012323
            }
        ],
        "authorization": "Basic my-secret-token"
    },
    "ab_config": {
        "__": "A/B (seamless) update configurations",
        "__force_switch_slot": "if set true device will boot to a new slot, otherwise user has to manually switch the slot after the update",
        "__verify_payload_metadata": "if set true OTA package metadata will be verified prior to attempt the firmware update",
        "force_switch_slot": true,
        "verify_payload_metadata": true
     }
}

1. Generate the OTA configuration file

The Android sources provide a Python script that generates this JSON configuration file based on the OTA zip file and some user options.

The script is located at bootable/recovery/updater_sample/tools/gen_update_config.py and uses the following syntax:

usage: gen_update_config.py [-h] [--ab_install_type {STREAMING,NON_STREAMING}]
                            [--ab_force_switch_slot]
                            [--ab_verify_payload_metadata]
                            package out url

Where:

  • --ab_install_type: Determines how the OTA package is installed:

    • NON_STREAMING: The OTA package is located in the device and is installed from there.

    • STREAMING: The OTA package is downloaded from a HTTP server and installed on the fly.

  • --ab_force_switch_slot: After a successful install, it commands the update engine to switch the boot slot to the new one.

  • --ab_verify_payload_metadata: Verifies the OTA metadata before installing the package.

  • package: The location of the OTA package in the development computer for which the configuration file is to be generated.

  • out: The path where the generated configuration file is to be saved.

  • url: The location of the OTA package from the device perspective:

    • If the update type is NON_STREAMING and the package is located in the device file system, use the format "file:///<location>".

    • If the update type is STREAMING and the package is located in a web server, use this format "http://<server>:<port>/<file_path>".

To execute it you must add the release tools to the PYTHONPATH:

$ PYTHONPATH=$ANDROID_BUILD_TOP/build/make/tools/releasetools:$PYTHONPATH \
  bootable/recovery/updater_sample/tools/gen_update_config.py \
  --ab_install_type=STREAMING \
  --ab_force_switch_slot \
  ota-build-001.zip  \
  my-config-001.json \
  http://foo.bar/ota-builds/ota-build-001.zip

2. Update Android with OTA package

Once the JSON configuration file has been generated, you can apply the update to the device. There are several ways to update your device:

Update from Android Settings

Follow these steps to update your system from the Android settings menu using an already generated package:

  1. Copy the JSON configuration file you have generated anywhere inside the Android file system. It can be located either in the internal memory or in any removable device such as micro SD or USB stick.

  2. Copy the update OTA zip file in the correct place as described by the JSON configuration file:

    • If the firmware update is streamed, place the OTA file in the corresponding web server.

    • If the firmware update is non-streamed, place the OTA file in the configured path of the Android device.

  3. Navigate to the Android settings and select the System category.

    System

  4. Expand the Advanced category and select the Additional system updates option. The firmware update application opens.

    Firmware update application

  5. In the left panel, click the Browse button to select the JSON file to apply. A file explorer activity opens.

  6. Select the JSON configuration file you want to use for the update and navigate back to the update application.

  7. Click the Apply update button to start the firmware update process. At the right panel you can see the update progress and detailed information of the process.

    Firmware update progress

This panel also holds several buttons that allows you to control the firmware update process:

  • Cancel update: Permanently cancels an in-progress update.

  • Reset update: Resets the update engine to IDLE state. If an update has been applied it is reverted; however modified partitions cannot be restored.

  • Suspend update: Suspends a running update.

  • Resume update: Resumes a suspended update.

  • Switch Slot: For updates that do not force the A/B slot switching, this button allows you to perform this action manually.

When the firmware update process finishes, you must reboot the device to boot into the updated system.

You can also install an update package from a custom Android application using the Firmware update service API provided by Digi. See Firmware update API.