Skip to content
Snippets Groups Projects
Commit 4a6a6af2 authored by Steffen Vogel's avatar Steffen Vogel :santa_tone2:
Browse files

remove documentation which is now in separate repo

parent e7b20236
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 1 addition and 924 deletions
Doxyfile
+ 1
− 1
View file @ 4a6a6af2
......@@ -858,7 +858,7 @@ EXAMPLE_RECURSIVE = YES
# that contain images that are to be included in the documentation (see the
# \image command).
IMAGE_PATH = doc/figures/
IMAGE_PATH = doc/pictures
# The INPUT_FILTER tag can be used to specify a program that doxygen should
# invoke to filter for each input file. Doxygen will invoke the filter program
......
doc/Concept.md deleted 100644 → 0
+ 0
− 50
View file @ e7b20236
# Concept
VILLASnode is designed around the concept of _nodes_, _super-nodes_ and _paths_.
It's the task of the server to forward real-time simulation data between multiple parties.
In doing so, the server has to perform simple checks and collects statistics.
From the viewpoint of the communication parters the server is nearly transparent.
Hence, it's cruical to keep the added overhead as low as possible (in terms of latency).
## @subpage supernode
## @subpage node
All communication partners are represented by nodes.
Possible types of nodes are:
* Simulators (OPAL, RTDS)
* Servers (VILLASnode instances)
* Workstations (Simulink, Labview, ...)
* Data Loggers
* etc..
@see node for implementation details.
## @subpage path
A path is a **uni-directional** connection between incoming and outgoing nodes.
It forwards messages from a single incoming node to multiple outgoing nodes.
Therefore it represents a 1-to-n relation between nodes.
For bidirectional communication a corresponding path in the reverse direction must be added.
By default, message contents are not altered.
The server only performs checks for valid message headers (sequence number, cryptographic signature..).
However every path supports optional hook/callback functions which allow user-defined operations on the message contents.
@diafile path_simple.dia
@see path for implementation details.
## @subpage hook
## Interface
Interfaces are used to represent physical network ports on the server.
They are only used by the [Socket](socket) type of nodes.
@todo Add documentation
@see interface for implementation details.
doc/Configuration.md deleted 100644 → 0
+ 0
− 174
View file @ e7b20236
# Configuration
The VILLASnode configuration is completly contained in a single file.
Take a look at the example configuration: `server/etc/example.conf`.
The configuration file consists of three sections:
## Global
The global section consists of some global configuration parameters:
#### `debug` *(integer)*
`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` *(float)*
`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
#### `affinity` *(integer)*
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.
#### `priority` *(integer)*
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.
#### `name` *(string)*
By default the `name` of a VILLASnode instance is equalt to the hostname of the machine it is running on.
Some node types are using this name to identify themselves agains their remotes.
An example is the `ngsi` node type which adds a metadata attribute `source` to its updates.
## Log
```
log = {
file = "/var/log/villas-node.log";
level = 5;
facilities = "socket,log,mem"; // log socket node-type, log and memory sub-system
facilities = "nodes,!websocket"; // log all node-type but not the websocket node-type
//facilities = "all,!nodes"; // log everything but not the node-types
}
```
#### Available logging facilities
| Facility | Description |
|:- |:- |
| `pool` | Memory Pool for fixed size allocations |
| `queue` | Multiple-producer / Multiple-consumer queue |
| `config` | Configuration parser |
| `hook` | Hook sub-system |
| `path` | Send / Receive path |
| `node` | Node-types |
| `mem` | Memory management |
| `web` | Web sub-system |
| `api` | Remote API |
| `log` | Logging sub-system |
| `vfio` | Virtual Function Input/Output sub-system for access to PCI devices |
| `pci` | PCI device detection |
| `xil` | Xilinx drivers for FPGA components |
| `tc` | Linux traffic control for network emulation |
| `if` | Linux network interfaces |
| `socket` | BSD Socket node-type |
| `file` | File node-type |
| `fpga` | VILLASfpga node-type |
| `ngsi` | FIWARE NGSI node-type |
| `websocket` | WebSocket node-type |
| `opal` | OPAL-RT node-type |
## Web
## Nodes
The node section is a **directory** of nodes (clients) which are connected to the VILLASnode instance.
The directory is indexed by the name of the node:
```
nodes = {
"sintef_node" = {
type = "socket";
...
}
}
```
There are multiple diffrent type of nodes. But all types have the following settings in common:
#### `type` *("socket" | "gtfpga" | "file" | "ngsi")*
`type` sets the type of the node. This should be one of:
- `socket` which refers to a [Socket](socket) node.
- `gtfpga` which refers to a [GTFPGA](gtfpga) node.
- `opal` which refers to a [OPAL Asynchronous Process](opal) node.
- `file` which refers to a [File](file) node.
The remaining settings per node a depending on `type`.
Take a look a the specific pages for details.
## Paths
The path section consists of a **list** of paths:
paths = [
{
in = "rtds",
out = "broker",
reverse = false,
poolsize = 32,
msgsize = 16,
vectorize = 4,
hook = [ "print", "ts" ]
}
]
Every path is allowed to have the following settings:
##### `in` & `out` *(string)*
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.
##### `enabled` *(boolean)*
The optional `enabled` setting can be used to temporarily disable a path.
If omitted, the path is enabled by default.
##### `reverse` *(boolean)*
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`.
##### `vectorize` *(integer)*
This setting allows to send multiple samples in a single message to the destination nodes. Currently this is only supported by the `file` and `socket` node-types.
The value of this setting determines how many samples will be combined into one packet.
**Important:** Please make sure that the value of this setting is smaller or equal to the `poolsize` setting of this path.
##### `rate` *(float)*
A non-zero value for this setting will change this path to an asynchronous mode.
In this mode VILLASnode will send with a fixed rate to all destination nodes.
It will always send the latest value it received, possible skipping values which have been received in between.
If `vectorize` is larger than 1, it will send the last `vectorize` samples at once.
**Important:** Please note that there is no correlation between the time of arrival and time of departure in this mode. It might increase the latency of this path by up to `1 / rate` seconds!
##### `poolsize` *(integer)*
Every path manages a circular buffer to keep a history of past samples. This setting specifies the size of this circular buffer.
**Important:** There are some hook functions (or the `vectorize` setting) which require a minimum poolsize (for example the finite-impulse-response `fir` hook).
##### `hook` *(list of strings)*
A list of hook functions which will be executed for this path.
Please consult the hook chapter of this documentation for more details.
doc/DesignGoals.md deleted 100644 → 0
+ 0
− 14
View file @ e7b20236
# Design Goals {#designgoals}
VILLASnode ...
- is written in C the programming language
- is using features of the C11 standard
- is using an object oriented programming paradigm
- can be compiled with Clang / LLVM or GCC
- is released under the LGPLv2 license
- only relies on open source software libraries and the Linux kernel
- is extensible with new node types & hooks
- is heavily multi-threaded
- follows the Unix philosophy
- is separated into a library (libvillas) and a few binaries (villas-server, villas-pipe, villas-test-*, villas-signal, villas-hook) which link against the lib.
\ No newline at end of file
doc/GettingStarted.md deleted 100644 → 0
+ 0
− 31
View file @ e7b20236
# Getting started
## Installation
We put some effort in getting you started as smooth as possible.
For first tests and development you can use the Docker platform to bootstrap your environment.
Docker is a software to run containers (a.k.a images in Docker's terminology) on a Linux machine.
We use for development as well as for testing or demonstrating VILLASnode's functionality.
**Note:** Please be aware that we do not recommend to use Docker for running VILLASnode in a real-time simulation.
We prepared a image which you can download and run out of the box:
1. Download the Docker toolbox: https://www.docker.com/docker-toolbox .
This toolbox includes a virtual machine as well all the Docker tools you need to the Docker container which is provided by us.
More instructions to get with can be found here: http://docs.docker.com/windows/started/
2. After installing the toolbox, open the "Docker Quickstart Terminal"
3. Start the latest VILLASnode container by running:
```
$ docker run rwth-acs/villas-node --help
```
@todo Add a ASCIIcinema screencast here
## Guide
doc/Install.md deleted 100644 → 0
+ 0
− 83
View file @ e7b20236
# Setup
VILLASnode can be installed in multiple ways:
- Using a pre-build Docker image
- Using pre-build RPM packages for Redhat based Linux distributions
- or from source
## Prerequisites
VILLASnode currently has 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.
- libOpal{AsyncApi,Core,Utils} for running VILLASnode as an Asynchronous process inside your RT-LAB model.
- [libjansson](http://www.digip.org/jansson/) JSON parser for `websocket` and `ngsi` node-types.
- [libwebsockets](http://libwebsockets.org) for the `websocket` node-type.
- [libcurl](https://curl.haxx.se/libcurl/) for HTTP REST requests by the `ngsi` node-type.
- [openssl]()
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
```
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 build system to download, compile and install all dependencies:
```
$ make install-thirdparty
```
## Downloading VILLASnode
```
$ 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.
Afterwards, start the compilation with:
```
$ make
$ make run-tests
```
Append `V=5` to `make` for a more verbose debugging output.
Append `DEBUG=1` to `make` to add debug symbols.
## Installation
Install the files to your search path:
```
$ make install
$ make install-doc
```
Append `PREFIX=/opt/local` to change the installation destination.
## Test
Verify everything is working and required node-types are compiled-in:
```
$ villas node --help
```
Will print the current version including a list of all supported node-types, hooks, etc.
doc/Nodes.md deleted 100644 → 0
+ 0
− 33
View file @ e7b20236
# Node-types {#nodes}
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 villasfpga
- VILLASfpga sub-project connect RTDS via GTFPGA and PCIexpress (Linux vfio, uio)
#### @subpage opal
- OPAL via Asynchronous Process (libOpalAsyncApi)
#### @subpage file
- Log & replay of sample values
- Static load profiles
#### @subpage socket
- RTDS via GTFPGA and UDP
- OPAL via Asynchronous Process and UDP
#### @subpage websocket
- WebSockets for live monitoring and user interaction
#### @subpage ngsi
- NGSI 9/10 a.k.a. FIRWARE context broker
#### @subpage labview
- NI LabView RT-targets
#### @subpage cbuilder
- RTDS CBuilder Control System components
#### @subpage shmem
- POSIX shared memory interface
doc/Timing.md deleted 100644 → 0
+ 0
− 3
View file @ e7b20236
# Timing
@diafile timing.dia
doc/Tools.md deleted 100644 → 0
+ 0
− 80
View file @ e7b20236
# Tools {#tools}
VILLASnode comes with a couple of tools to test and debug connectivity and configurations.
All VILLASnode tools are available as subcommands to the `villas` wrapper:
### `villas node`
Starts the simulator to simulator server. The server acts as a central gateway to forward simulation data.
Usage: villas-node 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)
### `villas pipe`
The `pipe` subcommand allows to read and write samples to `stdin` / `stdout`.
Usage: villas-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)
### `villas signal`
The `signal` subcommand is a signal generator which writes samples to `stdout`.
This command can be combined with the `pipe` subcommand.
Usage: villas-signal SIGNAL [OPTIONS]
SIGNAL is on of: 'mixed', 'random', 'sine', 'triangle', 'square', 'ramp'
-v NUM specifies how many values a message should contain
-r HZ how many messages per second
-f HZ the frequency of the signal
-a FLT the amplitude
-d FLT the standard deviation for 'random' signals
-l NUM only send LIMIT messages and stop
### `villas test`
Usage: villas-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
### `villas fpga`
Usage: ./fpga CONFIGFILE CMD [OPTIONS]
Commands:
tests Test functionality of VILLASfpga card
benchmarks Do benchmarks
Options:
-d Set log level
## Examples
1. Start server:
$ villas node etc/example.conf
2. Receive/dump data to file
$ villas pipe etc/example.conf node_name > dump.csv
3. Replay recorded data:
$ villas pipe etc/example.conf -r node_name < dump.csv
4. Send random generated values:
$ villas signal random 4 100 | villas pipe etc/example.conf destination_node
5. Test ping/pong latency:
$ villas test latency etc/example.conf test_node
\ No newline at end of file
doc/Tuning.md deleted 100644 → 0
+ 0
− 61
View file @ e7b20236
# Tuning {#tuning}
This page is not directly related to VILLASnode.
It describes several ways to optimize the host system for running real-time applications like VILLASnode.
## Operating System and Kernel
For minimum latency several kernel and driver settings can be optimized.
A [PREEMPT_RT patched Linux](https://rt.wiki.kernel.org/index.php/Main_Page) kernel is recommended.
Precompiled kernels for Fedora can be found here: http://ccrma.stanford.edu/planetccrma/software/
1. Tune overall system performance for real-time:
1.1. Use the `tuned` tool for imprving general real-time performance.
Please adjust the setting `isolated_cpucores` according to your hardware.
```bash
$ dnf install tuned-profiles-realtime
$ echo "realtime" > /etc/tuned/active_profile
$ echo "isolated_cpucores=6-7" >> /etc/tuned/realtime-variables.conf
$ systemctl enable tuned && systemctl start tuned
```
This enables the following `tuned` profiles:
- latency-performance
- network-latency
- realtime
1.2 Install a `PREEMPT_RT` patched Linux kernel.
2. Optimize the VILLASnode configuration
2.1. Map NIC IRQs (see global setting `affinity`)
2.2. Map Tasks (see global setting `affinity`)
2.3. Increase priority of server task (nice(2)) (see global setting `priority`)
2.4. Increase BSD socket priority (see global setting `priority` for node-type `socket`)
3. Configure NIC interrupt coalescence with `ethtool`:
```bash
$ ethtool --coalesce eth0 adaptive-rx off adaptive-tx off
```
4. Configure NIC kernel driver in `/etc/modprobe.d/e1000e.conf`:
```
# More conservative interrupt throttling for better latency
# https://www.kernel.org/doc/Documentation/networking/e1000e.txt
option e1000e InterruptThrottleRate=
```
## Hardware
This are some proposals for the selection of appropriate server hardware:
- Server-grade CPU: Intel Xeon
- A multi-core systems enable true paralell execution of multiple send / receive paths.
- Server-grade network cards: Intel PRO/1000
- These allow offloading of UDP checksumming to the hardware
doc/Usage.md deleted 100644 → 0
+ 0
− 56
View file @ e7b20236
# Usage {#usage}
# `villas signal`
# `villas pipe`
# `villas hook`
## `villas node`
The core of VILLASnode is the `villas-node` daemon.
The folling usage information is provided when called like `villas-node --help`;
```
Usage: villas-node [CONFIG]
CONFIG is the path to an optional configuration file
if omitted, VILLASnode will start without a configuration
and wait for provisioning over the web interface.
Supported node types:
- file : support for file log / replay node type
- cbuilder : RTDS CBuilder model
- socket : BSD network sockets
- fpga : VILLASfpga PCIe card (libxil)
- ngsi : OMA Next Generation Services Interface 10 (libcurl, libjansson)
- websocket : Send and receive samples of a WebSocket connection (libwebsockets)
Supported hooks:
- restart : Call restart hooks for current path
- print : Print the message to stdout
- decimate : Downsamping by integer factor
- fix_ts : Update timestamps of sample if not set
- skip_first : Skip the first samples
- drop : Drop messages with reordered sequence numbers
- convert : Convert message from / to floating-point / integer
- shift : Shift the origin timestamp of samples
- ts : Update timestamp of message with current time
- stats : Collect statistics for the current path
- stats_send : Send path statistics to another node
Supported API commands:
- nodes : retrieve list of all known nodes
- config : retrieve current VILLASnode configuration
- reload : restart VILLASnode with new configuration
VILLASnode v0.7-0.2-646-g59756e7-dirty-debug (built on Mar 12 2017 21:37:40)
copyright 2014-2016, Institute for Automation of Complex Power Systems, EONERC
Steffen Vogel <StVogel@eonerc.rwth-aachen.de>
```
The server requires root privileges for:
- Enable the realtime FIFO scheduler
- Increase the task priority
- Configure the network emulator (netem)
- Change the SMP affinity of threads and network interrupts
\ No newline at end of file
doc/concept/Hooks.md deleted 100644 → 0
+ 0
− 70
View file @ e7b20236
# Hooks {#hook}
Hooks are simple callback functions which are called whenever a message is processed by a path.
There are several built-in hooks for:
- collecting, show & reset statistics
- drop reordered messages
- verify message headers
- handle simulation restarts
But main goal of this mechanism is to provide extensibility for the end user.
Example applications for hooks might be:
1. Filter sample values
2. Manipulate sample values: FIR
3. Transform sample values: FFT, DCT
4. Update network emulation settings based on sample values
## Configuration
Each path is allowed to have multiple active hooks.
Those can be configured in the path section using the `hooks` setting:
paths = [
{
in = "input_node",
out = "output_node",
hooks = [ "fir", "print" ]
# hooks = "decimate" // alternative syntax for a single hook
}
]
**Please note:** the hooks will be executed in the order they are given in the configuration file!
## API
The interface for user-defined hook functions is defined in (`server/include/hooks.h`):
```
typedef int (*hook_cb_t)(struct path *p, struct hook *h, int when);
```
There are several occasions when a hook can be executed in the program flow (@see hook_type).
There is a dedicated queue for each occasion.
The queue for which a hook can be called is encoded as a mask and specified during registration of that hook.
| Queue | Desciption |
| --------------------- | --------------------------------------------------------------------- |
| `HOOK_PATH_START` | Called whenever a path is started; before threads are created. |
| `HOOK_PATH_STOP` | Called whenever a path is stopped; after threads are destoyed. |
| `HOOK_PATH_RESTART` | Called whenever a new simulation case is started. This is detected by a sequence no equal to zero. |
| `HOOK_PRE` | Called when a new packet of messages (samples) was received. |
| `HOOK_POST` | Called after each message (sample) of a packet was processed. |
| `HOOK_MSG` | Called for each message (sample) in a packet. |
| `HOOK_PERIODIC` | Called periodically. Period is set by global 'stats' option in the configuration file. |
## Examples
There are already several hooks defined in (server/src/hooks.c).
Use one of those as a starting point for your own hook.
A typical hook function might look like this one:
int my_super_hook_function(struct path *p, struct hook *h, int when)
{
struct msg *last_received_msg = p->current;
printf("The last message contained %u values\n", last_received_msg->length);
}
doc/concept/Node.md deleted 100644 → 0
+ 0
− 1
View file @ e7b20236
#Nodes {#node}
\ No newline at end of file
doc/concept/Path.md deleted 100644 → 0
+ 0
− 1
View file @ e7b20236
#Paths {#path}
\ No newline at end of file
doc/concept/SuperNode.md deleted 100644 → 0
+ 0
− 1
View file @ e7b20236
# Super Nodes {#supernode}
\ No newline at end of file
doc/development/AdvancedIO.md deleted 100644 → 0
+ 0
− 54
View file @ e7b20236
# Advanced IO {#advio}
__This page is intended for developers only__
Implements an fopen() abstraction allowing reading from URIs.
This file introduces a c library buffered I/O interface to URI reads it supports fopen(), fread(), fgets(), feof(), fclose(), rewind(). Supported functions have identical prototypes to their normal libc namesakes and are preceaded by 'a'.
Using this code you can replace your program's fopen() with afopen() and fread() with afread() and it become possible to read remote streams instead of (only) local files. Local files (ie those that can be directly fopened) will drop back to using the underlying libc implementations.
Advanced IO (ADVIO) is an extension of the standard IO features (STDIO) which can operate on files stored remotely via a variety of different protocols.
As ADVIO is built upon libcurl, it supports all of [libcurl protocols](https://curl.haxx.se/libcurl/c/CURLOPT_PROTOCOLS.html).
When openeing a file with ADVIO, the file is requested from the remote server and stored as a local temporary file on the disk.
Subsequent operations use this local copy of the file.
When closing or flushing the file, the local copy gets checked for modifications and uploaded to the remote.
There are a few points to keep in mind:
- `afflush()` uploads the file contents to its origin URI if it was changed locally.
- `afclose()` flushes (and hence uploads) the file only if it has been modified. Modifications are detected by comparing the files SHA1 hashes.
## Extensions
The following functions have been added:
- `aupload()` uploads the file irrespectively if it was changed or not.
- `adownload()` downloads the file and discards any local changes.
- `auri()` returns a pointer to the URI.
- `ahash()` returns a pointer to a
## Example
#include <advio.h>
AFILE *f;
char buf[1024];
f = afopen("ftp://user:passwd@server/path/to/file.txt", "r");
if (!f)
serror("Failed to open file");
afread(buf, 1, 1024, f);
printf("%s", buf);
afclose(f);
## Usage for VILLASnode
VILLASnode uses ADVIO currently for:
- Fetchting the configuration file. This means VILLASnode can be started like `villas-node http://server/config.conf`
- As source and destination file for the `file` node-type. Please have a look at the example configuration file `etc/advio.conf`.
\ No newline at end of file
doc/development/Development.md deleted 100644 → 0
+ 0
− 54
View file @ e7b20236
# Development
Developement is currently coordinated by Steffen Vogel <stvogel@eonerc.rwth-aachen.de> using [GitLab](http://git.rwth-aachen.de/VILLASframework/VILLASnode).
Please feel free to submit pull requests or bug reports.
@todo Add link to contribution guidelines
## Programming Paradigm
VILLASnode is currently written in C using the ISO C99 standard.
Yet, it is heavily structured into modules / plugins and uses a C++-like object oriented style.
In the future, VILLASnode might switch to lightweight C++.
Main _classes_ in VILLASnode are struct node, struct path, struct hook and struct api_ressource.
In order to track the life cycle of those objects, each of them has an enum state member.
The following figure illustrates the state machine which is used:
@diafile states.dia
## Shared library: libvillas
VILLASnode is split into a shared library called libvillas and a couple of executables (`villas-node`, `villas-pipe`, `villas-test`, `villas-signal`, ...) which are linked against this library.
## Extensibilty / Plugins
There are many places where VILLASnode can easily extended with plugins:
### Example of new node type
See `include/villas/plugin.h`
See `lib/nodes/file.c`:
[...]
static struct plugin p = {
.name = "file",
.description = "support for file log / replay node type",
.type = PLUGIN_TYPE_NODE,
.node = {
.vectorize = 1,
.size = sizeof(struct file),
.reverse = file_reverse,
.parse = file_parse,
.print = file_print,
.start = file_start,
.stop = file_stop,
.read = file_read,
.write = file_write,
.instances = LIST_INIT()
}
};
REGISTER_PLUGIN(&p)
\ No newline at end of file
doc/development/RemoteAPI.md deleted 100644 → 0
+ 0
− 157
View file @ e7b20236
#Remote Application Programming Interface (API) {#API}
VILLASnode can be controlled remotely with an Application Programming Interface (API).
## Transports
The API is accessible via multiple transports:
- HTTP POST requests
- WebSockets
- Unix Domain sockets (planned)
### HTTP REST
**Endpoint URL:** `http[s]://server:port/api/v1`
**HTTP Method:** POST only
### WebSockets
**Protocol:** `api`
**Endpoint:** `ws[s]://server:port/v1`
### Unix socket
_This transport is not implemented yet_
## Protocol
All transports use the same JSON-based protocol to encode API requests and responses.
Both requests and responses are JSON objects with the fields described below.
Per API session multiple requests can be sent to the node.
The order of the respective responses does not necessarily match the order of the requests.
Requests and responses can be interleaved.
The client must check the `id` field in order to find the matching response to a request.
#### Request
| Field | Description |
|:------------------------ |:---------------------- |
| `action` | The API action which is requested. See next section. |
| `id` | A unique string which identifies the request. The same id will be used for the response. |
| `request` | Any JSON data-type which will be passed as an argument to the respective API action. |
#### Response
The response is similar to the request object.
The `id` field of the request will be copied to allow
| Field | Description |
|:------------------------ |:---------------------- |
| `action` | The API action which is requested. See next section. |
| `id` | A unique string which identifies the request. The same id will be used for the response. |
| `response` | Any JSON data-type which can be returned. |
## Actions
### `restart`
Restart VILLASnode with a new configuration file.
**Request:** _application/json_
{
"action": "restart",
"id": "66675eb4-6a0b-49e6-8e82-64d2b2504e7a"
"request" : {
"configuration": "smb://MY-WINDOWS-HOST/SHARE1/path/to/config.conf"
}
}
**Response:** _application/json_
{
"action": "reload",
"id": "66675eb4-6a0b-49e6-8e82-64d2b2504e7a"
"response" : "success"
}
### `config`
Retrieve the contents of the current configuration.
**Request:** _application/json_
{
"action": "config",
"id": "66675eb4-6a0b-49e6-8e82-64d2b2504e7a"
}
**Response:** _application/json_
{
"action": "config",
"id": "66675eb4-6a0b-49e6-8e82-64d2b2504e7a",
"response" : {
"nodes" : {
"socket_node" : {
"type": "socket",
"layer": "udp",
...
}
},
"paths" : [
{
"in": "socket_node",
"out": "socket_node"
}
]
}
}
### `nodes`
Get a list of currently active nodes.
**Request:** _application/json_
{
"action": "nodes",
"id": "5a786626-fbc6-4c04-98c2-48027e68c2fa"
}
**Response:** _application/json_
{
"action": "nodes",
"response": [
{
"name": "ws",
"state": 4,
"vectorize": 1,
"affinity": 0,
"id": 0,
"type": "websocket",
"description": "Demo Channel"
}
],
"id": "5a786626-fbc6-4c04-98c2-48027e68c2fa"
}
### `capabilities`
Get a list of supported node-types, hooks and API actions.
### `paths`
Get a list of currently active paths.
_This request is not implemented yet_
### `status`
The the status of this VILLASnode instance.
_This request is not implemented yet_
\ No newline at end of file
doc/figures/build.dia deleted 100644 → 0
+ 0
− 0
View file @ e7b20236
File deleted
doc/figures/msg_format.dia deleted 100644 → 0
+ 0
− 0
View file @ e7b20236
File deleted
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment