Auto-tools/Projects/SUTAgent/CommandReference

Note: The agent was originally written for windows mobile and newlines there are \r\n references in code that interacts with the agent. When the Android agent was introduced, we needed to support the code and it would have been a lot of work to retrofit the windows agent, so we made the android agent support \r\n. This is known to be seen in the 'cat' command which is used in some sut_tools scripts. Just keep this in mind as we might have some backwards compatibility issues.

Required Commands

The SUTAgent shall support at least the following commands:

cd <dir>

Change the current working directory to <dir>. <dir> can be absolute or relative to the cwd.

clok 

Print system time in milliseconds since Jan 1, 1970, in UTC.

cwd

Print the current working directory.

dirw <dir>

Indicates whether a directory is writable or not. Prints the string "[<dir>] is writable" or "[<dir>] is not writable".

exec ["env1=val1,env2=var2,..."] <prog> [arg1] [arg2] [...]

Executes <prog>, optionally passing one or more attributes, as a separate process. Prints out a platform-dependent message indicating success or failure. Environment variables to pass to the process should precede the program name and be of the form <variable name>=<value>.

The command should not be completed until the process has terminated. Note that it *may* terminate quickly if <prog> spawns another process, as with "am start" on Android.

hash <file path>

Prints an MD5 hash of the contents of <file path>, if found and readable.

info [subcommand] 

Prints out some system information. [subcommand] can be one of the following subcommands:

• id: unique device ID, such as a MAC address
• os: operating system version, e.g. "GINGERBREAD.XXKI4"
• systime: ISO-style system time, e.g. "2012/08/01 02:00:27:274"
• uptime: elapsed time since the device was last started, e.g. "0 days 2 hours 13 minutes 51 seconds 957 ms"
• uptimemillis: elapsed time since the device was last started in total number of milliseconds, e.g. "8078506"
• screen: screen resolution in the form "X:<pixels> Y:<pixels>"
• rotation: angle of rotation, in degrees, e.g. "0" or "90"
• memory: amount of available and free memory in bytes, e.g. "PA:644018176, FREE: 456482816"
• power: power status, e.g.

Power status:
  AC power ONLINE
  Battery charge HIGH FULL
  Remaining charge:      100%
  Battery Temperature:   32.0 (c)

• process: process list, as with the "ps" command below

If no subcommand is given, all the info is printed out in the above order.

isdir <path>

Prints "TRUE" if <path> is a directory, "FALSE" if it exists but isn't a directory, or an error string if <path> doesn't exist or isn't readable.

ls [path]

Prints the contents of [path], one entry per line. [path] defaults to cwd.

mkdr <path>

Creates <path> as a directory. If successful, prints the string "<path> successfully created". If failure, prints "Could not create directory <path>" as an error.

ps

Prints a process list, one process per line, in the form "<user id> <pid> <name>".

pull <path> [offset] [length]

Dumps [length] bytes of the contents of <path> starting at [offset] bytes. If not specified, [offset] defaults to 0 and [length] to the size of the file. The contents are preceeded by a line of the form <path>,<length>, regardless of whether <length> was specified. No trailing newline should be added if not present in the file.

push <destination path> <length>

Writes data to the remote file at <destination path>, creating it if required. This command should be followed by exactly <length> bytes of data, which are written, without translation, to the file. After closing the file, the SUTAgent prints out the MD5 hash of the contents of the file.

quit

Terminates the command connection.

rebt [callback IP] [callback port]

Reboots the device. If both callback IP and port are specified, the SUTAgent, when it comes back up after the reboot, will connect to that IP and port and send the same registration data as when it boots up.

rm <file path>

Removes the file at <file path>, which must be a regular file.

rmdr <dir>

Removes <dir> and all contents (i.e. recursive delete).

settime <datetime> deprecated

Sets the system time to <datetime> in local time, which should be in the form "yyyy/mm/dd HH:MM:SS". Note that this command should be avoided, since (a) it may not be clear what timezone the device is in and (b) ambiguity of datetimes in the DST-ST boundary range (times from 01:00:00 to 01:59:59 on the day that DST switches to ST are repeated, once for each time zone). Use setutime instead.

setutime <milliseconds>

Sets the system time to <milliseconds>, which should be a number of milliseconds since Jan 1, 1970, in UTC.

testroot

Prints the root test directory, that is, a writable location to be used for test support files.

ver

Prints the product name and version, e.g. SUTAgentAndroid Version 1.13 or SUTAgentNegatus Version 1.1.

Optional Commands

kill <name>

Kill all processes running on the system that match <name>. In the Java implementation, if the process name contains <name> it will be killed (e.g. "kill fire" will kill all firefox processes.) In Negatus, a full match is required.

Unsupported Commands

The original Java SUTAgent implemented these commands. They will not be implemented in the new SUTAgent. Instead, SUTAgent-specific DeviceManager objects will build this functionality out of lower-level commands like 'exec' and 'push'.

inst <path to package file>

Installs an application from a package located on the device.

unzp <zip file> [dest dir]

Unzips <zip file> to [dest dir]. [dest dir] defaults to cwd.

updt <path to apk>

Updates a previously installed application from a package located on the device.