From c1e2711ff891d17fb3a38a33f65d3ce1cd4cbb17 Mon Sep 17 00:00:00 2001 From: Steffen Vogel Date: Tue, 22 Sep 2015 15:27:23 +0200 Subject: [PATCH] improved documentation --- documentation/clients/File.md | 2 +- documentation/clients/GTFPGA.md | 2 ++ documentation/clients/NGSI.md | 39 +++++++++++++++++++++++++++++++++ documentation/clients/OPAL.md | 10 +++++---- documentation/clients/Socket.md | 10 +++++---- server/include/ngsi.h | 12 +++++++++- 6 files changed, 65 insertions(+), 10 deletions(-) create mode 100644 documentation/clients/NGSI.md diff --git a/documentation/clients/File.md b/documentation/clients/File.md index d77c298cb..2551ec89c 100644 --- a/documentation/clients/File.md +++ b/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)* diff --git a/documentation/clients/GTFPGA.md b/documentation/clients/GTFPGA.md index 015942eca..1a5db6722 100644 --- a/documentation/clients/GTFPGA.md +++ b/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` diff --git a/documentation/clients/NGSI.md b/documentation/clients/NGSI.md new file mode 100644 index 000000000..a08d2f512 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/documentation/clients/OPAL.md b/documentation/clients/OPAL.md index 81bc4e68c..e115f38f5 100644 --- a/documentation/clients/OPAL.md +++ b/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 diff --git a/documentation/clients/Socket.md b/documentation/clients/Socket.md index 491242593..2748cb0e8 100644 --- a/documentation/clients/Socket.md +++ b/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 diff --git a/server/include/ngsi.h b/server/include/ngsi.h index f8d08a060..52e321bd3 100644 --- a/server/include/ngsi.h +++ b/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; };