# SwisTrack/Interfacing SwisTrack

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

If you have netcat installed on your system, type
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
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

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.)
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.

## Message Format

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:
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

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

## Message Types

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

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
You can use netcat as well:
Sometimes, it is useful to write all data into a log file at the same time. To do this, you can sqeeze in tee:
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

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.