improved documentation

documentation/clients/File.md

@@ -4,7 +4,7 @@ The `file` node-type can be used to log or replay samples to / from disk.
 
 ## Configuration
 
-Every `file` node supports the following settings:
+Every `file` node supports the following special settings:
 
 #### `in` *(string: filesystem path)*
 

documentation/clients/GTFPGA.md

@@ -10,6 +10,8 @@ The PowerPC core is used to forward values between RTDS and the S2SS server.
 
 ## Configuration
 
+Every `gtfpga` node support the following special settings:
+
 #### `slot`
 
 #### `id`

documentation/clients/NGSI.md

@@ -0,0 +1,39 @@
+# OMA Next Generation Services Interface 10 {#ngsi}
+
+The `ngsi` node type implements an interface to FIWARE context brokers following the NGSI 10 RESTful HTTP API.
+
+This implementation if currently limited to the `updateContext` operation.
+Therefore only publishing updates is supported. Subscribtion or polling of events is planned for later versions.
+It's using `libcurl` and `libjansson` to communicate with the context broker over JSON.
+
+## Configuration
+
+Every `ngsi` node supports the following special settings:
+
+#### `endpoint` *(string: URL)*
+
+#### `ssl_verify` *(boolean)*
+
+#### `timeout` *(float: seconds)*
+
+#### `structure` *("flat" | "children")*
+
+  - `flat`:
+  - `children`:
+
+#### `mapping` *(array of strings)*
+
+Format for `structure = flat`: `"entityId(entityType).attributeName(attributeType)"`
+
+Format for `structure = children`: `"parentId(entityType).value(attributeType)"`
+
+### Example
+
+@todo add example from example.conf
+
+## Further reading
+
+This standard was specified by the Open Mobile Alliance (OMA).
+
+@see https://forge.fiware.org/plugins/mediawiki/wiki/fiware/index.php/FI-WARE_NGSI-10_Open_RESTful_API_Specification
+@see http://technical.openmobilealliance.org/Technical/Release_Program/docs/NGSI/V1_0-20120529-A/OMA-TS-NGSI_Context_Management-V1_0-20120529-A.pdf

documentation/clients/OPAL.md

@@ -1,4 +1,4 @@
-# OPAL-RT {#opal}
+# OPAL-RT Asynchronous Process {#opal}
 
 The communication between OPAL-RT models and the S2SS is established by using ansychronous programs.
 Asynchronous programs are are a feature of RT-LAB. They are used to exchange data between Simulink models and custom C programs.
@@ -7,11 +7,13 @@ For this purpose the C program handels IP/UDP communication via BSD sockets.
 
 ## Configuration
 
-`send_id`
+Every `opal` node supports the following special settings:
 
-`recv_id`
+#### `send_id` *(integer)*
 
-`reply`
+#### `recv_id` *(integer)*
+
+#### `reply` *(boolean)*
 
 ## Arguments for OPAL-RT block
 

documentation/clients/Socket.md

@@ -15,13 +15,15 @@ The implementation supports multiple protocols / OSI layers:
 
 ## Configuration
 
-#### `local`
+Every `socket` node supports the following special settings:
 
-#### `remote`
+#### `local` *("ip:port" | "mac:protocol")*
 
-#### `netem`
+#### `remote` *("ip:port" | "mac:protocol")*
 
-#### `layer`
+#### `netem` *(dictionary)*
+
+#### `layer` *("udp" | "ip" | "eth")*
 
 ### Example
 

server/include/ngsi.h

@@ -33,22 +33,32 @@
 struct node;
 
 struct ngsi {
+	/** The NGSI context broker endpoint URL. */
 	const char *endpoint;
+	/** An optional authentication token which will be sent as HTTP header. */
 	const char *token;
 
+	/** HTTP timeout in seconds */
 	double timeout;
+	/** Boolean flag whether SSL server certificates should be verified or not. */ 
 	int ssl_verify;
 
+	/** Structure of published entitites */
 	enum ngsi_structure {
 		NGSI_FLAT,
 		NGSI_CHILDREN
 	} structure;
 	
-	struct curl_slist *headers;	
+	/** List of HTTP request headers for libcurl */
+	struct curl_slist *headers;
+	/** libcurl handle */
 	CURL *curl;
 
+	/** The complete JSON tree which will be used for contextUpdate requests */
 	json_t *context;
+	/** A mapping between indices of the S2SS messages and the attributes in ngsi::context */
 	json_t **context_map;
+	/** The number of mappings in ngsi::context_map */
 	int context_len;
 };