From cbd1982f6eea463415ce83105e56f01d35694fce Mon Sep 17 00:00:00 2001
From: Steffen Vogel <stvogel@eonerc.rwth-aachen.de>
Date: Wed, 10 Feb 2016 19:22:06 +0100
Subject: [PATCH] improving documentation

---
 doc/nodes/NGSI.md   | 11 ++++++-----
 doc/nodes/OPAL.md   | 10 ++++++++--
 doc/nodes/Socket.md | 17 +++++++++++++++--
 3 files changed, 29 insertions(+), 9 deletions(-)

diff --git a/doc/nodes/NGSI.md b/doc/nodes/NGSI.md
index 5935de330..b44e42063 100644
--- a/doc/nodes/NGSI.md
+++ b/doc/nodes/NGSI.md
@@ -1,4 +1,4 @@
-# OMA Next Generation Services Interface 10 {#ngsi}
+# OMA Next Generation Services Interface {#ngsi}
 
 The `ngsi` node type implements an interface to FIWARE context brokers following the NGSI 10 RESTful HTTP API.
 
@@ -24,7 +24,7 @@ Every `ngsi` node supports the following special settings:
 
 #### `mapping` *(array of strings)*
 
-Format `AttributeName(AttributeType)`
+Example: `AttributeName(AttributeType) MetadataName1(MetadataType1)=MetadataValue1 MetadataName2(MetadataType2)=MetadataValue2 ...`
 
 ### Example
 
@@ -42,9 +42,10 @@ Format `AttributeName(AttributeType)`
 			timeout = 5,				# Timeout of HTTP request in seconds (default is 1)
 			verify_ssl = false,			# Verification of SSL server certificates (default is true)
 	
-			mapping = [				# Format: "AttributeName(AttributeType)"
-				PTotalLosses(MW)",
-				"QTotalLosses(Mvar)"
+			mapping = [
+				"PTotalLosses(MW)",
+				"QTotalLosses(Mvar)",
+				"Phase(rad) min(rad)=0 max(rad)=3.141"
 			]
 		}
 	}
diff --git a/doc/nodes/OPAL.md b/doc/nodes/OPAL.md
index 16f9354e2..04c5c39a6 100644
--- a/doc/nodes/OPAL.md
+++ b/doc/nodes/OPAL.md
@@ -1,9 +1,15 @@
 # OPAL-RT Asynchronous Process {#opal}
 
-The communication between OPAL-RT models and the S2SS is established by using ansychronous programs.
+The communication between OPAL-RT models and the S2SS is established by using asynchronous programs.
 Asynchronous programs are are a feature of RT-LAB. They are used to exchange data between Simulink models and custom C programs.
+There are two ways to exchange sample values with an OPAL-RT simulator:
 
-For this purpose the C program handels IP/UDP communication via BSD sockets.
+1. Use our adapted version of OPAL-RT's AsyncIP example for asynchronous processes (see `clients/opal`)
+   In this mode, OPAL will send sample data via UDP to S2SS. S2SS has to use the `socket` node-type.
+2. Run S2SS as an asynchronous process itself. This is a highly experimental feature and implemented in the node-type `opal`.
+   It requires a 32-bit version of the `s2ss-server`. Data exchange is then handled using OPAL-RT's libAsyncApi.
+
+The following description applies only to the `opal` node-type:
 
 ## Configuration
 
diff --git a/doc/nodes/Socket.md b/doc/nodes/Socket.md
index eefa3eccf..308bfc881 100644
--- a/doc/nodes/Socket.md
+++ b/doc/nodes/Socket.md
@@ -1,4 +1,4 @@
-# Socket {#socket}
+# Berkely BSD Sockets {#socket}
 
 The socket node-type is the most comprehensive and complex one.
 It allows to send and receive simulation data over the network.
@@ -23,6 +23,19 @@ Every `socket` node supports the following special settings:
 
 #### `netem` *(dictionary)*
 
+Enables and configures the network emulation qeueing discipline.
+See below for a more detailed description of this feature.
+
+	netem = {				# Network emulation settings
+						# Those settings can be specified for each node invidually!
+		delay		= 100000,	# Additional latency in microseconds
+		jitter		= 30000,	# Jitter in uS
+		distribution	= "normal",	# Distribution of delay: uniform, normal, pareto, paretonormal
+		loss		= 10		# Packet loss in percent
+		duplicate	= 10,		# Duplication in percent
+		corrupt 	= 10		# Corruption in percent
+	}
+
 #### `layer` *("udp" | "ip" | "eth")*
 
 ### Example
@@ -87,7 +100,7 @@ This allows us to reduce the amount of conversions during one transfer.
 
 S2SS supports the emulation of wide-area network characterisics.
 
-This emulation can be configured on a per-node basis for **outgoing** / **egress** data only.
+This emulation can be configured on a per-node basis for **outgoing** (egress) data only.
 Incoming data is not processed by the network emulation!
 
 This network emulation is handled by Linux' [netem queuing discipline](http://www.linuxfoundation.org/collaborate/workgroups/networking/netem) which is part of the traffic control subsystem.