Interacting with devices using adb
With Device Connect for AWS Device Farm, you use the Android Debug Bridge (adb) with an attached device as you use a local device. During the remote access session, you can run as many adb commands as you want, from any adb client on your computer. For example, you can install your app from Android Studio, then run a shell script that copies test files to the device. A session can last up to 150 minutes. For more information, see Service limits.
While a device is attached, the bridge keeps the session active between commands. The session can still end if your computer loses its network connection for about 5 minutes, or sleeps for a long time.
Before you start, attach a device. For instructions, see Step 3: Attach the device and run adb. In the examples, replace each session ARN with your session ARN.
Topics
Running adb commands
You run adb as usual, with no extra options. The bridge handles a few requests on your computer,
such as adb devices and adb version. It sends the other requests, such as
adb shell, adb install, adb push, and
adb pull, to the device.
On some devices, the first adb command after you attach the device can take several seconds while the device warms up.
To run one shell command, pass it to adb shell. For example, the following command
prints the Android version of the device:
adb shell getprop ro.build.version.release
To open an interactive shell, run adb shell with no command.
To install an app, run adb install with the path to the APK file. adb prints
Success when the install is complete. To remove the app, run adb uninstall
with its package name.
adb install -rapp-debug.apkadb uninstallcom.example.myapp
To copy files, use adb push and adb pull. For example, the following
commands copy a file to the device, copy it back, and then delete it from the device:
adb pushnotes.txt/data/local/tmp/notes.txtadb pull /data/local/tmp/notes.txtreceived.txtadb shell rm /data/local/tmp/notes.txt
To read the device log, run adb logcat. To stop the log stream, press Ctrl+C.
adb logcat
Because the bridge holds one device, adb commands need no device option. You can also use the device options of a local adb server:
-
-schooses the device with that serial.serial -
The
ANDROID_SERIALenvironment variable works the same as-s, for exampleANDROID_SERIAL=R3CN30ABCDE adb shell getprop ro.build.version.release. In PowerShell, run$env:ANDROID_SERIAL = 'R3CN30ABCDE'before the adb command. The value stays set in that window until you runRemove-Item Env:ANDROID_SERIAL. If the variable holds another serial, adb printsdevice '. Unset the variable when you don't need it.serial' not found -
-tchooses the device with thatidtransport_idinadb devices -l.
Each open shell, log stream, and forwarded connection counts toward the limit of 24 open adb connections for the device. For more information, see Device Connect limits.
Device Farm refuses some adb commands, such as adb root, adb
remount, and adb tcpip. adb then prints the reason and exits with a nonzero
code. A refusal ends only that command, and the device stays attached. For more information, see Supported adb commands.
Using Android Studio
Android Studio uses the adb server on port 5037. The bridge listens on the same port, so Android Studio can connect to the attached device through the bridge.
The adb that Android Studio uses must be version 1.0.41. An adb with another version can't connect through the bridge, so every command fails.
To update that adb, update Android SDK Platform-Tools in the SDK Manager of Android
Studio. To check the version of the adb on your PATH and of the adb that Android Studio
uses, run devicefarm-connect doctor with --session-arn. For more information, see Run the doctor command.
To use Android Studio with an attached device
-
Quit Android Studio.
-
Start the bridge. If the adb server that Android Studio started still holds port 5037, the bridge stops that server first.
devicefarm-connect bridge start -
Attach the device.
devicefarm-connect device add --session-arn "arn:aws:devicefarm:us-west-2:111122223333:session:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/c3d4e5f6-7890-12cd-ef01-EXAMPLE33333/00000" -
Open Android Studio. Android Studio uses the bridge as its adb server on port 5037.
If Android Studio takes port 5037 back, quit Android Studio. Then run devicefarm-connect bridge
start again, and open Android Studio. For more information, see Local devices disappear, or Android Studio takes port 5037 back.
Viewing the device screen while you use Android Studio
Device mirroring in Android Studio doesn't work with Device Connect. The Running Devices window can't show the screen of the attached device.
We recommend that you use the pop-out window of the remote access session instead. It shows the device screen and the menu of actions in a separate browser window.
To pop out the device screen
-
Open the remote access session in the Device Farm console.
-
In the menu on the left-hand side of the device, choose Pop out.
-
Place the pop-out window next to Android Studio. In some browsers, such as Google Chrome and Microsoft Edge, the window stays on top of other windows.
-
To move the device screen back, choose Return to page, or close the pop-out window.
Keep the session page open. If you close it, the pop-out window closes. Some actions work only on the session page. For the details, see Popping out the device screen.
Forwarding ports
With adb forward, a program on your computer can reach a port on the device. For
example, a test that runs on your computer can call a server that your app runs on the device.
A forward rule connects a tcp: on your computer to a
porttcp: on the device. At this time, both ends must be TCP
ports. For more information, see Supported port forwarding.port
To forward a local port to the device
-
Add the rule. The following command forwards local port 18080 to port 18082 on the device.
adb forward tcp:18080tcp:18082 -
List the rules. adb shows the rule with the serial of the device.
adb forward --list -
Connect your program to
127.0.0.1:18080. For example, runcurl 127.0.0.1:18080. The bridge carries the connection to port 18082 on the device. -
When you finish, remove the rule.
adb forward --remove tcp:18080
adb forward --remove-all removes every rule.
Forward rules end when you detach the device or stop the bridge. For more information, see Detaching the device and stopping the bridge.
Reaching your computer from the device with adb reverse
With adb reverse, the device can open connections to a port on your computer. For
example, an app on the device can call a development server that runs on your computer. adb reverse is off
by default. To turn it on, start the bridge with --allow-adb-reverse.
--allow-adb-reverse lets the device open connections to this machine, so use it only with
a device you trust; a public device can run software you do not control.
When adb reverse is off, adb prints an error that starts with adb reverse is off for this
bridge. bridge start restarts a running bridge with the
options you give. The restart detaches the device and removes every forward rule.
To turn on adb reverse and add a rule
-
Start the bridge with adb reverse on.
devicefarm-connect bridge start --allow-adb-reverse -
Attach the device.
devicefarm-connect device add --session-arn "arn:aws:devicefarm:us-west-2:111122223333:session:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/c3d4e5f6-7890-12cd-ef01-EXAMPLE33333/00000" -
If you use forward rules, add them again.
-
Add a reverse rule. The following command lets the device reach port 18083 on your computer through port 18082 on the device.
adb reverse tcp:18082tcp:18083 -
List the reverse rules of the device. adb lists the rule that you added.
adb reverse --list
When you add a reverse rule, use tcp: on both ends, and keep the device port outside
5555 to 5585. Device Farm refuses a reverse rule to a socket on the device, such as a
localabstract: socket. For more information, see Refused commands.
After you attach a device with adb reverse on, the first reverse command can wait a few seconds.
Add your reverse rules again each time you attach the device.
When you no longer need adb reverse, run devicefarm-connect bridge start without
--allow-adb-reverse. The restart turns it off.
Switching to another device
The bridge holds the device of one remote access session at a time. To use another device, detach the attached device. Then attach the new device.
To switch to another device
-
Create a remote access session for the other device. For instructions, see Step 2: Create a remote access session.
-
Detach the attached device.
devicefarm-connect device remove -
Attach the device of the other session.
devicefarm-connect device add --session-arn "arn:aws:devicefarm:us-west-2:111122223333:session:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/d4e5f6a7-8901-23de-f012-EXAMPLE44444/00000" -
If you no longer need the first session, stop it with its own ARN. Device Farm bills a session until you stop it. This command doesn't change the attached device.
aws devicefarm stop-remote-access-session --arn "arn:aws:devicefarm:us-west-2:111122223333:session:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/c3d4e5f6-7890-12cd-ef01-EXAMPLE33333/00000" --region us-west-2
If a device is attached and you run device add with another session, the command
fails and prints the following:
devicefarm-connect: error: could not attach the device
cause: a different device is already attached (Google Pixel 9 (OS 16))
fix: Remove that device with 'devicefarm-connect device remove', then run 'devicefarm-connect device add --session-arn arn:aws:devicefarm:us-west-2:111122223333:session:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/d4e5f6a7-8901-23de-f012-EXAMPLE44444/00000' again.
Using a different port
By default, the bridge listens on port 5037, the default port of adb. Use a different port when another program must keep port 5037. For example, you can keep the local adb server on port 5037 for your USB devices.
To use a different port
-
Start the bridge on the new port. This restarts any running bridge and detaches its device.
devicefarm-connect bridge start --port5038 -
Attach the device.
devicefarm-connect device add --session-arn "arn:aws:devicefarm:us-west-2:111122223333:session:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/c3d4e5f6-7890-12cd-ef01-EXAMPLE33333/00000" -
Run adb with
-Pand the same port.adb -P5038devicesadb lists the attached device.
Pass -P with the port on every adb command. To check the port, run
devicefarm-connect doctor --port 5038.
Detaching the device and stopping the bridge
When you finish, detach the device with devicefarm-connect device remove, and stop the
bridge with devicefarm-connect bridge stop. For the steps, including how to stop
the session, see Step 4: Clean up.
Device Farm bills the remote access session until you stop it. device remove and
bridge stop don't stop the session.
The following list shows what each command removes:
-
devicefarm-connect device removecloses the forward rules and open adb connections of the device. With adb reverse on, it also removes the reverse rules. The bridge keeps listening. -
devicefarm-connect bridge stopdetaches the device, and closes every connection and forward rule. Reverse rules stop working.