Connecting To Devices

Connecting to Devices — Listing, Selecting, and Waiting on Transports

adb devices is the most-typed adb command. The follow-on traps are real: scripts run before the device is actually online, multi-device shells fail with more than one device/emulator, Linux misses udev rules, and tutorials reference a fictional wait-for-device-online form. This skill encodes the truth set.

When to use this skill

• The user runs adb shell with two devices plugged in and gets error: more than one device/emulator.
• The user reports a device showing as unauthorized, offline, or no permissions in adb devices.
• The user wants a CI script to wait until a device finishes booting before running tests.
• The user copy-pasted adb wait-for-device-online from a blog post and it errors with usage text.
• The user is on Linux and a freshly plugged phone never appears in adb devices.

When NOT to use this skill

• The user wants the high-level architecture / server lifecycle / env vars — use ../../architecture/understanding-adb-architecture/SKILL.md.
• The user wants Wi-Fi / wireless debugging — use ../connecting-over-wifi/SKILL.md.
• The user wants to install or clear app state on the connected device — use ../../apps/installing-and-managing-apps/SKILL.md.

Prerequisites

• Working ADB server (see ../../architecture/understanding-adb-architecture/SKILL.md).
• Device with USB debugging enabled in Settings → System → Developer options. On Android 4.2+ developer options is hidden until "Build number" is tapped seven times in About phone.
• On Linux: ability to write /etc/udev/rules.d/51-android.rules with sudo.
• On Windows: a vendor USB driver (Google USB Driver via SDK Manager for Pixel/Nexus; OEM driver for other manufacturers).

Workflow

• 1. Run adb devices first, every time. It prints one line per attached transport in the form <serial> <state> [details...]. Add -l whenever scripting:

  adb devices -l
  # List of devices attached
  # emulator-5556  device  product:sdk_google_phone_x86_64 model:Android_SDK_built_for_x86_64 device:generic_x86_64 transport_id:1
  # 0a388e93       device  usb:1-1 product:razor model:Nexus_7 device:flo transport_id:2

  -l adds product, model, device, transport_id, and (for USB) the USB bus path.

• 2. Pick the right selector for the situation:

  Flag	Meaning	Fails when
  -s <serial>	Explicit serial. Works for USB serials (0a388e93), emulators (emulator-5554), and TCP devices (192.168.1.42:5555). Overrides $ANDROID_SERIAL.	Serial not connected.
  -d	The single USB device.	Zero or more than one USB device.
  -e	The single TCP/IP device (covers emulators and adb connect-ed phones).	Zero or more than one TCP device.
  -t <transport_id>	Numeric transport ID from adb devices -l. Stable across re-plugs of the same port.	Transport ID not present.

  Note: -t is the transport ID, not a timeout flag. Wrap with shell timeout (or gtimeout on macOS) if the goal is a per-command time limit.

• 3. Filter to "ready" devices in scripts:

  adb devices | awk '$2=="device"{print $1}'

  Single-device shortcuts: adb get-serialno returns the serial, adb get-state returns one of offline | bootloader | device, adb get-devpath returns the USB path. For the full state set, parse adb devices directly.

• 4. Use the canonical wait-for-* form. The variants you may have seen are wrong. From adb help (scripting section), the only valid syntax is:

  wait-for[-TRANSPORT]-STATE
      TRANSPORT ∈ { usb, local, any }            (transport defaults to any)
      STATE     ∈ { device, recovery, rescue, sideload, bootloader, disconnect }

  Common forms:

  Command	Blocks until...
  adb wait-for-device	Any transport, state device. The default — used at the start of CI scripts.
  adb wait-for-usb-device	A USB-attached device reaches state device.
  adb wait-for-local-device	A TCP/IP device (emulator or wireless) reaches state device.
  adb wait-for-bootloader	Device shows up in bootloader (fastboot) state.
  adb wait-for-recovery / wait-for-sideload / wait-for-rescue	Same idea for those modes.
  adb wait-for-disconnect	The currently selected device disconnects (e.g. after adb reboot).

  The doc does NOT define a wait-for-device-online form. wait-for-* only checks the transport, not boot completion — pair it with a sys.boot_completed poll:

  adb wait-for-device
  until [[ "$(adb shell getprop sys.boot_completed | tr -d '\r')" == "1" ]]; do
    sleep 1
  done
  adb shell input keyevent 82   # unlock the AOSP slide-up screen

  Compound flow around a reboot:

  adb shell reboot
  adb wait-for-disconnect
  adb wait-for-device

• 5. Read device states correctly. From the adb page (Query for devices) plus adb help:

  State	Meaning	Recovery
  device	Online, adbd is responsive. Does not imply boot complete — gate on sys.boot_completed.	n/a
  offline	Transport exists but adbd isn't talking. Common after suspend/resume or USB hubs.	adb reconnect offline, then re-plug if needed.
  unauthorized	Host RSA key not yet accepted on-device.	Unlock device, tap Allow on the on-device dialog. Try a different USB cable if no dialog appears (some "charge-only" cables block data).
  recovery	Booted into recovery. Only a small subset of adb works.	n/a
  sideload	OTA sideload mode. Use adb sideload package.zip.	n/a
  bootloader	At the bootloader (fastboot). adb cannot talk; use fastboot.	n/a
  rescue	Rescue Party mode (Android 10+).	n/a
  connecting	Transient TLS handshake state over wireless.	wait.
  no permissions	(Linux only) USB visible but blocked by missing udev rules.	install rules — see step 7.

• 6. Accept the RSA fingerprint dialog on first connect.

  "When you connect a device running Android 4.2.2 (API level 17) or higher, the system shows a dialog asking whether to accept an RSA key that allows debugging through this computer." — developer.android.com/tools/adb Sequence:

  1. adbd sees a new client offering an RSA public key.
  2. The OS pops the "Allow USB debugging?" dialog showing the workstation's key fingerprint.
  3. Until the user taps Allow, adb devices reports unauthorized.
  4. After acceptance, the public key is appended to /data/misc/adb/adb_keys on the device. Tick Always allow from this computer so future connections from the same ~/.android/adbkey skip the prompt.

  Revoke an old workstation's permission via Settings → Developer options → Revoke USB debugging authorizations.

• 7. (Linux) install udev rules so a freshly plugged phone is not stuck at no permissions. Canonical file: /etc/udev/rules.d/51-android.rules. Minimal example (one line per OEM):

  # Google
  SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", MODE="0660", GROUP="plugdev", TAG+="uaccess"
  # Samsung
  SUBSYSTEM=="usb", ATTR{idVendor}=="04e8", MODE="0660", GROUP="plugdev", TAG+="uaccess"

  Apply without reboot:

  sudo udevadm control --reload-rules
  sudo udevadm trigger
  # unplug and re-plug the device

  Most distros also ship a comprehensive android-udev / android-sdk-platform-tools-common package that drops the same file in /lib/udev/rules.d/.

• 8. (Windows) install the vendor USB driver. Pixel / Nexus / generic AOSP devices use the Google USB Driver from SDK Manager → SDK Tools → Google USB Driver (files at android_sdk\extras\google\usb_driver\). Other OEMs require manufacturer drivers from https://developer.android.com/tools/extras/oem-usb. macOS and Linux do not need vendor drivers.

• 9. Multi-device fan-out. ADB has no built-in --all flag. Two patterns:

  # Sequential
  for s in $(adb devices | awk '$2=="device"{print $1}'); do
    adb -s "$s" install -r app.apk
  done
  
  # Parallel (4 jobs at a time)
  adb devices | awk '$2=="device"{print $1}' \
    | xargs -I{} -P 4 adb -s {} install -r app.apk

  For sharded CI runners that each own one phone, lock the server to a single device:

  adb --one-device 0a388e93 start-server