From e6363d466f468cf0fd2c3650b4590028f45110e4 Mon Sep 17 00:00:00 2001
From: Anjan Chanda <anjan.chanda@iopsys.eu>
Date: Wed, 29 Jul 2020 12:35:07 +0200
Subject: [PATCH] update README
---
README.md | 91 +++++++++++++++++++++++++++++++------------------------
1 file changed, 51 insertions(+), 40 deletions(-)
diff --git a/README.md b/README.md
index 8968474..52ba96f 100644
--- a/README.md
+++ b/README.md
@@ -1,68 +1,70 @@
-# topology
+# map-topology
-ieee1905 stack provides methods which can be used by an application to build network topology with respect to a node in the network.
+This package provides the **topologyd** daemon.
## Overview
-map-topology daemon (topo1905d), as we speak, provides two ubus methods as mentioned in the UBUS API section below to build and dump network topology map of the node under test.
+The **topologyd** daemon constructs full topology of a IEEE1905 enabled Multi-AP network.
+It provides the `topology` UBUS object and methods ( *see UBUS API section below* ) for building and showing the full topology of a network.
-The daemon uses 1905 al-mac of the node as a starting point to find its immediate as well as far-1905 and non-1905 neighbors to build a complete topology map around the node.
+**topologyd** uses IEEE1905 AL macaddress of a node, where it is running, as the starting (or Root) node. It then discovers it's immediate neighbors, the next-hop neighbors, the next to next-hop neighbors, and so on... until there are no more neighbor nodes in the network, to build the full topology around the starting node.
-Topology is built every 60 seconds and the "dump_tree" ubus method displays the results of the last built topology within the 60 second period.
+>By default, **topologyd** rebuilds the topology every 60 seconds.
-To build a fresh topology, ubus method "build_tree" should be used. See Usage below
+To (re)build topology, the UBUS method "*refresh*" can be used. See Usage below -
-map-topology uses following algorithm to build network topology using the ieee1905 stack with an assumption that the information provided by the underlying ieee1905 stack is up-to-date.
+Following algorithm is used to build the full topology -
-At any node 'P' in the network -
+````
+At any node 'P' in the network:
-Intial state:
+Intial state :
Nbr(P) = {N0,..Nn} <== immediate neighbors of P.
-
G{P, N0,..Nn} <== graph of all known nodes at P.
-<u>Step 1</u>:
-
- for all Ni in G:
-
- Send Topology Request to Ni.
-
-<u>Step 2:</u>
-Read Topology Response from Ni.
+Step 1 :
+ for all Ni in G :
+ Send Topology Request to Ni.
-if Nbr(Ni) is not in G:
+Step 2 :
+ Read Topology Response from Ni.
-Insert Nbr(Ni) in G
+ if Nbr(Ni) is not in G :
+ Insert Nbr(Ni) in G
-<u>Step 3:</u>
+Step 3 :
+ Repeat Step 1-2 until no new Nbr(Ni) can be inserted in 'G'.
-Repeat Step 1-2 until no new Nbr(Ni) can be inserted in G.
+````
-### Ubus API
+### UBUS API
-This is a verbose print of all the methods provided by map-topology over ubus :
+map-topology provides the `topology` UBUS object with following methods :
````bash
-'topo1905' @fc2af0e9
- "build_tree":{}
- "dump_tree":{}
+'topology' @fc2af0e9
+ "refresh":{}
+ "status":{}
+ "refresh":{}
+ "changelog":{}
````
### Usage
-On successful registration, map-plugin broadcast an ubus event on arrival of
-multiAP specific CMDUs in below format.
-
````bash
-root@iopsys:~# ubus call topo1905 build_tree
+#To (re)build topology -
+root@iopsys:~$ ubus call topology refresh
+
+#To get status (can be "incomplete" or "available") -
+root@iopsys:~$ ubus call topology status
{
- "status": true
+ "status": "incomplete"
}
-
-root@iopsys:~# ubus call topo1905 dump_tree
+#To show current topology -
+root@iopsys:~$ ubus call topology dump
{
"Nodes": [
{
@@ -78,16 +80,25 @@ root@iopsys:~# ubus call topo1905 dump_tree
}
]
}
-````
-
-### Limitations
- * Network topology includes only neighbor's mac address information as of now.
+#To show the topology changelogs -
+root@iopsys:~$ ubus call topology changelog
+{
+ "changelog": [
+ {
+ <TODO>
+ },
+ {
+ <TODO>
+ }
+ ]
+}
+````
### Testing
-- Tested only with two ieee1905 devices in the network.
-- Tested with only one al-mac interface enabled.
+- Tested with two IEEE1905 devices in the network.
+- Tested with only one IEEE1905 AL macaddress interface.
### Dependencies
--
GitLab