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.

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

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

vendor/memfault/bort/bort_cli.py patch-aosp \
  --android-release 14 \
  <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.

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!