Debugging Android Applications : Eclipse Java Editor (part 4) - Android Debug Bridge, Dalvik Debug Monitor Service

4. Android Debug Bridge (adb)

Android comes with a specialized command-line debug utility called adb. It lets you control a device or emulator from your host, offering the kind of remote terminal or remote shell service that embedded programmers have come to expect when working with their target systems. Invoke the adb client from a command prompt on the host (Start → Run → cmd.exe on Windows, or open a terminal window on Linux or OS X). The client talks to an adb server that runs in background on the host and processes requests. If the server isn’t running when you start the client, it starts the server for you. The server in turn communicates with adb daemons that run on either a device or an emulator. All of this communication is through TCP/IP ports. A single client/server can deal with multiple devices and emulators, but to simplify things for our discussion, we’ll assume there’s only one.

If you just type adb at the command prompt, you get the help information for adb:

Android Debug Bridge version 1.0.20

 -d                            - directs command to the only connected USB device
                                 returns an error if more than one USB device 
                                   is present.
 -e                            - directs command to the only running emulator.
                                 returns an error if more than one emulator 
                                   is running.
 -s <serial number>            - directs command to the USB device or emulator with
                                 the given serial number
 -p <product name or path>     - simple product name like 'sooner', or
                                 a relative/absolute path to a product
                                 out directory like 'out/target/product/sooner'.
                                 If -p is not specified, the ANDROID_PRODUCT_OUT
                                 environment variable is used, which must
                                 be an absolute path.
 devices                       - list all connected devices

device commands:
  adb push <local> <remote>    - copy file/dir to device
  adb pull <remote> <local>    - copy file/dir from device
  adb sync [ <directory> ]     - copy host -> device only if changed
                                 (see 'adb help all')
  adb shell                    - run remote shell interactively
  adb shell <command>          - run remote shell command
  adb emu <command>            - run emulator console command
  adb logcat [ <filter-spec> ] - View device log
  adb forward <local> <remote> - forward socket connections
                                 forward specs are one of:
                                   tcp:<port>
                                   localabstract:<unix domain socket name>
                                   localreserved:<unix domain socket name>
                                   localfilesystem:<unix domain socket name>
                                   dev:<character device name>
                                   jdwp:<process pid> (remote only)
  adb jdwp                     - list PIDs of processes hosting a JDWP transport
  adb install [-l] [-r] <file> - push this package file to the device and install it
                                 ('-l' means forward-lock the app)
                                 ('-r' means reinstall the app, keeping its data)
  adb uninstall [-k] <package> - remove this app package from the device
                                 ('-k' means keep the data and cache directories)
  adb bugreport                - return all information from the device
                                 that should be included in a bug report.

  adb help                     - show this help message
  adb version                  - show version num

DATAOPTS:
 (no option)                   - don't touch the data partition
  -w                           - wipe the data partition
  -d                           - flash the data partition

scripting:
  adb wait-for-device          - block until device is online
  adb start-server             - ensure that there is a server running
  adb kill-server              - kill the server if it is running
  adb get-state                - prints: offline | bootloader | device
  adb get-product              - prints: <product-id>
  adb get-serialno             - prints: <serial-number>
  adb status-window            - continuously print device status for a specified 
                                   device
  adb remount                  - remounts the /system partition on the device 
                                   read-write

networking:
  adb ppp <tty> [parameters]   - Run PPP over USB.
 Note: you should not automatically start a PDP connection.
 <tty> refers to the tty for PPP stream. Eg. dev:/dev/omap_csmi_tty1
 [parameters] - Eg. defaultroute debug dump local notty usepeerdns

adb sync notes: adb sync [ <directory> ]
  <localdir> can be interpreted in several ways:

  - If <directory> is not specified, both /system and /data partitions will be 
      updated.

  - If it is "system" or "data", only the corresponding partition
      is updated.

					  

Here are a few of the more useful adb commands. There is much more information about these and other adb commands in the Android documentation and online.

adb devices

Displays a list of devices and emulators that the adb server knows about. This is a good way to find the TCP/IP port for an emulator or device if you don’t already know it. The port number is also displayed in the title of each emulator at the top of its window. If there’s only one device or emulator running (the normal case, unless you’re debugging a multidevice application), any adb commands you issue automatically go to that target. The -s and -e options are provided for multidevice applications to let you specify a device or emulator.

adb shell

This connects you with a shell running on the target and gives you a # prompt. The shell is a simplified Unix-like shell, so you can use the usual shell commands (ls, cat, rm, ps, etc.) to explore the target and make changes as appropriate. Ctrl-D or exit will get you out of the shell and back to your environment on the host.

sqlite3

[path_to_database]

A particularly useful shell command (you have to get into the shell with adb shell first) for manipulating SQLite database files. You can optionally include the path to the database file you want to manipulate (the MJAndroid database, for example, would be in data/data/com.microjob⁠sinc.mjan⁠droid/databases/MJAndroid).

adb

logcat

[filter_spec]

This is another way of looking at the logcat log on the target. When you run it, it dumps the existing log to your virtual terminal and continues to send additional log entries as they are generated in the running system. The command is normally entered with a trailing &, the Unix parameter for “run this in a separate process,” so that you can go on and use the terminal for other commands (including, eventually, to kill the logcat process). The filter specs are of the form tag:priority, where tag and priority were described in Section 5.2.3. So the command to see all AndroidRuntime log entries of priority E would be:

adb
									logcat AndroidRuntime:E &

This is also useful for reading the “other” logs, of which there are two: radio and events. The radio log is accessed through a command like:

adb -b radio &

Similarly, to read the events log, enter:

adb -b events &

adb install

[-l] [-r] file_spec

This can be used to install or reinstall an application. The -l option forward-locks the installation (preventing the application from being copied later to another device), and the -r option reinstalls the application without overwriting the existing application data. The file_spec must be a valid, signed .apk file for the application to be installed.

adb uninstall

[-k] package

This uninstalls the application with the given package name. The package parameter needs to be the full name of the package, without the “.apk” extension. So to uninstall MicroJobs, for example, you’d type:

adb uninstall com.microjobsinc.mjandroid

If you want to keep the application’s associated data, you include the -k option.

adb push

local remote

This command copies a file from the local name on the host to the remote name on the target.

adb pull

remote local

This is the counterpart to the previous command, and copies a file from the target to the host.

5. DDMS: Dalvik Debug Monitor Service

Installing the Android Software Development Kit adds DDMS to the Eclipse integrated development environment, providing a window-oriented interface to Android-specific debug information on the target. The most frequently used perspectives are displayed in the upper-right corner of the Eclipse window. If there’s a DDMS button there, you can just click on it to switch to DDMS. If not, in that same area there is a little window symbol with a + sign in its upper-right corner. Clicking on this window will open a menu of Perspectives, including DDMS.

The DDMS perspective has four panes by default. Starting from the upper left and going left to right down the screen, these are:

Devices

This lists the available target devices connected to Eclipse, and the processes running on each device. The default emulator device is labeled with its port number (5554). There are also some toolbar buttons in this pane, described later in this section.

Threads/Heap/File Explorer

This provides three different views of what is going on in the target. The Threads tab shows the currently active threads in the selected “client,” which is the application selected in the Devices pane. To see the Threads information, you have to click the “Update Threads” button at the top of the Devices pane. The Heap tab shows the state of the VM’s heap memory, and is updated at each garbage collect. Again, in order to see the Heap information, you need to enable it by clicking the “Update Heap” button at the top of the Devices pane, and you may need to exercise the application for a while until the VM decides a garbage collect is required before the information will be updated. You can also force a garbage collect by clicking on the “Cause GC” button in the Heap view.

Emulator Control

This gives you control of the Telephony and Location emulation functions:

Telephony Emulator

You can simulate voice and data operation in a variety of network states (unregistered, home, roaming, searching, denied) and at a variety of network speeds and latencies. It’s useful to vary these parameters during application testing to be sure that your application responds appropriately in all typical situations. You can also simulate incoming voice and SMS calls from a specific number (to test Caller ID), and create the SMS message to be received.

Location Emulator

Here you can send a specific location fix to the Location Provider by entering a latitude and longitude. You can alternatively load a GPX or KML file of locations to be played back to the Location Provider in a continuous sequence, as though the target was moving around.

Logcat/Console/Outline/Properties

This is similar to the “catchall” pane in the Debug perspective, providing a collection of useful tabs that display the indicated information.

Screen Capture

This isn’t a pane, but one of the toolbar buttons in the Display pane. It looks like a very small Android screen, and when you click it, it captures and displays what is currently showing on the target screen. It gives you the opportunity to save the capture to a PNG file, which you can then use as you would any other image.