View a markdown version of this page

Installing Device Connect and attaching a device - AWS Device Farm

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.

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:GetRemoteAccessSession on the sessions that you attach. To create and stop a session, you also need actions such as devicefarm:CreateRemoteAccessSession and devicefarm: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 version command must print Android Debug Bridge version 1.0.41, because other adb versions can't connect through the bridge. For more information, see SDK Platform Tools release notes on the Android Developers website.

    Put the platform-tools folder on your PATH, so that adb version works 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=folder. In PowerShell, run $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.sh less install.sh

In PowerShell, run the following commands.

irm https://github.com/aws/device-connect-devicefarm/releases/latest/download/install.ps1 -OutFile install.ps1 notepad 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/vX.Y.Z in each URL instead of releases/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 page on the GitHub website, choose a release. Download SHA256SUMS, 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 on the GnuPG website. On Windows, GnuPG is optional, because the Authenticode signature also proves who signed the file. On Windows without GnuPG, skip the next procedure and go to the Windows tab.

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
  1. Copy the key block above, paste it into a new plain text file, and save the file as release-key.asc in the directory that holds your downloads.

  2. Convert the key to a keyring file. The command prints nothing.

    gpg --dearmor -o release-key.gpg release-key.asc
  3. Check the signature. On macOS and Linux, run the following command. LC_ALL=C makes gpgv print its English messages.

    LC_ALL=C gpgv --keyring ./release-key.gpg SHA256SUMS.sig SHA256SUMS

    The output must contain Good signature from.

    gpgv: Good signature from "Device Connect for AWS Device Farm <aws-devicefarm-support@amazon.com>"

    On Windows, gpgv can print its messages in your language, so check its exit code instead. Run the following commands in PowerShell. The second command must print 0.

    gpgv --keyring ./release-key.gpg SHA256SUMS.sig SHA256SUMS $LASTEXITCODE

    If 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.

macOS
To verify the file on macOS
  1. Compare the file with its line in the list.

    grep ' devicefarm-connect_darwin_universal$' SHA256SUMS | shasum -a 256 -c -

    The output must end with OK.

    devicefarm-connect_darwin_universal: OK

    If not, make sure that the file is in this directory under its original name. If the check still fails, delete the file and download it again.

  2. Print the Apple signature of the file.

    codesign -dv --verbose=4 devicefarm-connect_darwin_universal

    The first Authority= line must be Authority=Developer ID Application: AMZN Mobile LLC (94KV3E626L), and the TeamIdentifier= line must be TeamIdentifier=94KV3E626L.

  3. Check that Apple notarized the file.

    codesign --verify --verbose=2 -R="notarized" --check-notarization devicefarm-connect_darwin_universal

    The output must end with explicit requirement satisfied.

    devicefarm-connect_darwin_universal: explicit requirement satisfied

    If it doesn't, make sure that your Mac is online, and run the command again.

Linux
To check the checksum on Linux
  • Compare the file with its line in the list. For ARM64, use devicefarm-connect_linux_arm64 in the grep pattern.

    grep ' devicefarm-connect_linux_amd64$' SHA256SUMS | LC_ALL=C sha256sum -c -

    The output must end with OK.

    devicefarm-connect_linux_amd64: OK

    If not, make sure that the file is in this directory under its original name. If the check still fails, delete the file and download it again.

Windows
To verify the file on Windows
  1. In PowerShell, print the Authenticode signature of the file.

    Get-AuthenticodeSignature .\devicefarm-connect_windows_amd64.exe | Format-List Status, StatusMessage, SignerCertificate, TimeStamperCertificate

    Check the output for all of the following. If one check fails, stop. Don't run the file.

    • Status is Valid.

    • In the subject of SignerCertificate, O is Amazon Web Services, Inc. and OU is AWS Dev Tools. PowerShell prints the O value in double quotes.

    • TimeStamperCertificate is not empty.

  2. Compare the file with its line in the list.

    $hash = (Get-FileHash .\devicefarm-connect_windows_amd64.exe -Algorithm SHA256).Hash [bool](Select-String -Path SHA256SUMS -Pattern "^$hash devicefarm-connect_windows_amd64\.exe$" -Quiet)

    The output must be True. If the output is False, make sure that both files are in the current folder under their original names. If they are, delete the file and download it again.

Note

You can also build devicefarm-connect from its source code in the aws/device-connect-devicefarm repository on the GitHub website. For build instructions, see README.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.

macOS

In a terminal, create the directory ~/.local/bin, make the file executable, and move it there under the name devicefarm-connect.

mkdir -p ~/.local/bin chmod 755 devicefarm-connect_darwin_universal mv devicefarm-connect_darwin_universal ~/.local/bin/devicefarm-connect

If devicefarm-connect --version doesn't work yet, add the directory to your PATH. Run the following command in the open terminal. For new terminals, also add the same line to your shell profile: ~/.zshrc for zsh, or ~/.bash_profile for bash.

export PATH="$HOME/.local/bin:$PATH"
Linux

In a terminal, create the directory ~/.local/bin, make the file executable, and move it there under the name devicefarm-connect. For ARM64, use devicefarm-connect_linux_arm64.

mkdir -p ~/.local/bin chmod 755 devicefarm-connect_linux_amd64 mv devicefarm-connect_linux_amd64 ~/.local/bin/devicefarm-connect

If devicefarm-connect --version doesn't work yet, add the directory to your PATH. Run the following command in the open terminal. For new terminals, also add the same line to your shell profile: ~/.bashrc for bash, or ~/.zshrc for zsh.

export PATH="$HOME/.local/bin:$PATH"
Windows

In PowerShell, create the folder %USERPROFILE%\.local\bin, and move the file there under the name devicefarm-connect.exe.

New-Item -ItemType Directory -Force "$env:USERPROFILE\.local\bin" | Out-Null Move-Item -Force .\devicefarm-connect_windows_amd64.exe "$env:USERPROFILE\.local\bin\devicefarm-connect.exe"

If devicefarm-connect --version doesn't work yet, add the folder to your PATH one time. The first command saves the folder in the PATH of your user account for new windows. The second command adds it to the open window.

[Environment]::SetEnvironmentVariable('Path', "$env:USERPROFILE\.local\bin;" + [Environment]::GetEnvironmentVariable('Path', 'User'), 'User') $env:Path += ";$env:USERPROFILE\.local\bin"

To replace an older copy, first run devicefarm-connect bridge stop. While the bridge runs, Move-Item fails, and the older copy stays installed.

Run devicefarm-connect from PowerShell or cmd.exe, not from File Explorer.

If Windows shows a SmartScreen notice, see Problems on Windows.

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-session includes 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.

Note

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
  1. 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)
  2. List the devices that adb sees. The attached device appears with its serial.

    adb devices
  3. Run a command on the device. For example, print its Android version.

    adb shell getprop ro.build.version.release

    On 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.

Important

Device Farm bills the remote access session until you stop it. device remove and bridge stop don't stop the session.

To clean up
  1. Detach the device.

    devicefarm-connect device remove
  2. Stop the bridge.

    devicefarm-connect bridge stop
  3. 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: