Android Debug Bridge, Adb Intro

What is adb?

The Android Debug Bridge (adb) is a development tool that facilitates communication between an Android device and a personal computer. This communication is most often done over a USB cable, but Wi-Fi connections are also supported. adb can also be used by developers to communicate with a virtual android machine running on the computer.

adb is like a “Swiss-army knife” of Android development. It provides numerous functions that are described in detail by the command: adb --help (see output here). Some of the more commonly used commands are listed in the Popular adb commands section below.

Installing adb & fastboot

Windows, Mac, and Linux

The best way to get adb and fastboot is to install the Android SDK directly from Google. After you install the SDK Tools, launch the SDK Manager and install the Android SDK Platform-tools package. Or alternatively run tools/android update sdk --no-ui. Note that the manager automatically selects the latest Android X.x (API YY) package on launch which you can safely deselect if you are only interested in adb and fastboot. Then, by running the SDK manager periodically to check for updates, you can ensure these tools are always at the latest version.

The adb and fastboot executables will be located in the platform-tools subdirectory of the SDK Tools. You can add this directory to your system’s PATH so that these tools are available from any Command Prompt or Terminal:

• Windows 7/8:
  1. From the desktop, right-click My Computer and select Properties
  2. In the System Properties window, click on the Advanced tab
  3. In the Advanced section, click the Environment Variables button
  4. In the Environment Variables window, highlight the Path variable in the Systems Variable section and click the Edit button
  5. Append ;<path-to-sdk>/platform-tools to the end of the existing Path definition (the semi-colon separates each path entry)

• Linux
  1. Add the following to ~/.profile and then logout/login:

  if [ -d "<path-to-sdk>/platform-tools" ] ; then
  PATH="<path-to-sdk>/platform-tools:$PATH"
fi

• Mac
  1. Add the following to ~/.bash_profile and then logout/login:

  if [ -d "<path-to-sdk>/platform-tools" ] ; then
  export PATH="<path-to-sdk>/platform-tools:$PATH"
fi

Ubuntu

An easy alternative to installing the SDK package as described above exists on Ubuntu and other debian-based Linux distributions. adb and fastboot can be installed via the following commands from the Terminal:

sudo apt-get install android-tools-adb
sudo apt-get install android-tools-fastboot

There is no need to manually edit your system’s Path if this method is used.

Fedora/Centos/RHEL

An easy alternative to installing the SDK package as described above exists on Fedora and other rpm-based Linux distributions. adb and fastboot can be installed via the following command from the Terminal:

sudo yum install android-tools

There is no need to manually edit your system’s Path if this method is used. Note that on Centos/RHEL you need to have the epel repository enabled – see EPEL.

Popular adb commands

Among the most popular among CyanogenMod include the following, which can be typed from a Terminal program on the attached computer:

• adb shell — this command establishes a shell interface for establishing a command-line session with the device. In practical purposes, this allows a person to type “into” their devices, much as one would use a terminal program on Linux or Mac OS X computers. Individual shell commands can be sent to the device by typing adb shell <command_to_be_executed_on_the_device>

• adb push <local> <remote> — this command pushes a local file on the computer to a remote file on the device. You can include the full path to either the local or remote file.

• adb pull <remote> [<local>] — this command will pull a remote file on the device (you can include the path) to either a specified location on the computer or, if no destination is specified, to the current directory where the command was issued.

• adb logcat — this command allows you to view the device log in real time. It is also very useful for discovering and reporting bugs. On newer versions of android, you can add -C (that is, adb logcat -C) to get the text to display in color.

• adb install <file> — this is used to “side-load” apps (in their .apk format) to the device.

There are many more useful commands. Check out the full instruction list here.

Secure USB debugging

In Android 4.2.2 (which corresponds to CyanogenMod 10.1), Google implemented some new security features for using adb. The new “secure debugging” feature requires that you manually approve your computer for an adb connection. This approval must be done on the device, and only after any screen lock has been passed.

To access your device via adb, ensure you are using a recently-updated version of adb, preferably from the latest Android SDK. If you are upgrading adb from a previous version, be sure to restart the daemon: adb kill-server.

The first time you connect your device to a computer via adb, you will receive a prompt on your device to Allow usb debugging?, along with an RSA fingerprint identifying the computer. You can select the Always allow from this computer checkbox if you want the device to remember this computer, in which case you will not be prompted again when connecting your device to that specific computer. This authorization must be done for each computer to which you connect your device.

This authorization prompt only appears while running Android. Recovery does not support authorizing a device, and instead checks whether Android has previously allowed the connection. So, if you see error: device unauthorized while attempting to use adb in recovery, restart to Android and authorize the connection. The next time you start recovery, adb should work.

Building adb

If you are already building CyanogenMod for yourself, you can actually compile adb. In fact, it is built for the host system (in addition to the device) with each full CyanogenMod build. You can find it in the out/host/linux-x86/bin directory, where linux-x86 should be replaced with your system type. If you do not want to build an entire release of CyanogenMod just for an updated adb binary, you can simply run mka adb from the top of your android build tree. After compiling, copy the binary to a directory in your PATH.

Troubleshooting adb

error: device unauthorized

See the Secure USB Debugging section.

“Device not found” errors

Sometimes adb can’t find your device. One solution is to run adb kill-server and then adb start-server as root or Administrator to restart the adb daemon with elevated privileges.

Also, you should make sure that the USB debugging or Android Debug Bridge option (this will vary depending on the version of Android) is checked in the Settings under Developer Options. Check out Doc: developer options if you don’t see it.

If adb still can’t find your device, make sure the USB connection method on the device is set to Camera (PTP) (sometimes called Mass storage mode) and not Media device (MTP). This setting can be accessed by swiping down on the status bar and tapping the Connected as a media device notification.

Once the device is configured correctly, you should be able to run adb devices and see something similar to the following:

$ adb devices
List of devices attached
abc12345        device

If instead of device it is unauthorized, then you need to approve your computer for an adb connection. See Secure USB Debugging.

error: insufficient permissions for device or no permission

On Linux, you need to setup UDEV rules to allow communication via adb. You can either use the entire rules configuration from the UDEV page, or add just those rules relevant to you. If you’re unsure of the vendor, idVendor can be determined with lsusb:

$ lsusb
Bus 002 Device 054: ID 0bb4:0f87 HTC (High Tech Computer Corp.)
...

In this example, 0bb4 is idVendor and 0f87 is idProduct (should you ever need it).

libncurses.so.5 64-bit troubles

Under the 64bit versions of some Ubuntu based distributions (e.g. Linux Mint 14), adb shows the following error:

adb: error while loading shared libraries: libncurses.so.5: cannot open shared object file: No such file or directory

You can remedy this by installing the i386 version of libncurses5. From a terminal, type:

sudo apt-get install libncurses5:i386

error: protocol fault

Your version of adb is too old, download a more recent version.

See also

• Android Debug Bridge by Google