Skip to main content

AOSP SDK Update Guide

The following guide walks through how to update the Memfault AOSP SDK in your project via Git, and how to validate the update.

Prerequisites​

Before updating the SDK, ensure you have:

  • The Memfault Android SDK already integrated in your AOSP project after following the AOSP Integration Guide. The SDK should have been cloned via Git in the folder.
  • Access to the AOSP source tree where the SDK is integrated.

We also recommend having shipped an AOSP update at least once before for familarity with your specific release process.

tip

You may not need to build and ship a full OS image at all. You can update Bort and the OTA Update Client on their own, by rebuilding the APK and distributing it to your fleet. See Updating Bort as an APK. A full AOSP build is required for a first integration and for SDK changes that touch the system image.

1. Update the Android SDK​

i. Navigate to the SDK directory​

Change to the directory where the Memfault Android SDK is located in your CLI:

cd <AOSP_ROOT>/vendor/memfault/bort

This may vary depending on your project setup.

ii. Commit all existing changes​

Before updating, check which branch you're on and if there are any uncommitted changes:

git status
git branch

We broadly recommend having a singular custom branch with all your SDK changes:

git checkout -b <ORG>-sdk-release

If you have uncommitted changes, you may want to commit before updating:

git add .
git commit -m "Your commit message"

iii. Update the local remote​

Fetch the latest changes from the remote repository:

git fetch

iv. Rebase to the latest version​

We strongly recommend rebasing instead of merging any changes to your custom branch for readability.

# Check available tags/releases
git tag -l

# Update to a specific release tag
git rebase <RELEASE_TAG>
# For example: git checkout 5.5.0

# Android 8-10 devices will need to use the 8-10 releases
# For example: git checkout 5.5.0-8-10

# Android 7.1 devices will need to use the 7 release
# For example: git checkout 5.5.0-7

Conflicts in patch files​

If conflicts occur in patch files or the patches/ directory:

  • Review the patch changes carefully
  • Ensure patches are compatible with your AOSP version
  • You may need to revert any existing patches and re-apply them

Conflicts in application properties​

If conflicts occur in MemfaultPackages/bort.properties:

  • Preserve your local configuration (Project Key, Application IDs, etc.)
  • Merge any new SDK properties that may have been added

2. Build your AOSP project​

After successfully updating the SDK, you may need to re-apply certain configurations:

i. Re-apply AOSP patches (if required)​

If your AOSP version requires patches (see AOSP Patches), re-apply them:

vendor/memfault/bort/bort_cli.py patch-aosp \
  --android-release <YOUR_ANDROID_VERSION> \
  <AOSP_ROOT>

For example, for Android 17:

vendor/memfault/bort/bort_cli.py patch-aosp \
  --android-release 17 \
  <AOSP_ROOT>

ii. Re-apply application ID patches​

Re-apply your application IDs to the updated SDK:

vendor/memfault/bort/bort_cli.py patch-bort \
  --bort-app-id <YOUR_BORT_APPLICATION_ID> \
  --bort-ota-app-id <YOUR_BORT_OTA_APPLICATION_ID> \
  <AOSP_ROOT>/vendor/memfault/bort/MemfaultPackages

iii. Verify configuration files​

Check that your configuration files are still correct:

  • MemfaultPackages/bort.properties - Verify Project Key and other settings
  • keystore.properties - Ensure keystore paths and passwords are correct
  • ota_keystore.properties - If using OTA, verify OTA keystore settings

iv. Rebuild the APKs​

You must rebuild all the Android SDK APKs:

cd <AOSP_ROOT>/vendor/memfault/bort/MemfaultPackages
./gradlew assembleRelease

This will rebuild:

  • MemfaultBort.apk
  • MemfaultBortOta.apk (if using OTA)
  • MemfaultUsageReporter.apk

v. Rebuild and run the AOSP image on your device​

After updating the SDK and rebuilding the APKs, rebuild your AOSP image:

// e.g.
cd <AOSP_ROOT>
source build/envsetup.sh
lunch <your-target>
make -j$(nproc)

3. Validate the SDK update​

After flashing the updated image to your device, validate the SDK integration using the bort_cli.py tool.

Connect that device via ADB (verify via adb devices) and run the script:

./bort_cli.py validate-sdk-integration --bort-app-id <YOUR_BORT_APPLICATION_ID>

If using OTA:

./bort_cli.py validate-sdk-integration \
  --bort-app-id <YOUR_BORT_APPLICATION_ID> \
  --bort-ota-app-id <YOUR_BORT_OTA_APPLICATION_ID>

The tool should finish successfully with no errors.

info

We recommend running the validation tool with a userdebug system image. A user image does not allow all checks to be run, which may result in Bort configuration issues being missed.

4. Verify your updated device shows up in Memfault​

Once your device is updated and running with the new AOSP image, the Memfault SDK should automatically begin collecting metrics after (Memfault is enabled).

Data will typically begin being uploaded several hours after the device has been left powered and connected to the Internet. To speed up testing, you can trigger metrics collection manually.

Once the Device shows up in Memfault, you can look for the MemfaultSdkMetric_sdk_version Attribute in the Device Details page to verify the device is running the new SDK version.

Updating Bort as an APK​

Most SDK updates do not require a full OS release. The Bort app and the OTA Update Client ship as prebuilt APKs inside the platform image, and since they are signed with your own keystore rather than the platform key, the Android package manager can update them in place like any other app.

The rest of the SDK cannot be updated this way. MemfaultUsageReporter is signed with the platform certificate, and the native daemons (MemfaultDumpster, MemfaultStructuredLogd, MemfaultDumpstateRunner), the SELinux policy and any AOSP patches are part of the system image. Updating those requires a full OS update.

You must own and keep the Bort signing key​

important

Android installs an update to an app only if you sign it with the same key as the installed version, and it grants Bort's privileged permissions based on that signing certificate. The keystore you created during integration is therefore what lets you ship future Bort app updates.

Keep the keystore and its passwords under your control and backed up. If you lose the key, you can no longer update Bort as an APK on already-shipped devices.

The same applies to the separate OTA Update Client keystore, if you use the OTA Update Client.

1. Build the APK​

After updating the SDK, build the release APKs:

cd <AOSP_ROOT>/vendor/memfault/bort/MemfaultPackages
./gradlew assembleRelease

Make sure that keystore.properties (and ota_keystore.properties, if applicable) point at the same keystore that signed the build installed on your devices, and that the application IDs in bort.properties are unchanged. Under a different application ID, the package manager installs a second app alongside the old one instead of updating it.

The package manager will only install the new APK over the old one if its version code is higher than the installed one. By default the version code comes from the SDK version, so each SDK release bumps it and incorporating upstream changes is enough. If you are rebuilding without pulling in upstream changes, increment BUILD_ID_CODE_OVERRIDE in bort.properties (valid values are 0 to 99), which forms the two least significant digits of the version code.

warning

If you set VERSION_CODE_OVERRIDE in bort.properties, the SDK version no longer drives the version code. The override replaces it and stays fixed across SDK updates, so the package manager rejects an APK built with an unchanged override. You must increment VERSION_CODE_OVERRIDE yourself for every APK you distribute, and it must be higher than the version code of any APK you have already shipped. To check what a device is running:

adb shell dumpsys package <YOUR_BORT_APPLICATION_ID> | grep versionCode

2. Distribute the APK​

Memfault does not distribute the Bort APK to your devices. Install it using whichever app distribution mechanism your fleet already has, for example:

  • A device management (MDM) solution.
  • An app store.
  • adb install -r MemfaultBort.apk, for development and testing.

You do not need to reboot the device, and nothing else in the SDK changes.

Changes that still need a full OS update​

A newer Bort APK can run on an older system image, so some changes only take effect after a full OS update:

  • New privileged permissions. The privapp-permissions allowlist (com.memfault.bort.xml, com.memfault.bort.ota.xml) lives in the system image. If a newer APK requests a permission the installed image does not allowlist, Android denies it, and the feature that depends on it stays off.
  • Features that require AOSP patches, SELinux policy changes, or a newer native daemon.

Bort checks for these at runtime and keeps the affected feature off, rather than failing.

Best Practices​

  1. Review release notes: Before updating, check the SDK release notes for breaking changes or new requirements.
  2. Minimize Memfault code changes: Custom, extensive code changes to the Memfault SDK is generally discouraged as it will make future updates more difficult, and isn't tested by Memfault. Please reach out to Memfault Support for help if you'd like to see changes.
  3. Test in a dev build: Strongly consider testing the SDK update on a development build instead of directly in production. Ensure that the Memfault SDK runs to your satisfaction before releasing.
  4. Backup your changes: If you've made custom modifications to the SDK, consider documenting them or maintaining them as patches that can be re-applied.

Troubleshooting​

Conflicts in critical files​

If you encounter conflicts in files you're unsure about:

  1. Check the SDK release notes for changes
  2. Review the Git history to understand what changed
  3. When in doubt, prefer keeping the SDK's version and re-applying your customizations

Build errors after update​

If you encounter build errors after updating:

  1. Clean your build: make clean or ./gradlew clean
  2. Verify all patches are re-applied correctly
  3. Check that configuration files are valid
  4. Review the SDK release notes for any new requirements
Tags:
Last updated on
This page is human-authored. If you see any errors, outdated information, or any other suggestions for improving the contents, please contact us!