Bort Lite Preview

The Bort Lite preview is designed for trying out the Bort SDK quickly and easily. It contains a single Android application (apk) that can be sideloaded onto any device which has adb access, to preview what a full Bort SDK integration would look like, 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:

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

See 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 a Memfault Organization and Android Project. If you already have an Organization, we strongly recommend creating a new Project for Bort Lite.

2. Install Bort Lite

i. Enable adb access on your Android device

To use adb with a device connected over USB, you must enable USB debugging in the device system settings, under Developer options. The Developer options screen is hidden by default on most devices. To make it visible, enable Developer options, usually by tapping the Build Version 10+ times (this may vary by device).

ii. Connect the device to your computer

Connect the device to your computer using a USB cable. You can verify that your device is connected by executing adb devices from the $ANDROID_SDK/platform-tools/adb directory. If properly connected, you'll see the device identifier listed.

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 <project-key>, replacing <project-key with the project key noted down earlier.

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

This will install and enable Bort with the appropriate permissions granted!

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

To see captured data immediately, or to trigger a manual data collection, Bort Developer Mode can be used. To enable Developer Mode:

adb shell am broadcast -a com.memfault.intent.action.DEV_MODE --ez com.memfault.intent.extra.DEV_MODE_ENABLED true -n com.memfault.bort.lite/com.memfault.bort.receivers.ShellControlReceiver

To collect metrics (once Dev Mode is enabled):

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 app apk file. 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't capture Android bug reports, or continuous logs (these require a native system service).
• OTA 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 Features for a full breakdown of what features are available.