From 4c7f119ce85966a88e86a0ae86ec1956a65090b1 Mon Sep 17 00:00:00 2001
From: Alexey Rybalchenko <alexryba@gmail.com>
Date: Mon, 28 Aug 2017 16:04:15 +0200
Subject: [PATCH] Configuration docs

---
 fairmq/README.md             | 10 +++-
 fairmq/docs/Configuration.md | 94 ++++++++++++++++++++++++++++++++++++
 2 files changed, 102 insertions(+), 2 deletions(-)
 create mode 100644 fairmq/docs/Configuration.md

diff --git a/fairmq/README.md b/fairmq/README.md
index 60f7648c..aa5b4424 100644
--- a/fairmq/README.md
+++ b/fairmq/README.md
@@ -6,11 +6,17 @@ Standard FairRoot is running all the different analysis tasks within one process
    1. [Topology](docs/Device.md#11-topology)
    2. [Communication Patterns](docs/Device.md#12-communication-patterns)
    3. [State Machine](docs/Device.md#13-state-machine)
+   4. [Multiple devices in the same process](docs/Device.md#15-multiple-devices-in-the-same-process)
 2. [Transport Interface](docs/Transport.md#2-transport-interface)
    1. [Message](docs/Transport.md#21-message)
       1. [Ownership](docs/Transport.md#211-ownership)
    2. [Channel](docs/Transport.md#22-channel)
    3. [Poller](docs/Transport.md#23-poller)
-3. [Development](docs/Development.md#3-development)
+3. [Configuration](docs/Configuration.md#1-configuration)
+    1. [Device Configuration](docs/Configuration.md#31-device-configuration)
+    2. [Communication Channels Configuration](docs/Configuration.md#32-communication-channels-configuration)
+        1. [JSON Parser](docs/Configuration.md#321-json-parser)
+        1. [SuboptParser](docs/Configuration.md#322-suboptparser)
+4. [Development](docs/Development.md#3-development)
    1. [Testing](docs/Development.md#31-testing)
-4. [Examples](docs/Examples.md#4-examples)
+5. [Examples](docs/Examples.md#4-examples)
diff --git a/fairmq/docs/Configuration.md b/fairmq/docs/Configuration.md
new file mode 100644
index 00000000..153a073c
--- /dev/null
+++ b/fairmq/docs/Configuration.md
@@ -0,0 +1,94 @@
+← [Back](../README.md)
+
+# 3. Configuration
+
+## 3.1 Device Configuration
+
+Devices receive configuration primarily via provided command line options (that can be extended per device).
+
+## 3.2 Communication Channels Configuration
+
+The communication channels can be configured via configuration parsers. The parser system is extendable, so if provided parsers do not suit your style, you can write your own and plug them in the configuration system.
+
+The provided parsers are:
+
+### 3.2.1 JSON Parser
+
+This parser reads channel configuration from a JSON file. Example:
+
+```JSON
+{
+    "fairMQOptions": {
+        "devices": [
+            {
+                "id": "sampler1",
+                "channels": [
+                    {
+                        "name": "data",
+                        "sockets": [
+                            {
+                                "type": "push",
+                                "method": "bind",
+                                "address": "tcp://*:5555",
+                                "sndBufSize": 1000,
+                                "rcvBufSize": 1000,
+                                "rateLogging": 1
+                            }
+                        ]
+                    }
+                ]
+            },
+            {
+                "id": "sink1",
+                "channels": [
+                    {
+                        "name": "data",
+                        "sockets": [
+                            {
+                                "type": "pull",
+                                "method": "connect",
+                                "address": "tcp://localhost:5555",
+                                "sndBufSize": 1000,
+                                "rcvBufSize": 1000,
+                                "rateLogging": 1
+                            }
+                        ]
+                    }
+                ]
+            }
+        ]
+    }
+}
+```
+
+The JSON file can contain configuration for multiple devices.
+
+- The mapping between device and configuration happens via the device ID (the `--id` parameter of the launched device and the `"id"` entry in the config).
+- Instead of `"id"`, JSON file may contain device configurations under `"key"`, which allows launched devices to share configuration, e.g.: `my-device-executable --id <device-id> --config-key <config-key>`.
+- Socket options must contain at least *type*, *method* and *address*, the rest of the values are optional and will get default values of the channel.
+- If a channel has multiple sub-channels, common properties can be defined under channel directly, and will be shared by all sub-channels, e.g.:
+
+```JSON
+"channels": [{
+    "name": "data",
+    "type": "push",
+    "method": "bind",
+    "sockets": [{
+        "address": "tcp://*:5555",
+        "address": "tcp://*:5556",
+        "address": "tcp://*:5557"
+    }]
+}]
+```
+
+### 3.2.2 SuboptParser
+
+This parser configures channels directly from the command line.
+The parser handles a comma separated key=value list format by using the getsubopt function of the standard library.
+The option key `--channel-config` can be used with the list of key/value pairs, e.g.:
+
+```
+--channel-config name=output,type=push,method=bind,address=tcp://127.0.0.1:5555
+```
+
+← [Back](../README.md)