Skip to main content

Quickstart APK (Bort Lite)

The Bort Lite preview is designed to try out the Bort SDK quickly and easily without requiring a full installation. It contains a single Android application (APK) that can be sideloaded onto any device that has adb access without requiring modifications to AOSP. It is not designed to be used in production. However, it can still collect much of the data that the full SDK is capable of, including:

  • Crashes (Tombstones, Java exceptions, ANRs, WTFs, Last KMSG)
  • Metrics
  • Log files (up to Android 12)

See Bort Features for a full breakdown of which features are available in Bort Lite versus the full Bort SDK.

Bort Lite releases are published to the Bort Lite Github repo, on the same cadence as Bort SDK releases. See the changelog in the main Bort repo.

1. Create a Project

Create or use an existing Memfault Organization. Once you have a Memfault Organization, create a new Android Project for Bort Lite.

2. Install Bort Lite

i. Enable adb access on your Android device

Ensure that adb is installed - download here if required.

To use adb with a device connected over USB, you need to ensure two settings are enabled on your Android device. Please reference the two links below to set up your device:

ii. Connect the device to your computer

Connect the device to your computer using a USB cable. Verify that your device is connected by executing adb devices from the $ANDROID_SDK/platform-tools/adb directory. Your phone will pop up a banner Allow USB Debugging. Check Always allow from this computer and press Allow.

If properly connected, you'll see the device identifier listed under List of devices attached.

With some additional work, you can also connect to your device over Wi-Fi.

iii. Run the install script

Download bort-lite-release.zip from the master branch of the Bort Lite Github repo (you don't need to check out the repo), and extract to a folder.

On macOS, open the Terminal, and run ./install-bort-lite.sh -k <project-key> -s <device-identifier>, replacing <project-key with the Project Key noted down earlier, and using the optional -s argument to specify a custom device identifier.

On Windows, open the Command Prompt, and run install-bort-lite.bat <project-key>, replacing <project-key with the project key noted down earlier.

Bort is now installed and enabled! Developer mode is ewnabled by default, meaning that all data collected will be uploaded immediately.

3. Collect your first device metrics

Bort Lite will continually capture data, and will upload to the Memfault dashboard every 2 hours (when there is connectivity available). So by default, it may take up to 2 hours before seeing the device in the Memfault dashboard.

i. Trigger metrics collection manually

Bort Lite will automatically collect metrics immediately after install. These will be visible in the Memfault dashboard, on the Device Timeline.

To collect metrics again:

adb shell am broadcast -a com.memfault.intent.action.REQUEST_METRICS_COLLECTION -n com.memfault.bort.lite/com.memfault.bort.receivers.ShellControlReceiver

Consider enabling Server-Side Developer Mode as well, when using Bort Developer Mode.

Additional Information

Bort Lite is released as a single pre-signed binary for convenience — the bort-lite.apk. This is different to how the full Bort SDK is released (built from source, signed with your certificate).

Bort Lite is limited in what operations it can perform:

  • It can only be granted development permissions (i.e. cannot be granted any signature, privileged or system permissions, unless it is also available via developer). Most of the data collected by Bort is available with this permission, but not all.
  • It also cannot perform any operations which require a system UID (which would need Usage Reporter, or one of the Bort system services MemfaultStructuredLogD or MemfaultDumpster) or modified SELinux configuration. This includes full access to all sysprops.
  • It can not capture Android bug reports or continuous logs (these require a native system service).
  • Performing an OTA via Memfault is not possible (this would need both SELinux changes, and system permissions).

The bundled installation script grants all development permissions at install time, using the -g argument to adb install. It also whitelists Bort to run in the background (using dumpsys deviceidle whitelist), without which Bort would not be able to do anything.

See Bort Features for a full breakdown of what features are available.