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 thedata
folder located in theGameBench
installation folder.
fileformat
option removed in version 4248gb --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.