Auto-tools/Projects/SUTAgent

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 (see below). The sutini app from mozdevice can be used to update this file on a remote device.

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 current Android Java implementation is found in mozilla-central under build/mobile/sutagent/android.

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