respondd: extend README

2016-06-18 16:20:42 +02:00 · 2016-06-18 16:20:42 +02:00 · fed34e05cd
parent 37c7cebf10
commit fed34e05cd
1 changed files with 107 additions and 0 deletions
--- a/net/respondd/README.md
+++ b/net/respondd/README.md
@ -1,3 +1,110 @@
+# What is respondd?
+
+## Introduction
+respondd is a server distributing information within a network.
+
+For doing so, respondd spawns a UDP socket (in Gluon 1001/udp), optionally joining a multicast group. When a request is received, the information requested is transmitted to the requester.
+
+All information is organized in a non-hierarchical namespace. Each entry identifies a *request name* (e.g. `statistics`, `nodeinfo`, ...) implemented by at least one "provider" C module.
+The respond is the result of merging the outputs of all providers for the given request name.
+
+Some providers are implemented in [/package/gluon-respondd](https://github.com/freifunk-gluon/gluon/tree/master).
+
+## Usage
+```
+respondd [-p <port>] [-g <group> -i <if0> [-i <if1> ..]] [-d <dir>]
+  -p <int>         port number to listen on
+  -g <ip6>         multicast group, e.g. ff02::2:1001
+  -i <string>      interface on which the group is joined
+  -d <string>      data provider directory (default: current directory)
+  -h               this help
+```
+
+## Procotol
+Request and response are encoded as byte strings. These strings are sent as UDP packets. Fragmentation is not supported (except by the IP stack), responses are compressed using the *deflate* algorithm.
+
+- The request is the the word '`GET`' followed by any number of request name, separated by spaces.
+- The response is a compressed JSON document. The top level object will contain a property for each
+  requested name, the rest of the structure is determined by the actual data.
+- (Using just a single request name, without '`GET`', as request will return the data uncompressed
+  and without an enclosing object. This kind of request is deprecated.)
+
+### Example
+Requesting `nodeinfo` as implemented in the Gluon modules.
+
+#### Request
+```
+GET nodeinfo
+```
+
+#### Response (decompressed)
+```json
+{
+  "nodeinfo": {
+    "software": {
+      "autoupdater": {
+        "branch": "stable",
+        "enabled": true
+      },
+      "batman-adv": {
+        "version": "2015.1",
+        "compat": 15
+      },
+      "fastd": {
+        "version": "v17",
+        "enabled": false
+      },
+      "firmware": {
+        "base": "gluon-v2016.1.5-8-gdeac14e",
+        "release": "20160615"
+      },
+      "status-page": {
+        "api": 1
+      }
+    },
+    "network": {
+      "addresses": [
+        "fda0:cab1:e1e5:5116:eade:27ff:fe65:a5af",
+        "fe80::eade:27ff:fe65:a5af",
+        "2a03:2260:3011:1160:eade:27ff:fe65:a5af"
+      ],
+      "mesh": {
+        "bat0": {
+          "interfaces": {
+            "wireless": [
+              "ea:e3:29:65:a5:af",
+              "ea:e3:28:65:a5:af"
+            ],
+            "other": [
+              "ea:df:27:65:a5:af"
+            ]
+          }
+        }
+      },
+      "mac": "e8:de:27:65:a5:af"
+    },
+    "location": {
+      "latitude": 51.10727924,
+      "longitude": 7.00933367
+    },
+    "owner": {
+      "contact": "me@petabyteboy.de"
+    },
+    "system": {
+      "site_code": "lln"
+    },
+    "node_id": "e8de2765a5af",
+    "hostname": "PetaByteBoy",
+    "hardware": {
+      "model": "TP-Link TL-WDR3600 v1",
+      "nproc": 1
+    }
+  }
+}
+```
+
+## Implementing modules
+
 respondd providers are C modules (shared objects). These modules should include
 \<json-c/json.h> and \<respondd.h>, the latter of which provides the following definitions: