A. The Android Debug Bridge Quick-Start Guide
The Android Debug Bridge (ADB) is a client-server tool that interacts directly with Android devices and emulators using a command-line interface. You can use this tool, which is provided as part of the Android SDK, to manage and interact with emulator and device instances connected to a development machine and view logging and debugging information. ADB also provides the underpinnings for other tools, such as the Android Plug-In for Eclipse (ADT) and Dalvik Debug Monitor Service (DDMS). This Quick-Start Guide is not complete documentation of the ADB functionality. Instead, it is designed to get you up and running with common tasks. See the ADB documentation provided with the Android SDK for a complete list of features.
Much of the functionality provided by the ADB (such as the LogCat Android logging utility or pushing and pulling files using the File Explorer) is closely integrated into the development environment through DDMS and ADT. Developers might prefer to use these friendly methods to interact with devices and emulators; however, you can use ADB for automation and scripting purposes. You can also use ADB to customize functionality, instead of relying on the defaults exposed through secondary tools.
Listing Connected Devices and Emulators
You can use ADB to list all Android devices and emulator instances connected to a development machine. To do this, simply use the devices command of the adb command line. For example:
adb devices
This command lists the emulators and devices attached to this machine by their serial number and state (offline or device). For emulator instances, the serial number is based on their unique port numbers. For example, in this case, we have one emulator instance (Port 5554) and one Android device:
C:>adb devices
List of devices attached
emulator-5554 device
HT841LC1977 device
Directing ADB Commands to Specific Devices
When you know the serial number of the device you want to connect to, you can issue commands as follows:
adb -s <serial number> <command>
For example, to get the state of a specific device, type
adb -s emulator-5554 get-state
Instead of using the -s flag with a unique serial number, you can also use the -d flag to direct a command to the only device instance connected or the -e flag to direct a command to the only emulator instance, provided you have only one of each type connected. For example, if we have only one Android phone connected, we can query its serial number as follows:
adb -d get-serialno
Starting and Stopping the ADB Server
Sometimes you might need to manually restart the ADB server process. We have, for example, needed to do this when we’ve had an emulator instance running for a long time and have repeatedly connected and disconnected the debugger, eventually resulting in a loss of LogCat logging. In this case, you might want to kill and restart the ADB server (and perhaps Eclipse).
Stopping the ADB Server Process
To terminate the ADB server process, use the kill-server command. For example, type
adb kill-server
Starting and Checking the ADB Server Process
You can start the ADB server using the start-server command.
adb start-server
You can also use the start-server command to check whether the server is running. If the server isn’t running when other commands are issued, it is started automatically.
Listing ADB Commands
To get a list of all ADB commands, type
adb help
You can also simply type adb without any arguments to get a list of all other commands available through the adb shell.
Issuing Shell Commands
ADB includes a shell interface (ash) where you can interact directly with the device and issue commands and run binaries. The ash shell has your typical file access commands, such as pwd and ls.
For more information on the ash shell, check out the Linux Blog Man at http://www.thelinuxblog.com/linux-man-pages/1/ash
Issuing a Single Shell Command
You can issue a single shell command without starting a shell session using the following command:
adb shell <command>
For example, to list all the files in the /sdcard/download directory on the emulator, type
adb -e shell ls /sdcard/download
Using a Shell Session
Often you might want to issue more than one command. In this case, you might want to start a shell session. To do so, simply type
adb shell
For example, to connect to a specific device instance by serial number and start a shell session, type
adb -s emulator-5554 shell
# <type commands here>
# exit
You can then issue commands. Ending your session is as easy as typing exit.
If you connect to a device instead of the emulator, you might see a $ as a prompt instead of a # prompt. This indicates user-level access, but the commands, such as logcat and monkey, work as described.
Using the Shell to Start and Stop the Emulator
Stopping the emulator makes it stop responding, although it still displays on your development machine. To stop the emulator, you can issue the stop command in the ADB shell.
adb -s emulator-5554 shell stop
You can then restart the emulator using the start command:
adb -s emulator-5554 shell start
You could also perform these commands from within a shell session, like this:
adb -s emulator-5554 shell
# stop
# start
You can also use the shell interface to run built-in command-line programs such as sqlite3 to examine SQLite application databases and monkey to stress test an application. You can also install custom binaries on the emulator or device. We talk more about this later in the appendix. That said, you can only run sqlite3 on the device shell if the device is rooted, which we do not recommend, although many people do it.
Copying Files
You can use the ADB command line to copy files to and from your hard drive to an Android device. You need to know the full path information to the file you want to copy. File operations are subject to your user permissions (locally and remotely).
Sending Files to a Device or Emulator
You can copy files to the device using the push command, as follows:
adb push <local file path> <remote file path on device>
For example, to copy the file Pic.jpg from the local hard drive to a device’s SD Card download directory, use the following command:
adb -s HT841LC1977 push c:Pic.jpg /sdcard/download/Pic.jpg
Retrieving Files from a Device or Emulator
You can copy files from the device using the pull command, as follows:
adb pull <remote file path on device> <local file path>
For example, to copy the file Lion.jpg to your local hard drive from a device’s SD Card download directory, use the following command:
adb -s HT841LC1977 pull /sdcard/download/Lion.jpg C:Lion.jpg
If you put picture files onto your SD Card—virtual or otherwise—using this method, you might need to force the Android operating system to refresh using the Media Scanner (available in the Dev Tools application on the Emulator).
Installing and Uninstalling Applications
You can use ADB to install and uninstall packages (applications) on a given Android device or emulator. Although the Eclipse plug-in does this for developers automatically, this functionality is useful for developers not using the Eclipse and for those developers and testers who want to create automated build procedures and testing environments. ADB can also be used to install third-party application packages, including those that are self-distributed and not found on application stores such as the Android Market.
All Android applications are installed as packages created with the Android Asset Packaging Tool (aapt). This is the tool used by the Eclipse plug-in as well.
Installing Applications
To install applications, first create an Android package (.apk) file, and then use the install command:
adb install <apk file path>
For example, to install the sample application Snake on the emulator, you can use the following command:
adb -e install C:android-sdksamplesSnakeinSnake.apk
821 KB/s (17656 bytes in 0.021s)
pkg: /data/local/tmp/Snake.apk
Success
Reinstalling Applications
You can use the -r to reinstall the application package without overwriting its data. For example, you can now reinstall the Snake application without losing your data by using the following command:
adb -e install -r C:Snake.apk
Uninstalling Applications
To uninstall an Android application, you need to know the name of its package:
adb uninstall <package>
For example, to uninstall the MyFirstAndroidApp application from the emulator, you can use the following command:
adb -e uninstall com.androidbook.myfirstandroidapp
You might use this command often if you switch between computers and, thus, switch signatures frequently.
Working with LogCat Logging
Android logging information is accessible through the LogCat utility. This utility is integrated into DDMS and Eclipse (using the ADT plug-in), but you can also access it directly from the ADB command line using the following command:
adb logcat <option> <filter>
This type of command is best done from within the adb shell.
Displaying All Log Information
For example, you can display all LogCat logging information from the emulator instance by opening the shell and typing the logcat command:
adb -e shell
# logcat
By default, the logging mode is set to brief. For example, the following is an Informational (I) log message (brief mode) from the debug tag called AppLog from process ID 20054:
I/AppLog(20054): An Informational Log message.
Including Date and Time with Log Data
Another useful mode is the time mode, which includes the date and time the log message was invoked. To change the logging mode, use the -v flag and specify the format. For example, to change to time mode, use the following adb shell command:
# logcat -v time
The resulting log messages are formatted with the date and time, followed by the event severity, tag, process ID, and log message:
01-05 21:52:22.465 I/AppLog(20054): Another Log Message.
Filtering Log Information
All the log information available through the LogCat tool can be overwhelmingly verbose. Most of the time, a filter or two is required to sift out only the messages you want to view. Filters are formatted tags and event priority pairs. The format for each filter is
<Tag Name>:<Lowest Event Priority to Print>
For example, a filter to display Informational log messages (and higher-priority messages including Warnings, Errors, and Fatal messages) from log messages tagged with the string AppLog would look like this:
AppLog:I
You can also use the asterisk (*), which means “all.” So if you use an asterisk on the Tag side of the filter, it means “All tags.” If you put it on the Event Priority side, it’s much like using the V priority—the lowest priority, so all messages display.
Filtering by Event Severity
You can create filters to display only log events of a certain severity. The severity types (from lowest priority or most verbose to highest priority or least verbose) follow:
• Verbose (V)
• Debug (D)
• Info (I)
• Warning (W)
• Error (E)
• Fatal (F)
• Silent (S)
For example, the following shell command displays all Errors and Fatal errors but suppresses warnings, informational messages, debug messages, and verbose messages:
# logcat *:E
In API Level 8, a new type of error was created called a wtf error. These errors are generated using the Log.wtf() method. In this case, wtf supposedly stands for “What a terrible failure.” This log method should be used to report events that should never happen. See the Log class documentation for more details.
Filtering by Tag
You can use multiple filters, ending with a catch-all. Perhaps you want to see all messages from a specific application (a specific tag) and no others. In this case, you want to create a filter to show all messages for a given tag and another filter to suppress all other tags. We also change into time mode, so we get the date and time of the logged events messages. The following shell command displays all AppLog-tagged logging information and suppresses all other tags:
# logcat -v time AppLog:V *:S
This filter is roughly equivalent to this other command line:
# logcat -v time AppLog:* *:S
The resulting log messages are formatted with the date and time, followed by the event severity, tag, process ID, and message:
01-05 21:52:22.465 I/AppLog(20054): Another Log Message.
Clearing the Log
You can clear the emulator log using the -c flag:
adb -e logcat -c
Or, you can clear it from the ADB shell like this:
# logcat -c
Redirecting Log Output to a File
You can redirect log output to a file on the deviceusing the -f flag. For example, to direct all informational logging messages (and those of higher priority) from the emulator to the file mylog.txt in the sdcard directory, you can use the following ADB shell command:
# logcat -f /sdcard/mylog.txt *:I
This file is stored on the emulator or device. You need to pull it onto your desktop either using ADB or the DDMS File Explorer.
Accessing the Secondary Logs
Android has several different logs. By default, you look at the main log. However, an events log and a radio log also exist. You can connect to the other log buffers using the -b flag. For example, to connect to the event log to review events, type
# logcat -b events
The radio log is similarly accessed as follows:
# logcat -b radio
Controlling the Backup Service
Android 2.2 introduced a backup service that applications can use to archive important data in case of a factory reset or lost device. This service normally runs in the background, backing up data and restoring it on its own schedule. However, you can use the bmgr shell tool to prompt the backup service to do its thing, which is helpful for testing backup functionality. You can check to see whether the Backup Manager is enabled using the following ADB shell command:
# bmgr enabled
Backup Manager currently disabled
You can enable the Backup Manager from the ADB shell as follows:
# bmgr enable true
Backup Manager now enabled
The user can enable and disable the Backup Manager on a specific device by navigating to the backup settings, accessed via Settings, Privacy, Backup, and Restore.
Forcing Backup Operations
From the ADB shell, you can schedule a backup using the following command:
# bmgr backup <package>
For example, you can schedule a backup of the SimpleBackup application data as follows:
# bmgr backup com.androidbook.simplebackup
The previous commands only schedule the backup to occur at some point in the future. You can trigger all scheduled backup tasks with the following command:
# bmgr run
Forcing Restore Operations
From the ADB shell, you can force a restore using the following command:
# bmgr restore <package>
For example, you can force a restore of the SimpleBackup application data as follows:
# bmgr restore com.androidbook.simplebackup
Unlike the backup command, the restore command immediately causes a restore operation.
Wiping Archived Data
From the ADB shell, you can wipe archived data for a specific application using the following command:
# bmgr wipe <package>
For example, you wipe out all archived backup data from the SimpleBackup application as follows:
# bmgr wipe com.androidbook.simplebackup
Generating Bug Reports
You can create a rather verbose bug report to attach to application defects using the bugreport command. For example, to print the debug information for the sole emulator instance running on your development machine, use
adb -e bugreport
To print the debug information for the sole phone connected via USB, you issue this command instead:
adb -d bugreport
Using the Shell to Inspect SQLite Databases
You can use the standard sqlite3 database tool from within the ADB shell. This tool enables you to inspect and interact directly with a SQLite database on the emulator. For a thorough explanation of the sqlite3 tool, see Appendix B, “The SQLite Quick-Start Guide.”
Using the Shell to Stress Test Applications
You can use the Exerciser/Monkey tool from within the ADB shell to send random user events to a specific application. Think of it as handing your phone (or emulator) to a monkey (or a baby, or a baby monkey) and letting it push random keys, causing random events on the phone—events that can crash your application if it doesn’t handle them correctly. If your application crashes, the monkey application stops and reports the error, making this a useful tool for quality assurance.
Letting the Monkey Loose on Your Application
To launch the monkey tool, use the following ADB shell command:
# monkey -p <package> <options> <event count>
For example, to have the monkey tool generate five random events in the GroceryList application in the emulator, do the following:
adb -s emulator-5554 shell
# monkey -p com.androidbook.grocerylist 5
Listening to Your Monkey
You can watch each event generated by using the verbose flag -v. For example, to see which events you send to the preceding GroceryList application, use this command:
adb -s emulator-5554 shell
# monkey -p com.androidbook.grocerylist -v 5
Here is the important output from this command:
:SendKey: 21 // KEYCODE_DPAD_LEFT
:Sending Trackball ACTION_MOVE x=-4.0 y=2.0
:Sending Trackball ACTION_UP x=0.0 y=0.0
:SendKey: 82 // KEYCODE_MENU
:SendKey: 22 // KEYCODE_DPAD_RIGHT
:SendKey: 23 // KEYCODE_DPAD_CENTER
:Dropped: keys=0 pointers=0 trackballs=0
// Monkey finished
You can tell from the verbose logging that the monkey application sent five events to the GroceryList application: a navigation event (left), two trackball events, the Menu button, and then two more navigation events (right, center).
Directing Your Monkey’s Actions
You can specify the types of events generated by the monkey application. You basically give weights (percentages) to the different types of events. The event types available are shown in Table A.1.
To use a different mix of events, you need to include the event type’s command-line flag as listed in Table A.1, followed by the desired percentage:
# monkey [<command line flag> <percentage>...] <event count>
For example, to tell the monkey tool to use only touch events, use the following command:
# monkey -p com.androidbook.grocerylist -pct-touch 100 -v 5
Or, let’s say you want just Basic and Major navigation events (50%/50%):
# monkey -p com.androidbook.grocerylist -pct-nav 50 -pct-majornav 50
-v 5
You get the picture.
Training Your Monkey to Repeat His Tricks
For random yet reproducible results, you can use the seed option. The seed feature enables you to modify the events that are produced as part of the event sequence, yet you can rerun sequence in the future (and verify bug fixes, for example). To set a seed, use the -s flag:
# monkey -p <package> -s <seed> -v <event count>
For example, in the command we used previously, we can change the five events by setting a different starting seed. In this case, we set a seed of 555:
# monkey -p com.androidbook.grocerylist -s 555 -v 5
Changing the seed changes the event sequence sent by the monkey, so as part of a stress test, you might want to consider generating random seeds, sending them to the monkey, and logging the results. When the application fails on a given seed, keep that seed (and any other command-line options, such as event type percentages) when you log the bug and rerun the test later to verify the bug fix.
Keeping the Monkey on a Leash
By default, the monkey generates events as rapidly as possible. However, you can slow down this behavior using the throttle option, as follows:
# monkey -throttle <milliseconds> <event count>
For example, to pause for 1 second (1000 milliseconds) between each of the five events issued to the GroceryList application, use the following command:
# monkey -p com.androidbook.grocerylist -v -throttle 1000 5
Learning More About Your Monkey
For more information about the monkey commands, see the Android SDK Reference website at http://d.android.com/guide/developing/tools/monkey.html. You can also get a list of commands by typing monkey without any command options, like this:
adb -e shell monkey
Installing Custom Binaries via the Shell
You can install custom binaries on the emulator or device. For example, if you spend a lot of time working in the shell, you might want to install BusyBox, which is a free and useful set of command-line tools available under the GNU General Public License and has been called “The Swiss Army Knife of Embedded Linux” (thanks, Wikipedia, for that little fact). BusyBox provides a number of helpful and familiar UNIX utilities, all packaged in a single binary—for example, utilities such as find and more. BusyBox provides many useful functions (although some might not apply or be permissible) on Android, such as the following:
[, [[, addgroup, adduser, adjtimex, ar, arp, arping, ash, awk,
basename, bunzip2, bzcat, bzip2, cal, cat, catv, chattr, chgrp,
chmod, chown, chpasswd, chpst, chroot, chrt, chvt, cksum, clear,
cmp, comm, cp, cpio, crond, crontab, cryptpw, cut, date, dc, dd,
deallocvt, delgroup, deluser, df, dhcprelay, diff, dirname, dmesg,
dnsd, dos2unix, du, dumpkmap, dumpleases, echo, ed, egrep, eject,
env, envdir, envuidgid, ether-wake, expand, expr, fakeidentd, false,
fbset, fdflush, fdformat, fdisk, fgrep, find, fold, free, freer-
amdisk, fsck, fsck.minix, ftpget, ftpput, fuser, getopt, getty,
grep, gunzip, gzip, halt, hdparm, head, hexdump, hostid, hostname,
httpd, hwclock, id, ifconfig, ifdown, ifup, inetd, init, insmod,
install, ip, ipaddr, ipcalc, ipcrm, ipcs, iplink, iproute, iprule,
iptunnel, kbd_mode, kill, killall, killall5, klogd, last, length,
less, linux32, linux64, linuxrc, ln, loadfont, loadkmap, logger,
login, logname, logread, losetup, ls, lsattr, lsmod, lzmacat,
makedevs, md5sum, mdev, mesg, microcom, mkdir, mkfifo, mkfs.minix,
mknod, mkswap, mktemp, modprobe, more, mount, mountpoint, mt, mv,
nameif, nc, netstat, nice, nmeter, nohup, nslookup, od, openvt,
passwd, patch, pgrep, pidof, ping, ping6, pipe_progress, pivot_root,
pkill, poweroff, printenv, printf, ps, pscan, pwd, raidautorun,
rdate, readlink, readprofile, realpath, reboot, renice, reset,
resize, rm, rmdir, rmmod, route, rpm, rpm2cpio, run-parts, runlevel,
runsv, runsvdir, rx, sed, seq, setarch, setconsole, setkeycodes,
setlogcons, setsid, setuidgid, sh, sha1sum, slattach, sleep, soft-
limit, sort, split, start-stop-daemon, stat, strings, stty, su,
sulogin, sum, sv, svlogd, swapoff, swapon, switch_root, sync,
sysctl, syslogd, tail, tar, taskset, tcpsvd, tee, telnet, telnetd,
test, tftp, time, top, touch, tr, traceroute, true, tty, ttysize,
udhcpc, udhcpd, udpsvd, umount, uname, uncompress, unexpand, uniq,
unix2dos, unlzma, unzip, uptime, usleep, uudecode, uuencode, vcon-
fig, vi, vlock, watch, watchdog, wc, wget, which, who, whoami,
xargs, yes, zcat, zcip
All you need to do is install the binary (which is available online) using the following steps:
1. Download the BusyBox binary (at your own risk, or compile it for yourself). You can find the binary online at http://benno.id.au/blog/2007/11/14/android-busybox, where Benno has kindly hosted it for you. (Thanks, Benno!)
2. Make a directory called /data/local/busybox/ on your emulator using the ADB shell; for example, adb -e shell mkdir /data/local/busybox/.
3. Copy the BusyBox binary to the directory you created; for example, adb -e push C:usybox /data/local/busybox/busybox.
4. Launch the ADB shell; for example, adb -e shell.
5. Navigate to the BusyBox directory; for example, #cd /data/local/busybox.
6. Change the permissions on the BusyBox file; for example, #chmod 777 busybox.
7. Install BusyBox; for example, #./busybox -install.
8. Export the path for ease of use. Note: You need to reset the PATH for each session; for example, #export PATH=/data/busybox:$PATH.
You can find out more about BusyBox at http://www.busybox.net.