SwisTrack/Interfacing SwisTrack

From Wikibooks, open books for an open world
Jump to: navigation, search

SwisTrack acts as a TCP server (default port: 3000) and can therefore easily be connected to other programs for further processing of the results. The text-based NMEA 0183 protocol (with optional checksum) is used to encode the data.

Testing the Connection on Linux or Mac OS X[edit]

If you have netcat installed on your system, type

nc HOSTNAME 3000

to open a TCP connection to SwisTrack. Netcat will print messages from SwisTrack on your terminal, and send everything you type back to SwisTrack. (You could use telnet as well, although telnet does more than just opening a TCP connection.)

If you are using a recent version of bash, you can also type

cat < /dev/tcp/HOSTNAME/3000

on your bash shell to read all messages from SwisTrack. Note that this just prints messages from SwisTrack on your terminal, but doesn't send what you type.

Testing the Connection on Windows[edit]

To connect to SwisTrack, launch HyperTerminal and select "TCP / IP Winsock" in the "Connect To" dialog. Set the host address to "localhost", or the hostname / IP address of the computer SwisTrack is running on, and port number to 3000. When you click OK, HyperTerminal will establish a connection to SwisTrack. (Note that SwisTrack currently doesn't show whether a connection is open or not.)

HyperTerminal's configuration screen

If you are connecting from another computer, you may have to configure the firewall on the computer SwisTrack is running on to allow incoming connections on port 3000.

If you perform a step in SwisTrack now, with at least one output component (e.g. the Output Particles component) active, you will see a couple of lines appearing in the HyperTerminal window.

HyperTerminal with output from SwisTrack (two manual steps)

Message Format[edit]

SwisTrack uses NMEA 0183 messages to exchange data with other programs. (Note that NMEA 0183 is more than just a message format, but SwisTrack does not use the other parts of the protocol.) Such messages look as follows:

$MESSAGE_TYPE,FIELD1,FIELD2,...FIELDn*XX

where XX denotes the checksum, obtained by xor'ing all bytes between $ and *, and writing the result as two-digit hex number. SwisTrack always adds a checksum to outgoing messages, but doesn't require a checksum on incoming messages. Messages without a checksum or with a correct checksum are accepted, while messages with an incorrect checksum are discarded.

All messages start with a $ sign, and end with a <CR><LF> (char 13 or 0xD, followed by char 10 or 0xA). The data fields are comma separated, and fractional numbers are written with a dot. The message type is a case-insensitive string of any length (as opposed to the standard which limits it to 5 characters).

Sample Code[edit]

Sample code for parsing NMEA messages in various programming languages is available in the Examples/OutputProcessing folder of the SwisTrack SVN tree.

Message Types[edit]

Output components are free to define their own message types. The documentation of these types is available on the corresponding output component description.

Additionally, SwisTrack provides some built-in message types:

SUBSCRIBE
Tells SwisTrack to only send messages of a certain type, instead of all messages. For example, to receive only STEP_START and STEP_STOP messages, send the following message to SwisTrack:
$SUBSCRIBE,STEP_START,STEP_STOP
To receive all messages again, send
$SUBSCRIBE
STEP
Executes a step, as if you had clicked on the Step button in the toolbar. Example:
$STEP
RUN
Sets the running mode. Examples:
$RUN,true          or          $RUN,false
START
Starts the pipeline in testing or production mode mode. Examples
$START          or          $START,production
STOP
Stops the pipeline. Example:
$STOP
RELOADCONFIGURATION
Reloads the configuration. Example:
$RELOADCONFIGURATION
BROADCAST
Broadcasts a message to all SwisTrack clients. The first argument becomes the message type of the broadcasted message. This is useful if you want to insert information (e.g. state information) from another program. For example, your main experiment control program may broadcast the start of an experiment with
$BROADCAST,EXPERIMENT_START,some_parameters

Interfacing SwisTrack from Linux or Mac OS X[edit]

The simplest way to log or process data from SwisTrack is to pipe the output into a Perl or a Python script (or any other script language you like). If your version of bash supports /dev/tcp, then you could write

./my-filter-script.pl < /dev/tcp/HOSTNAME/3000

You can use netcat as well:

nc HOSTNAME 3000 | ./my-filter-script.pl

Sometimes, it is useful to write all data into a log file at the same time. To do this, you can sqeeze in tee:

nc HOSTNAME 3000 | tee mylogfile.txt | ./my-filter-script.pl

If you also need to send commands to SwisTrack, then you have to open your own TCP connection from your script.

Sample scripts are available in the Examples/OutputProcessing folder of the SwisTrack SVN tree.

Interfacing SwisTrack from Windows[edit]

On Windows, you have to write a dedicated program which opens a TCP connection to SwisTrack. Sample code for parsing NMEA messages is available in the Examples/OutputProcessing folder of the SwisTrack SVN tree.