C. Control Protocol

You can control the production computer or a cluster of WATCHOUT display computers from other programs or systems, including general purpose control systems such as AMX or Crestron. This is usually done through the network, but other options (such as serial port or a script file) are also available.

The control protocol uses simple and readable command strings, making it easy to learn and implement from an external system.

To get started with controlling WATCHOUT, use a TELNET client to connect to WATCHOUT and give the commands from there. Both Windows and MacOS X come with a TELNET client (although under Windows it needs to be enabled before it can be used).

Command Format Details

Each command is sent as a string, terminated by a carriage return, line feed or CR/LF pair. A command consists of a command name, sometimes followed by parameters. Commands are case-sensitive.

Commands are encoded using the UTF-8 UNICODE character format, which is downward compatible with ASCII.

IMPORTANT: Commands containing non-ASCII characters – such as å, ä, ü, ç – must be encoded using the UTF-8 format in order to work properly.

String parameters are sent within double quotes. Backslash is used as an escape character (that is, to encode a double quote in a string, precede it with a backslash). To send a backslash character, use “\\” inside the string.

Commands are case-sensitive. Successfully performed commands are normally not acknowledged (although you can use the Command ID Tagging option to force explicit feedback for all commands).

While most commands are available in both the production and display programs, not all are. Furthermore, in a few cases, parameters to commands are slightly different in the two programs. Such differences are noted in the detailed descriptions of commands in this appendix.

WATCHOUT uses a simple text format for its commands. Some commands may return a reply, error message or other kind of response to the controller. Such responses are also sent as text.

Parameters

In commands that take parameters, the parameters are separated by white-space only. Optional parameters are shown in square brackets, like this: [<uint>]. Parameter types are described below.

<string>. String parameters are sent within straight double quotes:

"This is a string"

Backslash is used as an escape character (that is, to encode a double quote in a string, precede it with a backslash). To send a backslash character, use “\\” inside the string.

<uint> and <int>. An unsigned or possibly signed decimal integral number:

123

<float>. A possibly signed decimal number with an optional fractional part:

0.25

<bool>. The keyword true or false, with no quotes:

true