From b70fdaac9a4858a799eabeebdcdb612ad65a576b Mon Sep 17 00:00:00 2001 From: Steffen Vogel Date: Fri, 11 Dec 2015 19:20:50 +0100 Subject: [PATCH] updated documentation --- doc/Clients.md | 19 ----------- doc/Nodes.md | 22 +++++++++++++ doc/Tools.md | 56 +++++++++++++++++++++++++++----- doc/Usage.md | 35 ++++++++++---------- doc/clients/GTFPGA.md | 32 ------------------ doc/{clients => nodes}/File.md | 44 +++++++++++++------------ doc/nodes/GTFPGA.md | 34 +++++++++++++++++++ doc/{clients => nodes}/NGSI.md | 30 +++++++++-------- doc/{clients => nodes}/OPAL.md | 18 +++++----- doc/{clients => nodes}/Socket.md | 28 ++++++++-------- doc/nodes/WebSocket.md | 22 +++++++++++++ 11 files changed, 206 insertions(+), 134 deletions(-) delete mode 100644 doc/Clients.md create mode 100644 doc/Nodes.md delete mode 100644 doc/clients/GTFPGA.md rename doc/{clients => nodes}/File.md (82%) create mode 100644 doc/nodes/GTFPGA.md rename doc/{clients => nodes}/NGSI.md (67%) rename doc/{clients => nodes}/OPAL.md (77%) rename doc/{clients => nodes}/Socket.md (82%) create mode 100644 doc/nodes/WebSocket.md diff --git a/doc/Clients.md b/doc/Clients.md deleted file mode 100644 index 288058399..000000000 --- a/doc/Clients.md +++ /dev/null @@ -1,19 +0,0 @@ -# Clients - -@subpage gtfpga -@subpage opal -@subpage file -@subpage socket -@subpage ngsi - -Every server needs clients which act as sinks / sources for simulation data. In case of S2SS these clients are called _nodes_. - -Take a look at the `clients/` directory for them: - - - RTDS via GTFPGA and UDP - - RTDS via GTFPGA and PCIexpress - - OPAL via Asynchronous Process and UDP - - OPAL via Asynchronous Process and Shared memory - - NGSI 9/10 (FIRWARE context broker) - - Labview (*planned*) - - Simulink (*planned*) diff --git a/doc/Nodes.md b/doc/Nodes.md new file mode 100644 index 000000000..54d7048ac --- /dev/null +++ b/doc/Nodes.md @@ -0,0 +1,22 @@ +# Nodes {#nodes} + +Every server needs clients which act as sinks / sources for simulation data. In case of S2SS these clients are called _nodes_. +Every node is an instance of a node type. S2SS currently supports the following node types: + +@subpage gtfpga +@subpage opal +@subpage file +@subpage socket +@subpage websocket +@subpage ngsi + +Use cases: + + - RTDS via GTFPGA and UDP (`socket`) + - RTDS via GTFPGA and PCIexpress (`gtfpga`) + - OPAL via Asynchronous Process and UDP (`socket`) + - OPAL via Asynchronous Process and Shared memory (`opal`) + - NGSI 9/10 (FIRWARE context broker, `ngsi`) + - WebSockets for live monitoring (`websocket`) + - Labview (*planned*) + - Simulink (*planned*) diff --git a/doc/Tools.md b/doc/Tools.md index a59dcc538..3751e0d6f 100644 --- a/doc/Tools.md +++ b/doc/Tools.md @@ -1,29 +1,67 @@ # Tools {#tools} -S2SS comes with a couple of tools to test and debug: +S2SS comes with a couple of tools to test and debug connectivity and configurations. +All S2SS tools are available as subcommands to the `s2ss` wrapper: + +### `s2ss server` - 1. `send` can be used to send samples from STDIN to a node - 2. `receive` can be used to read samples from a node and write it to STDOUT - 3. `random` writes random sample data to STDOUT +Starts the simulator to simulator server. The server acts as a central gateway to forward simulation data. + + Usage: s2ss-server CONFIG + CONFIG is a required path to a configuration file + + Supported node types: + - file: support for file log / replay node type + - socket: Network socket (libnl3) + - gtfpga: GTFPGA PCIe card (libpci) + - ngsi: OMA Next Generation Services Interface 10 (libcurl, libjansson, libuuid) + - websocket: Send and receive samples of a WebSocket connection (libwebsockets) + +### `s2ss pipe` + +The `pipe` subcommand allows to read and write samples to `stdin` / `stdout`. + + Usage: s2ss-pipe CONFIG [-r] NODE + CONFIG path to a configuration file + NODE the name of the node to which samples are sent and received from + -r swap read / write endpoints) + +### `s2ss signal` + +The `signal` subcommand is a signal generator which writes samples to `stdout`. +This command can be combined with the `pipe` subcommand. + + Usage: s2ss-signal SIGNAL VALUES RATE [LIMIT] + SIGNAL is on of: mixed random sine triangle square + VALUES is the number of values a message contains + RATE how many messages per second + LIMIT only send LIMIT messages + +### `s2ss test` + + Usage: s2ss-test CONFIG TEST NODE [ARGS] + CONFIG path to a configuration file + TEST the name of the test to execute: 'rtt' + NODE name of the node which shoud be used ## Examples 1. Start server: - $ ./server etc/example.conf + $ s2ss server etc/example.conf 2. Receive/dump data to file - $ ./receive etc/example.conf node_name > dump.csv + $ s2ss pipe etc/example.conf node_name > dump.csv 3. Replay recorded data: - $ ./send etc/example.conf -r node_name < dump.csv + $ s2ss pipe etc/example.conf -r node_name < dump.csv 4. Send random generated values: - $ ./random 4 100 | sudo ./send etc/example.conf destination_node + $ s2ss signal random 4 100 | s2ss pipe etc/example.conf destination_node 5. Test ping/pong latency: - $ ./test latency etc/example.conf test_node \ No newline at end of file + $ s2ss test latency etc/example.conf test_node \ No newline at end of file diff --git a/doc/Usage.md b/doc/Usage.md index 8cf8abaf8..a3501510e 100644 --- a/doc/Usage.md +++ b/doc/Usage.md @@ -1,17 +1,17 @@ # Usage {#usage} -The S2SS server (`server`) expects the path to a configuration file as a single argument. +The S2SS server (`s2ss server`) expects the path to a configuration file as a single argument. - Usage: ./server CONFIG - CONFIG is a required path to a configuration file - - Simulator2Simulator Server 0.1-d7de19c (Jun 4 2014 02:50:13) - Copyright 2014, Institute for Automation of Complex Power Systems, EONERC - Steffen Vogel + Usage: ./s2ss-server CONFIG + CONFIG is a required path to a configuration file + + Simulator2Simulator Server 0.1-d7de19c (Jun 4 2014 02:50:13) + Copyright 2015, Institute for Automation of Complex Power Systems, EONERC + Steffen Vogel The server requires root privileges for: - - Enable the realtime fifo scheduler + - Enable the realtime FIFO scheduler - Increase the task priority - Configure the network emulator (netem) - Change the SMP affinity of threads and network interrupts @@ -26,16 +26,17 @@ The server requires root privileges for: 2. Connect to S2SS server -| Setting | Value | -| :------- | :------------- | -| IP | 130.134.169.31 | -| Port | 22 | -| Protocol | SSH | -| User | acs-admin | +| Setting | Value | +| :------- | :-------------- | +| IP | 130.134.169.31 | +| Port | 22 | +| Protocol | SSH | +| User | root | +| Password | *please ask msv | 3. Go to S2SS directory - $ cd /home/acs-admin/msv/s2ss/server/ + $ cd /s2ss/ 4. Edit configuration file @@ -47,9 +48,7 @@ The server requires root privileges for: 5. Start server - $ sudo ./server etc/opal-test.conf - - - `sudo` starts the server with super user priviledges + $ s2ss server etc/opal-test.conf 6. Terminate server by pressing Ctrl+C diff --git a/doc/clients/GTFPGA.md b/doc/clients/GTFPGA.md deleted file mode 100644 index 9eda5944c..000000000 --- a/doc/clients/GTFPGA.md +++ /dev/null @@ -1,32 +0,0 @@ -# GTFPGA {#gtfpga} - -The GTFPGA card is an extension card for simulator racks from RTDS. -The manufacturer provides a VHDL module to exchange data via fiber optics between the GTFPGA and GPC cards. - -The GTFPGA card is based on the Xilinx ML507 evaluation board. -This board consists of a Virtex 5 FPGA, Ethernet and Fiberoptic MACs and an integrated PowerPC core. - -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` - -#### `rate` - -### Example - - gtfpga_node = { - type = "gtfpga", - - ### The following settings are specific to the gtfpga node-type!! ### - - slot = "01:00.0", # The PCIe slot location (see first column in 'lspci' output) - id = "1ab8:4005", # The PCIe vendor:device ID (see third column in 'lspci -n' output) - - rate = 1 - } diff --git a/doc/clients/File.md b/doc/nodes/File.md similarity index 82% rename from doc/clients/File.md rename to doc/nodes/File.md index 3015ea6f9..9b37a6aaa 100644 --- a/doc/clients/File.md +++ b/doc/nodes/File.md @@ -77,30 +77,32 @@ Expects the input data in splitted format. ### Example - file_node = { - type = "file", + nodes = { + file_node = { + type = "file", - ### The following settings are specific to the file node-type!! ### - - in = { - path = "logs/input.log", # These options specify the path prefix where the the files are stored - mode = "w+", # The mode in which files should be opened (see open(2)) + ### The following settings are specific to the file node-type!! ### + + in = { + path = "logs/input.log", # These options specify the path prefix where the the files are stored + mode = "w+", # The mode in which files should be opened (see open(2)) - epoch_mode = "direct" # One of: direct (default), wait, relative, absolute - epoch = 10 # The interpretation of this value depends on epoch_mode (default is 0). - # Consult the documentation of a full explanation - - rate = 2.0 # A constant rate at which the lines of the input files should be read - # A missing or zero value will use the timestamp in the first column - # of the file to determine the pause between consecutive lines. + epoch_mode = "direct" # One of: direct (default), wait, relative, absolute + epoch = 10 # The interpretation of this value depends on epoch_mode (default is 0). + # Consult the documentation of a full explanation + + rate = 2.0 # A constant rate at which the lines of the input files should be read + # A missing or zero value will use the timestamp in the first column + # of the file to determine the pause between consecutive lines. - splitted = false - }, - out = { - path = "logs/output_%F_%T.log" # The output path accepts all format tokens of (see strftime(3)) - mode = "a+" # You might want to use "a+" to append to a file - - split = 100, # Split output file every 100 MB + splitted = false + }, + out = { + path = "logs/output_%F_%T.log" # The output path accepts all format tokens of (see strftime(3)) + mode = "a+" # You might want to use "a+" to append to a file + + split = 100, # Split output file every 100 MB + } } } diff --git a/doc/nodes/GTFPGA.md b/doc/nodes/GTFPGA.md new file mode 100644 index 000000000..28eff8282 --- /dev/null +++ b/doc/nodes/GTFPGA.md @@ -0,0 +1,34 @@ +# GTFPGA {#gtfpga} + +The GTFPGA card is an extension card for simulator racks from RTDS. +The manufacturer provides a VHDL module to exchange data via fiber optics between the GTFPGA and GPC cards. + +The GTFPGA card is based on the Xilinx ML507 or ML605 evaluation boards. +This board consists of a Virtex 5 FPGA, Ethernet and Fiberoptic MACs and an hard macro PowerPC core. + +This node type uses the PCIexpress bus to communicate with the FPGA cards. + +## Configuration + +Every `gtfpga` node support the following special settings: + +#### `slot` + +#### `id` + +#### `rate` + +### Example + + nodes = { + gtfpga_node = { + type = "gtfpga", + + ### The following settings are specific to the gtfpga node-type!! ### + + slot = "01:00.0", # The PCIe slot location (see first column in 'lspci' output) + id = "1ab8:4005", # The PCIe vendor:device ID (see third column in 'lspci -n' output) + + rate = 1 + } + } diff --git a/doc/clients/NGSI.md b/doc/nodes/NGSI.md similarity index 67% rename from doc/clients/NGSI.md rename to doc/nodes/NGSI.md index 6e1ac9ddb..48d34438b 100644 --- a/doc/clients/NGSI.md +++ b/doc/nodes/NGSI.md @@ -28,23 +28,25 @@ Format `AttributeName(AttributeType)` ### Example - ngsi_node = { - type = "ngsi", + nodes = { + ngsi_node = { + type = "ngsi", - ### The following settings are specific to the ngsi node-type!! ### - - endpoint = "http://46.101.131.212:1026",# The HTTP REST API endpoint of the FIRWARE context broker + ### The following settings are specific to the ngsi node-type!! ### + + endpoint = "http://46.101.131.212:1026",# The HTTP REST API endpoint of the FIRWARE context broker - entity_id = "S3_ElectricalGrid", - entity_type = "ElectricalGridMonitoring", + entity_id = "S3_ElectricalGrid", + entity_type = "ElectricalGridMonitoring", - 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)" - ] + 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)" + ] + } } ## Further reading diff --git a/doc/clients/OPAL.md b/doc/nodes/OPAL.md similarity index 77% rename from doc/clients/OPAL.md rename to doc/nodes/OPAL.md index 692019ad9..16f9354e2 100644 --- a/doc/clients/OPAL.md +++ b/doc/nodes/OPAL.md @@ -17,14 +17,16 @@ Every `opal` node supports the following special settings: ### Example - opal_node = { # The server can be started as an Asynchronous process - type = "opal", # from within an OPAL-RT model. - - ### The following settings are specific to the opal node-type!! ### - - send_id = 1, # It's possible to have multiple send / recv Icons per model - recv_id = 1, # Specify the ID here. - reply = true + nodes = { + opal_node = { # The server can be started as an Asynchronous process + type = "opal", # from within an OPAL-RT model. + + ### The following settings are specific to the opal node-type!! ### + + send_id = 1, # It's possible to have multiple send / recv Icons per model + recv_id = 1, # Specify the ID here. + reply = true + } } ## Arguments for OPAL-RT block diff --git a/doc/clients/Socket.md b/doc/nodes/Socket.md similarity index 82% rename from doc/clients/Socket.md rename to doc/nodes/Socket.md index 4d7817a72..7104e741d 100644 --- a/doc/clients/Socket.md +++ b/doc/nodes/Socket.md @@ -27,22 +27,24 @@ Every `socket` node supports the following special settings: ### Example - udp_node = { # The dictionary is indexed by the name of the node. - type = "socket", # Type can be one of: socket, opal, file, gtfpga, ngsi - # Start the server without arguments for a list of supported node types. + nodes = { + udp_node = { # The dictionary is indexed by the name of the node. + type = "socket", # Type can be one of: socket, opal, file, gtfpga, ngsi + # Start the server without arguments for a list of supported node types. - ### The following settings are specific to the socket node-type!! ### - - layer = "udp" # Layer can be one of: - # udp Send / recv UDP packets - # ip Send / recv IP packets - # eth Send / recv raw Ethernet frames (IEEE802.3) - + ### The following settings are specific to the socket node-type!! ### + + layer = "udp" # Layer can be one of: + # udp Send / recv UDP packets + # ip Send / recv IP packets + # eth Send / recv raw Ethernet frames (IEEE802.3) + - local = "127.0.0.1:12001", # This node only received messages on this IP:Port pair - remote = "127.0.0.1:12000" # This node sents outgoing messages to this IP:Port pair + local = "127.0.0.1:12001", # This node only received messages on this IP:Port pair + remote = "127.0.0.1:12000" # This node sents outgoing messages to this IP:Port pair - combine = 30 # Receive and sent 30 samples per message (multiplexing). + combine = 30 # Receive and sent 30 samples per message (multiplexing). + } } ## Packet Format diff --git a/doc/nodes/WebSocket.md b/doc/nodes/WebSocket.md new file mode 100644 index 000000000..a59e97eb0 --- /dev/null +++ b/doc/nodes/WebSocket.md @@ -0,0 +1,22 @@ +# WebSocket {#websocket} + +The `websocket` node type spawns a HTTP / WebSocket server. + +## Configuration + +There is no node specific configuration. + +### Example + + nodes = { + ws = { + type = "websocket" + } + } + + http = { + port = 8080; + htdocs = "/opt/s2ss/contrib/websocket/"; + ssl_cert = "/etc/ssl/certs/mycert.pem"; + ssl_private_key= "/etc/ssl/private/mykey.pem"; + } \ No newline at end of file