diff --git a/Doxyfile b/Doxyfile index 8bbbc085b..a1b3a6c16 100644 --- a/Doxyfile +++ b/Doxyfile @@ -765,7 +765,7 @@ WARN_LOGFILE = doc/warnings.log # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = src/ lib/ include/ doc/ +INPUT = README.md CONTRIBUTING.md COPYING.md src/ lib/ tests/ include/ doc/ # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -906,7 +906,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = doc/Mainpage.md +USE_MDFILE_AS_MAINPAGE = README.md #--------------------------------------------------------------------------- # Configuration options related to source browsing @@ -2196,7 +2196,7 @@ GROUP_GRAPHS = YES # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. -UML_LOOK = NO +UML_LOOK = YES # If the UML_LOOK tag is enabled, the fields and methods are shown inside the # class node. If there are many fields or methods and many nodes the graph may diff --git a/README.md b/README.md index 1faecce2e..68ff8db46 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,53 @@ -# VILLASnode [![build status](https://git.rwth-aachen.de/acs/VILLASnode/badges/develop/build.svg)](https://git.rwth-aachen.de/acs/VILLASnode/commits/develop) [![coverage report](https://git.rwth-aachen.de/acs/VILLASnode/badges/develop/coverage.svg)](https://git.rwth-aachen.de/acs/VILLASnode/commits/develop) +# VILLASnode +[![build status](https://git.rwth-aachen.de/VILLASframework/VILLASnode/badges/develop/build.svg)](https://git.rwth-aachen.de/acs/VILLASnode/commits/develop) +[![coverage report](https://git.rwth-aachen.de/VILLASframework/VILLASnode/badges/develop/coverage.svg)](https://git.rwth-aachen.de/acs/VILLASnode/commits/develop) This is VILLASnode, a gateway for processing and forwardning simulation data between real-time simulators. +VILLASnode is a client/server application to connect simulation equipment and software such as: + - OPAL-RT eMegaSim, + - RTDS GTFPGA cards, + - Simulink, + - LabView, + - and FPGA models. -## Documentation +It's designed with a focus on very low latency to achieve almost realtime exchange of simulation data. +VILLASnode 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. -The documentation for this software is available at [doc/Mainpage](doc/Mainpage.md). +## Overview -The full documentation is available at [doc/html/index.html](doc/html/index.html) after running `doxygen` in this directory. +The project consists of a server daemon and several client modules which are documented here. -You can access the prebuild documentation at: http://134.130.169.32/villas/node/ (available only from ACS *Office network* and *Simulation Network*). +[TOC] + +### Server + +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 [PREEMPT_RT](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 VILLASnode. + In this scenario, VILLASnode 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 VILLASnode. +Using a dedicated client-application which communicates via the 'socket' type is deprecated because it leads to code duplication. ## Contact diff --git a/doc/Contributing.md b/doc/Contributing.md deleted file mode 120000 index 44fcc6343..000000000 --- a/doc/Contributing.md +++ /dev/null @@ -1 +0,0 @@ -../CONTRIBUTING.md \ No newline at end of file diff --git a/doc/GettingStarted.md b/doc/GettingStarted.md index 363c462e2..342e76613 100644 --- a/doc/GettingStarted.md +++ b/doc/GettingStarted.md @@ -15,7 +15,9 @@ We prepared a image which you can download and run out of the box: 3. Start the latest VILLASnode container by running: - $ docker run rwthacs/villas + $ git clone --recursive git@git.rwth-aachen.de:VILLASframework/VILLASnode.git + $ cd VILLASnode + $ make docker ### To be added diff --git a/doc/Install.md b/doc/Install.md index 204519322..45833121e 100644 --- a/doc/Install.md +++ b/doc/Install.md @@ -1,10 +1,8 @@ # Setup -## Compilation +## Prerequisites -### Prerequisites - -Install libraries and developement headers for: +For all features VILLASnode currently requires the following list of dependencies: - [libconfig](http://www.hyperrealm.com/libconfig/) for parsing the configuration file. - [libnl3](http://www.infradead.org/~tgr/libnl/) for the network communication & emulation support of the `socket` node-type. @@ -13,6 +11,10 @@ Install libraries and developement headers for: - [libwebsockets](http://libwebsockets.org) for the `websocket` node-type. - [libcurl](https://curl.haxx.se/libcurl/) for HTTP REST requests by the `ngsi` node-type. +There are two ways to install these dependencies: + +1. You can most of the dependencies using the package manger of your Linux distribution: + Use the following command to install the dependencies under Debian-based distributions: $ sudo apt-get install build-essential pkg-config wget tar cmake doxygen dia graphviz libconfig-dev libnl-3-dev libnl-route-3-dev libjansson-dev libcurl4-openssl-dev @@ -20,8 +22,15 @@ Use the following command to install the dependencies under Debian-based distrib or the following line for Fedora / CentOS / Redhat systems: $ sudo yum install gcc pkgconfig make wget tar cmake openssl-devel doxygen dia graphviz libconfig-devel libnl3-devel libcurl-devel jansson-devel + + 2. Alternatively, you can use the make targets `make thirdparty` and `make install-thirdparty` which will compile and install all required dependencies from source. + +## Fetching VILLASnode -### Compilation + $ git clone --recursive git@git.rwth-aachen.de:VILLASframework/VILLASnode.git + $ cd VILLASnode + +## Compilation Checkout the `Makefile` and `include/config.h` for some options which have to be specified at compile time. @@ -32,7 +41,7 @@ Afterwards, start the compilation with: Append `V=5` to `make` for a more verbose debugging output. Append `DEBUG=1` to `make` to add debug symbols. -### Installation +## Installation Install the files to your search path: @@ -40,10 +49,10 @@ Install the files to your search path: Append `PREFIX=/opt/local` to change the installation destination. -### Test +## Test Verify everything is working and required node-types are compiled-in: - $ villas server + $ villas node Will show you the current version of the server including a list of all supported node-types. diff --git a/doc/License.md b/doc/License.md deleted file mode 120000 index 0c9476f2b..000000000 --- a/doc/License.md +++ /dev/null @@ -1 +0,0 @@ -../COPYING.md \ No newline at end of file diff --git a/doc/Mainpage.md b/doc/Mainpage.md deleted file mode 100644 index 42b376f97..000000000 --- a/doc/Mainpage.md +++ /dev/null @@ -1,51 +0,0 @@ -VILLASnode is a client/server application to connect simulation equipment and software such as: - - - OPAL-RT eMegaSim, - - RTDS GTFPGA cards, - - Simulink, - - LabView, - - and FPGA models. - -It's designed with a focus on very low latency to achieve almost realtime exchange of simulation data. -VILLASnode 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 daemon and several client modules which are documented here. - -[TOC] - -### Server - -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 [PREEMPT_RT](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 VILLASnode. - In this scenario, VILLASnode 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 VILLASnode. -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), EON Energy Research Center (EONERC) at the [RWTH University](http://www.rwth-aachen.de) in Aachen, Germany. - - - Steffen Vogel - - Marija Stevic diff --git a/doc/Nodes.md b/doc/Nodes.md index c2c8f111c..9b59dfbf7 100644 --- a/doc/Nodes.md +++ b/doc/Nodes.md @@ -3,8 +3,8 @@ Every server needs clients which act as sinks / sources for simulation data. In case of VILLASnode these clients are called _nodes_. Every node is an instance of a node-type. VILLASnode currently supports the following node-types: -#### @subpage gtfpga - - RTDS via GTFPGA and PCIexpress (Linux vfio, uio) +#### @subpage villasfpga + - VILLASfpga sub-project connect RTDS via GTFPGA and PCIexpress (Linux vfio, uio) #### @subpage opal - OPAL via Asynchronous Process (libOpalAsyncApi) @@ -24,4 +24,7 @@ Every node is an instance of a node-type. VILLASnode currently supports the foll - NGSI 9/10 a.k.a. FIRWARE context broker #### @subpage labview - - NI LabView RT-targets \ No newline at end of file + - NI LabView RT-targets + +#### @subpage cbuilder +- RTDS CBuilder Control System components \ No newline at end of file diff --git a/doc/Readme.md b/doc/Readme.md deleted file mode 120000 index 32d46ee88..000000000 --- a/doc/Readme.md +++ /dev/null @@ -1 +0,0 @@ -../README.md \ No newline at end of file diff --git a/doc/nodes/CBuilder.md b/doc/nodes/CBuilder.md index 360c85bd2..ada575c88 100644 --- a/doc/nodes/CBuilder.md +++ b/doc/nodes/CBuilder.md @@ -1,4 +1,4 @@ -# RTDS CBuilder models for VILLASnode +# RTDS CBuilder Control System Components {#cbuilder} RTDS's Component Builder creates user-defined components including graphical representation, data menus and real-time code. diff --git a/doc/nodes/FPGA.md b/doc/nodes/FPGA.md deleted file mode 100644 index 85299e3fb..000000000 --- a/doc/nodes/FPGA.md +++ /dev/null @@ -1,34 +0,0 @@ -# VILLASfpga {#fpga} - -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/nodes/VILLASfpga.md b/doc/nodes/VILLASfpga.md new file mode 100644 index 000000000..285951c4b --- /dev/null +++ b/doc/nodes/VILLASfpga.md @@ -0,0 +1,63 @@ +# VILLASfpga {#villasfpga} + +__This documentation is outdated!__ + +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 `fpga` node support the following special settings: + +#### `datamover` + +### Example + + fpgas = { + vc707 = { + /* Card identification */ + id = "10ee:7022"; + slot = "01:00.0"; + + intc = 0x5000; + reset = 0x2000; + do_reset = true; + + ips = { + switch_0 = { + vlnv = "xilinx.com:ip:axis_interconnect:2.1" + baseaddr = 0x0000; + numports = 3; + }, + rtds_0 = { + vlnv = "acs.eonerc.rwth-aachen.de:user:rtds_axis:1.0" + baseaddr = 0x3000; + port = 0; + }, + dma_0 = { + vlnv = "xilinx.com:ip:axi_dma:7.1"; + baseaddr = 0x1000; + port = 2; + irq = 0 + } + } + + /* Configure switch_0 */ + paths = ( + { in = "dma_0", out = "rtds_0" }, + { in = "rtds_0", out = "dma_0" } + ) + } + } + + nodes = { + rtds = { + datamover = "dma_0"; + use_irqs = false; + } + }