Menu
AWS Device Farm
Developer Guide (API Version 2015-06-23)

Create a Remote Debugging Session in AWS Device Farm

Prerequisites

  1. Complete the steps in Setting Up, which include signing up for an AWS account, creating or using an IAM user in the AWS account, and giving the IAM user permission to access Device Farm.

  2. Download the Device Farm app from one of the following locations:

  3. Install the Device Farm app. On Macintosh, you'll need to drag it into your Applications folder.

    
                        Device Farm - Welcome screen

    On Windows, you'll need to double-click the .exe file to install the app. The installer creates a shortcut on the desktop and one in the Start menu.

    
                        Device Farm - Welcome screen
  4. If you're using Android Studio or ADB, you'll need to replace your copy of ADB with the version that Device Farm currently supports.

Replace Your Copy of ADB

  1. Download the Device Farm-supported version of ADB.

  2. Extract the files from the downloaded .zip file. The MacOS version has one file. The Windows version has three files (adb.exe, AdbWinApi.dll, and AdbWinUsbApi.dll).

  3. If you are using Android Studio, open Android Studio and perform the following steps:

    Replacing ADB for Android Studio

    1. In the Tools menu, choose Android, and then choose Android SDK Manager.

      
                                Open Android Studio and the SDK Manager
    2. Choose the SDK Platforms tab.

      
                                Enter the location of the Android SDK
    3. Navigate to the folder specified in the Android SDK location field. You can do this by copying the folder path into an open File Explorer window.

    4. Open the platform-tools folder.

      
                                Enter the location of the platform-tools folder
    5. If you're on MacOS, make a backup of the original ADB binary in the platform-tools folder and copy the Device Farm-supported one into the platform-tools folder.

      
                                Backup .adb binary: MacOS

      If you're on Windows, make backups of the original adb.exe, AdbWinApi.dll, and AdbWinUsbApi.dll in the platform-tools folder, and copy the Device Farm-supported one into the platform-tools folder.

      
                                Backup ADB files: Windows
  4. If you're accessing devices using ADB from the command line, perform the following steps on Macintosh or Windows:

    Replacing command-line ADB on Macintosh

    1. Open a terminal window and enter which adb.

      
                                Macintosh command-line window showing which adb
                                    command
    2. Copy the location returned by the which command and navigate to it by using File Explorer.

    3. Make a backup of the original ADB library and copy the Device Farm-supported one into the folder.

      
                                Macintosh File Explorer window showing backed-up ADB
                                    files

    Replacing command-line ADB on Windows

    1. Open a command-prompt window and enter where adb.

      
                                Windows command-prompt window showing where adb
                                    command
    2. Copy the location returned by the which command and navigate to it by using File Explorer.

    3. Make backups of the original adb.exe, AdbWinApi.dll, and AdbWinUsbApi.dll, and copy the Device Farm-supported one into the folder.

      
                                Windows File Explorer window showing backed-up ADB
                                    files

Launch the Device Farm App and Start a Remote Debugging Session

  1. Double-click the app desktop shortcut to open it.

  2. Enter your AWS credentials if prompted to do so.

    When you open the app, it looks for stored AWS credentials in two locations:

    • If you have already installed the AWS CLI on your computer, your AWS credentials are stored in your AWS CLI configuration file located at ~/.aws/credentials on Linux and OS X systems or C:\Users\USERNAME\.aws\credentials on Windows systems.

    • Otherwise, the first time you open the app, you'll be prompted to enter your AWS credentials. When you do that, your credentials are stored in the app.

    Note

    We recommend that you create an IAM user with full Device Farm access.

    
                        Device Farm - Enter Credentials screen
  3. (OPTIONAL) If you have an existing Device Farm project, you can choose the project from the Projects drop-down menu. The default project is Remote Debug.

  4. Choose the Start a new session button.

    
                        Device Farm - Start a New Session button
  5. Choose devices for your remote debugging sessions. You can choose multiple devices. Each device will get its own session. You can choose from the list of available devices or search for a device. You can also filter the list by platform or type.

    
                        Device Farm - Start a New Session button
  6. Choose the Start session with n devices button.

    
                        Device Farm - Start a New Session button

Device Farm will start the session as soon as the requested device is available, typically within a few minutes. The requested device appears in the Pending Sessions list until the session starts.

To determine the status of a pending session, hover over the session entry in the Pending Sessions list. Pending session status can be:

  • Scheduling - Device Farm is scheduling a session

  • Pending - the session is pending

  • Preparing - Device Farm is getting the device ready

  • Waiting for available device - waiting for a device to become available


                Device Farm - Start a New Session button

To cancel the session request, choose Cancel request.


                Device Farm - Start a New Session button

If the session starts successfully, it moves from the Pending Sessions list to the Active Sessions list. An active session is one with a device that you can connect to.

Once the session appears in the Active Sessions list, you can connect to the device and debug it. See Use a Remote Debugging Session in AWS Device Farm.


                Device Farm - Start a New Session button

Once a session is completed, it moves to the Completed Sessions list.

Note

If a session fails, it moves directly from the Pending Sessions list to the Completed Sessions list.

To determine the status of a completed session, hover over the session entry in the Completed Sessions list. Completed session status can be:

  • Stopping - the session is in the process of being stopped

  • Passed - the session has completed successfully

  • Errored - the session encountered a problem


                Device Farm - Start a New Session button

To view the results of a session in the Completed Sessions list, choose View report to see the results in the Device Farm console.


                Device Farm - Start a New Session button

How to Stop a Remote Debugging Session

To stop a session that is still pending, choose Cancel request.


                Device Farm - Start a New Session button

To stop an active session, choose Terminate.


                Device Farm - Start a New Session button

After a session starts (becomes active), if you close the Device Farm app without stopping the session or if the connection between the app and the Internet is lost, the session remains active for five minutes from that time. After that, Device Farm ends the session automatically. Your account will be charged for the idle time, however.

Tips and Tricks

At the bottom of the Device Farm app screen are the following dropdown menus:

  • The Profile menu can be used to switch from the default profile to an AWS CLI profile that you have configured.

    
                        Device Farm - Start a New Session button
  • The Project menu can be used to switch from the default Remote Debug project to another project that you previously created.

    
                        Device Farm - Start a New Session button