Debugging Android applications remotely

In this article we will try to setup Android device for remote debugging over the Internet. This will allow you to connect to your development machine from anywhere and debug your android apps on your device as it would be connected to your development machine using USB – run applications from IDE, debug and stop on breakpoints, view log cat output and basically everything that Android Debug Bridge allows.

In short here is what it looks like:

Prerequisites

• Android device with USB debugging enabled. 
• WiFi network.
• Access to WiFi router to setup port forwarding.
• Computer with ADB tool installed and ability to connect Android device with USB cable – we will call it local machine.
• Computer with Android development environment that can be accessed remotely – remote computer
• Minimum version of ADB – 1.0.31

Enabled remote debugging on the Android device with ADB

We are using Android 4.2+ device for reference because additional steps are required to set it up. Devices with earlier versions of Android need to follow the same steps but omit security setup. We will start from the very beginning as if you never had your device connected to development machine. You probably already have some of steps completed so please skip them accordingly.

Enable USB debugging on Android 4.2+ device

On Android 4.2+ devices developer options are hidden by default. To reach USB debugging setting you need to enable it first.

1. Go to Settings
2. Tap on About Phone
3. Now tap of Build number several times until you see a small popup with text You are now a developer.

Now go to Settings -> Developer Options and enable USB debugging. 

Now its time to connect to local computer for the first time. If you are using Android 4.2+ device you need to have ADB version 1.0.31 or greater. This is due security improvements which require you to whitelist all computers on your Android device before they can execute any of ADB commands. When you connecting to local computer using USB cable for the first time your Android 4.2+ device will prompt you if you want to allow connection.

You want to check Always allow from this computer and tap OK. This will place computer RSA public key on your device into /data/misc/adb/adb_keys folder and allow all subsequent connections.

Its important to make sure connection is successful before moving any further.

Type following commands in the shell:

1. adb devices – should show “XXXXXXXXXXXX device”, if you see “XXXXXXXXXXXXXX offline” this might mean that you have not allowed RSA key or have outdated ADB version (use adb version to make use you have at least 1.0.31 and SDK manager to update it).
2. adb shell – should log you in in Android device shell
3. grep ro.build.version.sdk= system/build.prop  – displays SDK version

Successful output should looks like this

Enabling ADB debugging over TCP/IP in local WiFi network

Now its time to enable TCP/IP connection between you local computer and Android device. To set it up you need to know your device IP address. You can get it from your router or from adb shell netcfg command output while device is connected on USB.

1. Keep device connected to USB
2. Execute adb tcpip 5555  – will enable remote debugging on connected USB device
3. Disconnect device from USB
4. Execute adb connect <device-ip-address>:5555 – will connect to your device using WiFi network. It may take 10-15 seconds for Android to start accepting connections so be patient and try a few times if you see unable to connect message.
5. Execute adb devices to check device status – should show <device-ip-address>:5555 device if connection is established successfully. Sometimes it shows offline when device is sleeping, try waking it up and retrying.

Debugging over Internet

Same requirements apply to your remote machine as for local machine – you need to have ADB version 1.0.31 and machine RSA key should be whitelisted on your Android 4.2+ device.

Whitelisting remote machine for ADB debugging on Android 4.2+ device

If your remote machine is not whitelisted on your Android device you can copy over ADB RSA key from the local machine to the remote one.

ADB RSA key is located here:

• Windows – %HOMEPATH%\.android
• Linux – ~/.android

You need to get two files from your local machine and copy them over to you remote machine

• adbkey
• adbkey.pub

Connecting to your device over Internet

1. If adb on your local machine is still connected to device disconnect it with adb disconnect command
2. Setup port forwarding on your router for port 5555. You need to forward all incoming traffic for port 5555 on the same port on your device.
3. Find out your external IP by typing my ip in google – google search for ‘my ip’. If you have domain name linked to your IP you can use it instead.
4. On the remote machine execute adb connect <your-external-ip-address>:5555
5. To make sure it works execute adb devices and look for “<your-external-ip-address>:5555 device”. If you are getting offline status make sure device is not sleeping and that you have setup Android 4.2+ security.
6. Test it out with adb shell

Now you are ready to open IDE on remote machine and start debugging your applications as if you have your Android device connected using USB.