We are now having a newer, more neutral vis output so that we won't have to change the kernelmodule for adding support of new vis output formats. This patch adds an explanation about this in the README file of batman-adv and removes the description about the dot/json format (they will be added to the README of batctl).
Signed-off-by: Linus Lüssing linus.luessing@web.de --- README | 43 ++++++++++++++++++++++++++++--------------- 1 files changed, 28 insertions(+), 15 deletions(-)
diff --git a/README b/README index df21c61..2058a13 100644 --- a/README +++ b/README @@ -1,4 +1,4 @@ -[state: 01-01-2010] +[state: 21-03-2010]
BATMAN-ADV ---------- @@ -57,10 +57,11 @@ regular interface: # ping 192.168.0.2 ...
+--- If you want topology visualization, your meshnode must be configured as VIS-server:
-# echo "server" > /proc/net/batman-adv/vis +# echo "server" > /proc/net/batman-adv/vis_server
Each node is either configured as "server" or as "client" (default: "client"). Clients send their topology data to the server next to them, @@ -71,19 +72,31 @@ more vis servers sharing the same (or at least very similar) data.
When configured as server, you can get a topology snapshot of your mesh:
-# cat /proc/net/batman-adv/vis - -This output format is a graphviz formatted text file which can be -processed with graphviz-tools like dot. -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. - -Alternatively, a JSON output format is available. The format can be set -using by writing either "dot_draw" or "json" into the vis_format file. -"dot_draw" is selected by default. - -echo "json" > /proc/net/batman-adv/vis_format - +# cat /proc/net/batman-adv/vis_data + +This raw output is intended to be easily parsable and convertable with +other tools. Have a look at the batctl README if you want a vis output +in dot or json format for instance and how those outputs could then be +visualised in an image. + +The raw format consists of comma seperated values per entry where each +entry is giving information about a certain source interface. Each entry +can/has to have the following values: +-> "mac" -> mac address of an originator's source interface + (each line begins with it) +-> "TQ mac value" -> src mac's link quality towards mac address of a neighbor + originator's interface which is being used for routing +-> "HNA mac" -> HNA announced by source mac +-> "PRIMARY" -> this is a primary interface +-> "SEC mac" -> secondary mac address of source (requires preceeding +-> PRIMARY) + +The TQ value has a range from 4 to 255 with 255 being the best. +The HNA entries are showing which hosts are connected to the mesh via bat0 +or being bridged into the mesh network. +The PRIMARY/SEC values are only applied on primary interfaces + +--- In very mobile scenarios, you might want to adjust the originator interval to a lower value. This will make the mesh more responsive to topology changes, but will also increase the overhead. Please make sure
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 linus.luessing@web.de Index: README =================================================================== --- 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 + + +Usage: + +batctl vis dot {-h}{--no-HNA|-H} {--no-2nd|-2} {--numbers|-n} +or +batctl vis json {-h}{--no-HNA|-H} {--no-2nd|-2} {--numbers|-n} + + +Example: +(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] + } +} + + +Explanation: + +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/graph.dot +$ fdp -Tpng /tmp/graph.dot > 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
b.a.t.m.a.n@lists.open-mesh.org
-
Linus Lüssing