Wireless ADB: Debug Your Android Device Without a Cable

You need to clear an app’s data. The app you’re testing has stale state from a previous test run, and the fastest way to reset it is pm clear com.example.app. Five seconds. One command. Except you need ADB to run it.

So you find the USB cable. You plug the phone into your laptop. You wait for the device to appear in adb devices. You open a terminal. You type adb shell pm clear com.example.app. Five-second command, 90-second setup. You unplug, put the laptop away, pick the phone back up, and try to remember where you were in the test flow.

Maybe you’ve heard that Android 11 introduced wireless debugging. No cable required. You turn it on in Developer Options, and the device shows a pairing code and an IP address. But to use it, you still need a computer: open a terminal, type adb pair 192.168.1.42:39587 123456, wait for the pairing confirmation, then adb connect 192.168.1.42:5555. You’ve replaced the USB cable with a Wi-Fi connection, but you haven’t replaced the laptop. The computer is still in the loop, and the context switch is still there.

What if the pairing happened on the phone itself? What if the device running ADB commands and the device being debugged were the same device — no laptop, no cable, no second screen? Test Nexus implements the exact same pairing protocol that adb pair uses on your computer, but runs it directly on the Android device. You enter a 6-digit code, tap Connect, and start running commands. The computer is removed from the equation entirely.

How It Works: Pairing in 30 Seconds

From the user’s perspective, pairing is a four-step process that takes less than 30 seconds:

1. Enable Wireless Debugging. Open Settings > Developer Options > Wireless debugging and toggle it on. Your device shows a pairing code (6 digits) and an IP address with a port number.

2. Open Test Nexus. Navigate to Terminal and select ADB connection. Enter the 6-digit pairing code and the IP:port displayed on your device.

3. Tap Pair. Test Nexus connects to the pairing service, exchanges credentials, and stores the device’s identity for future connections.

4. You’re connected. Start running commands immediately. Next time, reconnecting is a single tap — no pairing code needed.

That’s it. The pairing flow is a one-time setup. Once the device is paired, reconnection is automatic: tap the saved device, wait for the connection handshake, and you’re in a shell.

What Happens Under the Hood

If you’re curious about the protocol (and if you’re reading a blog post about ADB internals, you probably are), here’s what Test Nexus does when you tap Pair:

Your Phone (Test Nexus)              Your Phone (ADB Daemon)
──────────────────────               ──────────────────────
1. TLS 1.3 connection                ←→  TLS handshake (Conscrypt)
2. SPAKE2 with 6-digit code          ←→  SPAKE2 verification
3. Derive AES-128-GCM key (HKDF)     ←→  Derive same key
4. Exchange RSA-2048 keys (encrypted) ←→  Store authorized key
5. Done — future connections skip pairing

Step 1: TLS connection. Test Nexus connects to the pairing port over TLS 1.3 using the Conscrypt provider. This establishes an encrypted channel before any credentials are exchanged.

Step 2: SPAKE2 key exchange. The 6-digit pairing code you entered is combined with TLS exported keying material to create a 70-byte password. Both sides run the SPAKE2 protocol — a password-authenticated key exchange that proves both parties know the code without ever transmitting it. If the code is wrong, the exchange fails. No brute-force opportunity exists because the pairing code is only valid for the current session.

Step 3: Key derivation. Both sides derive a shared secret from the SPAKE2 output, then use HKDF-SHA256 to produce an AES-128-GCM encryption key. This key encrypts the next step.

Step 4: RSA key exchange. Test Nexus sends its RSA-2048 public key to the ADB daemon, encrypted with the derived AES-128-GCM key, inside an 8192-byte peer info structure. The daemon stores this key as an authorized debugging key. Future connections authenticate with RSA signatures instead of repeating the pairing flow.

Step 5: TOFU. On the first successful pairing, Test Nexus captures the SHA-256 fingerprint of the device’s TLS certificate. Every subsequent connection verifies this fingerprint. If the certificate changes unexpectedly, Test Nexus raises a security warning — the same Trust On First Use model that SSH uses for host key verification.

After pairing, the actual ADB connection works over TLS with STLS upgrade (ALPN protocol “adb”), RSA-2048 authentication, and full stream multiplexing for concurrent command execution.

What You Can Do

ADB commands give you direct access to the Android system layer — package management, activity control, device settings, and system diagnostics. Here are the commands you’ll actually use during testing, organized by category:

Package Management

pm clear com.example.app              # Reset app data (fastest way to start fresh)
pm list packages -3                    # List all third-party installed apps
pm install /sdcard/Download/app.apk    # Install an APK from the device
pm uninstall com.example.app           # Remove an app completely

pm clear alone justifies wireless ADB for most QA workflows. Instead of manually navigating to Settings > Apps > [App] > Storage > Clear Data, you run one command. When you’re testing the same app 20 times in a session, those saved taps compound.

Activity Management

am start -n com.example.app/.MainActivity          # Launch a specific activity
am force-stop com.example.app                      # Kill the app immediately
am broadcast -a android.intent.action.AIRPLANE_MODE  # Simulate system broadcasts

Force-stopping and relaunching lets you test cold start behavior without waiting for Android to reclaim the process naturally. Useful for verifying that your app restores state correctly after being killed.

Device Settings

settings put global airplane_mode_on 1        # Enable airplane mode
settings get secure android_id                 # Read the device's Android ID
settings list system                           # List all system settings

System Information

getprop ro.build.version.release     # Android version
getprop ro.product.model             # Device model
dumpsys battery                      # Battery status and health
top -n 1                             # One snapshot of running processes
df                                   # Disk usage

Logcat

logcat -d -s "MyAppTag"              # Dump logs filtered by tag
logcat -t 100                        # Last 100 log lines
logcat -d | grep "FATAL"             # Search for crash markers

Logcat over ADB is particularly useful when combined with Deep Inspector. Run logcat -d -s "YourTag" to see your app’s debug output, while Deep Inspector captures any crashes in the background. Two monitoring approaches, complementary data.

Script Runner: Automate Command Sequences

When you find yourself running the same sequence of commands repeatedly — clear app data, grant permissions, launch a specific activity, check the result — Script Runner lets you save that sequence and execute it with one tap.

Example: Test Session Setup Script

pm clear com.example.app
pm grant com.example.app android.permission.ACCESS_FINE_LOCATION
pm grant com.example.app android.permission.CAMERA
am start -n com.example.app/.onboarding.OnboardingActivity

Save this as “Reset & Launch Onboarding” and run it at the beginning of every test session. Four commands, one tap, consistent starting state every time.

Variable Placeholders

Scripts support ${VAR_NAME} placeholders that prompt you for values at execution time:

pm clear ${PACKAGE_NAME}
am start -n ${PACKAGE_NAME}/${ACTIVITY}

One script template works for any app — enter the package name and activity when you run it.

Execution Modes

• Stop on first failure: If pm clear fails (maybe the package name is wrong), the script halts immediately. Useful for setup scripts where each command depends on the previous one.
• Continue on error: If one command fails, the rest still execute. Useful for cleanup scripts where you want to delete as much as possible even if some commands fail.

Script Runner tracks per-command timing and execution progress, so you can see exactly which commands succeeded, which failed, and how long each took. You can cancel mid-execution if something looks wrong.

What Script Runner Is Not

Script Runner executes saved command sequences — it’s not a bash interpreter with control flow. There’s no if/else, no for loops, no pipes between commands. Each line is sent to ADB individually and executed in order. For complex automation with branching logic, use the SSH terminal to connect to a server where you can run full shell scripts, or use the local terminal for on-device scripting with a proper shell.

What ADB Terminal Is (and Isn’t)

This is important to be upfront about. ADB over wireless is a line-by-line command adapter optimized for quick debugging commands. It is not a full interactive terminal.

What works well over ADB: pm clear, am start, settings put, getprop, dumpsys, logcat -d, ls, cat — commands that produce output and exit. These are the commands you’ll use 95% of the time during testing.

What doesn’t work over ADB: vim, htop, continuous top, or any program that requires a full interactive terminal with cursor positioning and real-time input. ADB shell sends commands line by line and reads output — it doesn’t provide the full pseudo-terminal that interactive programs expect.

When to use which: Need to clear app data, check a setting, or read a log? ADB terminal. Need to SSH into your staging server and run database queries? SSH terminal. Need to run a shell script on the device itself with full bash capabilities? Local shell. All three share the same unified terminal UI in Test Nexus — you switch between them based on what you need.

Security

Wireless debugging means your device is accepting network connections for a privileged service. Test Nexus applies several layers of protection to make sure this is safe:

Trust On First Use (TOFU). The first time you pair with a device, Test Nexus captures the SHA-256 fingerprint of the device’s TLS certificate. Every subsequent connection verifies that the certificate matches. If the fingerprint changes — which could indicate a man-in-the-middle attack or that you’re connecting to a different device — Test Nexus shows a security warning and blocks the connection until you explicitly re-authorize.

Rate limiting. A maximum of 5 failed pairing attempts are allowed per 60-second window. After 5 failures, the device is blocked for 5 minutes. This prevents brute-force attacks against the 6-digit pairing code.

Encrypted storage. All credentials are encrypted at rest. RSA key pairs are stored in EncryptedSharedPreferences. The paired device list (including IP addresses, display names, and certificate fingerprints) is stored in an EncryptedFile. All stored data uses AES-256-GCM encryption.

Device limit. A maximum of 10 paired devices are stored. When you pair an 11th device, the oldest (by last-connected timestamp) is automatically pruned. This limits the credential surface area on any single device.

Paired Device Management

After pairing, Test Nexus saves the device’s connection details:

• Device IP address and port
• Display name and model
• Android version
• Certificate fingerprint (for TOFU verification)
• Last connected timestamp

Reconnecting to a previously paired device is a single tap. Test Nexus authenticates using the stored RSA key pair — no pairing code needed. Connection timeout is 30 seconds; command timeout is 30 seconds. If the device is unreachable (Wi-Fi changed, device asleep, wireless debugging turned off), the connection attempt fails cleanly with an actionable error message.

You can save up to 10 paired devices. If you regularly test on multiple physical devices — a Pixel for stock Android, a Samsung for One UI edge cases, a budget device for performance testing — each device pairs once and stays in your saved list.

Integration With Other Modules

Wireless ADB doesn’t exist in isolation. It connects to the rest of your testing workflow:

Deep Inspector + ADB. Run logcat -d -s "YourTag" to read your app’s debug logs while Deep Inspector monitors for crashes in the background. The ADB command gives you the verbose debug output; Deep Inspector gives you the structured crash capture. Two complementary data streams from the same testing session.

DataHub + ADB. Generate test profiles in DataHub, export to CSV, and reference the data in ADB commands. For example, generate a batch of package names for a multi-app test scenario, then run pm clear on each one via Script Runner.

Terminal unification. ADB, SSH, and Local Shell all live in the same Terminal module. During a single test session, you might clear app data via ADB, verify a transaction on your staging server via SSH, and run a local script via the shell. Same UI, same workflow, different connection types.

Get Started

Requirements:

• Android 11 or later (API level 30+)
• Wi-Fi enabled (both Test Nexus and the target device must be on the same network — in this case, both are the same device, so this is automatic)
• Wireless Debugging enabled in Developer Options

Setup:

1. Enable Developer Options — Settings > About Phone > tap Build Number 7 times
2. Enable Wireless Debugging — Settings > Developer Options > Wireless debugging > On
3. Open Test Nexus > Terminal > ADB
4. Tap “Pair new device” in Wireless Debugging settings to get a pairing code
5. Enter the 6-digit code and IP:port in Test Nexus
6. Tap Pair — credentials are exchanged and stored
7. Start running commands — pm clear, am start, logcat, anything you need

Next time: open Test Nexus > Terminal > tap the saved device > connected. No code needed.

🚀 Debug wirelessly without a computer. Test Nexus handles SPAKE2 pairing, TLS encryption, and device management — so you just enter a 6-digit code and start running commands. Download Test Nexus →

What’s Next

• Post #06 — Terminal SSH/SFTP: SSH, SFTP, and port forwarding for backend verification
• Post #09 — Token System: what’s free, what uses tokens, and how rewarded ads work