batctl: Update README's vis section

Message ID
State Accepted, archived

Commit Message

Linus Lüssing March 21, 2010, 11:14 p.m. UTC
  This patch adds a short description and a more detailed explanation
of the vis_data output. Furthermore the final steps of how to
convert a vis-dot file to a png graphic is now being explained here.

Signed-off-by: Linus Lüssing <>


--- README	(revision 1607)
+++ README	(working copy)
@@ -335,7 +335,7 @@ 
  * ca:a1:5b:e5:00:00 via fe:fe:00:00:06:01
 batctl vis_server
 display or modify the status of the VIS server
@@ -348,4 +348,80 @@ 
 [ ] server mode (server enabled)
+batctl vis_data
+display the VIS data in dot or JSON format
+batctl vis dot {-h}{--no-HNA|-H} {--no-2nd|-2} {--numbers|-n}
+batctl vis json {-h}{--no-HNA|-H} {--no-2nd|-2} {--numbers|-n}
+(A <- 100% -> B,B-if2 <- 50% -> C)
+$ batctl vis_data dot
+digraph {
+	"A" -> "B" [label="1.00"]
+	"A" -> "00:ff:f3:cc:68:ac" [label="HNA"]
+	subgraph "cluster_A" {
+		"A" [peripheries=2]
+	}
+	"B" -> "A" [label="1.00"]
+	"B-if2" -> "C" [label="2.00"]
+	"B" -> "22:ff:f3:cc:68:ac" [label="HNA"]
+	subgraph "cluster_B" {
+		"B" [peripheries=2]
+		"B-if2"
+	}
+	"C" -> "B-if2" [label="2.00"]
+	"C" -> "44:ff:f3:cc:68:ac" [label="HNA"]
+	subgraph "cluster_C" {
+		"C" [peripheries=2]
+	}
+The vis dot (or json) output is adding an entry for each link between two
+originator's interfaces which are being used for batman's internal routing.
+The labels are similar/compatible to the ETX metric, 1.0 means perfect
+connection (100%), 2.0 means 50%, 3.0 means 33% and so on.
+A host's mac address which is currently connected to the interface of a mesh
+node (either the mesh node itself or hosts being bridged into the mesh) is
+being displayed with an "HNA"-label. (--no-hna omits this output)
+To still have the information about which interfaces belong to which mesh node
+a subgraph/cluster is being added. The subpgraph is being labeled with a mesh
+nodes's primary interface mac (= Originator MAC) which is also having an
+additional [peripheries=2] to make this important MAC address visible in an
+image for instance. (--no-2nd omits this output)
+After the conversion to a png file with graphviz-tools' fdp, all interfaces of
+a node would be combined in a visual box (see below for details).
+vis-dot to png
+The vis dot output could then further be converted to an image of the topology
+graph with the help of the graphviz-tools for instance. The according commands
+could then look like this:
+$ batctl vis_data dot > /tmp/
+$ fdp -Tpng /tmp/ > graph.png
+Meaning of the shapes in this image file:
+* Ellipses: Every BATMAN-node's and host's interface can be found in here
+            labeled with the according interface's MAC-address.
+* Boxes:    interfaces belonging to one BATMAN-node
+* double circled interfaces: the primary interface of a BATMAN-node
+      (which is known to other BATMAN-nodes only, except direct neighbours)
+* Ellipses with an HNA-arrow: mesh clients (this can be a BATMAN-node itself
+      with its bat0 interface or computers/devices being bridged into the mesh)
+* Arrows with numbers: the transmit quality (in the form 1/TQ) from one
+      BATMAN-node's interface to another BATMAN-node's interface