Device Pairing and Wireless Debugging

Device Pairing and Wireless Debugging

中文 · ADB, USB, and Wireless

Wireless Debugging has two independent phases: pairing establishes trust material, while connect establishes a verifiable TLS ADB transport. Pairing success is not connect success, and mDNS discovery is not automatic pairing.

User flow

1. Enable Developer Options and Wireless Debugging on the controlled Android 11+ device.
2. In the QR flow, the controller generates a WIFI:T:ADB QR code. The controlled device scans it through “Pair device with QR code” and advertises a temporary _adb-tls-pairing._tcp service under the requested instance name.
3. The controller matches that service and pairs with the temporary password from the QR code. In the pairing-code flow, the user enters the pairing IP, temporary port, and six-digit code.
4. Use the device's _adb-tls-connect._tcp service or a user-provided connect endpoint to establish the real ADB connection.
5. Only after ADB verification may management begin or scrcpy startup continue.

The pairing and connect ports are different concepts and must not be assumed fixed. Pairing codes and ports expire.

Implementation boundaries

• DevicePairingViewModel and pairing UI own ephemeral QR credentials, manual input, progress, and user feedback.
• The QR code contains only a random service name and temporary pairing password. The UI matches the service published after the controlled device scans it through the shared mDNS monitor, then reuses the pairWithCode() protocol entry point.
• AdbPairingManager.pairWithCode() checks the Android version and calls AdbRuntimeProvider.get().pairWithCode().
• Pairing protocol, key and peer material, and TLS implementation live in the external/dadb runtime. The main app does not duplicate the protocol.
• PairingEndpointMetadataManager stores successful records used by UI and mDNS pairing recognition. Pairing codes are not persisted into long-lived docs or logs.
• AdbConnectionManager.connectMdnsService() resolves a TLS connect service and then creates network Dadb under an mDNS transport identity.

mDNS state

MdnsSessionDiscoveryManager consumes pairing and connect services from the dadb monitor and exposes monitoring, loading, online sessions, and selectable services as a StateFlow. UI expresses interactive consumers through acquire/release instead of maintaining another refresh timer or deduplication cache.

Keep these concepts separate:

• Service name: used for current resolution and user selection.
• Canonical mDNS serial: used for session presence matching and connection-pool identity.
• Resolved host and port: a temporary network endpoint, not session identity.

A pairing service may prompt the user to pair first. Only a connect service can be used for a direct connect attempt.

Failure stages

Stage	Typical evidence	Next step
Discovery	No service, monitor stopped or failed	Check same-network reachability, Wireless Debugging, and monitor lifecycle
Pairing	Unsupported version, endpoint refusal, expired QR code or pairing code	Generate a new QR code, or reopen the pairing-code screen and use the new port and code
TLS connect	Service found but handshake or trust fails	Check peer material, connect service, and endpoint resolution
ADB verify	TLS established but serial or command verification fails	Inspect the ADB connector and runtime diagnostics
scrcpy	ADB management works but remote control does not	Inspect server, sockets, metadata, and decoders

Primary log tags are ADBP for pairing and ADBC for connection and verification. Never log a complete pairing code, private key, or reusable sensitive material.

Regression anchors

• MdnsSessionPresenceTest: service normalization, presence matching, and pairing/connect merging.
• MdnsServiceSelectionTest: selection and pairing-prompt policy.
• DeviceTransportSerialTest: mDNS identity normalization.
• AdbQrPairingTest: QR payload, credential redaction, and exact pairing-service matching.
• Pairing, TLS trust, and Android system prompts still require Android 11+ device testing.