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] https://downloads.open-mesh.org/batman/misc/wbm2009/08-vis_zoomed.png
[2] http://s3d.sourceforge.net/