Using Android Debug Bridge with Collect

Android Debug Bridge is a tool that provides command-line access to a USB-connected Android device. It can be used to move files between the device and your computer, install applications, and take screenshots and videos. When connected to a device that has ODK Collect installed, it can be used to push blank form definitions and pull completed forms.

Installing and setting up ADB

Android Studio

The easiest and most well-supported way to install ADB is to install Android Studio, which includes ADB. After installing, you'll need to enable USB Debugging.

Standalone ADB

You can also install ADB without Android studio. This is not well supported, though, and should only be done if you cannot install Android Studio on your computer.

Managing forms with ADB

Forms are stored on the device in /sdcard/odk/forms/.

Loading blank forms

$ adb push local/path/to/form.xml /sdcard/odk/forms/form.xml

Note

The target path on the phone (the last part of the command) must include the file name.

Deleting forms

$ adb shell rm -d /sdcard/odk/forms/form.xml

Downloading forms to your computer

To download a completed form or form instance from the computer:

$ adb pull /sdcard/odk/forms/form.xml

Developer tasks and troubleshooting with ADB

Downloading Collect databases

Collect stores settings and form state information in a few SQLite databases, which you can pull onto your local computer.

$  adb pull /sdcard/odk/metadata/*.db

Taking screenshots

$ adb exec-out screencap /sdcard/image-name.png

To pull the saved image locally:

$ adb pull /sdcard/image-name.png

Note

ODK Docs contributors can use the screenshot utility script, which wraps the adb commands and assists with saving the images to the correct location and inserting appropriate markup in the documentation source.

Recording video

$ adb shell screenrecord /sdcard/video-name.mp4

When you hit Enter, the video starts recording immediately.

To stop the recording, press CTRL-C. If you don't interrupt the recording, it will stop after three minutes.

To pull the video locally:

$ adb pull /sdcard/video-name.png

Capturing logs for debugging

Capturing in-progress logs with logcat

If you are experiencing crashes or other serious glitches, and you can reproduce the bug, use adb logcat to capture log events during the crash.

  1. Before reproducing the bug, begin piping logs to a file:

    adb logcat > logfile.txt
    

    This will write all logged errors to your local file logfile.txt as they occur.

  2. Reproduce the bug or crash event.

  3. Type CTRL-C to stop logging.

You can then upload the logfile.txt file to a Collect issue on GitHub or post in the ODK Forum.

Pull a bug report

If more in-depth information is needed, you can pull a complete bug report from the device.

adb bugreport

This copies a ZIP file locally containing all system messages, error logs, and diagnostic output, along with information about the device's hardware, firmware, and operating system.