CMap


CMap is open source software from the Naval Research Laboratory (NRL) PROTocol Engineering Advanced Networking (PROTEAN) group. It provides a means of translating output from log files for MGEN, OLSR, MNE, etc. into output which can be read by the Scripted Display Tool (SDT). The result is a flexible, easy-to-customize mobility visualization tool. It keeps track of node movements, links between nodes, data reception status, etc.

CMap was designed to be very flexible. The background image and coordinates are set via an sdtsetup.cfg file in standard SDT-style input format. The parser can read in a cmap.cfg file that is used to give names to nodes, and provide a list of corresponding MAC addresses, IP addresses, etc. It can also be used to specify the icon/image/sprite associated with that node, along with height and width specifications for that image. However, you can still run CMap without this file; it just won't look as nice. If you don't specify nodes and corresponding IPs, MACs, etc. then everything falls back to defaults (i.e., you cannot specify images or image sizes, etc.). Also, if you are reading in both MNE and MGEN data, then it will create two separate nodes for each machine: one with the IP address and one with the MAC address, unless you specify the two addresses of the node in the cmap.cfg file. The parser keeps track of all the nodes in the system, all the links between them, etc. It also supports a "clock" node that can be used to display time.

CMap is written in C++. It requires ProtoLib and SDT, both of which are available right here on Protean Forge. While SDT runs on a variety of systems, CMap may not be that flexible. It has only been tested under Linux at this time.

Downloads

CMap source code is available at http://downloads.pf.itd.nrl.navy.mil/proteantools/.

This program is designed to send data to a program designed at NRL called SDT. SDT download and build instructions are available here.

This code relies heavily on a library called ProtoLib. CMap comes with a version of ProtoLib (usually the latest version at the time of release, newer releases may or may not break CMap). If you find the need to update ProtoLib for whatever reason, source code for ProtoLib is available at http://downloads.pf.itd.nrl.navy.mil/protolib/.

Installation

Please note that the installation instructions are listed in more detail in the README.txt file included with the source code.

Starting CMap

The cmap program must currently be launched from a command-line or executed by another script or program.. To launch cmap (assuming both cmap and sdt are in your path), use the following command-line syntax:

cmap <options> | sdt

If you wish to have the ability to double-click nodes to pop up informational windows, it is a little more complex. You should use the following command-line syntax:

rm /tmp/sdt.out; touch /tmp/sdt.out; cmap <options> sdt /tmp/sdt.out | sdt > /tmp/sdt.out

You can use whatever file location you want; /tmp/sdt.out is just an example.

Note that at a minimum, you must specify at least an MGEN, MNE, or generic log file location for cmap to start.

Command-line Options

period <seconds>

Specifies the number of seconds between screen updates. Must be positive. Can be anything greater than zero. 0.25 seconds is the default value.
sdt <sdtFeedbackFile> Specifies the location of the SDT output file. This is used so that the parser can receive feedback from SDT to support popup windows (or potentially other future similar capabilities).
mgen <mgenLogFile> Specifies the location of the MGENv4 text-style log file. Log files from previous MGEN versions are not supported. MGENv4 binary log files are not yet supported, though this is a planned addition.
mne <mneLogFile> Specifies the location of the MNE log file. If both MNE and MGEN logs are supplied, preference for GPS location will be given to the MNE log file.
generic <genericLogFile>

Specifies the location of a "generic" log file. This parameter can be used multiple times to support multiple "generic" files (up to 8 by default). Generic files are simply files that contain a lits of time-stamped SDT commands. The commands must be given in chronological order, and the line format must be as follows (capitalization is important):

Time>hh:mm:ss.uuuuuu node node01 pos 38.123456,-77.123456

The "node node01 pos 38.123456,-77.123456" part is the command that would be passed to SDT by this example. You can use any valid SDT command: bgimage, sprite, link, node, whatever.

It should also be noted that if a generic logfile has been specified, but no MGEN or MNE logfile has been specified, CMap will initialize nodes using cmap.cfg, but CMap will not send any node updates. The assumption is that your generic log file is doing the node movement, and may also be specifying its own label coloring and/or naming scheme.

olsr <olsrLogFile> Specifies the location of the OLSR log file. Works for NRLOLSRD, CRC-OLSRDv6, INRIA-OLSR, and any with similar log file formats.
realtime Tells CMap that you are viewing a test as it is running. When this is given, the parser will (after reading in your sdtsetup.cfg and cmap.cfg files) immediately jump to the end of all log files and read data as it comes in. Also see the note below concerning realtime operation.
playback Tells the parser that you are viewing a test after it is over. It will start from the beginning of all files and go through them at a given rate (configurable using the "speed" parameter). You can, of course, use playback mode for a live/realtime test, but you will be watching the playback delayed from realtime (at least until you catch up using a faster speed, but that may result in clock skew). Playback, as opposed to realtime, is the default mode of operation.
speed <playbackSpeed> Specifies the speed of playback when in playback mode. A speed of one means that one second of real test time corresponds to one second of playback time. A speed of ten means that ten seconds of test time corresponds to one second of playback time. The value must be greater than zero, and the default is one. This parameter has no effect in realtime mode.
linkcolor <color> Specifies the color of all links. Default link color is purple. Please see the wxWindows documentation for a list of valid color names.
usedlinkcolor <color> Specifies the color of "used" links (as reported by OLSR). Default color is blue.
staticlinkcolor Disables "used" link color so that all links are the same color.
disableused Same as staticlinkcolor above.
linkwidth <width>

Specifies the width of all links. Default is to not pass any value, and let SDT use its default (1). Value should be from 1-8, 8 being thickest.

OLSR may optionally return a link metric/hysteresis value representing link quality. If this metric is present in the logfile, then this linkwidth value will be ignored, and all links will be given a thickness based on their metric.

staticlinkwidth This parameter causes CMap to ignore the metric/hysteresis value from the OLSR log file, and use the specified linkwidth for every node.
warntime <seconds> Specifies the amount of time it takes until a node goes into "warning" state. This happens when no MGEN data is received from a node for the given amount of time. When this happens, the node's label will turn yellow (that color is configurable via a #define statement). The default value is 3 seconds.
failtime <seconds> Specifies the amount of time it takes until a node goes into "failure" state. This happens when no MGEN data is received from a node for the given amount of time. When this happens, the node's label will turn red (also configurable via a #define statement). This time must be greater than the warntime. The default value is 5 seconds.
logmode

Enables "logging" mode. In this mode, the parser will print out WAIT commands between each update period. This allows the user to save the CMap output from to a file (by directing it to a file using >file, rather than piping it directly into SDT). The file can then be used alone for playback with SDT, without having to use CMap for time synchronization, and without needing a copy of all the log files for re-parsing. The downside to using logging mode is that it does not allow you to use the double-click features.

Logging mode should not be used when piping data directly into SDT, as it may cause SDT to lag behind and gradually fill up the input buffer

savesettings Saves some of these parameters as defaults so that they need not be entered on the commandline every time. Period, speed, linkcolor, linkwidth, warntime, and failtime are all saved. These saved parameters will be overridden by any parameters given on the commandline. To delete saved parameters, you must manually edit (or delete) the CMAP_HOME/cmap_defaults.cfg file.

Each of these parameters may be shortened as much as you want, so long as it remains unique. For instance, you can use "save" instead of "savesettings", "gen" or even "g" instead of "generic", "log" instead of "logmode", etc.

cmap.cfg Format:

<node_name> IP <ip1 ip2 ...> MAC <mac1 mac2 ...> IMAGE <path|"none"> IMGSIZE <width height> SYMBOL <symbol_param>

All fields except <node_name> are optional. Just supply as much information as you want. Of course, the more you give, the better it will probably look.

The symbol parameter should be supplied in the format required by the SDT input format, please see the SDT documentation for details.

As an example, take a node called "m1-xcom" with three network adapters. The IPv4 IP addresses are 192.168.1.100, 192.168.10.100, and 192.168.0.100. The IPv6 addresses are 2010:8:1:59::100, 2010:8:1:58::100, and the third interface has no IPv6 address. We have 4 MAC addresses for these interfaces: 00:06:5B:B8:3D:B1, 00:02:2D:3F:F0:2A, 00:02:2D:74:55:99, and 00:50:BA:7E:57:D5. The 4th MAC address is assigned because we have data we want to play back from an experiment where we used a different wireless card than the one we have now. This is perfectly legitimate, as long as no other node used or is currently using that wireless card. We will also use the helicopter image set to a size of 48x48. The line we put in the cmap.cfg file for this machine would be (all on one line, of course):

m1-xcom IP 192.168.1.100 192.168.10.100 192.168.0.100 2010:8:1:59::100 2010:8:1:58::100 MAC 00:06:5B:B8:3D:B1 00:02:2D:3F:F0:2A 00:02:2D:74:55:99 00:50:BA:7E:57:D5 IMGSIZE 48 48 IMAGE helo1.gif

sdtsetup.cfg Format:

This file uses normal SDT-style input. Please see the SDT documentation for more details. This is most useful for specifying what background image SDT should use (bgimage), along with setting up the coordinate system by giving the upper-left and lower-right GPS coordinates of your background image (bgbounds command). However, it can be used for initializing nodes or whatever you want. Here is an example where we set the background image and the GPS coordinates of that image.

bgimage nrl4.jpg
bgbounds -77.028633,38.828533,-77.021267,38.822817

Note that for the bgimage parameter alone, you are not required to give the full path, as CMap can insert that for you.

Using CMap

CMap will automatically play through all your data, assuming you have started the program correctly. During execution, you can do different things, some of which are actually features of SDT, but are worth mentioning here. You can use Ctrl-S to automatically scale the background to fit the window, while preserving the aspect ratio tof the background image. You can use Ctrl-A to stretch the background to fit the entire window, without preserving the aspect ratio. You can zoom in and out by holding down the right mouse button and dragging up and down. You can also take screenshots using Ctrl-P. These commands are all available via SDT's menus as well.

You can also double-click a node, and a window will pop up for it. A separate window will pop up for each node you double-click. The popup window displays the node name, status (getting data, no data warning, no data failure), IP addresses, MAC addresses, attached networks (e.g. HNAs in Optimized Link State Routing, or OLSR) that the node is advertising (currently only works with NRLOLSRD as far as I know, but support could be added for other protocols), etc. The window is updated automatically whenever any of this information changes. On attached networks, it is assumed that you are looking at the network from the point of view of a single node (probably a valid assumption given that you only have one routing log file). Thus any HNAs being used by the machine whose OLSR log you are using will be displayed with a * to indicate this. If an IP, MAC, HNA, etc. are added to the node, that increases the number of lines being displayed, and the window will be resized to fit the new data. It will not resize when the number of lines decreases, only when it increases. You can close and re-open windows whenever you want.

Realtime Mode

When CMap is run with the realtime option, CMap will immediately jump to the end of every logfile and start reading from there. It is very important that the programs outputting to these logfiles flush their buffers consistently. If this is not done, CMap will not be able to give an accurate representation of the network, as it will get invalid partial lines. It should be noted that MGEN does not flush its output by default, and must therefore be run with the flush parameter for proper realtime visualization.

Example Screenshot

This screenshot is taken from a Mobile Network Emulator (MNE) test modeled after some live MANET field tests we did here at NRL. Popup windows for "m1-xcom" and "m1-node02" have been brought up. We can see the IP and MAC addresses for each node, and we can see that we are running an IPv6 version of OLSR because of the IPv6 HNAs (attached networks) that are being advertising to the network. The green color of the node labels means that "m1-xcom" (from whose viewpoint we are watching) is getting data from all the nodes. If it were not getting data from a node, we would be able to tell this both from the label of that node becoming yellow or red, as well as a "No Data Warning" or "No Data Failure" status in the popup window. We are running a version of NRLOLSR which specifies which links it thinks will be used if it sends data to another node in the network. The color of these links has been changed to white instead of the default blue color. Other links that m1-xcom knows about show up in purple. They will (probably) not be used if XCom sends data to some other node, but may be used by other nodes sending traffic.

Limitations


Any problems or issues with CMap should be directed to the author.