starting to work on documentation

documentation/Clients.md

@@ -3,9 +3,8 @@
 @subpage gtfpga
 @subpage opal
 
-Every server needs clients which they serve. In case of S2SS these clients are called _nodes_.
+Every server needs clients which act as sinks / sources for simulation data. In case of S2SS these clients are called _nodes_.
 
-Its a goal of this project to provide connectors so several proven simulators.
 Take a look at the `clients/` directory for them:
 
  - RTDS UDP Network Card ?

documentation/Configuration.md

@@ -0,0 +1,67 @@
+# Configuration
+
+The S2SS server configuration is completly done in a single file.
+Take a look at the example configuration: `server/etc/example.conf`.
+
+The configuration file mainly consists of three sections:
+
+### Global
+
+The global section consists of some global configuration parameters:
+
+`debug` expects an integer number (0-10) which determines the verbosity of debug messages during the execution of the server.
+Use this with care! Producing a lot of IO might decrease the performance of the server.
+Omitting this setting or setting it to zero will disable debug messages completely.
+
+`stats` specifies the rate in which statistics about the actives paths will be printed to the screen.
+Setting this value to 5, will print 5 lines per second.
+A line of includes information such as:
+  - Source and Destination of path
+  - Messages received
+  - Messages sent
+  - Messaged dropped
+
+The `affinity` setting allows to restrict the exeuction of the daemon to certain CPU cores.
+This technique, also called 'pinning', improves the determinism of the server by isolating the daemon processes on exclusive cores.
+
+The `priority` setting allows to adjust the scheduling priority of the deamon processes.
+By default, the daemon uses a real-time optimized FIFO scheduling algorithm.
+
+### Nodes
+
+The node section is a directory of nodes (clients) which are connected to the S2SS instance.
+The directory is indexed by the name of the node:
+
+    nodes = {
+        "sintef_node" = {
+	    type = "udp"
+	    ....
+	}
+    }
+
+There are multiple diffrent type of nodes. But all types have the following settings in common:
+
+`type` sets the type of the node. This should be one of:
+  - `udp`
+  - `ip`
+  - `gtfpga`
+  - `opal`
+  - `file`
+
+For a detailed description of the node-specific settings, please
+
+### Paths
+
+The path section consists of a list of paths.
+Every path is allowed to have the following settings:
+
+The `in` and `out` settings expect the name of the source and destination node.
+The `out` setting itself is allowed to be list of nodes.
+This enables 1-to-n distribution of simulation data.
+
+The optional `enabled` setting can be used to temporarily disable a path.
+If omitted, the path is enabled by default.
+
+By default, the path is unidirectional. Meaning, that it only forwards samples from the source to the destination.
+Sometimes a bidirectional path is needed.
+This can be accomplished by setting `reverse` to `true`.

documentation/Contributors.md

@@ -1,3 +0,0 @@
-The following persons have been working on the S2SS:
-
-- Steffen Vogel <StVogel@eonerc.rwth-aachen.de>

documentation/Mainpage.md

@@ -1,32 +1,49 @@
-S2SS is a client/server application based on UDP/IP to connect simulation equipment/software such as:
+S2SS is a client/server application to connect simulation equipment and software such as:
 
- - OPAL-RT,
- - RTDS,
+ - OPAL-RT eMegaSim,
+ - RTDS GTFPGA cards,
  - Simulink,
  - LabView,
- - custom made equipment,
  - and FPGA models.
 
-It's designed with focus on very low latency to achieve almost realtime communication.
-S2SS is used in distributed- and co-simulation scenarios and developed for the field of power grid simulation at the EON Energy Research Centre in Aachen, Germany.
+It's designed with a focus on very low latency to achieve almost realtime exchange of simulation data.
+S2SS is used in distributed- and co-simulation scenarios and developed for the field of power grid simulation at the EON Energy Research Center in Aachen, Germany.
 
 ## Overview
 
-The project consists of a server and several client applications.
-Both server-to-server and direct client-to-client communication is possible.
-All communication links use the same message protocol to exchange their measurement values.
+The project consists of a server daemon and several client modules which are documented here.
 
 ### Server
 
-For optimal performance the server is implemented in lowlevel C and makes use of several Linux-specific realtime features.
+The server simply acts as a gateway to forward simulation data from one client to another.
+Furthermore, it collects statistics, monitors the quality of service and handles encryption or tunneling through VPNs.
+
+For optimal performance the server is implemented in low-level C and makes use of several Linux-specific realtime features.
+The primary design goal was to make the behaviour of the system as deterministic as possible.
+
+Therefore, it's advisable to run the server component on a [RT_PREEMPT](https://rt.wiki.kernel.org/index.php/CONFIG_PREEMPT_RT_Patch) patched version of Linux. In our environment, we use Fedora-based distribution which has been stripped to the bare minimum (no GUI, only a few background processes).
+
+The server is a multi-threaded application.
 
 ### Clients
 
+There are two types of clients:
+
+1.  The server handles diffrent types of nodes.
+    The most commonly used node-type is the 'socket' type which allows communication over network links (UDP, raw IP, raw Ethernet frames).
+    But there are also other specialized node types to retreive or send data to equipemnt, which is directly connected to or running on the server itself.
+    An example for such a node is the 'gtfpga' type which directly fetches and pushes data to a PCIe card.
+    Or the 'file' type which logs or replays simulation data from the harddisk.
+
+2. An other way to connect simulation equipment is by using a client-application which itself sends the data over the network to the S2SS server.
+   In this scenario, the S2SS server uses the 'socket' node-type to communicate with the client-application.
+
+Usually, new clients / equipemnt should be implemented as a new node-type as part of the S2SS server.
+Using a dedicated client-application which communicates via the 'socket' type is deprecated because it leads to code duplication.
+
 ## Contact
 
-This project is developed at the [Institute for Automation of Complex Power Systems](www.acs.eonerc.rwth-aachen.de) (ACS) at the EON Energy Research Center (EONERC) at the [RWTH University](http://www.rwth-aachen.de) in Aachen.
+This project is developed at the [Institute for Automation of Complex Power Systems](www.acs.eonerc.rwth-aachen.de) (ACS), EON Energy Research Center (EONERC) at the [RWTH University](http://www.rwth-aachen.de) in Aachen, Germany.
 
  - Steffen Vogel <StVogel@eonerc.rwth-aachen.de>
  - Marija Stevic <MStevic@eonerc.rwth-aachen.de>
-
-

documentation/Setup.md

@@ -11,7 +11,6 @@
 Install libraries including developement headers for:
 
  - _libconfig_ for parsing the config file
- - _libsodium_ for message authentification and signing
 
 	$ sudo apt-get install iproute2 libconfig-dev libsodium-dev
 or:

documentation/clients/File.md

@@ -0,0 +1 @@
+# File

documentation/clients/Socket.md

@@ -0,0 +1,12 @@
+# Socket
+
+The socket node type is the most comprehensive one. It allows to send / receive simulation data over the network.
+Internally it uses the well known BSD sockets.
+
+The implementation allows to chose the OSI layer which should:
+
+ - Layer 1: Raw Ethernet Frames (no routing!)
+ - Layer 2: Raw IP (internet / VPN routing possible)
+ - Layer 3: UDP encapsulation
+ 
+