adbutils

You can intercept and inspect ADB protocol traffic using Charles Proxy by setting up port forwarding. This is useful for debugging the communication between the host and the ADB server.

Setup Steps:

1. In Charles, go to Proxy -> Port Forwarding.
2. Add a rule to map a local TCP port to the remote ADB server port:
   • Local: 5555 (or any available port)
   • Remote: localhost:5037 (the default ADB server port)
3. Execute ADB commands using the specified port via the -P flag:

   adb -P 5555 devices

4. The traffic should now appear in Charles.

You can install adbutils using pip. To include all optional dependencies, use the [all] extra.

pip3 install adbutils

# or
pip3 install adbutils[all]

If you are upgrading from version 1.x to 2.x, note the following breaking changes:

Removed:

• current_app (Use app_current instead)
• package_info (Use app_info instead)

Added:

• volume_up
• volume_down
• volume_mute

You can control the behavior of adbutils and its connection logic using the following environment variables:

• ADBUTILS_ADB_PATH: Path to the adb binary (defaults to searching the system PATH).
• ANDROID_SERIAL: The serial number of the device to connect to.
• ANDROID_ADB_SERVER_HOST: The host address of the ADB server (defaults to 127.0.0.1).
• ANDROID_ADB_SERVER_PORT: The port of the ADB server (defaults to 5037).

Docker Note: If running in a Docker environment, you may need to set ANDROID_ADB_SERVER_HOST=host.docker.internal to reach the host's ADB server.

export ANDROID_ADB_SERVER_HOST=host.docker.internal

To read logcat output programmatically, use d.shell("logcat", stream=True) and iterate over the stream connection.

d.shell("logcat --clear")
stream = d.shell("logcat", stream=True)
with stream:
    f = stream.conn.makefile()
    for _ in range(100): # read 100 lines
        line = f.readline()
        print("Logcat:", line.rstrip())
    f.close()

You can manually control the start and stop of a screen recording using the screenrecord method on a device object.

# Manual control approach
r = d.screenrecord(no_autostart=True)
r.start() # start record
r.stop_and_pull("video.mp4") # stop and pull to local

# Alternative: shell approach
import time
stream = d.shell("screenrecord /sdcard/s.mp4", stream=True)
time.sleep(3) # record for 3 seconds
with stream:
    stream.send(b"\003") # send Ctrl+C
    stream.read_until_close()
d.sync.pull("/sdcard/s.mp4", "s.mp4")

Manage remote connections (equivalent to adb connect and adb disconnect).

from adbutils import adb, AdbTimeout, AdbError

# Connect to a remote device
output = adb.connect("127.0.0.1:5555")

# Connect with a specific timeout
try:
    adb.connect("127.0.0.1:5555", timeout=3.0)
except AdbTimeout as e:
    print(e)

# Disconnect
adb.disconnect("127.0.0.1:5555")

# Disconnect and raise error if device is not present
adb.disconnect("127.0.0.1:5555", raise_error=True)

# Wait for device state
adb.wait_for("127.0.0.1:5555", state="device")      # Wait for online
adb.wait_for("127.0.0.1:5555", state="disconnect") # Wait for disconnect

Use AdbClient to manage connections to the ADB server. You can specify the host, port, and socket_timeout.

By default, you can use the shorthand from adbutils import adb to get a pre-configured client.

import adbutils

# Explicit client configuration
adb = adbutils.AdbClient(host="127.0.0.1", port=5037, socket_timeout=10)

# List all devices with extended info (serial, state, transport_id)
for info in adb.list(extended=True):
    print(info.serial, info.state, info.transport_id)

# List only devices with state='device'
print(adb.device_list())

import adbutils

# Explicit client configuration
adb = adbutils.AdbClient(host="127.0.0.1", port=5037, socket_timeout=10)
for info in adb.list(extended=True):
    print(info.serial, info.state)

# only list state=device
print(adb.device_list())

Retrieve a device instance using adb.device(). You can identify a device by its serial or transport_id.

If only one device is connected, you can call adb.device() without arguments. Note that this will raise a RuntimeError if multiple devices are connected.

from adbutils import adb

# Get device by serial
d = adb.device(serial="33ff22xx")

# Get device by transport_id (found via 'adb devices -l')
d = adb.device(transport_id=24)

# Get the only connected device
d = adb.device()