From 8a5f907cbe791060926c638832619be41e5cb6fc Mon Sep 17 00:00:00 2001
From: Martin Geno <geno+dev@fireorbit.de>
Date: Mon, 30 Jan 2017 15:23:36 +0100
Subject: [PATCH] Some doku

---
 README.md           | 21 +++++++++++++--------
 config_example.toml | 28 +++++++++++++++++++++++++++-
 2 files changed, 40 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index b5c59be..38caea1 100644
--- a/README.md
+++ b/README.md
@@ -4,25 +4,30 @@
 [![Coverage Status](https://coveralls.io/repos/github/FreifunkBremen/respond-collector/badge.svg?branch=master)](https://coveralls.io/github/FreifunkBremen/respond-collector?branch=master)
 
 `respond-collector` is a respondd client that fetches, stores and publishes information about a Freifunk network. The goals:
-* Generating JSON for [MeshViewer](https://github.com/ffnord/meshviewer) (Works with branch [JSONv2](https://github.com/FreifunkBremen/meshviewer/tree/JSONv2))
+* Generating JSON for [Meshviewer](https://github.com/ffrgb/meshviewer)
 * Storing statistics in [InfluxDB](https://influxdata.com/) to be analyzed by [Grafana](http://grafana.org/)
-* Provide information via JSON-APIs
+* Provide a little webserver for a standalone installation with a meshviewer
 
 ## Usage
 ```
 Usage of ./respond-collector:
   -config path/to/config.toml
 ```
+## Configuration
+Read comments in [config_example.toml](config_example.toml) for more information.
+
+## Live
+* [meshviewer](https://map.bremen.freifunk.net) **Freifunk Bremen** with a patch to show state-version of `nodes.json`
+* [grafana](https://grafana.bremen.freifunk.net)  **Freifunk Bremen** show data of InfluxDB
+
+## How it works
 
-## Development
-### respond
 It sends the `gluon-neighbour-info` request and collects the answers.
 
 It will send UDP packets with multicast group `ff02:0:0:0:0:0:2:1001` and port `1001`.
 
-### nodes.Nodes
-It caches the information of the nodes and will save them periodical to a JSON file.
-The current nodes are saved default under `nodes.json`.
+If a node does not answer, it will request with the last know address under the port `1001`.
+
 
 ## Related projects
 
@@ -31,5 +36,5 @@ Collecting data from respondd:
 * [HopGlass Server](https://github.com/plumpudding/hopglass-server) written in Node.js
 
 Respondd for servers:
-* [respondd branch of ffnord-alfred-announce](https://github.com/ffnord/ffnord-alfred-announce/tree/respondd) from FreiFunkNord
+* [ffnord-alfred-announce](https://github.com/ffnord/ffnord-alfred-announce) from FreiFunkNord
 * [respondd](https://github.com/Sunz3r/ext-respondd) from Sunz3r
diff --git a/config_example.toml b/config_example.toml
index 48ad64b..48b21f9 100644
--- a/config_example.toml
+++ b/config_example.toml
@@ -1,9 +1,13 @@
+# Send respondd request to update information
 [respondd]
 enable           = true
-interface        = "eth0"
+# how oftern request per multicast
 collect_interval = "1m"
+# on which interface
+interface        = "eth0"
 
 
+# A little build-in webserver
 [webserver]
 enable  = false
 bind    = "127.0.0.1:8080"
@@ -12,9 +16,20 @@ webroot = "webroot"
 
 [nodes]
 enable         = true
+# structur of nodes.json, which to support
+# version 1 is to support legacy meshviewer (which are in master branch)
+#    i.e. https://github.com/ffnord/meshviewer/tree/master
+# version 2 is to support new version of meshviewer (which are in legacy develop branch or newer)
+#    i.e. https://github.com/ffnord/meshviewer/tree/dev
+#         https://github.com/ffrgb/meshviewer/tree/develop
 nodes_version  = 2
+# path where to store nodes.json
 nodes_path     = "/var/www/html/meshviewer/data/nodes.json"
+# path where to store graph.json
 graph_path     = "/var/www/html/meshviewer/data/graph.json"
+
+# state-version of nodes.json to store cached data,
+#  these is the directly collected respondd data
 state_path     = "/var/lib/collector/state.json"
 
 # Export nodes and graph periodically
@@ -27,9 +42,20 @@ offline_after = "10m"
 prune_after = "7d"
 
 
+# Save collected data to InfluxDB
+# there would be the following measurments:
+#  node: store node spezific data i.e. clients memory, airtime
+#  global: store global data, i.e. count of clients and nodes
+#  firmware: store count of nodes tagged with firmware
+#  model: store count of nodes tagged with hardware model
 [influxdb]
 enable   = false
 address  = "http://localhost:8086"
 database = "ffhb"
 username = ""
 password = ""
+# cleaning data of measurement node,
+#   which are older than 7d
+delete_after = "7d"
+#   how often run the cleaning
+delete_interval = "1h"