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¶
Managing forms with ADB¶
Form definitions are stored on the device in the
forms subdirectory of your Collect directory.
Loading blank forms¶
$ adb push local/path/to/form.xml <collect-directory>/forms/form.xml
The target path on the phone (the last part of the command) must include the file name.
$ adb shell rm -d <collect-directory>/forms/form.xml
Downloading forms to your computer¶
To download all filled records from a device:
$ adb pull <collect-directory>/instances/*
Developer tasks and troubleshooting with ADB¶
Downloading Collect databases¶
Collect stores form definition and form record state information in a few SQLite databases, which you can pull onto your local computer.
$ adb pull <collect-directory>/metadata/*.db
$ adb exec-out screencap /sdcard/image-name.png
To pull the saved image locally:
$ adb pull /sdcard/image-name.png
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.
$ 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.
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.txtas they occur.
Reproduce the bug or crash event.
CTRL-Cto stop logging.
You can then upload the
logfile.txt file to
a a support forum post
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.
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.
Identifying the Collect directory on your device¶
The ODK Collect directory on your device is:
/sdcard/odkif you are running an ODK Collect version less than v1.26.0 or have a file migration banner on the main screen
/sdcard/Android/data/org.odk.collect.android/filesif you have ODK Collect version v1.26.0+ and don't have a file migration banner on the main screen
Prior to ODK Collect v1.26.0, all Collect files were stored in the
/sdcard/odk directory. This directory was available to other applications to integrate with which can be very useful but can pose privacy risks.
Starting August 2020, Google will no longer allow Android applications to read or write files directly to this folder. Instead, each application will only be able to write files to a special directory that only it has access to. You can read more about this change on the forum.