Getting Started

The automation interface (GBA) is a client-server program that includes 2 components:

  • A client runs on your development machine. You can start a client from the shell by issuing the gb command. A client issues the server commands, which executes them and returns the result back to the client.
  • A server, which needs to be run as a background process on your development machine, manages the communication between your development machine and the devices connected.


Starting the Server

Before using the gb client, the server needs to be started. On Linux you can start the server by executing the following:

sudo service gbaserver start

Or alternatively, in a separate terminal instance;

gb --start-server


List Devices

To list the devices connected to the development machine, execute the following:

gb --list-devices

This will return a list of devices with their name and UDID. Take note of the UDID as this is used to identify the device when using other gb options documented below.

  • Note: Due to issues with the Linux implementation of usbmuxd, when plugging in a new iOS device into a Linux host and hitting 'Trust' when prompted on the device, you may need to wait up to 60 seconds and disconnect and reconnect the device before GBA acknowledges it. Still having problems?


List Apps

To list the apps installed on a device, execute the following:

gb --list-apps <udid>

This will return a list of apps installed on the device with their name and package name. Take note of the package name as this will be needed when using the --record option.

  • Note: The first time you issue this command for a device, you may have to wait for an extended period of time as the server will need to setup the device. This includes installing the companion app for Android and mounting the developer disk images for iOS.


Recording

Before you can collect data from an iOS device, you need to obtain a zip of Developer Disk Images. At the very least, it will need to include the disk image for the version of iOS that is running on your device.

For more information, please read Developer Disk Images.

If you do wish to collect data from an iOS device, you will need to provide the path of the zip to GBA by executing the following, otherwise you may skip this step.

gb --setprop imgZip /home/user/ddimg.zip

To collect performance data of an application, launch the application on the device and execute the following:

gb --record <udid> <package> <email> [--no-screenshots]
  • <email> is a required parameter. To view this session in the Web Dashboard, you will need to register and login using this email address.
  • --no-screenshots is an optional parameter to disable the collection of screenshots during the session.

This will start collecting data for all the available metrics on the device until a --stop has been issued. You can stop recording by executing the following:

gb --stop <udid> [--outputDir <directory>]
  • --outputDir can be used to specify the directory in which the JSON file with this session's data will be written. If not provided, the file will be written in the data folder located in the GameBench installation folder.
fileformat option removed in version 4248
gb --stop <udid> [--fileformat json [<file>]]
* --fileformat is an option that can be used to generate a JSON file with this session's data. <file> is an optional parameter. If provided, the session will be written to this file path.


Syncing

After all recordings have stopped you can upload your sessions to the Web Dashboard, by executing the following:

gb --sync

If you would like to automatically sync a single session after its completion, you can append the --record option with the --autosync option, like so:

gb --record <udid> <package> <email> --autosync



Selecting Metrics

Before recording, you can select the metrics you would like to collect, by executing the following:

gb --setprop collect_<metric> [true|false]

Possible metrics for selecting are [ fps,mem,cpu,net,gpu,threads,janks,energy,power ].


List Available Metrics

To list the available metrics for a device, execute the following:

gb --info <udid>

This will return some basic information about the device along with a list of metrics that are available for collection.

Still need help? Get in touch!
Last updated on 1st Feb 2018