# SwisTrack/Examples/OutputProcessing

SwisTrack/Interfacing SwisTrack gives you an overview about how to communicate with SwisTrack. The OutputProcessing folder in the SwisTrack examples folder contains a few sample scripts and programs that help you to implement this.

## Sample Code
### Interfacing SwisTrack with Scripts

The NMEA format is extremely easy to process with regular expressions, as each message is on a separate line and starts with a $-sign. Hence - for all simple tasks - a Perl, Python, Ruby or Shell script is the easiest way to go. And often - if you reduce it to what you really need - your task IS simple.
The swistrack-filter.* files contain simple examples how SwisTrack messages can be processed. The swistrack-interface.pl script furthermore shows how you can send messages to remotely control SwisTrack. How to use these filter scripts in a terminal (shell) is explained in SwisTrack/Interfacing SwisTrack.

### Interfacing SwisTrack with a C/C++ Program

To ease interfacing SwisTrack with your C/C++ program, we provide you code for parsing NMEA messages. The necessary files along with a sample program and some implementation hints are available in the folders NMEAParserC and NMEAParserC++ respectively. Both merely consist of a state machine scanning a data stream for NMEA messages, and are suited for both blocking and non-blocking IO.

### Interfacing SwisTrack with a Microcontroller

The C implementation of the NMEA parser (NMEAParserC) can also be used on microcontrollers (if a C compiler for your microcontroller is available). In addition, you may need to write a script which forwards data between a TCP connection to SwisTrack and a serial connection to your microcontroller. One-way forwarding can even be achieved on the shell):
The overhead for parsing NMEA is very small, and the overhead in terms of message size is reasonable as well. It is therefore rarely necessary to convert the data to another format when sending it over a slow serial link to a microcontroller.

### Interfacing SwisTrack with SWIG

We have written swig/python bindings that allow you to instantiate a swistrack pipeline and get the output as an IplImage. This makes it possible to view all parts of the pipeline in a SWIG-compatible language. (We've only tested python so far, but Swig supports lots of languages.)

## Hints
### Checksum

The NMEA message checksum is optional and only makes sense if you are sending the data over an unreliable channel. SwisTrack always adds a checksum on outgoing messages, but does not require any checksum for incoming messages. However, if a checksum is provided, it has to be correct! (Messages with wrong checksums are discarded.)
As long as you are transmitting your messages over a TCP connection, you can safely assume that the channel is reliable (transmission errors are handled by lower network layer) and you don't need to implement checksum checking. USB and Bluetooth transmission are safe as well. If you transmit the messages over a serial cable (e.g. to a robot), however, handling the checksum may make sense - especially if you plug/unplug the cable while the system is running.

### Plotting Results in Matlab

Matlab (or similar programs) doesn't read NMEA messages directly. The simplest way to plot data in Matlab is to write a filter script (adapt swistrack-filter.*) which extracts the relevant information among all incoming NMEA messages and prints it in matrix form. E.g.
would be converted into
The resulting file can then be read with the Matlab load function.

### Multiple Scripts/Programs

It is sometimes helpful to split a task into a few smaller (unrelated) tasks, and therefore create a few small, independent scripts/programs which all connect to SwisTrack. As SwisTrack accepts multiple TCP connections at the same time, this works just as fine as a single big script/program. All these scripts/programs may run on the same or on different computers, which gives you maximum flexibility.
If you need to exchange information between your scripts/programs, you can use the BROADCAST message. This allows you to send messages through SwisTrack to all clients, without the hassle to establish dedicated communication channels between them.