Khepera III Toolbox/Parsing Program Output

The Khepera III Toolbox (notably the programs) uses NMEA 0183 messages as output data format. NMEA 0183 is a message-oriented communication protocol known from GPS receivers, which is about equally simple to read for humans and for computers.

NMEA 0183 Messages

NMEA 0183 is a communication standard specifying electrical characteristics as well as data format characteristics. Here, we are only using the message format of NMEA.

An NMEA message (or sentence) looks as follows:

$SPEED,10000,15000

Messages always start with a $ sign, followed by a command and a list of arguments. The command as well as the arguments are separted by commas. Optionally, the message contain a trailing checksum (e.g., *4D), but none of the Khepera III programs writes this checksum.

The original NMEA specification does not allow the command to be longer than 5 characters. The Khepera III toolbox, however, does not use this restriction in favor of longer and more explicit command names.

A stream of NMEA messages can contain different types of messages, e.g.

$STATE,random_motion
$SPEED,10000,15000
$SPEED,11000,14000
$SPEED,12000,13000
$STATE,follow_wall
$SPEED,5000,5000

which is very handy for reporting results.

Advantages of NMEA 0183

The NMEA 0183 message format has several advantages:

It is human readable.
It is easy to parse by computers and the checksum (if any) is easy to calculate.
As it uses a start of message character ($) and an end of message character (CRLF), you can break a data stream apart at any point, and the parser will be able to resynchronize (i.e., read all complete messages).
It starts with a message type and therefore allows messages of different types to be interleaved in the same stream.
It optionally allows for a checksum, which is useful when the data is transmitted over lossy channels.
It can be converted to a CSV file with search-and-replace (see below).

Converting NMEA messages to CSV with a Text Editor

If you have a file with messages of one single type, e.g.

$SPEED,10000,15000
$SPEED,11000,14000
$SPEED,12000,13000
$SPEED,5000,5000

you can use any text editor to transform it into CSV. Simply replace $SPEED, by nothing, and save the file. The resulting file can be loaded in almost any program (Matlab, Microsoft Excel, ...).

Converting NMEA messages to CSV with k3-nmea-to-csv

Instead of using a text editor, you can also use the k3-nmea-to-csv filter script to convert NMEA messages to CSV. Just pipe your file through that script, by providing the NMEA command of the messages to extract, e.g.:

k3-nmea-to-csv SPEED < my_nmea_file > my_csv_file

All messages that are not of type SPEED will be ignored.

Note that you can use this filter script with any program to convert its output to CSV. For example,

./infrared_proximity -r | k3-nmea-to-csv IRPROXIMITY

would output the IR proximity sensor values as CSV.

Parsing NMEA with Scripts

NMEA can easily be processed with Perl, Python, Ruby or similar scripting languages. Example scripts can be found in the Examples section.

Parsing NMEA on the Robot

The modules section contains an NMEA parser (module nmea) written in C with can be used to parse NMEA messages on the robot. This can be useful to read a configuration file, for instance.