diff --git a/documentation/Clients.md b/documentation/Clients.md index 10ab64ad4..8ef49397c 100644 --- a/documentation/Clients.md +++ b/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 ? diff --git a/documentation/Configuration.md b/documentation/Configuration.md new file mode 100644 index 000000000..e7399a360 --- /dev/null +++ b/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`. diff --git a/documentation/Contributors.md b/documentation/Contributors.md deleted file mode 100644 index e1173eab7..000000000 --- a/documentation/Contributors.md +++ /dev/null @@ -1,3 +0,0 @@ -The following persons have been working on the S2SS: - -- Steffen Vogel diff --git a/documentation/Mainpage.md b/documentation/Mainpage.md index cc46db98d..35525edca 100644 --- a/documentation/Mainpage.md +++ b/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 - Marija Stevic - - diff --git a/documentation/Server.md b/documentation/Setup.md similarity index 94% rename from documentation/Server.md rename to documentation/Setup.md index d87ce1c2e..ae620ff7b 100644 --- a/documentation/Server.md +++ b/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: diff --git a/documentation/clients/File.md b/documentation/clients/File.md new file mode 100644 index 000000000..24aa6176a --- /dev/null +++ b/documentation/clients/File.md @@ -0,0 +1 @@ +# File \ No newline at end of file diff --git a/documentation/clients/Socket.md b/documentation/clients/Socket.md new file mode 100644 index 000000000..40bc49994 --- /dev/null +++ b/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 + + \ No newline at end of file