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