Automation Commands

An incoming TCP/IP socket connection on port 923 is automatically provided with a command line interpreter (CLI) to process incoming commands. Multiple CLI's may be active at any time. If you connect via PUTTY or some other terminal emulator software, the system will automatically detect a carriage-return at the end of a line of input and establish an "interactive" communications session. In this mode, the system will output a command prompt '%' character and you can simply type your commands to the CLI processor and your commands will be echoed back to the port and command output will also be sent to the port. If only a newline character is at the end of the first command, then the non-interactive mode is selected and commands are not echoed and no prompt is provided. This is the mode used when computer automation is intended.

In both modes, you can use menu commands to perform basic functions like property set and get or command method invocation. The {key} values referred to below are hierarchical named labels that refer to each and every category, property, command method of the device. For example, the "Sys:IP" key is a read-only property containing the local IP address of the device, and retrieving this property can be achieved by sending the key followed by a question mark, such as: "Sys:IP?". The response will be the ascii character string such as "192.168.1.105" for example, followed by a newline character (or a newline character and a carriage return for interactive mode).

The menu of commands include the following:

Menu commands:

{key} <value> ............. Set keyed property to specified value

{key} ? ................... Get keyed property value

{key} <arg-list> .......... Execute keyed method

(h)elp .................... Display help message

(ev)ents .................. List outstanding events

(st)atus .................. List outstanding status messages

(evc)lear ................. Clears outstanding events

(stc)lear ................. Clears status queue

(pr)op [opts] <prefix> .... Displays list of properties, opts: -(a)ll -(h)idden -(t)op

(tr)ee [opts] <prefix> .... Displays tree, opts: -(a)ll, -(h)idden -(t)op, -(p)roperty, -(m)ethod, -(c)ategory

(sa)ve <name> ............. Save configuration

(re)store <name> .......... Restore configuration

(q)uit .................... Quit program

(en)um <{key}> ............ Display list of enum values for the indicated enumerated property key

To query a property use the property name followed by a question mark. If you use a double question mark, you get the property value together with any special formatting. For example:

% Sys:PmuTemp?

20.2

% Sys:PmuTemp??

"20.2 C"

To set a property, specify the property name followed by the new value. You only need double-quotes if there is a space or punctuation in the value.

% Sys:Nickname "Lab One"

% Sys:Nickname?

"Lab One"

The device may have multiple error status conditions simultaneously. These are queried using the status query command. Each status is separated by a semi-colon. Status is recorded for each user separately, so that each user can determine when to retrieve status. Once status is retrieved for a specific user, the status list for that user is cleared. It is possible to clear the status directly using the status-clear (stc) command. Here is an example of retrieving status:

% st?

[Property_Is_Read_Only]; [Unrecognized_Command]

% st?

[none]

For non-interactive automation, it can be useful to gang together multiple set commands or methods and verify the status response is okay for all of them at the end of the sequence. Do this by separating each command with a semicolon and clearing status at the beginning and querying status at the end, for example:

% stc; Step:Cfg:PAmpl 200; Step:Cfg:PSource Local; st?

[none]

The device also maintains memory of what property values each connection has received and can provide a list of changes for properties that the requesting user should be notified of. This is done using the events-command (ev). This list is automatically cleared when read, or it can be manually cleared using the event-clear-command (evc). Notice the 'X' refers to an event of type "change notification". Then the name of the property and the property value follow. For array properties, the array is surrounded by braces. Multiple events are separated by semi-colons, for example (from the Decombiner device):

% ev

X Eye:Duration 216; X Eye:Sequence 5; X Temp:Current 36.4; X Pam:TopShift 700; X Pam:BotShift 3300; X Pam:Path Normal; X Pam:SmplDelay 0; X Pam:BotSmplDelay 0; X Clock:TopDelay 47.44; X Clock:BotDelay 53.706; X Eye:Running Stop; X Pam:AlignResult "[Unable_To_Find_Middle_Opening_During_Alignment]"; X Pam:TopAlign 0; X Pam:BotAlign 0; X Pam:AutoResult "[success]"; X Prompt:Response "[cancel]"; X Prompt:ProgTitle "Auto-align in progress"; X Prompt:Progress -1; X Prompt:ScrollMsg "[none]"; X Prompt:Prompt "[none]"; X Pam:Delay 27.5; X Pam:High 202.866; X Eye:Chart:CursValue {45.25,0,0,202.87,0,-209.38,24.56,27.5,26.544}; X Hist:Volt:Chart:CursValue {-209.38,0,202.87,0,0,0,-181,-181,-181}; X Pam:Low -209.379; X Pam:TopTime 24.56; X Pam:MidTime 27.5; X Timing:Chart:CursValue {27.5,0,0,0,0,0,0,0,0}; X Hist:Time:Chart:CursValue {27.5,0,0,0,0,0,0,0,0}; X Pam:BotTime 26.544; X Eye:Chart:Locked T; X Eye:Chart:CursEnabled {F,F,F,F,F,F,T,T,T}; X Eye:Cfg:Mode Bot-Mid-Top

% ev

[none]

Before retrieving results from a particular application, you have to ensure the application is available. The easiest way to do this is to select the application group Tab associated with the application. If you need to, you can create your own Tab contents using one of the user-customizable tabs (U1, U2, U3). Once you select the tab, the user interface should display this tab with the available applications. To start running all the applications on the tab, issue the command "App:Run". If you only want them to run once, you can issue "App:Run Once". Other commands include "App:Stop".

Some properties, such as "Step:Binary", respond with binary bytes of information. In this case, the bytes correspond to a LITTLE_ENDIAN byte-order buffer of 32-bit Float numbers. Binary buffers are preceded by a 4-byte count field comprising a LITTLE_ENDIAN integer specifying the number of _bytes_ to be transmitted _after_ the 4-byte count field.

Using CLI Commands

You can use a terminal emulator program to connect directly to port 923 and interactively operate the device using CLI commands.

When you connect interactively using a terminal-emulator program and press the ENTER keyboard button, this carriage-return character (0xD, 13 in decimal) indicates to the device server that this connection will be an "interactive " connection - as opposed to an automation host connection. Interactive sessions provide more output, such as helpful usage messages explaining parameters. Notice this means for automation programs, you should terminate each command only with a newline character (0x0A, 10 in decimal).

Use the tree (tr) command to display all the properties and commands that match a specified prefix, for example (from the Decombiner device):

% tr Pam

Pam: Demux Threshold Control - Category

Pam:TopTime..................Top Time - Double, 0.000 to 100.000, ps

Pam:MidTime..................Mid Time - Double, 0.000 to 100.000, ps

Pam:BotTime..................Bot Time - Double, 0.000 to 100.000, ps

Pam:HwVersion................Hardware Version - Int, (RO)

Pam:High.....................High level value - Double, -900.000 to 900.000

Pam:Center...................Center level value - Double, -900.000 to 900.000

Pam:Low......................Low level value - Double, -900.000 to 900.000

Pam:AutoResult...............Auto-align Result - String, (RO)

Pam:AlignResult..............Alignment Result - String, (RO)

Pam:Auto.....................Auto-align - Method, (NoAuth)

The property (pr) command displays the current value for the properties that match the specified prefix, for example (from the Decombiner device):

% pr Pam

Pam: [Demux Threshold Control]

Pam:TopTime..................25.094 ps

Pam:MidTime..................28 ps

Pam:BotTime..................27.249 ps

Pam:HwVersion................3

Pam:High.....................204.96

Pam:Center...................0

Pam:Low......................-208.298

Pam:AutoResult...............[success]

Pam:AlignResult..............[success]

The enum (en) command displays the enumerated list of values for the specified property that must be an enumerated type, for example (from the Decombiner device):

% enum Clock:Source

{"Ext","CR"}