AOSP Insider
AOSP Foundations
3 min read

ADB (Android Debug Bridge)

Learn how the Android Debug Bridge connects your host workstation to a physical Android device for logging, shell access, and file transfers.

Once you have successfully compiled AOSP and flashed it onto a device (or launched it in an emulator), you need a way to communicate with it. The Android Debug Bridge (ADB) is the primary command-line tool used by developers to interact with a running Android operating system.

The ADB Architecture

ADB is not a single program; it is a complex client-server architecture consisting of three distinct components:

  1. The Client: The command-line program (adb) running on your Ubuntu host machine. When you type adb shell, you are invoking the client.
  2. The Server: A background process running on your Ubuntu host machine. The server manages the communication between the client and the actual USB connection to the device.
  3. The Daemon (adbd): A background process running natively on the Android device itself. This daemon listens for commands from the host server and executes them directly on the phone.

Essential ADB Commands

Accessing the Shell

  • adb shell: Drops you into a standard Unix shell running natively on the Android device. From here, you can navigate the internal file system (like /system and /data) using standard Linux commands (ls, cd, cat).

File Transfers

  • adb push <local> <remote>: Copies a file from your Ubuntu computer onto the Android device.
  • adb pull <remote> <local>: Copies a file from the Android device back to your Ubuntu computer.
# Push a newly compiled framework binary to the device
adb push out/target/product/coral/system/lib64/libsurfaceflinger.so /system/lib64/

Viewing System Logs

  • adb logcat: Streams the main Android system log to your terminal. This is arguably the most important command in AOSP development. If an app crashes or a framework service fails to start, the exact Java stack trace or native C++ crash tombstone will be printed in logcat.
# Filter logcat to only show fatal errors and crashes
adb logcat *:E

# Clear the logcat buffer completely
adb logcat -c

Elevated Privileges (Root)

By default, the adbd daemon on the phone runs with standard user privileges. It cannot modify files in the read-only /system partition.

However, if you compiled a "userdebug" or "eng" build of AOSP, you can elevate ADB to run as the root user.

  1. adb root: Restarts the adbd daemon on the phone with full root permissions.
  2. adb remount: After achieving root, this command mounts the /system and /vendor partitions as read-write, allowing you to push new framework binaries or modify system properties on the fly without needing to flash the entire OS again.
adb root
adb remount
# The /system partition is now writable!

Port Forwarding

ADB can route network traffic from your host computer directly into the Android device over the USB cable.

# Forward a local port to a remote socket on the device
adb forward tcp:8080 tcp:8080

This is incredibly useful for connecting debuggers (like Android Studio or gdb) to specific processes running on the phone.

Previous Lesson
Build Optimization
Next Lesson
Fastboot