Skip to main content

Android OTA Integration Guide

info

The Bort SDK includes a full OTA update client, from version 3.7.0 onwards. See Bort OTA client below for more information.

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: a unique identifier of a device (often the device serial number). The system property ro.serialno or android.os.Build.getSerial() API is used to get this value. Make sure it is unique for every device in the same Project, and that the calling app has the requisite permissions to obtain the device serial number.
  • 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".

note

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

Getting Started

OTA Update Client

The Bort SDK (since version 3.7.0) includes an OTA Update Client. Including this in your build is simple.

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.

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

info

The OTA Update Client manages this process!

Roll Back the Release

Aborting or Rolling back from a Release which has a firmware 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.