Android OTA Integration Guide

This tutorial covers how to manage your Android over-the-air update flow with Memfault!

tip

Memfault uses a globally distributed CDN for low latency and high speed downloads regardless of geolocation. It supports features such as HTTP/2, Brotli and GZip, and byte range requests, among others.

Terminology Overview

Please refer to Over-the-Air Updates(OTA) for an introduction to Memfault's OTA concepts and terminology. The paragraphs below discuss the platform-specific aspects for Android.

Identifying an Android Device

For a device in a project, several pieces of identifying information are tracked.

• Device ID: By default, the Device's Serial Number is used as the Device ID, collected from the ro.serialno system property. Make sure that it is unique for every device in the same Project.
• Hardware Version: for a given device, the revision of the hardware. For more information, see our Hardware Version documentation.

By default, the value of the ro.product.board system property is used as "Hardware Version".

caution

For any given device, neither of these pieces of information should ever change.

Getting Started

OTA Update Client

First, you will want to include an OTA client into your Android OS. The Android SDK includes an OTA Update Client that is easy to use and ready to start updating your devices. Including it in your build is simple.

We also have a legacy example of building your own OTA client, though we recommend using the one we've provided for you.

Memfault CLI Tool

Releases can be managed either from the Memfault web UI or via the memfault cli tool. In this tutorial we will make use of the CLI client which can be installed via pip:

$ pip3 install memfault-cli

Organization API Token

This is an auth token that can be used as the "password" to make Memfault API requests which require Authentication.

Tokens can be generated by going to the Admin / Organization Auth Tokens page.

This token should be passed in as the --org-token parameter when using the Memfault CLI.

For more information about authentication, see Authentication

Project & Organization Slug

When using email & API key authentication, the Memfault CLI tool also needs to know what organization and project to target. To find the "slugs" of the organization and project in the Memfault UI:

1. Make sure that you've selected the right project on the top-left
2. Click on "Settings" and then "General Settings"

Project Key

This is a token that is used when pushing data between a device and the Memfault cloud. We will be using this to query for OTA Payloads in this tutorial. To locate this token you will also want to navigate to the "Settings" → "General" page in the Memfault UI and copy/paste the token in the "Project Key" section.

Managing Your First Release

Create Release

The Hardware Version we will be targeting is matches our products' ro.product.board system property value. In the commands below, please replace ${YOUR_PRODUCT_BOARD_HERE} with your products' ro.product.board system property value.

To find the Software Version from the Android build artifacts, we can print the out/target/product/$DEVICE/build_fingerprint.txt file, for example:

$ cd /dev/smartfridge/
$ cat out/target/product/smartfridge/build_fingerprint.txt
acme_inc/smartfridge/smartfridge:10/QQ2A.200405.005/04302340:user/release-keys

To indicate to Memfault we are uploading the OTA payload for the Android system itself, we need to use android-build as the software_type.

The complete Memfault CLI invocation to upload the OTA payload:

$ cd /dev/smartfridge/
$ memfault --org-token ${YOUR_ORG_TOKEN} \
  --org ${YOUR_ORG_SLUG} \
  --project ${YOUR_PROJECT_SLUG} \
  upload-ota-payload \
  --hardware-version ${YOUR_PRODUCT_BOARD_HERE} \
  --software-type android-build \
  --software-version $(< out/target/product/smartfridge/build_fingerprint.txt) \
  --notes "Bug fixes and performance improvements: September 2021" \
  out/dist/path-to-ota-user.zip

INFO: out/dist/path-to-ota-user.zip: uploaded!
INFO: You can view in the UI here:
    <Link to Release in UI>

Versioning

Android versioning configuration is set when creating your project. See the project settings page to find the Software Version Source for a project.

See more information on Android software versioning.

Build Fingerprint Only

The fingerprint (see above) is the only versioning property. The example above describes this:

--software-version $(< out/target/product/smartfridge/build_fingerprint.txt) \

Build Fingerprint and System Property

A system property is used in combination with the build fingerprint. Modify the --software-version argument to include the build property value e.g.

--software-version $(< out/target/product/smartfridge/build_fingerprint.txt)::123456789 \

where 123456789 is the value of the selected system property. You can find the value of system properties in the build output folder: out/target/product/**/product/build.prop.

System Property Only (not recommended)

--software-version 123456789 \

where 123456789 is the value of the selected system property. You can find the value of system properties in the build output folder: out/target/product/**/product/build.prop.

Tip

If you are going to be working with the same project you can add standard arguments as environment variables to your shell init file or via the command line:

$ export MEMFAULT_ORG_TOKEN=<Organization Token>
$ export MEMFAULT_ORG=<Organization slug>
$ export MEMFAULT_PROJECT=<Project slug>

With these changes, our invocation reduces to:

$ cd /dev/smartfridge/
$ memfault upload-ota-payload \
  --hardware-version ${YOUR_PRODUCT_BOARD_HERE} \
  --software-type android-build \
  --software-version $(< out/target/product/smartfridge/build_fingerprint.txt) \
  --notes "Bug fixes and performance improvements: September 2021" \
  out/dist/path-to-ota-user.zip

INFO: out/dist/path-to-ota-user.zip: uploaded!
INFO: You can view in the UI here:
    <Link to Release in UI>

Activating the Release

Now let's activate the Release in the default Cohort.

note

Any new device seen that has not explicitly been assigned to a custom Cohort will be part of the default Cohort. To pre-create devices assigned to a specific Cohort check out our api-docs.

In the application, navigate to Fleet → Cohorts. Click on the picker under next to the default Cohort under "Target Release", select the Release to activate and you will be prompted with options that can be performed for the Release.

Query for OTA Payload

The OTA Update Client manages this process.

Using the OTA Update client is our recommended method for managing device updates. You can also perform these operations directly through the Memfault OTA API. See an example of this in our MCU OTA section. The examples shown apply to any device using this API.

Roll Back the Release

Aborting a Release which has a regression is easy to do from the UI. Simply navigate to "Fleet" → "Cohorts", click on the picker under "Options" and select the "Abort Rollout" option.

Due to the secure architecture of Android, it prevents rolling back to an older version of software. If you are in need of performing a rollback, you will instead need to rollforward. To do this, you will want to rebuild it from source with a new version code that is higher than the current version running on the device. From there, you will release the update like you would a normal release.

Legacy OTA example app

caution

The OTA example app has been replaced with the new OTA Update Client.

A basic example OTA agent application can be found on Memfault's Github. Be sure to check the README and note the limitations of this example code.