Installing Device Connect and attaching a device
With Device Connect for AWS Device Farm, most Android Debug Bridge (adb) workflows need no change. Device Connect runs a bridge in the background. The bridge takes the place of your local adb server.
Cost: Device Farm bills each device minute of the remote access session until you stop it. Device Connect adds
no charge. For more information, see Device Farm
pricing
Topics
Prerequisites
Before you start, make sure that you have the following:
-
An AWS account, and credentials for it on your computer. Device Connect uses the default AWS credential chain, such as environment variables, a named profile, or an IAM Identity Center (SSO) profile. The bridge reads the credentials of the shell that starts it. For more information, see Authentication and access credentials for the AWS CLI.
-
AWS Identity and Access Management (IAM) permissions for Device Farm. Device Connect needs only
devicefarm:GetRemoteAccessSessionon the sessions that you attach. To create and stop a session, you also need actions such asdevicefarm:CreateRemoteAccessSessionanddevicefarm:StopRemoteAccessSession. For more information, see Identity and access management in AWS Device Farm. -
The AWS CLI, to create and stop sessions. For more information, see Installing or updating to the latest version of the AWS CLI.
-
Android SDK Platform-Tools 29.0.0 or later. The
adb versioncommand must printAndroid Debug Bridge version 1.0.41, because other adb versions can't connect through the bridge. For more information, see SDK Platform Tools release noteson the Android Developers website. Put the
platform-toolsfolder on yourPATH, so thatadb versionworks in a new terminal. -
A computer that runs macOS 13 or later, Linux, or Windows 10 or later. For the supported versions and architectures, see Supported operating systems.
Step 1: Install Device Connect
Device Connect is a command-line tool, devicefarm-connect. You can install it in two ways.
The install script downloads the release file for your computer, verifies it, and installs it. Or
you download the release file yourself, and then verify and install it.
Option 1: Install with the script
On macOS or Linux, run the following command in a terminal.
curl -fsSL https://github.com/aws/device-connect-devicefarm/releases/latest/download/install.sh | sh
On Windows, run the following command in PowerShell.
irm https://github.com/aws/device-connect-devicefarm/releases/latest/download/install.ps1 | iex
The script checks the SHA-256 checksum of the release file, the Authenticode signature
on Windows, and the Apple signature and notarization on macOS. With gpg and
gpgv on your computer, the script also checks the signature of the checksum
list. Without them, the script says that it skips this check. If a check fails, the
script installs nothing.
The script needs no administrator rights. It installs devicefarm-connect in
~/.local/bin on macOS and Linux, and in
%USERPROFILE%\.local\bin on Windows. If the folder is not on your
PATH, the script prints how to add it. To use another folder, first set the
DEVICEFARM_CONNECT_INSTALL_DIR environment variable. On macOS and Linux, run
export DEVICEFARM_CONNECT_INSTALL_DIR=. In
PowerShell, run folder$env:DEVICEFARM_CONNECT_INSTALL_DIR =
'.folder'
The script is a plain text file. To read it before you run it, download it first. On macOS or Linux, run the following commands.
curl -fsSLO https://github.com/aws/device-connect-devicefarm/releases/latest/download/install.shless install.sh
In PowerShell, run the following commands.
irm https://github.com/aws/device-connect-devicefarm/releases/latest/download/install.ps1 -OutFile install.ps1notepad install.ps1
After you read the file, run it. On macOS or Linux, run sh install.sh. In
PowerShell, run Get-Content -Raw .\install.ps1 | iex.
To install a specific version, use
releases/download/v in each URL instead of
X.Y.Zreleases/latest/download.
To confirm the installation, run devicefarm-connect --version.
Option 2: Install manually
The following steps do by hand what the install script does for you: download the release file, verify it, and install it.
On the Device Connect
Releases pageSHA256SUMS, SHA256SUMS.sig, and one of the
following files from that release into the same directory. On Linux, uname -m
prints the architecture.
-
macOS, Apple silicon or Intel:
devicefarm-connect_darwin_universal -
Linux, x86-64 (
x86_64):devicefarm-connect_linux_amd64 -
Linux, ARM64 (
aarch64):devicefarm-connect_linux_arm64 -
Windows, x86-64:
devicefarm-connect_windows_amd64.exe
Then verify the files and install the program, as the following sections describe.
Verify your download
SHA256SUMS lists the SHA-256 checksum of every file in the release.
SHA256SUMS.sig is the signature of that list. A good
signature proves that the list comes from Device Farm. A matching checksum proves that your file is on
the list. If a check fails, don't run the file. The list uses the original file names, so do both checks
before you rename the file.
To check the signature, you need GNU Privacy Guard (GnuPG). Most Linux
distributions include it. For macOS and Windows, see GnuPG downloads
Use the following public key to check the signature. Its user ID is Device Connect for AWS
Device Farm <aws-devicefarm-support@amazon.com>.
-----BEGIN PGP PUBLIC KEY BLOCK----- xsFNBGr8hMwBEACQTMhDZ0tuEkysoiZZXcCquLJKlbuVP4rUFKSi4qofc3TlMk2g Q1DjMsSknZhBg+oYFxXWvhbr43WK8TL7sv9LlEAUR4jZzKQqpmCLqMc6uxEX6tuX tuob3N6iEe6ODo1WG5XTvJCuHF6w+2al8pVVpJ+rkPHchTTqr2DM3z4SBBTPzPNG 5YLYtOx4+Ezah73Rk8eDF19WZYa0V6ROlPMkMW1As6mSlXJZ0zdueiICwBee7k1Q wzdFfbGMDws25sMAuXEJDDBKmAsjCUK8l9okBkZryCuJ5y8bApEwWHNNtqCHIZr2 nfLCqu8nvTPpQRa8ls9QF0SULHqeDYuQ3SXZVRnwp0q2LvneV0yz4llEQhhoIMc4 iACJl8lbYzQT5TECbebtV3BaxxPmtQPxbr7pYIwqJJbsuAVuDr6OiggUXI2pNykf RY5Px+dKdaxlZUeZhR7Ws5FZF52McMLwZQbqcOaGb1VyQpT7VgnSrvUUVxRZowOj VKgGJbir4eOtdil0azRtvA15gO5jkFRy0Yx9WpD1h9pwnUxfUR3ywpnCroeiWZ8o 8fHozYyHm/4t8pcwH6Tzuhc9ggBdzdGVyn1Jp4vnMWPfspMJqTR6COOyeosCU+8d vpxc8xtNdbZswirqfkz+pq/h3EqL/c72N8oKRsPJkXjOJi4dkfWbOVgQ8QARAQAB zUZEZXZpY2UgQ29ubmVjdCBmb3IgQVdTIERldmljZSBGYXJtIDxhd3MtZGV2aWNl ZmFybS1zdXBwb3J0QGFtYXpvbi5jb20+wsG+BBMBCgByBYJq/lh5CRAjauf/+g0I bkcUAAAAAAAeACBzYWx0QG5vdGF0aW9ucy5zZXF1b2lhLXBncC5vcmelZsyeD18R C6+TbEYMAOqoWPoQosEmqdc8WWm3sTPW4QKbAxYhBEkslsCDiTyWC6SG3iNq5//6 DQhuAAD/cw/+MTRDSXrUfRl7k2LOcHuezQ8wOLg96+Yr2y/uTlELpsvrRAxmT/Il Y8ma6h9mgy5Xk+VlbrOY9FPD5HN4a3j0IHrCJFX0ruUyUgus6lf+GejNwkXh2/Z/ qwDJDPcOAHLm6f/jvcFxK8DnTEG4ZfkWgXH7Epqok4nAzmdrvDHTnCLDsQj/4gi7 RjSQsD0OdGMr3X9kaGLEvNibwpUUvXcQd2WCerW3OOIWbs+ruW8SyHzYQcWsat6N mAmhVqp0q0HOVDJ0Tr4vXRISXbZ4KpDXbOaIAeHzTauR+RRJehz7ZoWQA+QcT062 r+goT7WI691VCYGlo3UdC8Hkroo4490Hp2RE/pMRbIv7v71lKd60/pQ9IhB1vuI5 16SNtFsFosx1pg88AGW/f6HtAwI2Iowrl2EQqX9Wa5+7R2uArIdT35P0jXFY3mAt p1RStDtSbiKdyOQVwZZ710tEh6gp0C+psSpVtuoTHcnFJXjRDujMZAVxWddCrW8Y J37f5H0FQrbQGJLJxptkJgrggVWVWUbe7DBRqqZLL2AD3q1OTyVD9eby2m0mOAu5 /HVcBBtT85iuSF1Ie+FVcimK4WWODnKuA/yTRsEnw7sjNx7U48EEEfunsmEtncxB Rrqtp8537D/2lxbsri9Zb1p4kHHcQJ6Gs/f3v2sJ2lqdRUpW+39r4L0= =w0bv -----END PGP PUBLIC KEY BLOCK-----
The fingerprint of this key is 492C 96C0 8389 3C96 0BA4 86DE 236A E7FF FA0D 086E. The
release notes list the same fingerprint.
To check the signature of the checksum list
-
Copy the key block above, paste it into a new plain text file, and save the file as
release-key.ascin the directory that holds your downloads. -
Convert the key to a keyring file. The command prints nothing.
gpg --dearmor -o release-key.gpg release-key.asc -
Check the signature. On macOS and Linux, run the following command.
LC_ALL=Cmakesgpgvprint its English messages.LC_ALL=C gpgv --keyring ./release-key.gpg SHA256SUMS.sig SHA256SUMSThe output must contain
Good signature from.gpgv: Good signature from "Device Connect for AWS Device Farm <aws-devicefarm-support@amazon.com>"On Windows,
gpgvcan print its messages in your language, so check its exit code instead. Run the following commands in PowerShell. The second command must print0.gpgv --keyring ./release-key.gpg SHA256SUMS.sig SHA256SUMS$LASTEXITCODEIf PowerShell can't find
gpgv, the exit code proves nothing. Install GnuPG, open a new PowerShell window, and run the commands again.
Then check your file. Choose the tab for your operating system.
You can also build devicefarm-connect from its source code in the aws/device-connect-devicefarmREADME.md in the source code. A rebuild can differ from the release file, so don't use a rebuild to verify a
download.
Install the file
After the checks pass, install the file in .local/bin in your home directory, the
directory that the install script uses. Choose the tab for your operating system.
Then run devicefarm-connect --version to confirm the installation.
Update Device Connect
To update Device Connect to the latest release, run the same install command again. The script replaces the installed file. If you installed the file manually, install the new release file the same way.
A bridge that runs during the update keeps the earlier version. Run
devicefarm-connect doctor. The doctor warns when the bridge runs another version
than the command, and prints the devicefarm-connect bridge start command that
starts the bridge again with the new version. Then attach the device again with
devicefarm-connect device add.
Step 2: Create a remote access session
Device Connect attaches a device through its remote access session. Create a session in the Device Farm console or with the AWS CLI. For the steps, see Creating a session. Choose a device that runs Android 9 or later. For now, Device Connect supports only public devices that use the metered, pay-as-you-go billing method.
You need the Amazon Resource Name (ARN) of the session in the next step. A session ARN contains
:session:. It is not the same as the device ARN.
-
In the console, after the session starts, in the menu on the left-hand side of the device, choose Session ARN. The console copies the ARN. The same menu can also show an ADB session action, which lists the Device Connect commands with the session ARN.
-
With the AWS CLI, the output of
create-remote-access-sessionincludes the session ARN.
Each session leases one device and can last up to 150 minutes. For more information, see Service limits.
Step 3: Attach the device and run adb
After the status of the session is RUNNING, attach its device to Device Connect. In the
commands, replace the session ARN with your session ARN.
Device Connect stops a local adb server that uses port 5037. Your local devices then disappear from adb. To keep them, see Using a different port.
To attach the device and run adb
-
Attach the device. If no bridge runs, this command starts one on port 5037.
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"The last line of the output names the port and the device.
devicefarm-connect listening on port 5037 with connected device: Google Pixel 9 (OS 16) -
List the devices that adb sees. The attached device appears with its serial.
adb devices -
Run a command on the device. For example, print its Android version.
adb shell getprop ro.build.version.releaseOn some devices, the first adb command after you attach can take several seconds.
You can now use adb and tools such as Android Studio with the device. If a step fails, run the following command and follow the fixes that it lists. For more information, see Run the doctor command.
devicefarm-connect doctor --session-arn "arn:aws:devicefarm:us-west-2:111122223333:session:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/c3d4e5f6-7890-12cd-ef01-EXAMPLE33333/00000"
Step 4: Clean up
When you finish, detach the device, stop the bridge, and stop the session.
Device Farm bills the remote access session until you stop it. device remove and
bridge stop don't stop the session.
To clean up
-
Detach the device.
devicefarm-connect device remove -
Stop the bridge.
devicefarm-connect bridge stop -
Stop the session with the AWS CLI, or choose Stop session on the session page in the console.
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
Next steps
Now that you can attach a device, you can do more with Device Connect:
-
To run more adb commands, use Android Studio, forward ports, and switch to another device, see Interacting with devices using adb.
-
To check the bridge and find its log file, see Working with the Device Connect bridge.
-
To fix a problem, see Troubleshooting Device Connect.
-
To keep Device Connect secure, see Infrastructure security for Device Connect.