Field Debugging for Android Users: ADB

Apr 29, 2021

If you have trouble with an Android app which is misbehaving, there are several steps you can take to help the developers figure out what’s wrong.

General

Please be as specific as you can when reporting errors. Developers need to know the kind of device you’re on (make and model, OS Version) which you get from the Settings App, under "About phone (or tablet)". They also need to know what version of their app you are using, which you can usually get from the App’s own "About" menu or by long-pressing on the App’s icon and choosing "App Info." And they need to know exactly what you did, and what didn’t work, and/or any messages the app gave.

ADB

adb is a program known as the "Android Debug Bridge". It is what developers use (either directly or via their development tools) to install apps under development, upload and download files, examine device logs, and more. There is no secret password needed, and no fee, to run adb. But there is a tiny bit of setup.

Terminal Windows

No, we’re not talking about terminating Windows (much as there may be frustrated users who’d like that). The "terminal window" is a generic term for either a program that emulates a "computer terminal" from the 1960’s. For example, "cmd" (command.com) or PowerShell on Windows. On macOS, the program is actually called Terminal.app, and is hidden away in /Applications/Utilities. On Linux and BSD, there are usually several terminal-type programs with names like xterm, kterm, and stranger names like rxvt (the last letters stand for virtual terminal).

Installing ADB

While you could download the full Android SDK, it’s pretty large and you probably won’t use most of it. Therefore, most package management systems include adb as a standalone package. On Windows, please follow one of these directions: https://www.xda-developers.com/install-adb-windows-macos-linux/ or https://www.androidrecovery.com/blog/install-use-adb-windows.html.

On macOS, to download ADB by itself, check out https://technastic.com/adb-fastboot-command-mac-terminal/. If you have or would like to have the HomeBrew package installer, use these directions.

On BSD or Linux, there should be a package, using whatever packaging tools your OS offers. On BSD, try pkg_add adb (works for me). On Linux, use dnf, rpm, apt, or whatever.

Developer Mode on device

In the Settings app on your device, there will be an About section at the bottom. Tap it. Go to the bottom of the resulting page, and you should see a sectino called Build number. Some device manufacturers feel they have to improve things pointlessly; for example, on Huawei "EMUI" systems, Build Number is near the top of the About section. Tap it. Tap it again. And again. After a few taps it should say something like "You are X taps away from being a developer." When you get to seven taps, it will say "You are now a developer." Well it hasn’t magically loaded developer-fu into your brain like in The Matrix movies, but it has enabled "developer mode". Now, somewhere in Settings, there is a new section called Developer Options. And in there, is the all-important USB Debugging option. Enable that, and you’re done. Almost.

When you now connect your phone to your computer, it will ask you if you trust the computer and, if so, to click OK. There is an option "Always allow", which I discourage you from using for security reasons. It’s mainly meant for developers' test devices which typically do not have any valuable personal information on them; please don’t use it for your "daily driver" phone.

On most devices USB Debugging is persistent. On some it is turned off after use, and has to be re-enabled. Don’t get discouraged.

If your phone is connected, it will show up in the output of adb devices:

$ adb devices
* daemon not running. starting it now on port 5037 *
* daemon started successfully *
List of devices attached
A4N4C19511003333	unauthorized
$ adb devices
List of devices attached
A4N4C19511003333	device
$

The first time you run adb it may give you two lines about "starting daemon". Don’t worry, there is nothing satanic about that - "daemon" is an old English word for "assistant" and was used early on in Unix as a term for a background server process.

The funky string A4N…​ is a string that identifes your phone, and typically includes the manufacturer, and model, and serial number. The unauthorized just means that you haven’t yet answered the "trust this computer" prompt. After that, it should show up as device.

Getting 'adb logcat' output

Now you’re ready to use adb to get some real work done. The 'LogCat' mechanism is the Android system logfile, and adb logcat will display it. The output normally contains a huge amount of debugging "chatter" from all the apps that are running. You should just forward the `adb logcat to your developers without trying to pare it down.

Give the command adb logcat in a terminal window now if you have adb installed and your device is connected and has "USB Debugging" enabled. Looks like a load of nonsense, eh? But it makes sense to Android developers who are used to staring at this stuff. Type CTRL/C (^C) in the terminal window to cancel or kill the running command.

When you want to grab an adb logcat output to save, you could do something like this:

  • Make sure the app is not running (use process killer, or eject from running list - square button at bottom of modern Android), because sometimes problems get started at the beginning of the app.

  • Also close any other apps that you can close without inconvenience.

  • Run adb logcat into a file, like adb logcat > someapp-someprob-somedate.txt (with the obvious substitutions in the filename).

  • Start the app

  • Quickly perform the steps in the app that show the problem.

  • When done, type CTRL/C (^C) in the terminal window.

  • Send the text file to the developer.

ADB screen record

Android has its own built-in screen recorder, just waiting to be invoked via ADB.

adb shell screenrecord  > /sdcard/sample.mp4
# Do the things you want to show
^C
adb pull /sdcard/sample.mp4
# Move sample.mp4 to a safe location, send it to the developer,
# edit it and publish on Vimeo/Youtube, whatever.
# When *sure* it's no longer needed, free up disk space on phone:
adb shell rm /sdcard/sample.mp4

Other things to do with adb

Copy files to/from the phone. To get a listing of what’s on the phone:

$ adb ls /sdcard
000041f8 00001000 5d6eec8d Music
000041f8 00001000 495c7806 Podcasts
000041f8 00001000 5a009d78 Ringtones
000041f8 00001000 495c7806 Alarms
000041f8 00001000 5a05d184 Notifications
000041f8 00002000 60116392 Pictures
000041f8 00001000 6052a1ee Movies
000041f8 00001000 601f3f70 Download
000041f8 00001000 5d6eec7b Android
000041f8 00001000 5a009d46 Mobile Systems
000041f8 00001000 5b5f2cc5 panoramas
000041f8 00001000 5f5a3e26 Documents
000041f8 00001000 5f73c83c Signal
000081b0 000262dd 608ac281 id.mp4
...
$ adb ls /sdcard/Pictures
000041f8 00002000 5fd9d5be Screenshots
000041f8 00001000 5a009d48 Photoshop Express
000081b0 0053e0af 5b9d0fd1 IMG_20180915_095737.jpg
000041f8 00001000 5f315357 PIVO
000041f8 00005000 60897348 .thumbnails
000041f8 00001000 5fe4b0a3 PhotosEditor
000041f8 00001000 60123e4b Instagram
$

The output is primitive compared to regular ls -l. The number with 41 indicates a directory, while 81 indicates a file.

$ adb pull /sdcard/Pictures/IMG_20180915_095737.jpg
/sdcard/Pictures/IMG_20180915_095737.jpg: 1 file pulled...
$

To go the other way - load files onto your phone - use adb push.