ADB USB and Wireless

ADB, USB, and Wireless

中文 · Integration Guide

This page defines the common model and transport-specific boundaries for TCP, USB, and mDNS connections. A connection-pool identity represents one ADB transport, not a globally unique physical device.

Capability layers

• ADB provides authentication, transports, shell, files, forwarding, and device queries.
• Management features can work once ADB is available.
• Remote control additionally needs the scrcpy server, ordered sockets, metadata, decoders, rendering, and control.
• Therefore management availability does not prove that the remote path is complete, and a remote media failure does not automatically prove that the ADB transport failed.

Transports and identity

ConnectionTransport currently has TCP, USB, and MDNS. ConnectionCandidate.deviceIdentifier() produces:

• usb:<serial>
• tcp:<normalized-host>:<port>
• mdns:<canonical-device-serial>

An mDNS session retains service information for resolution, but runtime identity is normalized to the device serial through DeviceTransportSerial.mdnsDeviceSerial(). A resolved ip:port is only the current endpoint and does not replace mDNS identity. Business code must not automatically merge USB, TCP, and mDNS into one physical-device identity.

TCP and TLS

A TCP candidate consists of host and port. The connector builds a dadb runtime connection and verifies its serial. Whether it is TLS comes from the actual Dadb connection, not a fixed port or a speculative transport enum. An mDNS connect service ultimately resolves to a network endpoint while the connection pool retains the mDNS transport identity.

USB Host

The USB path is: scan ADB interfaces → request permission → refresh the authorized UsbDevice → create a dadb USB transport → verify → register the usb:<serial> connection. Permission has an explicit timeout, and scan results include unauthorized candidates so the UI can present them.

Physical detach is a hard transport signal. AdbConnectionManager observes ACTION_USB_DEVICE_DETACHED and, after matching the active USB connection:

1. Marks the transport disconnected.
2. Removes and closes it in the registry.
3. Publishes UsbDeviceDisconnected and ConnectionLost with the device id.

Heartbeat is a fallback and must not override or delay detach cleanup. USB recovery must reacquire a valid system device object and permission state instead of applying network-endpoint assumptions.

Wireless Debugging and mDNS

Wireless Debugging has separate pairing and connect phases. The mDNS monitor observes both TLS pairing and connect services and supplies presence and selection state for saved mDNS sessions. Monitoring starts for tracked sessions or interactive consumers and may pause during a connected game session to reduce unrelated work.

mDNS is not automatic pairing. A pairing service may trigger a pairing prompt; a connect service can create a TLS ADB connection only when trust material is valid. See Device Pairing and Wireless Debugging.

Troubleshooting split

Symptom	Check first
USB absent or unauthorized	ADB-interface scan, permission receiver, post-permission device refresh
Still online after unplug	Detach matching, registry removal, disconnect events
Pairing failure	Pairing endpoint, code lifetime, Android version, dadb runtime
Pairing succeeds but connect fails	Connect service/port, TLS trust material, ADB verification
Management works but remote control fails	Server, socket order, metadata, and decoder
Both remote control and management fail	ADB registry, transport health, and reconstruction

Regression anchors

• DeviceTransportSerialTest and ConnectionCandidatePolicyTest: identity normalization and candidate policy.
• SessionDataEndpointTest and SessionDialogStateConnectionCandidatesTest: persistence and UI endpoint conversion.
• MdnsSessionPresenceTest and MdnsServiceSelectionTest: discovery, presence, and selection.
• USB permission and physical detach still require device acceptance testing.