Visualize the mesh
==================


Concept
-------

In contrast to other routing protocols each batman node only knows the path to its single hop neighbors and knows nothing about the topology behind it. In practice it means that a batman node S is aware of node A which is somewhere in the mesh and reachable via neighbor B but it does not know about the number of hops and / or nodes in between. This approach is quite handy with regard to memory footprint, mesh stability and bandwidth friendliness but somewhat hard to visualize. Therefore a small helper was created: the vis server. It gathers the local views of each node and assembles a graph that can be fed into various tools which output an eye-candy graphic of the networks topology.


Batman nodes
------------

Each batman node needs to know the IP address of the vis server it should send the vis packets to. This packet is sent every few seconds containing various information about the local neighbors (including their link qualities), secondary interfaces and announced networks.

Example: batmand -s visIP [interface]

The vis server can run in the mesh itself or somewhere in the internet, just make sure that batman can reach the given vis IP.


Vis server
----------

The vis server can run on multiple interfaces and expects incoming vis packets on UDP port 4307. Per default it sends the assembled graph to all clients connected to TCP port 2004 every few seconds. It uses the standardized dot draw format to express the relationships among the nodes.

Example: vis [interface] [interface]

The vis server 0.3.2 (and later) additionally offer JSON as output format. Once activated you can retrieve the JSON output on TCP port 2005 (dot draw remains available on port 2004).

Example: vis -j [interface] [interface]

Make sure that all mentioned ports are not blocked by a firewall. You can verify whether your setup works by using e.g. telnet to connect to port 2004 or 2005.


Fancy graphics
--------------

If you intend to create images like this one [1] you need to use one of the many tools available. That screenshot was made by connecting mesh3d (which is part of the s3d tools [2] - debian packages are available) to the vis servers dot draw output (on port 2004). If you have impressive screenshots don't hesitate to let us know. :-)

[1] http://downloads.open-mesh.net/batman/misc/wbm2009/08-vis_zoomed.png
[2] http://s3d.berlios.de/