Android Device Debug

ADB-based debugging for the RIPDPI app on physical devices and emulators. No third-party tools -- uses only adb, Gradle, and existing repo scripts.

Full test stack documentation: docs/testing.md. Do not duplicate it here -- read it when you need runner details, CI lanes, or fixture locations.

Device Discovery & Connection

For local emulator work, first read Local Android emulator pool. Run the full investigation or test command under scripts/ci/android-avd-pool.py. Use its exported ANDROID_SERIAL throughout the lease. The discovery commands below do not grant ownership of an existing device.

adb devices -l                        # list connected devices/emulators
adb wait-for-device                   # block until a device is available

Multi-device disambiguation:

export ANDROID_SERIAL=<serial>        # all subsequent adb commands target this device
adb -s <serial> <command>             # one-off targeting

Build, Install & Launch

Build

# Physical device (ARM)
./gradlew :app:assembleGithubFullDebug -Pripdpi.localNativeAbis=arm64-v8a

# Emulator (x86_64 -- fast path)
./gradlew :app:assembleGithubFullDebug -Pripdpi.localNativeAbis=x86_64

Install

adb install -r app/build/outputs/apk/githubFull/debug/app-github-full-debug.apk

Launch with Automation Extras

Source of truth: app/src/main/kotlin/com/poyka/ripdpi/automation/AutomationLaunchContract.kt

adb shell am start -n com.poyka.ripdpi/.activities.MainActivity \
  --ez com.poyka.ripdpi.automation.ENABLED true \
  --ez com.poyka.ripdpi.automation.RESET_STATE true \
  --ez com.poyka.ripdpi.automation.DISABLE_MOTION true \
  --es com.poyka.ripdpi.automation.START_ROUTE home \
  --es com.poyka.ripdpi.automation.PERMISSION_PRESET granted \
  --es com.poyka.ripdpi.automation.SERVICE_PRESET idle \
  --es com.poyka.ripdpi.automation.DATA_PRESET clean_home

Deep link equivalent:

adb shell am start -a android.intent.action.VIEW \
  -d "ripdpi-debug://automation/launch?enabled=true&reset_state=true&start_route=home"

Automation Preset Values

Extra	Values
PERMISSION_PRESET	granted, notifications_missing, vpn_missing, battery_review
SERVICE_PRESET	idle, connected_proxy, connected_vpn, live
DATA_PRESET	clean_home, settings_ready, diagnostics_demo
START_ROUTE	onboarding, home, config, diagnostics, history, logs, settings, mode_editor, dns_settings, advanced_settings, biometric_prompt, app_customization, about, data_transparency

Route source of truth: app/src/main/kotlin/com/poyka/ripdpi/ui/navigation/Route.kt

Logcat Filtering

Native logcat tags (from Rust source):

Tag	Source
ripdpi-native	Proxy engine + diagnostics (ripdpi-android crate)
ripdpi-tunnel-native	VPN tunnel (ripdpi-tunnel-android crate)

# Native layer only
adb logcat -s ripdpi-native:V ripdpi-tunnel-native:V

# App process only (all tags)
adb logcat --pid=$(adb shell pidof com.poyka.ripdpi)

# Broad filter
adb logcat | grep -i ripdpi

# Crash buffer
adb logcat -b crash -d

# Clear buffer, then reproduce and capture
adb logcat -c
# ... reproduce the issue ...
adb logcat -d > android-logcat.txt

Port Forwarding for Local Network Fixture

The fixture exposes TCP/UDP/TLS echo, DNS responders, DoH, SOCKS5 relay, and fault injection.

# Start fixture on host
bash scripts/ci/start-local-network-fixture.sh

# Forward ports to device
adb reverse tcp:46090 tcp:46090   # control/health
adb reverse tcp:46001 tcp:46001   # TCP echo
adb reverse tcp:46003 tcp:46003   # TLS echo
adb reverse tcp:46053 tcp:46053   # DNS
adb reverse tcp:46054 tcp:46054   # DNS secondary

# Verify
curl -fsS http://127.0.0.1:46090/health
curl -fsS http://127.0.0.1:46090/manifest | jq .
adb reverse --list

Stop: bash scripts/ci/stop-local-network-fixture.sh

For physical devices set RIPDPI_FIXTURE_ANDROID_HOST=127.0.0.1 before starting the fixture.

Instrumented Tests on Device

# Full suite
./gradlew :app:connectedGithubFullDebugAndroidTest -Pripdpi.localNativeAbis=arm64-v8a

# Integration tests only
./gradlew :app:connectedGithubFullDebugAndroidTest -Pripdpi.localNativeAbis=arm64-v8a \
  -Pandroid.testInstrumentationRunnerArguments.package=com.poyka.ripdpi.integration

# E2E tests only
./gradlew :app:connectedGithubFullDebugAndroidTest -Pripdpi.localNativeAbis=arm64-v8a \
  -Pandroid.testInstrumentationRunnerArguments.package=com.poyka.ripdpi.e2e

# Single test class
./gradlew :app:connectedGithubFullDebugAndroidTest -Pripdpi.localNativeAbis=arm64-v8a \
  -Pandroid.testInstrumentationRunnerArguments.class=com.poyka.ripdpi.e2e.NativeTelemetryGoldenSmokeTest

# Maestro smoke flows
bash scripts/ci/run-maestro-smoke.sh

# Coverage report
./gradlew :app:createGithubFullDebugAndroidTestCoverageReport -Pripdpi.localNativeAbis=x86_64

Use -Pripdpi.localNativeAbis=x86_64 for emulator, arm64-v8a for physical device.

Screenshot & Screen Recording

# Screenshot
adb exec-out screencap -p > screenshot.png

# Screen recording (Ctrl+C to stop, max 3 min)
adb shell screenrecord /sdcard/recording.mp4
adb pull /sdcard/recording.mp4 .
adb shell rm /sdcard/recording.mp4

App State Inspection

# Package info (permissions, components, version)
adb shell dumpsys package com.poyka.ripdpi

# Running services
adb shell dumpsys activity services com.poyka.ripdpi

# VPN and network state
adb shell dumpsys connectivity

# DataStore / shared prefs
adb shell run-as com.poyka.ripdpi ls shared_prefs/

# App ops (battery optimization, etc.)
adb shell cmd appops get com.poyka.ripdpi

# Force stop
adb shell am force-stop com.poyka.ripdpi

# Clear all app data
adb shell pm clear com.poyka.ripdpi

Network Debugging

# Check VPN tunnel interface
adb shell ip addr show tun0

# Routing table (all tables -- VPN creates its own)
adb shell ip route show table all

# Listening sockets (proxy port)
adb shell ss -tlnp

# Active reverse forwards
adb reverse --list

# Remove all reverse forwards
adb reverse --remove-all

# DNS resolution
adb shell nslookup example.com

Crash & ANR Debugging

Java/Kotlin Crash

adb logcat -b crash -d
adb shell dumpsys dropbox --print | grep -A 20 data_app_crash

Native Crash (Rust)

# Tombstone summary
adb logcat -s DEBUG:E

# Full tombstone files (may need root)
adb shell ls /data/tombstones/

# Complete bug report
adb bugreport bugreport.zip

Symbolicate with NDK addr2line:

$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/*/bin/llvm-addr2line \
  -e native/rust/target/<triple>/debug/libripdpi.so <address>

Debug .so files with symbols are under native/rust/target/<triple>/debug/. The stripped copies in core/engine/build/generated/jniLibs/ lack symbols.

ANR

# Main thread state
adb shell dumpsys activity processes com.poyka.ripdpi

# ANR traces (may need root)
adb pull /data/anr/traces.txt

Common RIPDPI ANR cause: JNI call blocking the main thread. The proxy jniStart is intentionally blocking -- see the rust-jni skill.

Emulator Management

Read the required API, ABI, and image tag from the current CI or test lane. Use the local pool for repeated tests, screenshots, and UI inspection:

python3 scripts/ci/android-avd-pool.py status
python3 scripts/ci/android-avd-pool.py run \
  --api 37 --arch arm64-v8a --target google_apis --profile pixel_10_pro_xl \
  -- zsh

This example uses the host ARM64 image. Adjust it to the selected lane. Keep all device operations inside the leased shell. A busy pool is a reason to serialize work. Use the documented temporary mode only for a test-specific requirement; the wrapper owns creation, stop, and deletion. Use its cleanup dry run before authorized cleanup. See the pool document for complete lifecycle rules.

Quick Reference

Task	Command
List devices	adb devices -l
Install debug APK	adb install -r app/build/outputs/apk/githubFull/debug/app-github-full-debug.apk
Launch app (clean)	adb shell am start -n com.poyka.ripdpi/.activities.MainActivity --ez com.poyka.ripdpi.automation.ENABLED true --ez com.poyka.ripdpi.automation.RESET_STATE true
Native logs	adb logcat -s ripdpi-native:V ripdpi-tunnel-native:V
Screenshot	adb exec-out screencap -p > screenshot.png
Forward fixture ports	adb reverse tcp:46090 tcp:46090 (repeat for 46001, 46003, 46053, 46054)
Run integration tests	./gradlew :app:connectedGithubFullDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.package=com.poyka.ripdpi.integration
Force stop	adb shell am force-stop com.poyka.ripdpi
VPN interface check	adb shell ip addr show tun0
Crash logs	adb logcat -b crash -d

See Also

• rust-performance -- CPU flamegraphs with simpleperf, HWASan memory debugging, offline symbolication
• network-traffic-debug -- mitmproxy SOCKS5 inspection, tcpdump on TUN, PCAPdroid, log correlation
• rust-jni -- JNI exports, lifecycle rules, and native crash triage