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).

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

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.
• HARDWARE: Short description of the device.
• POOL: Free-form string that can be used for categorizing the device or other administration tasks.

When the agent starts, it connects to the registration server as described in SUTAgent.ini and sends 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

Implementation

See SUTAgentImplementation.