Team

jmaher, mcote, wlach

Problem

Automated testing of mobile devices requires a platform-independent system-level interface on the device in order to manipulate the filesystem, processes, and other core components.

Goals & Considerations

The SUTAgent requires a simple network interface that can be used for access to the remove filesystem and processes.

Non-Goals

Functionality should be limited to basic building blocks as much as possible. It should be up to user applications to do more complex operations using the lower-level features of the agent.

While it is nice to be able to connect directly to the interface (e.g. via telnet or nc), not all commands need support such a terminal-friendly interface. In particular, the SUTAgent should not be required to translate nonprintable characters when sending and receiving files. A simple client-side command-interface utility can support these features.

Design and Approach

Configuration

The SUTAgent can be configured by providing it with a file called SUTAgent.ini. This optional file can be used to configure the network connection and the registration server.

For the original Java Android agent, SUTAgent.ini should be put into the "files" directory of the package installation path, typically /data/data/com.mozilla.SUTAgentAndroid/files/SUTAgent.ini. For the C++ agent, Negatus, it should be /data/local/SUTAgent.ini.

The sutini app from mozdevice can be used to update this file on a remote device for the Java agent (Negatus is not yet supported by sutini).

There are two supported sections in SUTAgent.ini.

[Registration Server]

A [Registration Server] section can be included in SUTAgent.ini to cause the agent to register itself upon start-up. The section should contain the following variables:

• IPAddr: Address of the registration server.
• PORT: Port of the registration server (normally 28001).
• HARDWARE: Short description of the device.
• POOL: Free-form string that can be used for categorizing the device or other administration tasks.

See the Registration Server section below for more details.

[Network Settings]

The [Network Settings] section provides a limited ability to configure the device's wireless network settings via the Java agent. Some options are read by the agent but not actually used; these are indicated below. Note that Negatus does not yet support this section at all.

• SSID: Name (SSID) of the wireless network to which the device should connect.
• AUTH: Authentication protocol. Currently only "wpa2" is supported.
• ENCR: Encryption algorithm. Currently only "aes" is supported.
• KEY: Ignored. Probably intended to store the network password, e.g. WPA key.
• EAP: Authentication protocol. Currently only "peap" is supported.
• ADHOC: Ignored.

It seems that, if authentication is enabled, the username is always "bmoss@mozilla.com" and the password is "password", though I haven't verified that.

Start up

The device must start the SUTAgent automatically when it boots. Upon starting, the SUTAgent connects to a registration server, if configured. If it is restarting after a SUTAgent-initiated reboot (see below), it then connects to a callback server to indicate that it is back up.

Interface

The SUTAgent maintains two open ports: a command port (default 20701) and a monitor port (default 20700). The command port receives line-based commands and, depending on the command, prints a response. The monitor port (sometimes referred to as the data port) sends a periodic heartbeat and log messages. At a minimum, all command lines should be logged.

Logs are also kept in a file on the device and rotated periodically to ensure they don't take up too much disk space.

Note that, regardless of the device's platform, paths are always in POSIX format (using forward slashes). The SUTAgent is responsible for translating these to and from the native format (e.g. c:\dir\ might be translated as /c/dir/).

The SUTAgent shall also remember the current working directory for the duration of a command-socket connection. The default cwd is device-specific.

When errors are printed in response to commands, they should be of the form "##AGENT-WARNING## <detailed error message>".

See the command reference for supported commands.

Registration Server

As described in the Configuration section above, if a [Registration Server] section is present in SUTAgent.ini and configured appropriately, upon start-up the agent will connect to the registration server and send a short description of the phone and agent. The description is in the form of a URL-encoded query string with the following parameters:

• NAME: MAC address
• IPADDR: IP address
• CMDPORT: Port number of the command socket
• DATAPORT: Port number of the monitor socket
• OS: OS string
• SCRNWIDTH: Screen width in pixels
• SCRNHEIGHT: Screen height in pixels
• BPP: Screen colour depth
• MEMORY: Amount of available memory in bytes
• HARDWARE: Description of hardware as specified in the SUTAgent.ini file
• POOL: Value of the POOL option in the SUTAgent.ini

Example registration string:

NAME=14%3A7d%3Ac5%3Aaf%3Ac8%3Ae3&IPADDR=192.168.1.146&CMDPORT=20701&DATAPORT=20700&OS=Android-GINGERBREAD.XXKI4&SCRNWIDTH=480&SCRNHEIGHT=800&BPP=8&MEMORY=603811840&HARDWARE=samsung_gs2&POOL=304D19C38653ED7E

Example SUTAgent.ini

 [Registration Server]
 IPAddr = 10.250.120.62
 PORT = 28001
 HARDWARE = nexus_s
 POOL = 3833F770946F00EC

 [Network Settings]
 SSID = Mozilla Ateam
 AUTH = open
 ENCR = disabled
 KEY = auto
 ADHOC = 0

Implementation

The old Android Java implementation was found in mozilla-central under build/mobile/sutagent/android; it was removed in bug 1255527.

See SUTAgentImplementation for a plan for a cross-platform C++ implementation.