Skip to content

Quickstart

This guide walks you through the core workflow: connect to a device, run commands, interact with the UI, and use gestures.

Connect to a Device

import asyncio
from adbflow import ADB

async def main():
    adb = ADB()

    # Auto-detect the first connected device
    device = await adb.device_async()
    print(f"Connected to {device.serial}")

    # Or specify a serial
    device = await adb.device_async(serial="emulator-5554")

    # Connect over TCP/IP
    device = await adb.connect_async("192.168.1.100", port=5555)

asyncio.run(main())

Run Shell Commands

async def shell_example(device):
    # Simple command — returns stdout as string
    model = await device.shell_async("getprop ro.product.model")
    print(f"Model: {model}")

    # Full result with exit code and stderr
    result = await device.shell_result_async("ls /sdcard/")
    print(f"Exit code: {result.exit_code}")
    print(f"Output: {result.stdout}")

Device Info

async def info_example(device):
    model = await device.info.model_async()
    version = await device.info.android_version_async()
    sdk = await device.info.sdk_level_async()
    battery = await device.info.battery_async()
    screen = await device.info.screen_size_async()

    print(f"{model} — Android {version} (SDK {sdk})")
    print(f"Battery: {battery.level}%")
    print(f"Screen: {screen.width}x{screen.height}")

UI Automation

from adbflow.ui import Selector

async def ui_example(device):
    # Find an element by text
    element = await device.ui.find_async(
        Selector().text("Settings")
    )
    if element:
        await element.tap_async()

    # Find by resource ID
    button = await device.ui.find_async(
        Selector().resource_id("com.example:id/submit").clickable()
    )

    # Wait for an element to appear
    element = await device.ui.wait_for_async(
        Selector().text("Welcome"),
        timeout=10.0
    )
    await element.tap_async()

    # Type text into a focused field
    search = await device.ui.find_async(
        Selector().resource_id("com.example:id/search")
    )
    await search.tap_async()
    await search.text_input_async("hello world")

Gestures

from adbflow.utils.types import SwipeDirection
from adbflow.utils.geometry import Point

async def gesture_example(device):
    # Tap at coordinates
    await device.gestures.tap_async(500, 1000)

    # Tap a Point
    await device.gestures.tap_async(Point(500, 1000))

    # Swipe up
    await device.gestures.swipe_direction_async(SwipeDirection.UP)

    # Long press
    await device.gestures.long_tap_async(Point(500, 1000), duration_ms=2000)

    # Type text
    await device.gestures.text_async("hello")

    # Press keys
    from adbflow.utils.types import KeyCode
    await device.gestures.key_async(KeyCode.HOME)
    await device.gestures.key_async(KeyCode.BACK)

App Management

async def app_example(device):
    # Install an APK
    await device.apps.install_async("/path/to/app.apk")

    # Launch an app
    await device.apps.start_async("com.example.myapp")

    # Check current foreground app
    current = await device.apps.current_async()
    print(f"Foreground: {current}")

    # Stop an app
    await device.apps.stop_async("com.example.myapp")

    # List installed packages
    packages = await device.apps.list_async()

Screenshots

async def screenshot_example(device):
    # Get raw PNG bytes
    png = await device.screenshot_async()

    # Save to file
    await device.media.screenshot.capture_to_file_async("screen.png")

    # Get as PIL Image
    image = await device.media.screenshot.capture_pil_async()

Sync Wrappers

Every _async method has a sync wrapper for scripts that don't need asyncio:

from adbflow import ADB

adb = ADB()
device = adb.device()
output = device.shell("getprop ro.product.model")
print(output)

Next Steps