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. Choose “Pair device with pairing code” and obtain the pairing IP, temporary port, and code.
3. Submit all three in the controller and wait for explicit pairing success or failure.
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 input, progress, and user feedback.
• 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 code	Reopen the device pairing screen and use the new pairing 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.
• Pairing, TLS trust, and Android system prompts still require Android 11+ device testing.