Cassini System Message (SM) control Interface
The Cassini system software and it's software environment (including Guru) offers a standardized messaging protocol called System Message (SM). This protocol is used by the ATE itself to exchange data and coordinate actions between components of the system. It also permits unprecedented control of the system for customers who wish to exploit this powerful interface.
The full SM specification contains routing information and can be a little unwieldy for customers who want to interact with components such as the Test Executive software. To facilitate easier adoption of the SM format, Roos Instruments created a software component called the "SM Bridge". This middleware layer presents an easy-to-use TCP/IP interface to the SM protocol and allows easy exchange of messages for any programming language that supports TCP/IP ports such as Java, C++, Python, and Tcl/Tk.
This document presents the command interface available to control the Cassini's Test Executive software -- particularly the commands and responses available to control the tester remotely from another process. It also introduces the basics of SM communication and how to utilize the SM Bridge to provide an easy communications interface. The commands described herein are for version 0.1 of the external Test Exec interface -- customers are encouraged to contact us with ideas to make the interface better and more complete.
Cassini Test Executive Remote Interface
The remote interface of the Cassini Test Exec software is based on asynchronous communications. That is, the Cassini system expects users to "subscribe" to events of interest and. once subscribed, those event notification might occur at any time. Similarly, the commands sent to the Cassini are received and acted upon in an asynchronous manner -- there are no special "command modes" or other such constructs to change the way commands are handled.
The table below summarizes the very basic Cassini Test Exec command interface.
Note : Each command may be followed by zero or more key/value pairs which are passed along as parameters. If a key/value pair is not understood, it is ignored by the software. This permits us to add additional parameters in the future without breaking backward or even forward compatibility.
Values shown in angle brackets <> are simple strings, with no quotes or delimiters. They may include spaces. Choices listed as "true|false" require "true" or "false" answers only, again with no quotes or delimiters. The "stdfoptions" key may be suffixed with a list of key/value pairs where each key is a valid STDF v4 field name and associated value. These values will be used in the STDF file directly, giving the user complete control of the MIR and SDR records.
TESTEXEC channel commands:
|load||Cause the RI Test Exec to load a named program|
|name=<program name>||yes||The name of the Test Exec to be loaded and run|
|showui=true|false||Disable or enable the user interface on the Cassini tester|
|manual=true|false||Require a "test" command for each part or auto-run handler|
|unload||Cause the RI Test Exec to stop and close the currently running program|
|start||Cause the loaded program to start running|
|lotname=<lot name>||Provide the string to be used in the STDF file|
|stdfoptions=<STDF key./value pairs>||STDF key/value pairs as defined in the STDFv4 documentation, e.g. NODE_NAM=Roos#1|
|testonce||Run the testexec one time and wait. Used to coordinate tester with handler or prober.|
|stop||Cause the RI Test Exec to stop and finish the STDF data file|
|pause||Cause the RI Test Exec to pause but leave STDF data file open|
|resume||Resume testing (and operating handler) after a pause|
|subscribe||Subscribe to a channel to receive notifications|
|unsubscribe||Unsubscribe to the channel and stop receiving notifications|
Roos Instruments System Message communications supports the concept of "channels" to divide the messaging into groups of interest. All of the commands above, for example, as sent to the channel called "testexec". The RI System Software test executive subsystem listens to that "channel" and receives any commands sent to it. Similarly, the commands "subscribe" and "unsubscribe" are used to direct the responses from the testexec channel back to a remote control program. There is a second channel which you may subscribe to and send back a wealth of debugging information. It is called "testexecdebug". Other than "subscribe" and "unsubscribe", no commands are sent to the testexecdebug channel.
Using SM Bridge to Communicate
The SM Bridge application is launched from Guru by selecting it from the menu. When started, it provides a display that shows the traffic of System Messages between various components of the Cassini test system. Even without launching a test executive, you will see "broadcast" messages from the Guru for every object that is saved or updated.
To create a connection using the SM Bridge, first open a socket on the IP interface of the Cassini system computer at port 50050. This connection will be used for sending control messages to the system as well as receiving the messages you subscribe to. To send a command you need to provide the command itself and a "channel" name, such as TESTEXEC. The command and channel are not case-sensitive. To separate the components of this message, non-printable characters are used. Hex character 0x1c is the most "outer level" separator, while hex 0x1d, 0x1e, and 0x1f are used for finer and finer separations within message blocks. The final message looks like this:
0x1c TESTEXEC 0x1c SUBSCRIBE <cr-lf> (spaces are added for clarity, they are not in the message)
If a message has parameters, they are separated by the next level of separator, within the message portion of the transmission:
0x1c TESTEXEC 0x1c LOAD 0x1d name=JbTest Exec <cr-lf>
If the parameter has a list in its body, the list items are separated by the next level separator:
0x1c TESTEXEC 0x1c START 0x1d lotname=ABCD 1234 0x1d stdfoptions=SBLOT_ID=1234 0x1e LOT_ID=ABCD 0x1e NODE_NAM=Roos #1 <cr-lf>
Note that values in the key/value pairs MAY include punctuation and spaces. This is one of the advantages of using non-printable characters as separators in the message body. The same separators are used to return structured data back from the exec. In the case of the TESTEXEC subscription, the information passed back comprises two dictionaries -- one for part information and one for lot information. These dictionaries likely contain more information that you need, but it is relatively easy to filter out the stuff you don't want. For example, the returned values for the part data might look like this:
0x1c SMBRIDGE_0B651UC 0x1c 0x1c TestStatus
0x1d TestdataAttributes=softbin=Softbin: 'Standard Pass'
0x1e hardbinName=Bin 1
0x1e hardbin=Hardbin: 'Bin 1'
0x1e softbinName=Standard Pass
The message above has been separated into lines for clarity, the actual message has no embedded CR or LF characters. This structure is a "dump" of the internal data dictionary of Cassini during the test process and it likely contains too much information. We expect to reduce the information so please tell us which fields you find useful so we can preserve the values which are actually useful.
The string "SMBRIDGE_0B651UC" represents your connection to the SM Bridge program. All messages targeted to your program will begin with a similar string. Once you have made a connection, the value does not change. However, the value after the SMBRIDGE will change if you disconnect and reconnect to the SM Bridge program.
Subscribing to the TESTEXECDEBUG channel allows you to receive notification of all internal state changes while the test executive runs. For example, when stopping the exec:
0x1c SMBRIDGE_0B651UC 0x1c 0x1c StateChange
0x1d transition=input symbol: runTestComplete-->About to stop output state: Stop Pending-->doEndRun
To permit experimentation, we developed a Java program that lets you communicate to the SM Bridge program directly. You can directly enter messages to the SM Bridge and receive its responses. To make it easier to deal with non-printable separators, it maps them into printable equivalents for easy entry and viewing. Remember that the actual messages DO NOT use these printable equivalents -- they are mapped to and from the characters 0x1c to 0x1f:
Of course, this means that you may not used these characters inside strings and parameters when playing with the Java program. But they are completely legal in your finished application.