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
[edit | edit source]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 | edit source]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
[edit | edit source]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 | edit source]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 | edit source]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 | edit source]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 | edit source]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.