openapi: 3.0.3
info:
title: VILLASnode API
version: 0.10.0
description: >-
A HTTP/REST API for controlling VILLASnode remotely without the need to
restart the daemon.
termsOfService: https://www.fein-aachen.org/projects/villas-node/
contact:
name: Steffen Vogel
email: post@steffenvogel.de
url: https://fein-aachen.org/contact/
license:
name: Apache-2.0
url: https://www.apache.org/licenses/LICENSE-2.0
externalDocs:
url: https://villas.fein-aachen.org/doc/node.html
servers:
- url: https://villas.k8s.eonerc.rwth-aachen.de/api/v2
description: The production API server in our EONERC OpenStack Kubernetes
- url: http://localhost:8080
description: Your local host
tags:
- name: super-node
x-displayName: Super Node
description: Global super-node related operations.
- name: nodes
x-displayName: Nodes
description: Node related operations.
- name: paths
x-displayName: Paths
description: Path related operations.
- name: config
x-displayName: VILLASnode configuration file
description: |
This section decribes the schema of the VILLASnode configuration file.
Please use the `>` to expand the individual sub-sections.
- name: format-edgeflex
x-displayName: Edgeflex Format
description: |
- name: format-igor
x-displayName: Igor's Format
description: |
- name: format-sogno
x-displayName: SOGNO Format
description: |
- name: format-sogno-old
x-displayName: Old SOGNO Format
description: |
x-tagGroups:
- name: VILLASnode APIs
tags:
- super-node
- nodes
- paths
- name: Configuration Files
tags:
- config
- name: Format Schemas
tags:
- format-edgeflex
- format-igor
- format-sogno
- format-sogno-old
paths:
/status:
get:
operationId: get-status
summary: Get the current status of the VILLASnode instance.
tags:
- super-node
responses:
'200':
description: Success
content:
application/json:
examples:
example1:
value:
state: running
version: v0.10.0
release: 1.node_uuid_unique_debug.20201015git335440d
build_id: v0.10.0-335440d-debug
build_date: '20201015'
hostname: ernie
uuid: c9d64cc7-c6e1-4dd4-8873-126318e9d42c
time_now: 1602765814.9240997
time_started: 1602765814.3103526
timezone:
name: CEST
offset: -3600
dst: true
kernel:
sysname: Linux
nodename: ernie
release: 5.6.17-rt10
version: '#5 SMP Fri Jul 10 14:02:33 CEST 2020'
machine: x86_64
domainname: (none)
system:
cores_configured: 28
cores: 28
processes: 780
uptime: 1379600
load:
- 1.66259765625
- 1.271484375
- 1.18701171875
ram:
total: 269994606592
free: 262204465152
shared: 44191744
buffer: 130211840
swap:
total: 4294963200
free: 4294963200
highmem:
total: 0
free: 0
'400':
description: Failure
/capabilities:
get:
operationId: get-capabilities
summary: Get the capabilities of the VILLASnode instance.
tags:
- super-node
responses:
'200':
description: Success
content:
application/json:
examples:
example1:
value:
hooks:
- average
- cast
- decimate
- dp
- drop
- dump
- ebm
- fix
- gate
- jitter_calc
- limit_rate
- pps_ts
- print
- restart
- scale
- shift_seq
- shift_ts
- skip_first
- stats
- ts
node-types:
- amqp
- can
- ethercat
- example
- exec
- file
- influxdb
- kafka
- loopback
- loopback_internal
- mqtt
- ngsi
- redis
- shmem
- signal
- socket
- stats
- temper
- test_rtt
- websocket
- zeromq
apis:
- capabilities
- config
- node
- node/file
- node/pause
- node/restart
- node/resume
- node/start
- node/stats
- node/stats/reset
- node/stop
- nodes
- path
- path/start
- path/stop
- paths
- restart
- shutdown
- status
formats:
- csv
- gtnet
- iotagent_ul
- json
- json.kafka
- json.reserve
- raw
- tsv
- value
- villas.binary
- villas.human
- villas.web
'400':
description: Failure
/config:
get:
operationId: get-config
summary: Get the currently loaded configuration.
tags:
- super-node
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/config'
examples:
example1:
value:
nodes:
udp_node1:
type: socket
layer: udp
in:
address: '*:12000'
signals:
count: 8
type: float
out:
address: 127.0.0.1:12001
web_node1:
type: websocket
vectorize: 2
series:
- label: Random walk
unit: V
- label: Sine
unit: A
- label: Rect
unit: Var
- label: Ramp
unit: °C
paths:
- in:
- udp_node1
out:
- web_node1
hooks:
- type: decimate
ratio: 2
- in:
- web_node1
out:
- udp_node1
'400':
description: Failure
/restart:
post:
operationId: restart
summary: Restart the VILLASnode instance.
tags:
- super-node
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
config:
oneOf:
- type: string
example: http://example.com/path/to/config.json
title: URL
description: >
An optional path or URI to a new configuration file
which
should be loaded after restarting the node.
The file referenced by the URL must be a [VILLASnode
configuration file](#tag/config)
- $ref: '#/components/schemas/config'
responses:
'200':
description: Success. The instance has been restarted.
content:
application/json:
examples:
example1:
value:
restarts: 5
config: http://example.com/path/to/config.json
'400':
description: Failure
/shutdown:
post:
operationId: shutdown
summary: Shutdown the VILLASnode instance.
tags:
- super-node
responses:
'200':
description: Success. The instance has been shut down.
'400':
description: Failure
/nodes:
get:
operationId: get-nodes
summary: Get a list of all configure node instances.
tags:
- nodes
responses:
'200':
description: Success
content:
application/json:
examples:
schema:
type: array
items:
$ref: ../components/schemas/config/node_obj.yaml
example1:
value:
- name: udp_node1
uuid: b3df1d73-f483-f16c-5936-4ea48295615c
state: running
affinity: -1
in:
address: '*:12000'
signals:
count: 8
type: float
out:
address: 127.0.0.1:12001
type: socket
layer: udp
- name: web_node1
uuid: 19c84350-c83a-8a3b-224b-43fa591c8998
state: running
affinity: -1
in:
vectorize: 2
signals:
- type: float
enabled: true
name: signal0
- type: float
enabled: true
name: signal1
- type: float
enabled: true
name: signal2
- type: float
enabled: true
name: signal3
out:
vectorize: 2
signals:
- type: float
enabled: true
name: signal0
- type: float
enabled: true
name: signal1
- type: float
enabled: true
name: signal2
type: websocket
vectorize: 2
series:
- label: Random walk
unit: V
- label: Sine
unit: A
- label: Rect
unit: Var
- label: Ramp
unit: °C
'400':
description: Failure
/node/{uuid-or-name}:
get:
operationId: get-node
summary: Get the information of a specific node.
tags:
- nodes
parameters:
- $ref: '#/components/parameters/node-uuid-name'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/node_obj'
examples:
example1:
value:
name: udp_node1
uuid: b3df1d73-f483-f16c-5936-4ea48295615c
state: running
affinity: -1
in:
address: '*:12000'
signals:
count: 8
type: float
out:
address: 127.0.0.1:12001
type: socket
layer: udp
'404':
description: >-
Error. There is no node with the given UUID or the node does not
collect statistics.
/node/{uuid-or-name}/stats:
get:
operationId: get-node-stats
summary: Get the statistics of a node.
tags:
- nodes
parameters:
- $ref: '#/components/parameters/node-uuid-name'
responses:
'200':
description: Success
content:
application/json:
examples:
example1:
value:
rtp.jitter:
low: 1.3293196e-316
high: 0
total: 0
rtp.pkts_lost:
low: 1.3285797e-316
high: 1.3290532e-316
total: 0
rtp.loss_fraction:
low: 3.e-323
high: 1.32907453e-316
total: 0
age:
low: 1.3288619e-316
high: 1.32909588e-316
total: 0
owd:
low: 3.e-323
high: 3.e-322
total: 144
higher: 0
lower: 0
highest: 0.099986117
lowest: 0.09990915800000001
mean: 0.09998063221527778
variance: 7.736879555478282e-11
stddev: 0.000008795953362472019
buckets:
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
gap_received:
low: 0
high: 1.32743107e-316
total: 144
higher: 0
lower: 0
highest: 0.10000411000000001
lowest: 0.09999650900000001
mean: 0.09999998652777778
variance: 5.701784607620545e-13
stddev: 7.551016228045431e-7
buckets:
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
gap_sent:
low: 1.58e-321
high: 1.3292848e-316
total: 144
higher: 0
lower: 0
highest: 0.10004273400000001
lowest: 0.09926839700000001
mean: 0.09999436691666665
variance: 3.7637473716438304e-9
stddev: 0.00006134938770390321
buckets:
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
- 0
reordered:
low: 8.28904606e-315
high: 1.32930615e-316
total: 0
skipped:
low: 1.32879865e-316
high: 1.3293275e-316
total: 0
'404':
description: >-
Error. There is no node with the given UUID or the node does not
collect statistics.
/node/{uuid-or-name}/stats/reset:
post:
operationId: reset-node-stats
summary: Reset the statistics counters for a specific node.
tags:
- nodes
parameters:
- $ref: '#/components/parameters/node-uuid-name'
responses:
'200':
description: Success. The statistics of the node have been reset.
'404':
description: Error. There is no node with the given UUID.
/node/{uuid-or-name}/start:
post:
operationId: start-node
summary: Start a node.
tags:
- nodes
parameters:
- $ref: '#/components/parameters/node-uuid-name'
responses:
'200':
description: Success. The node has been started.
'404':
description: Error. There is no node with the given UUID.
/node/{uuid-or-name}/stop:
post:
operationId: stop-node
summary: Stop a node.
tags:
- nodes
parameters:
- $ref: '#/components/parameters/node-uuid-name'
responses:
'200':
description: Success. The node has been stopped.
'404':
description: Error. There is no node with the given UUID.
/node/{uuid-or-name}/pause:
post:
operationId: pause-graph
summary: Pause a node.
tags:
- nodes
parameters:
- $ref: '#/components/parameters/node-uuid-name'
responses:
'200':
description: Success. The node has been paused.
'404':
description: Error. There is no node with the given UUID.
/node/{uuid-or-name}/resume:
post:
operationId: resume-node
summary: Resume a node.
tags:
- nodes
parameters:
- $ref: '#/components/parameters/node-uuid-name'
responses:
'200':
description: Success. The node has been resumed.
'404':
description: Error. There is no node with the given UUID.
/node/{uuid-or-name}/restart:
post:
operationId: restart-node
summary: Retart a node.
tags:
- nodes
parameters:
- $ref: '#/components/parameters/node-uuid-name'
responses:
'200':
description: Success. The node has been restarted.
'404':
description: Error. There is no node with the given UUID.
/node/{uuid-or-name}/file/rewind:
post:
operationId: rewind-file-node
summary: Rewind the playback file to the beginning.
tags:
- nodes
parameters:
- $ref: '#/components/parameters/node-uuid-name'
responses:
'200':
description: Success. The file has been rewound.
'404':
description: Error. There is no node with the given UUID.
/node/{uuid-or-name}/file/seek:
post:
operationId: seek-file-node
summary: Rewind the playback file to the beginning.
tags:
- nodes
parameters:
- $ref: '#/components/parameters/node-uuid-name'
requestBody:
description: Sample position in file
required: true
content:
application/json:
schema:
type: object
required:
- position
properties:
position:
type: integer
example: 123
description: Skip the first nth samples in the file.
responses:
'200':
description: Success. The read-pointer of the file has been changed.
'404':
description: Error. There is no node with the given UUID.
/paths:
get:
operationId: get-paths
summary: Get a list of all paths.
tags:
- paths
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/path'
examples:
example1:
value:
- uuid: 251c99af-4b05-9de4-367e-2bb550412e56
state: running
mode: any
enabled: true
builtin: true
reverse: false
original_sequence_no: true
last_sequence: false
poll: false
queuelen: 1024
signals: []
hooks: []
in:
- udp_node1
out:
- web_node1
- uuid: 61b5674b-95fa-b35f-bff8-c877acf21e3b
state: running
mode: any
enabled: true
builtin: true
reverse: false
original_sequence_no: true
last_sequence: false
poll: false
queuelen: 1024
signals: []
hooks: []
in:
- web_node1
out:
- udp_node1
'400':
description: Failure
/path/{uuid}:
post:
operationId: get-path
summary: Get details of a single path.
tags:
- paths
parameters:
- $ref: '#/components/parameters/path-uuid'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/path'
examples:
example1:
value:
uuid: 251c99af-4b05-9de4-367e-2bb550412e56
state: running
mode: any
enabled: true
builtin: true
reverse: false
original_sequence_no: true
last_sequence: false
poll: false
queuelen: 1024
signals: []
hooks: []
in:
- udp_node1
out:
- web_node1
'404':
description: Error. There is no path with the given UUID.
/path/{uuid}/start:
post:
operationId: start-path
summary: Start a path.
tags:
- paths
parameters:
- $ref: '#/components/parameters/path-uuid'
responses:
'200':
description: Success. The path has been started.
'404':
description: Error. There is no path with the given UUID.
/path/{uuid}/stop:
post:
operationId: stop-path
summary: Start a path.
tags:
- paths
parameters:
- $ref: '#/components/parameters/path-uuid'
responses:
'200':
description: Success. The path has been stopped.
'404':
description: Error. There is no path with the given UUID.
/graph.{format}:
get:
operationId: get-graph
summary: Get a graph representation of the currently loaded configuration.
tags:
- super-node
parameters:
- in: path
name: format
schema:
type: string
description: The image format of the generated graph.
enum:
- ps
- eps
- txt
- svg
- svgz
- gif
- png
- jpg
- jpeg
- bmp
- dot
- fig
- json
- pdf
- in: query
name: layout
schema:
type: string
description: The Graphviz layout engine used for rendering the graph.
enum:
- circo
- dot
- fdp
- neato
- nop
- nop1
- nop2
- osage
- patchwork
- sfdp
- twopi
responses:
'200':
description: Success
'400':
description: Failure
components:
schemas:
Config:
$ref: '#/components/schemas/config'
TypeField:
type: object
required:
- type
properties:
type:
type: string
FormatEdgeflex:
$ref: '#/components/schemas/edgeflex'
FormatIgor:
$ref: '#/components/schemas/igor'
FormatSognoOld:
$ref: '#/components/schemas/sogno-old'
FormatSogno:
$ref: '#/components/schemas/sogno'
node_obj:
type: object
title: Format Object
required:
- type
properties:
type:
type: string
description: >
Specifies which protocol should be used by this node.
For a complete list of supported node-types run `villas node
--help`.
In addition to the node settings described in this section, every
node type has its own specific settings
discriminator:
propertyName: type
mapping:
amqp: '#/components/schemas/_amqp'
api: '#/components/schemas/_api'
can: '#/components/schemas/_can'
comedi: '#/components/schemas/_comedi'
ethercat: '#/components/schemas/_ethercat'
example: '#/components/schemas/_example'
exec: '#/components/schemas/_exec'
file: '#/components/schemas/_file'
fpga: '#/components/schemas/_fpga'
iec60870-5-104: '#/components/schemas/_iec60870-5-104'
iec61850-8-1: '#/components/schemas/_iec61850-8-1'
iec61850-9-2: '#/components/schemas/_iec61850-9-2'
infiniband: '#/components/schemas/_infiniband'
influxdb: '#/components/schemas/_influxdb'
kafka: '#/components/schemas/_kafka'
loopback: '#/components/schemas/_loopback'
mqtt: '#/components/schemas/_mqtt'
nanomsg: '#/components/schemas/_nanomsg'
ngsi: '#/components/schemas/_ngsi'
opal: '#/components/schemas/_opal'
redis: '#/components/schemas/_redis'
rtp: '#/components/schemas/_rtp'
shmem: '#/components/schemas/_shmem'
signal: '#/components/schemas/_signal_node'
signal.v2: '#/components/schemas/_signal_v2_node'
socket: '#/components/schemas/_socket'
stats_node: '#/components/schemas/_stats_node'
temper: '#/components/schemas/_temper'
test_rtt: '#/components/schemas/_test_rtt'
uldaq: '#/components/schemas/_uldaq'
webrtc: '#/components/schemas/_webrtc'
websocket: '#/components/schemas/_websocket'
zeromq: '#/components/schemas/_zeromq'
format_obj:
type: object
title: Format Object
required:
- type
properties:
type:
type: string
discriminator:
propertyName: type
mapping:
csv: '#/components/schemas/_csv'
gtnet: '#/components/schemas/_gtnet'
iotagent_ul: '#/components/schemas/_iotagent_ul'
json: '#/components/schemas/_json'
json.edgeflex: '#/components/schemas/_json_edgeflex'
json.kafka: '#/components/schemas/_json_kafka'
json.reserve: '#/components/schemas/_json_reserve'
opal.asyncip: '#/components/schemas/_opal_asyncip'
protobuf: '#/components/schemas/_protobuf'
raw: '#/components/schemas/_raw'
tsv: '#/components/schemas/_tsv'
value: '#/components/schemas/_value'
villas.binary: '#/components/schemas/_villas_binary'
villas.human: '#/components/schemas/_villas_human'
villas.web: '#/components/schemas/_villas_web'
format:
type: object
properties:
real_precision:
type: integer
default: 17
description: >
Output all real numbers with at most n digits of precision. The
valid range for this setting is between 0 and 31 (inclusive), and
other values result in an undefined behavior.
By default, the precision is 17, to correctly and losslessly encode
all IEEE 754 double precision floating point numbers.
ts_origin:
type: boolean
default: true
description: |
If set, include the origin timestamp in the output.
ts_received:
type: boolean
default: true
description: |
If set, include the received timestamp in the output.
sequence:
type: boolean
default: true
description: |
If set, include the sequence number in the output.
data:
type: boolean
default: true
description: |
If set, include the data in the output.
offset:
type: boolean
default: true
description: >
If set, include the offset between origin and received timestamp in
the output.
line:
allOf:
- type: object
properties:
separator:
type: string
- $ref: '#/components/schemas/format'
column:
allOf:
- type: object
properties:
delimiter:
type: string
- $ref: '#/components/schemas/line'
csv:
allOf:
- type: object
properties:
delimiter:
type: string
- $ref: '#/components/schemas/column'
_csv:
allOf:
- $ref: '#/components/schemas/format_obj'
- $ref: '#/components/schemas/csv'
raw:
allOf:
- type: object
properties:
bits:
type: integer
default: 32
description: Number of bits per signal. Must be one of 8, 16, 32, 64 or 128.
endianess:
type: string
description: The endianess of the data.
default: little
enum:
- big
- little
fake:
type: boolean
description: >
Send and interpret the first three signals of each sample as the
following header fields:
- sequence number
- timestamp seconds
- timestamp nano-seconds
default: false
- $ref: '#/components/schemas/format'
gtnet:
allOf:
- $ref: '#/components/schemas/raw'
_gtnet:
allOf:
- $ref: '#/components/schemas/format_obj'
- $ref: '#/components/schemas/gtnet'
iotagent_ul:
allOf:
- type: object
properties:
delimiter:
type: string
- $ref: '#/components/schemas/format'
_iotagent_ul:
allOf:
- $ref: '#/components/schemas/format_obj'
- $ref: '#/components/schemas/iotagent_ul'
json:
allOf:
- type: object
properties:
indent:
type: number
default: 0
description: >
Pretty-print the result, using newlines between array and object
items, and indenting with n spaces.
The valid range for n is between 0 and 31 (inclusive), other
values result in an undefined output.
If the settings is not used or is 0, no newlines are inserted
between array and object items.
compact:
type: boolean
default: false
description: >
This flag enables a compact representation, i.e. sets the
separator between array and object items to "," and between
object keys and values to ":".
Without this flag, the corresponding separators are ", " and ":
" for more readable output.
ensure_ascii:
type: boolean
default: false
description: >
If this flag is used, the output is guaranteed to consist only
of ASCII characters.
This is achieved by escaping all Unicode characters outside the
ASCII range.
sort_keys:
type: boolean
default: false
description: >
If this flag is used, all the objects in output are sorted by
key.
This is useful e.g. if two JSON texts are diffed or visually
compared.
escape_slash:
type: boolean
default: false
description: Escape the `/` characters in strings with `\/`.
- $ref: '#/components/schemas/format'
_json:
allOf:
- $ref: '#/components/schemas/format_obj'
- $ref: '#/components/schemas/json'
json_edgeflex:
allOf:
- type: object
properties:
delimiter:
type: string
- $ref: '#/components/schemas/json'
_json_edgeflex:
allOf:
- $ref: '#/components/schemas/format_obj'
- $ref: '#/components/schemas/json_edgeflex'
json_kafka:
allOf:
- type: object
properties:
delimiter:
type: string
- $ref: '#/components/schemas/json'
_json_kafka:
allOf:
- $ref: '#/components/schemas/format_obj'
- $ref: '#/components/schemas/json_kafka'
json_reserve:
allOf:
- type: object
properties:
delimiter:
type: string
- $ref: '#/components/schemas/json'
_json_reserve:
allOf:
- $ref: '#/components/schemas/format_obj'
- $ref: '#/components/schemas/json_reserve'
opal_asyncip:
allOf:
- type: object
properties:
dev_id:
type: integer
- $ref: '#/components/schemas/format'
_opal_asyncip:
allOf:
- $ref: '#/components/schemas/format_obj'
- $ref: '#/components/schemas/opal_asyncip'
protobuf:
allOf:
- type: object
properties:
delimiter:
type: string
- $ref: '#/components/schemas/format'
_protobuf:
allOf:
- $ref: '#/components/schemas/format_obj'
- $ref: '#/components/schemas/protobuf'
_raw:
allOf:
- $ref: '#/components/schemas/format_obj'
- $ref: '#/components/schemas/raw'
tsv:
allOf:
- type: object
properties:
delimiter:
type: string
- $ref: '#/components/schemas/column'
_tsv:
allOf:
- $ref: '#/components/schemas/format_obj'
- $ref: '#/components/schemas/tsv'
value:
allOf:
- type: object
properties:
delimiter:
type: string
- $ref: '#/components/schemas/format'
_value:
allOf:
- $ref: '#/components/schemas/format_obj'
- $ref: '#/components/schemas/value'
villas_binary:
allOf:
- type: object
properties:
delimiter:
type: string
- $ref: '#/components/schemas/format'
_villas_binary:
allOf:
- $ref: '#/components/schemas/format_obj'
- $ref: '#/components/schemas/villas_binary'
villas_human:
allOf:
- type: object
properties:
delimiter:
type: string
- $ref: '#/components/schemas/line'
_villas_human:
allOf:
- $ref: '#/components/schemas/format_obj'
- $ref: '#/components/schemas/villas_human'
villas_web:
allOf:
- type: object
properties:
delimiter:
type: string
- $ref: '#/components/schemas/villas_binary'
_villas_web:
allOf:
- $ref: '#/components/schemas/format_obj'
- $ref: '#/components/schemas/villas_web'
format_spec:
description: >
The payload format which is used to encode and decode exchanged
messages.
example: villas.human
oneOf:
- $ref: '#/components/schemas/format_obj'
- title: Format Name
type: string
enum:
- csv
- gtnet
- iotagent_ul
- json
- json.edgeflex
- json.kafka
- json.reserve
- opal.asyncip
- protobuf
- raw
- tsv
- value
- villas.binary
- villas.human
- villas.web
signal:
type: object
properties:
name:
type: string
title: Signal name
description: |
A name which describes the signal.
example: Bus123_U
unit:
type: string
title: Signal unit
description: The unit of the signal.
example: V
type:
type: string
title: Signal data-type
description: |
The data-type of the signal.
default: float
enum:
- integer
- float
- boolean
- complex
init:
title: Initial signal value.
description: |
The initial value of the signal.
oneOf:
- type: integer
- type: number
- type: boolean
- type: object
required:
- real
- imag
additionalProperties: false
properties:
real:
type: number
imag:
type: number
enabled:
type: boolean
default: true
description: |
Signals can be disabled which causes them to be ignored.
signal_list:
title: Signal list
description: |
Each node should define a list of signals which it receives.
There are three ways to specify the input signals of a node:
oneOf:
- type: array
title: List of signal definition objects
example:
- name: tap_position
type: integer
init: 0
- name: voltage
type: float
unit: V
init: 230
items:
$ref: '#/components/schemas/signal'
- type: object
title: Signal definition with `count`
allOf:
- $ref: '#/components/schemas/signal'
- type: object
required:
- count
properties:
count:
type: integer
minimum: 1
default: 64
- type: string
title: Signal format string
example: 64f
description: >
The easiest way to specify the signals, is by using a format string.
The format string consists of one ore more characters which define
the type for the signal corresponding to the position of the
character in the string.
| Character | Type | Setting for full and list
mode |
|:--- |:---
|:--- |
| `f` | Floating point |
"float" |
| `b` | Boolean |
"boolean" |
| `i` | Integer |
"integer" |
| `c` | Complex Floating point |
"complex" |
Optionally, the characters can be prefixed by an integer for easier
repetition.
**Example:** `12f3i` defines 15 signals, of which the first 12 are
floating point and the last 3 are integer values.
node_signals:
type: object
properties:
in:
type: object
properties:
signals:
$ref: '#/components/schemas/signal_list'
hook_obj:
type: object
title: Hook Object
required:
- type
properties:
type:
type: string
discriminator:
propertyName: type
mapping:
average: '#/components/schemas/_average'
cast: '#/components/schemas/_cast'
decimate: '#/components/schemas/_decimate'
dp: '#/components/schemas/_dp'
drop: '#/components/schemas/_drop'
dump: '#/components/schemas/_dump'
ebm: '#/components/schemas/_ebm'
fix: '#/components/schemas/_fix'
gate: '#/components/schemas/_gate'
jitter_calc: '#/components/schemas/_jitter_calc'
limit_rate: '#/components/schemas/_limit_rate'
limit_value: '#/components/schemas/_limit_value'
lua: '#/components/schemas/_lua'
ma: '#/components/schemas/_ma'
pmu_dft: '#/components/schemas/_pmu_dft'
pps_ts: '#/components/schemas/_pps_ts'
print: '#/components/schemas/_print'
restart: '#/components/schemas/_restart'
rms: '#/components/schemas/_rms'
round: '#/components/schemas/_round'
scale: '#/components/schemas/_scale'
shift_seq: '#/components/schemas/_shift_seq'
shift_ts: '#/components/schemas/_shift_ts'
skip_first: '#/components/schemas/_skip_first'
stats: '#/components/schemas/_stats'
ts: '#/components/schemas/_ts'
hook:
type: object
properties:
enabled:
type: boolean
default: true
description: An optional field which can be used to disable a hook.
priority:
type: integer
default: 99
description: >
The priority of this hook which determines the order in which hooks
are executed.
Hooks with a lwoer priority are executed before ones with a higher
priority.
If no priority is configured, hooks are executed in the order they
are configured in the configuration file.
hook_multi:
allOf:
- type: object
properties:
signals:
type: array
description: A list of signal names to which this hook should be applied
example:
- busA.V
- busB.V
- busC.V
items:
type: string
description: The name of a signal to which this hook should be applied
- $ref: '#/components/schemas/hook'
average:
allOf:
- type: object
required:
- offset
properties:
offset:
type: integer
description: >
The signal offset at which the average signal should be
inserted.
**Examples:**
- `0` inserts the averaged signal before all other signals in
the sample
- `1` inserts the averaged signal after the first signal.
- $ref: '#/components/schemas/hook_multi'
_average:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/average'
cast:
allOf:
- type: object
properties:
new_type:
type: string
enum:
- integer
- float
- boolean
- complex
description: The type of the casted signal.
example: integer
new_name:
type: string
description: The new name of the casted signal.
example: BusA.V
new_unit:
type: string
description: The new unit of the casted signal.
example: V
- $ref: '#/components/schemas/hook_multi'
_cast:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/cast'
decimate:
allOf:
- type: object
required:
- ratio
properties:
ratio:
type: integer
description: >-
The decimation ratio. A value of 4 will skip every, but the 4th
sample in a row.
example: 4
- $ref: '#/components/schemas/hook'
_decimate:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/decimate'
hook_single:
allOf:
- type: object
properties:
signal:
type: string
description: The name of a signal to which this hook should be applied
example: busA.V
- $ref: '#/components/schemas/hook'
dp:
allOf:
- type: object
required:
- f0
- harmonics
properties:
f0:
description: The fundamental frequency.
example: 50
type: number
dt:
description: >-
The timestep of the input samples. Exclusive with `rate`
setting.
default: 0.00005
type: number
rate:
type: number
description: The rate of the input samples. Exclusive with `dt` setting.
harmonics:
type: object
description: A list of selected harmonics which should be calculated.
example:
- 0
- 1
- 3
- 5
items:
type: integer
inverse:
description: Enable the calucation of the inverse transform.
type: boolean
default: false
- $ref: '#/components/schemas/hook_single'
_dp:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/dp'
drop:
allOf:
- $ref: '#/components/schemas/hook'
_drop:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/drop'
dump:
allOf:
- $ref: '#/components/schemas/hook'
_dump:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/dump'
ebm:
allOf:
- type: object
required:
- phases
properties:
phases:
description: Signal indices for voltage & current values for each phase.
example:
- - 0
- 1
- - 2
- 3
- - 4
- 5
type: array
items:
type: array
minItems: 2
maxItems: 2
items:
type: integer
- $ref: '#/components/schemas/hook'
_ebm:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/ebm'
fix:
allOf:
- $ref: '#/components/schemas/hook'
_fix:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/fix'
gate:
allOf:
- type: object
properties:
mode:
description: The triggering condition at which the gate opens.
type: string
default: rising_edge
enum:
- above
- below
- rising_edge
- falling_edge
threshold:
default: 0.5
description: >-
The threshold the signal needs to overcome before the gate
opens.
type: number
duration:
description: >-
The number of seconds for which the gate opens when the
triggering condition is met. Exclusive with the `samples`
setting.
type: number
samples:
description: >-
The number if samples for which the gate opens when the
triggering condition is met. Exclusive with the `duration`
setting.
type: number
- $ref: '#/components/schemas/hook_single'
_gate:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/gate'
jitter_calc:
allOf:
- $ref: '#/components/schemas/hook'
_jitter_calc:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/jitter_calc'
limit_rate:
allOf:
- type: object
required:
- rate
properties:
rate:
type: number
description: >-
The maximum sample rate in `1/s` before this hook will drop
samples.
mode:
type: string
default: local
description: Timestamp which should be used for rate estimation.
enum:
- local
- received
- origin
- $ref: '#/components/schemas/hook'
_limit_rate:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/limit_rate'
limit_value:
allOf:
- type: object
required:
- min
- max
properties:
min:
description: >-
The smallest value which will pass through the hook before
getting clipped.
type: number
max:
description: >-
The largest value which will pass through the hook before
getting clipped.
type: number
- $ref: '#/components/schemas/hook_multi'
_limit_value:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/limit_value'
lua:
allOf:
- type: object
additionalProperties:
description: >
The Lua hook will pass the complete hook configuration to the
`prepare()` Lua function.
So you can add arbitrary settings here which are then consumed by
the Lua script.
properties:
use_names:
type: boolean
default: true
description: >-
Enables or disables the use of signal names in the `process()`
Lua function. If disabled, numeric indices will be used.
script:
type: string
description: >
Provide the path to a Lua script containing functions for the
individual hook points.
Define some or all of the following functions in your Lua
script:
#### `prepare(cfg)`
Called during initialization with a Lua table which contains the
full hook configuration.
#### `start()`
Called when the associated node or path is started
#### `stop()`
Called when the associated node or path is stopped
#### `restart()`
Called when the associated node or path is restarted.
Falls back to `stop()` + `start()` if absent.
#### `process(smp)`
Called for each sample which is being processed.
The sample is passed as a Lua table with the following fields:
- `sequence` The sequence number of the sample.
- `flags` The flags field of the sample.
- `ts_origin` The origin timestamp as a Lua table containing
the following keys:
| Index | Description |
|:-- |:-- |
| 0 | seconds |
| 1 | nanoseconds |
- `ts_received` The receive timestamp a Lua table containing
the following keys:
| Index | Description |
|:-- |:-- |
| 0 | seconds |
| 1 | nanoseconds |
- `data` The sample data as a Lua table container either
numeric indices or the signal names depending on the 'use_names'
option of the hook.
#### `periodic()`
Called periodically with the rate of @ref node-config-stats.
signals:
description: >
A definition of signals which this hook will emit.
Here a list of signal definitions like @ref
node-config-node-signals is expected.
type: array
items:
allOf:
- type: object
properties:
expression:
type: string
example: math.sqrt(smp.data[0] ^ 2 + smp.data[1] ^ 2)
description: >
An arbitrary Lua expression which will be evaluated
and used for the value of the signal.
Note you can access the current sample using the
global Lua variable `smp`.
- $ref: '#/components/schemas/hook'
_lua:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/lua'
ma:
allOf:
- type: object
properties:
window_size:
type: integer
description: >-
The size of the window (number of samples) which should be used
for the moving average filter.
example: 100
default: 0
minimum: 0
- $ref: '#/components/schemas/hook_multi'
_ma:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/ma'
pmu_dft:
allOf:
- type: object
required:
- sample_rate
- start_frequency
- end_frequency
- frequency_resolution
- dft_rate
properties:
sample_rate:
type: integer
default: 0
min: 0
example: 10000
description: The sampling rate of the input signal.
start_frequency:
type: number
min: 0
example: 49.7
description: The lowest frequency bin.
end_frequency:
type: number
example: 50.3
min: 0
description: The highest frequency bin.
frequency_resolution:
type: number
example: 0.1
min: 0
description: The frequency resolution of the DFT.
dft_rate:
type: integer
example: 1
min: 1
description: The number of phasor calculations performed per second.
window_size_factor:
type: integer
default: 1
description: >-
A factor that increases the automatically determined window size
by a multiplicative factor.
window_type:
type: string
enum:
- flattop
- hamming
- hann
- none
default: none
description: The window type.
padding_type:
type: string
enum:
- zero
- signal_repeat
default: none
description: The padding type.
frequency_estimate_type:
type: string
enum:
- quadratic
default: none
description: The frequency estimation type.
pps_index:
type: integer
description: >-
The signal index of the PPS signal. This is only needed if data
dumper is active.
default: 0
angle_unit:
type: string
enum:
- rad
- degree
default: rad
description: The unit of the phase angle.
add_channel_name:
type: boolean
default: false
description: >-
Adds the name of the channel as a suffix to the signal name e.g
`amplitude_ch1`.
timestamp_align:
enum:
- left
- center
- right
default: center
description: The timestamp alignment in respect to the the window.
phase_offset:
type: number
default: 0
example: 10
description: An offset added to a calculated phase.
amplitude_offset:
type: number
default: 0
example: 10
description: An offset added to the calculated amplitude.
frequency_offset:
type: number
default: 0
example: 0.2
description: An offset added to the calculated frequency.
rocof_offset:
type: number
default: 0
example: 1
description: >-
An offset added to the calculated RoCoF. This setting does not
really make sense but is available for completeness reasons"
- $ref: '#/components/schemas/hook_multi'
_pmu_dft:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/pmu_dft'
pps_ts:
allOf:
- type: object
required:
- expected_smp_rate
properties:
mode:
type: string
enum:
- simple
- horizon
default: simple
description: >-
The synchronization mode. The `horizon` mode is currently no
recommended to use as it is not fully tested.
threshold:
type: number
default: 1.5
description: >-
The signal level threshold of the PPS signal which is used to
detect an edge.
expected_smp_rate:
type: integer
description: >-
The expected sampling rate of the input signal. Only important
for a faster initialization.
horizon_estimation:
type: integer
default: 10
horizon_compensation:
type: integer
default: 10
- $ref: '#/components/schemas/hook_single'
_pps_ts:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/pps_ts'
print:
allOf:
- type: object
properties:
output:
type: string
default: /dev/stdout
description: >-
An optional path to a file to which the samples processed by
this hook will be written to.
format:
$ref: '#/components/schemas/format_spec'
prefix:
type: string
default: ''
description: >-
An optional prefix which will be prepended to each line written
by this hook to the output
- $ref: '#/components/schemas/hook'
_print:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/print'
restart:
allOf:
- $ref: '#/components/schemas/hook'
_restart:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/restart'
rms:
allOf:
- type: object
properties:
window_size:
type: integer
description: >-
The size of the window (number of samples) which should be used
for the moving average filter.
example: 100
default: 0
minimum: 0
- $ref: '#/components/schemas/hook_multi'
_rms:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/rms'
- type: object
required:
- window_size
properties:
window_size:
type: integer
min: 1
example: 1000
description: The number of samples in the window.
round:
allOf:
- type: object
properties:
precision:
type: integer
default: 0
example: 4
description: The number of decimal digits to which the signal is rounded.
- $ref: '#/components/schemas/hook_multi'
_round:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/round'
scale:
allOf:
- type: object
properties:
offset:
type: number
default: 0
example: 100.5
description: The offset which is added to the signal after gain.
gain:
type: number
default: 1
example: 1000
description: >-
The gain which is multiplied to the signal before the offset is
added.
- $ref: '#/components/schemas/hook_multi'
_scale:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/scale'
shift_seq:
allOf:
- type: object
required:
- offset
properties:
offset:
type: integer
description: >-
The offset which is added to the sequence number of each
processed sample.
- $ref: '#/components/schemas/hook'
_shift_seq:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/shift_seq'
shift_ts:
allOf:
- type: object
required:
- offset
properties:
mode:
type: string
enum:
- origin
- ts_received
description: >-
The timestamp field which should be adjusted by the `offset`
setting.
offset:
type: number
description: >-
The offset in seconds which is added to the timestamp field of
each processed sample.
- $ref: '#/components/schemas/hook'
_shift_ts:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/shift_ts'
skip_first:
allOf:
- type: object
properties:
samples:
type: integer
description: >-
The number of samples which should be dropped by this hook after
a start or restart of the node/path.
seconds:
type: number
description: >-
The number of seconds for which this hook should initially drop
samples after a start or restart of the node/path.
- $ref: '#/components/schemas/hook'
_skip_first:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/skip_first'
stats:
allOf:
- type: object
properties:
format:
$ref: '#/components/schemas/format_spec'
buckets:
type: integer
default: 20
description: >-
The number of buckets which should be used for the underlying
histograms.
warmup:
type: integer
default: 500
description: >-
Use the first `warmup` samples to estimate the bucket range of
the underlying histograms.
verbose:
type: boolean
default: false
description: Include full dumps of the histogram buckets into the output.
output:
type: string
description: >-
The file where you want to write the report to. If omitted,
stdout (the terminal) will be used.
default: /dev/stdout
- $ref: '#/components/schemas/hook'
_stats:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/stats'
ts:
allOf:
- $ref: '#/components/schemas/hook'
_ts:
allOf:
- $ref: '#/components/schemas/hook_obj'
- $ref: '#/components/schemas/ts'
hook_spec:
description: >
Hooks form a pipeline of steps which process, filter or alter sample
data.
example: print
oneOf:
- $ref: '#/components/schemas/hook_obj'
- title: Hook Name
type: string
enum:
- average
- cast
- decimate
- dp
- drop
- dump
- ebm
- fix
- gate
- jitter_calc
- limit_rate
- limit_value
- lua
- ma
- pmu_dft
- pps_ts
- print
- restart
- rms
- round
- scale
- shift_seq
- shift_ts
- skip_first
- stats
- ts
hook_list:
type: array
title: Hook List
example:
- print
- type: limit_rate
rate: 1000
items:
$ref: '#/components/schemas/hook_spec'
node:
type: object
title: Node
properties:
vectorize:
type: integer
default: 1
description: >
This setting allows to send multiple samples in a single message to
the destination nodes.
The value of this setting determines how many samples will be
combined into one packet.
hooks:
$ref: '#/components/schemas/hook_list'
builtin:
type: boolean
default: true
title: Builtin hook functions
description: >
By default, each node and paths has a couple of default hooks
attached to them. With this setting the attachment of built-in hooks
can be disabled.
in:
type: object
title: Input configuration (received by VILLASnode)
properties:
vectorize:
type: integer
minimum: 1
hooks:
$ref: '#/components/schemas/hook_list'
out:
type: object
title: Output configuration (sent out by VILLASnode)
properties:
vectorize:
type: integer
hooks:
$ref: '#/components/schemas/hook_list'
amqp:
title: Advanced Messaging & Queuing Protocol (AMQP)
allOf:
- type: object
properties:
format:
$ref: '#/components/schemas/format_spec'
uri:
type: string
format: uri
description: |
See also: https://www.rabbitmq.com/uri-spec.html
exchange:
type: string
description: >
The name of the AMQP exchange the node will publish the messages
to.
routing_key:
type: string
description: >
The routing key of published messages as well as the routing key
which is used to bind the subcriber queue.
ssl:
description: >
Note: These settings are only used if the `uri` setting is using
the `amqps://` schema.
type: object
properties:
verify_hostname:
default: true,
verify_peer:
default: true,
ca_cert:
default: /path/to/ca.crt
client_cert:
default: /path/to/client.crt
client_key:
default: /path/to/client.key
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_amqp:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/amqp'
api_signal:
allOf:
- type: object
properties:
description:
type: string
description: A human readable description of the channel.
payload:
description: >
Describes the type of information which is exchanged over the
channel.
type: string
enum:
- events
- samples
range:
oneOf:
- type: object
description: Limits for numeric datatypes
properties:
min:
type: number
max:
type: number
- type: array
description: A list of allowed string values for string datatype
items:
type: string
rate:
optional: true
type: number
description: |
Expected refresh-rate in Hertz of this channel
Does not apply channels which have event payloads.
- $ref: '#/components/schemas/signal'
api:
allOf:
- $ref: '#/components/schemas/node'
- type: object
properties:
in:
type: object
required:
- signals
properties:
signals:
type: array
items:
$ref: '#/components/schemas/api_signal'
out:
type: object
required:
- signals
properties:
signals:
type: array
items:
$ref: '#/components/schemas/api_signal'
_api:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/api'
can_signal:
allOf:
- type: object
properties:
can_id:
type: integer
default: 0
can_size:
type: integer
default: 8
can_offset:
type: integer
default: 0
- $ref: '#/components/schemas/signal'
can:
allOf:
- type: object
properties:
interface_name:
type: string
description: Name of the Socket CAN interface
in:
type: object
properties:
signals:
type: array
items:
$ref: '#/components/schemas/can_signal'
out:
type: object
properties:
signals:
type: array
items:
$$ref: ./signals/can_signal.yaml
- $ref: '#/components/schemas/node'
_can:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/can'
comedi_signal:
allOf:
- type: object
required:
- channel
- range
- aref
properties:
channel:
type: integer
range:
type: integer
aref:
type: integer
- $ref: '#/components/schemas/signal'
comedi:
allOf:
- type: object
required:
- rate
- signals
properties:
subdevice:
type: integer
bufsize:
type: integer
default: 16
signals:
type: array
items:
$ref: '#/components/schemas/comedi_signal'
rate:
type: integer
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_comedi:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/comedi'
ethercat:
allOf:
- type: object
properties:
rate:
type: number
in:
type: object
properties:
num_channels:
type: integer
range:
type: number
product_code:
type: integer
vendor_id:
type: integer
out:
type: object
properties:
num_channels:
type: integer
range:
type: number
product_code:
type: integer
vendor_id:
type: integer
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_ethercat:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/ethercat'
example:
allOf:
- type: object
properties:
setting1:
type: integer
min: 0
max: 100
default: 72
description: A first setting
setting2:
type: string
min: 0
max: 10
default: something
description: Another setting
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_example:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/example'
exec:
allOf:
- type: object
properties:
format:
$ref: '#/components/schemas/format_spec'
shell:
type: boolean
default: false
description: >
If set, the `exec` setting gets passed the shell (`/usr/bin`).
In this case the `exec` setting must be given as a string.
If not set, we will directly execute the sub-process via
`execvpe(2)`.
In this case the exec setting must be given as an array
(`argv[]`).
exec:
description: |
The program which should be executed in the sub-process.
The option is passed to the system shell for execution.
oneOf:
- type: array
items:
type: string
- type: string
flush:
type: boolean
default: true
description: >
Flush stream every time VILLASnode passes data the
sub-process.
working_directory:
type: string
description: >
If set, the working directory for the sub-process will be
changed.
environment:
type: object
description: >
A object of key/value pairs of environment variables which
should be passed to the sub-process in addition to the parent
environment.
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_exec:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/exec'
file:
allOf:
- type: object
properties:
format:
$ref: '#/components/schemas/format_spec'
uri:
type: string
format: uri
description: >
Specifies the URI to a file from which is written to or read
from depending in which group (`in`or `out`) is used.
This setting allows to add special placeholders for time and
date values.
See
[strftime(3)](http://man7.org/linux/man-pages/man3/strftime.3.html)
for a list of supported placeholder.
**Example**:
```
uri = "logs/measurements_%Y-%m-%d_%H-%M-%S.log"
```
will create a file called:
```
./logs/measurements_2015-08-09_22-20-50.log
```
in:
type: object
properties:
epoch:
type: number
epoch_mode:
type: string
enum:
- direct
- wait
- relative
- absolute
description: "The *epoch* describes the point in time when the first message will be read from the file.\nThis setting allows to select the behavior of the following `epoch` setting.\nIt can be used to adjust the point in time when the first value should be read.\n\nThe behavior of `epoch` is depending on the value of `epoch_mode`.\n\nTo facilitate the following description of supported `epoch_mode`'s, we will introduce some intermediate variables (timestamps).\nThose variables will also been displayed during the startup phase of the server to simplify debugging.\n\n- `epoch` is the value of the `epoch` setting.\n- `first` is the timestamp of the first message / line in the input file.\n- `offset` will be added to the timestamps in the file to obtain the real time when the message will be sent.\n- `start` is the point in time when the first message will be sent (`first + offset`).\n- `eta` the time to wait until the first message will be send (`start - now`)\n\nThe supported values for `epoch_mode`:\n\n| `epoch_mode` \t| `offset` \t\t| `start = first + offset` |\n| :--\t\t| :--\t\t\t| :-- |\n| `direct` \t| `now - first + epoch` \t| `now + epoch` |\n| `wait` \t| `now + epoch` \t\t| `now + first` |\n| `relative` \t| `epoch` \t\t| `first + epoch` |\n| `absolute` \t| `epoch - first` \t| `epoch` |\n| `original` \t| `0` \t\t\t| immediately |\n"
rate:
type: number
default: 0
description: >
By default `send_rate` has the value `0` which means that
the time between consecutive samples is the same as in the
`in` file based on the timestamps in the first column.
If this setting has a non-zero value, the default behavior
is overwritten with a fixed rate.
eof:
type: string
default: exit
enum:
- rewind
- wait
- exit
description: >
Defines the behavior if the end of file of the input file
is reached.
- `rewind` will rewind the file pointer and restart
reading samples from the beginning of the file.
- `exit` will terminated the program.
- `wait` will periodically test if there are new samples
which have been appended to the file.
buffer_size:
type: integer
min: 0
default: 0
description: >
Similar to the [`out.buffer_size`
setting](#out-buffer_size). This means that the data is
loaded into the buffer before it is passed on to the node.
If `in.buffer_size = 0`, no buffer will be generated.
out:
type: object
properties:
flush:
type: boolean
description: >
With this setting enabled, the outgoing file is flushed
whenever new samples have been written to it.
buffer_size:
type: integer
default: 0
min: 0
description: >
If this is set to a positive value ``, the node will
generate a full [stream
buffer](https://linux.die.net/man/3/setvbuf) with a size
of `` bytes. This means that the data is buffered and
not written until the buffer is full or until the node is
stopped.
If `out.buffer_size = 0`, no buffer will be generated.
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_file:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/file'
fpga:
allOf:
- type: object
properties:
format:
$ref: '#/components/schemas/format_spec'
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_fpga:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/fpga'
iec60870_signal:
allOf:
- type: object
properties:
asdu_type:
description: Human readable names for the supported IEC60870 message types.
type: string
enum:
- single-point
- double-point
- scaled-int
- normalized-float
- short-float
asdu_type_id:
descrition: The IEC60870 standard type id.
type: string
enum:
- M_SP_NA_1
- M_SP_TB_1
- M_DP_NA_1
- M_DP_TB_1
- M_ME_NB_1
- M_ME_TB_1
- M_ME_NA_1
- M_ME_TA_1
- M_ME_NC_1
- M_ME_TC_1
with_timestamp:
description: (only for use with the human readable asdu_type)
type: boolean
default: false
ioa:
description: >-
The IEC60870 information object address associated with this
signal.
type: number
min: 1
- $ref: '#/components/schemas/signal'
iec60870-5-104:
allOf:
- type: object
properties:
in:
type: object
properties:
signals:
$ref: '#/components/schemas/signal_list'
out:
type: object
properties:
duplicate_ioa_is_sequence:
type: boolean
default: false
description: >
Treat consecutive signals with the same IOA as a sequence by
assigning subsequent IOAs.
signals:
type: array
items:
$ref: '#/components/schemas/iec60870_signal'
address:
type: string
default: localhost
description: |
Hostname or IP address for the IEC60870 slave to listen on.
port:
type: number
default: 2404
description: |
Port number of the IEC60870 slave.
ca:
type: number
default: 1
description: |
Common Address of the IEC60870 slave.
low_priority_queue:
type: number
default: 100
description: >
Message queue size for the periodic messages (increase on
dropped simulation data messages).
high_priority_queue:
type: number
default: 100
description: >
Message queue size for interrogation responses (increase on
missing signals in interrogation response).
apci_t0:
type: number
apci_t1:
type: number
apci_t2:
type: number
apci_t3:
type: number
apci_k:
type: number
apci_w:
type: number
- $ref: '#/components/schemas/node'
_iec60870-5-104:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/iec60870-5-104'
iec61850_goose_data:
allOf:
- type: object
required:
- mms_type
properties:
mms_type:
type: string
enum:
- boolean
- int8
- int16
- int32
- int64
- int8u
- int16u
- int32u
- float32
- float64
- bitstring
description: |
Expected basic data type in received array.
mms_bitstring_size:
type: integer
default: 32
description: |
Size metadata for mms_type bitstring.
iec61850_goose_subscriber_signal:
allOf:
- type: object
required:
- index
- subscriber
properties:
index:
type: number
description: |
Index within the received GOOSE event array.
subscriber:
type: string
- $ref: '#/components/schemas/iec61850_goose_data'
- $ref: '#/components/schemas/signal'
iec61850_goose_publisher_data:
allOf:
- oneOf:
- type: object
properties:
value:
oneOf:
- type: integer
- type: number
- type: boolean
description: |
Constant signal value.
- type: object
required:
- signal
properties:
signal:
type: string
description: |
Name of the input signal for the value.
- $ref: '#/components/schemas/iec61850_goose_data'
iec61850-8-1:
allOf:
- $ref: '#/components/schemas/node'
- type: object
properties:
in:
type: object
properties:
signals:
$ref: '#/components/schemas/iec61850_goose_subscriber_signal'
interface:
type: string
with_timestamp:
type: boolean
subscribers:
type: object
additionalProperties:
type: object
required:
- go_cb_ref
properties:
go_cb_ref:
type: string
dst_address:
type: string
app_id:
type: integer
trigger:
type: string
enum:
- always
- change
default: always
out:
type: object
properties:
signals:
$ref: '#/components/schemas/signal_list'
resend_interval:
type: number
default: 1
description: >
Time interval for periodic resend of last sample in floating
point seconds.
interface:
type: string
default: localhost
description: |
Name of the ethernet interface to send on.
publishers:
type: array
items:
type: object
properties:
go_id:
type: string
go_cb_ref:
type: string
data_set_ref:
type: string
dst_address:
type: string
app_id:
type: integer
conf_rev:
type: integer
time_allowed_to_live:
type: integer
burst:
type: integer
data:
type: array
items:
$ref: '#/components/schemas/iec61850_goose_publisher_data'
_iec61850-8-1:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/iec61850-8-1'
iec61850_signal:
allOf:
- type: object
properties:
iec_type:
type: string
enum:
- boolean
- int8
- int16
- int32
- int64
- int8u
- int16u
- int32u
- int64u
- float32
- float64
- enumerated
- coded_enum
- octet_string
- visible_string
- objectname
- objectreference
- timestamp
- entrytime
- bitstring
- $ref: '#/components/schemas/signal'
iec61850-9-2:
allOf:
- type: object
required:
- interface
properties:
in:
type: object
properties:
signals:
type: array
items:
$ref: '#/components/schemas/iec61850_signal'
out:
type: object
required:
- signals
- svid
properties:
signals:
type: array
items:
$ref: '#/components/schemas/iec61850_signal'
svid:
type: string
confrev:
type: integer
smpmod:
type: string
enum:
- per_nominal_period
- samples_per_second
- seconds_per_sample
smprate:
type: integer
vlan_id:
type: integer
vlan_priority:
type: integer
interface:
type: string
description: >-
Name of network interface to/from which this node will
publish/subscribe for SV frames.
app_id:
type: integer
dst_address:
type: string
- $ref: '#/components/schemas/node'
_iec61850-9-2:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/iec61850-9-2'
infiniband:
allOf:
- type: object
properties:
rdma_port_space:
type: string
enum:
- RC
- UC
- UD
default: RC
description: >
This specifies the type of connection the node will set up.
* `RC` provides reliable, connection-oriented, message based
communication between the nodes. Packets are delivered in order.
In this mode, one Queue Pair is connected to one other Queue
Pair.
* `UC` provides unreliable, connection-oriented, message based
communication between the nodes. This service type is not
officially supported by the RDMA communication manager and is
implemented for scientific purposes in VILLASnode. [The
InfiniBand node-type source code provides information on how to
enable this service
type.](https://git.rwth-aachen.de/acs/public/villas/node/blob/master/lib/nodes/infiniband.c#L429)
* `UD` provides unreliable, connection-less, datagram
communication between nodes. Both ordering and delivery are not
guaranteed in this mode.
`RC`, `UC`, and `UD` are mapped to the Queue Pair types as
`RDMA_PS_TCP`/`IBV_QPT_RC`, `RDMA_PS_IPOIB`/`IBV_QPT_UC`, and
`RDMA_PS_UDP`/`IBV_QPT_UD`, respectively.
If two nodes should be connected, both should be set to the same
`rdma_port_space`.
More information on these two modes can be found on the manual
page for
[`rdma_create_id()`](https://linux.die.net/man/3/rdma_create_id).
in:
type: object
properties:
address:
type: string
description: >
Connections between `infiniband` nodes are established over
IP over IB (IPoIP).
To use this node, you have to make sure that the linux
driver `ib_ipoib` is loaded.
If it is not loaded, load it with `modprobe ib_ipoib`.
If it is loaded, you have to make sure that the Host Channel
Adapters (HCAs) have an IP address.
You can configure the IP address of the Infiniband HCA with
the `ifconfig` utility, exactly like you would configure
normal Ethernet adapters.
As soon as an IP is set for the local HCA, this entry can be
used to point to the adapter and to define the port which
will be used for connection related communication.
**Example**:
```
in = {
address="10.0.0.1:1337"
}
```
binds the node to the local device which is bound to
`10.0.0.1`. It will use port `1337` for communication
related to the connection.
max_wrs:
type: integer
default: 128
description: >
Before a packet can be received with Infiniband, the
application has to describe how this will be handled
(e.g., to what address the data will be written).
This happens in a so called Work Request (WR).
`in.max_wrs` sets the maximum number of receive Work
Requests which can be posted to the receive queue of the
Queue Pair.
For higher throughput, it is recommended to increase this
value since it will serve as a buffer.
cq_size:
type: integer
default: 128
description: >
This value defines the number of Work Completions the
Completion Queue can hold.
If a packet is received, the Queue Pair will write a
Work Completion to the Completion Queue.
The node polls this queue to process received packets.
If the Completion Queue gets full, which is often caused
by `cq_size` being to small, and thus the receive queue
is not able to post Work Completions, the node will
abort.
If a connection is disconnected, all outstanding Work
Requests—even is they are not used—are flushed to the
Completion Queue.
Here applies the same as mentioned above: if the
Completion Queue has fewer space left than outstanding
Work Requests are available, this will result in an
error.
It is therefor recommended to set the value of `cq_size`
to at least
```
in.cq_size >= in.max_wrs - in.buffer_subtraction
```
buffer_subtraction:
type: integer
default: 16
description: >
As mentioned in the `in.max_wrs` settings, Work
Requests have to be present in the receive queue, for
it to be able to process received data.
To take full advantage of the zero-copy capabilities
of Infiniband this node-type directly posts addresses
from the VILLASnode to the receive queue instead of
copying all data over after receiving it.
This technique relies on the exchange of addresses.
This means that if an array of `in.vectorize`
addresses is handed over to the node-type, max
`release` <= `in.vectorize` addresses that point to
received data can be returned.
Furthermore, if `release` addresses should be
returned, `release` addresses from the original array
must be posted to the receive queue.
To ensure that we can always post at least
`in.vectorize` new samples to the receive queue,
`in.buffer_subtraction` must always be bigger than
`in.vectorize`.
A second factor is performance: if
`in.buffer_subtraction` is too small it might take
long before the node starts to process data since it
has to fill almost the complete queue first.
If `in.buffer_subtraction` is too big, the receive
buffer might be too small.
Thus, the maximum number of Work Requests to be
present in the receive queue is defined as follows:
```c
max_wrs_posted = in.max_wrs - in.buffer_subtraction
```
out:
type: object
properties:
address:
type: string
description: >
This value defines the IPoIB address of the remote node and
is used to establish a connection to the remote host—in case
of `RDMA_PS_TCP`—or to get the address handle of the remote
host—in case of `RDMA_PS_UDP`.
This is similar to `in.address`.
`out.address` has no default value and if it is not defined
the node will be set to listening mode and all `out`
configuration will be ignored.
**Example**:
```
out = {
address = "10.0.0.1:1337"
}
```
timeout:
type: integer
default: 1000
description: >
This defines the time in milliseconds
[`rdma_resolve_addr()`](https://linux.die.net/man/3/rdma_resolve_addr)
waits for the resolution of the destination address to
complete.
max_wrs:
type: integer
default: 128
description: >
This is similar to `in.max_wrs` but for the send side of the
Queue Pair.
In contrast to the receive queue, there is no minimum amount
of Work Requests in this queue and it can be filled up
completely to `out.max_wrs`.
cq_size:
type: integer
default: 128
description: >
This is similar to `in.cq_size`.
An important side note for the receive completion queue was
that it should be able to hold all Work Requests if the
receive queue is flushed.
Since no "preparatory" Work Requests are posted to the send
queue and and thus all work requests are send out as soon as
possible, there is no need for `out.cq_size` to be as big as
`out.max_wrs`.
send_inline:
type: boolean
default: true
description: >
It is possible that the CPU copies the data to be sent
directly to the HCA.
Then, the HCA can take the data from it's internal memory as
soon as it is ready to send it.
This has the advantage that the buffer can be returned
immediately to the VILLASnode and that it increases
performance.
If this flag is set, the
[`infiniband`](../nodes/infiniband.md) node-type checks if a
sample is small enough to be sent inline, and if this is the
case sends it inline.
max_inline_data:
type: integer
default: 0
description: >
This value represents the maximum number of bytes to be send
inline.
The maximum number of this value depends on the HCA.
The settings defaults to zero. However, many HCAs will
automatically adjust it to 60.
*Important note*: The greater this value gets, the smaller
`out.max_wrs` can be. If `out.max_inline_data` is too big
for the number specified in `out.max_wrs`, the node will
return an error that the Queue Pair could not be created.
Since this is different for various HCAs, it is not possible
for us to give more specified errors.
**Example**:
```
out = {
send_inline = 1,
max_inline_data = 60
}
```
Every sample which is smaller than 60 bytes will be send
inline. All other samples will be sent normally.
use_fallback:
type: boolean
default: true
description: >
If an out section with a valid remote entry is present in
the configuration file, the node will first bind to the
local host channel adapter and subsequentially try to
connect to the remote host.
If the latter fails (e.g., because the remote host was not
reachable or rejected the connection), there are two
possible outcomes: the node can throw an error and abort or
it can show a warning and continue in listening mode.
If `use_fallback = true`, the node will fallback to
listening mode if it is not able to connect to the remote
host.
periodic_signaling:
type: integer
default:
description: >
If a sample is sent inline, no Completion Queue Entry (CQE)
is generated.
However, once a while, a CQE must be generated to prevent
the Send Queue from overflowing.
Therefore, every `out.periodic_signaling`th sample will be
sent normally with signaling.
It turns out that the ideal value in most cases is
`out.max_wrs / 2`.
Hence, usually, it is not necessary to explicitly set this
value.
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_infiniband:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/infiniband'
influxdb:
allOf:
- type: object
properties:
server:
type: string
description: A hostname/port combination of the InfluxDB database server.
key:
type: string
description: >
The key is the measurement name and any optional tags separated
by commas.
See also: [InfluxDB
documentation](https://docs.influxdata.com/influxdb/v0.9/write_protocols/line/#key).
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_influxdb:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/influxdb'
kafka:
allOf:
- type: object
required:
- server
- client_id
properties:
format:
$ref: '#/components/schemas/format_spec'
server:
type: string
description: >
The bootstrap server `{ip}:{port}` of the Kafka message brokers
cluster.
protocol:
type: string
enum:
- PLAINTEXT
- SASL_PLAINTEXT
- SASL_SSL
- SSL
description: >
The [security
protocol](https://kafka.apache.org/24/javadoc/org/apache/kafka/common/security/auth/SecurityProtocol.html)
which is used for authentication with the Kafka cluster.
client_id:
type: string
description: The Kafka client identifier.
ssl:
type: object
properties:
ca:
type: string
description: >-
Path to a Certificate Authority (CA) bundle which is used to
validate broker server certificate.
sasl:
type: object
description: >
An object for configuring the SASL authentication against the
broker.
This setting is used if the `protocol` setting is on of
`SASL_PLAINTEXT` or `SASL_SSL`.
properties:
mechanisms:
type: string
username:
type: string
password:
type: string
in:
type: object
properties:
consume:
type: string
description: >-
The Kafka topic to which this node-type will subscribe for
receiving messages.
group_id:
type: string
description: >-
The group id of the Kafka client used for receiving
messages.
out:
type: object
properties:
produce:
type: string
description: >-
The Kafka topic to which this node-type will publish
messages.
timeout:
type: number
description: A timeout in seconds for the broker connection.
default: 1
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_kafka:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/kafka'
loopback:
allOf:
- type: object
properties:
queuelen:
type: integer
min: 0
description: >-
The queue length of the internal queue which buffers the
samples.
samplelen:
type: integer
min: 0
description: The number of values each buffered sample can store.
mode:
type: string
enum:
- pthread
- polling
- pipe
- eventfd
- auto
default: auto
description: Specify the synchronization mode of the internal queue.
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_loopback:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/loopback'
mqtt:
allOf:
- type: object
required:
- host
properties:
format:
$ref: '#/components/schemas/format_spec'
in:
type: object
properties:
subscribe:
type: string
description: Topic to which this node subscribes.
out:
type: object
properties:
publish:
type: string
description: Topic to which this node publishes.
username:
type: string
description: >-
The username which is used for authentication with the MQTT
broker.
password:
type: string
description: >-
The username which is used for authentication with the MQTT
broker.
host:
type: string
description: The hostname of the MQTT broker.
example: example.com
port:
type: integer
description: The port number of the MQTT broker.
default: 1883
retain:
type: boolean
description: Set to true to make the will a retained message.
default: false
keepalive:
type: integer
default: 5
description: The MQTT keepalive value.
qos:
type: integer
default: 0
description: The quality of service (QoS) to use for the subscription.
ssl:
type: object
properties:
enabled:
type: boolean
default: true
insecure:
type: boolean
cafile:
type: string
description: >-
Path to a file containing the PEM encoded trusted CA
certificate file.
capath:
type: string
description: >-
Path to a directory containing the PEM encoded trusted CA
certificate files.
certfile:
type: string
description: >-
Path to a file containing the PEM encoded certificate file
for this client.
keyfile:
type: string
description: >-
Path to a file containing the PEM encoded private key for
this client.
cipher:
type: string
description: >-
A string describing the ciphers available for use. See the
`openssl ciphers` tool for more information.
verify:
type: boolean
default: true
description: >
Configure verification of the server hostname in the server
certificate.
If value is set to true, it is impossible to guarantee that
the host you are connecting to is not impersonating your
server.
This can be useful in initial server testing, but makes it
possible for a malicious third party to impersonate your
server through DNS spoofing, for example.
Do not use this function in a real system.
Setting value to true makes the connection encryption
pointless.
tls_version:
type: string
enum:
- tlsv1
- tlsv1.1
- tlsv1.2
description: >
The version of the SSL/TLS protocol to use as a string.
If not set, the default value is used. The default value and
the available values depend on the version of openssl that
the library was compiled against.
For openssl >= 1.0.1, the available options are tlsv1.2,
tlsv1.1 and tlsv1, with tlv1.2 as the default.
For openssl < 1.0.1, only tlsv1 is available.
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_mqtt:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/mqtt'
netem:
description: >
The netem configuration allows the user to apply network impairments to
packets send out by the nodes.
Please note, that the network emulation feature is currently supported
by the following node-types:
- [`socket`](/docs/node/nodes/socket)
- [`nanomsg`](/docs/node/nodes/nanomsg)
- [`zeromq`](/docs/node/nodes/zeromq)
- [`rtp`](/docs/node/nodes/rtp)
type: object
properties:
enabled:
type: boolean
default: true
delay:
type: number
default: 0
description: |
Delay packets in microseconds.
jitter:
type: number
default: 0
title: Jitter
description: |
Apply a jitter to the packet delay (in microseconds).
distribution:
type: string
title: Delay distribution
description: >
One of the delay distributions supported by the `tc` command (see
[tc-netem(8)](https://man7.org/linux/man-pages/man8/tc-netem.8.html)).
enum:
- uniform
- normal
- pareto
- paretonormal
loss:
type: number
default: 0
title: Packet Loss Percentage
description: |
Percentage of packets which will be dropped.
duplicate:
type: number
default: 0
title: Packet Duplication Percentage
description: |
Percentage of packets which will be duplicated.
corrupt:
type: number
default: 0
title: Packet Corruption Percentage
description: |
Percentage of packets which will be corrupted.
nanomsg:
allOf:
- type: object
properties:
format:
$ref: '#/components/schemas/format_spec'
publish:
description: >-
A single endpoint URI or list of URIs on which this node should
listen for subscribers.
oneOf:
- type: string
format: uri
- type: array
items:
type: string
format: uri
subscribe:
description: >-
A single endpoint URI or list of URIs pointing to which this
node should connect to as a subscriber.
oneOf:
- type: string
format: uri
- type: array
items:
type: string
format: uri
out:
type: object
properties:
netem:
$ref: '#/components/schemas/netem'
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_nanomsg:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/nanomsg'
ngsi:
allOf:
- type: object
required:
- endpoint
properties:
endpoint:
type: string
format: uri
entity_id:
type: string
description: ID of NGSI entity.
entity_type:
type: string
description: Type of NGSI entity.
ssl_verify:
type: boolean
description: Verify SSL certificate against local trust store.
timeout:
description: Timeout in seconds for HTTP requests.
type: number
default: 1
rate:
description: Polling rate in Hz for requesting entity updates from broker.
type: number
default: 1
access_token:
type: string
description: Send 'Auth-Token' header with every HTTP request.
create:
type: boolean
default: true
description: Create NGSI entities during startup of node.
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_ngsi:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/ngsi'
opal:
allOf:
- type: object
properties:
send_id:
type: integer
recv_id:
type: integer
reply:
type: boolean
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_opal:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/opal'
redis:
allOf:
- type: object
properties:
mode:
type: string
enum:
- key
- hash
- channel
default: key
description: >
- `key`:
[Get](https://redis.io/commands/get)/[Set](https://redis.io/commands/set)
of [Redis strings](https://redis.io/topics/data-types#strings)
- The implementation uses the Redis `MSET` and `MGET` commands.
- `hash`: Hashtables using [hash
data-type](https://redis.io/topics/data-types#hashes)
- The implementation uses the Redis `HMSET` and `HGETALL` commands.
- `channel`: [Publish/subscribe](https://redis.io/topics/pubsub)
- The implementation uses the Redis `PUBLISH` and `SUBSCRIBE` commands.
uri:
type: string
format: uri
description: >
A Redis connection URI in the form of:
`redis://:@:/`.
host:
type: string
default: localhost
description: |
The hostname or IP address of the Redis server.
You can also connect to Redis server with a URI:
- `tcp://[[username:]password@]host[:port][/db]`
- `unix://[[username:]password@]path-to-unix-domain-socket[/db]`
port:
type: integer
description: The port number of the Redis server to connect to.
default: 6379
path:
type: string
description: A path of a Unix socket which should be used for the connection.
user:
type: string
default: default
description: |
The username which should be used for authentication.
See: https://redis.io/commands/auth
password:
type: string
description: |
The password which should be used for authentication.
See: https://redis.io/commands/auth
db:
type: integer
default: 0
description: |
The logical database which should be used by the Redis client.
See: https://redis.io/commands/select
timeout:
type: object
properties:
connect:
type: number
description: >-
The timeout in seconds for the initial connection
establishment.
socket:
type: number
description: >-
The timeout in seconds for executing commands against the
Redis server.
keepalive:
type: boolean
default: false
description: Enable periodic keepalive packets.
key:
type: string
default:
description: The key which this node will use in the Redis keyspace.
channel:
type: string
default:
description: >-
The channel which this node will use when `mode` setting is
`channel`.
notify:
type: boolean
default: true
description: >
Use [Redis keyspace
notifications](https://redis.io/topics/notifications) to listen
for new updates.
This setting is only used if setting `mode` is set to `key` or
`hash`.
ssl:
type: object
properties:
enabled:
type: boolean
default: true
description: >-
If enabled the connection to the Redis server will be
encrypted via SSL/TLS.
cacert:
type: string
description: A path to a CA certificate file.
cacertdir:
type: string
description: A path to a directory containing CA certificates.
cert:
type: string
description: A path to a client certificate file.
key:
type: string
description: A path to the private key file.
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_redis:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/redis'
rtp:
allOf:
- type: object
properties:
format:
$ref: '#/components/schemas/format_spec'
rtcp:
type: boolean
description: Enable Real-time Control Protocol (RTCP)
aimd:
type: object
properties:
a:
type: number
default: 10
b:
type: number
default: 0.5
Kp:
type: number
default: 1
Ki:
type: number
default: 0
Kd:
type: number
default: 0
rate_min:
type: number
default: 1
rate_source:
type: number
default: 2000
rate_init:
type: number
log:
type: string
hook_type:
type: string
default: disabled
enum:
- decimate
- limit_rate
- disabled
out:
type: object
properties:
netem:
$ref: '#/components/schemas/netem'
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_rtp:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/rtp'
shmem:
allOf:
- type: object
properties:
queuelen:
type: integer
default:
description: Length of the input and output queues in elements.
samplelen:
type: integer
description: >-
Maximum number of data elements in a single `struct Sample`` for
the samples handled by this node.
default:
mode:
type: string
default: pthread
enum:
- pthread
- polling
description: >
If set to `pthread`, POSIX condition variables (CV) are used to
signal writes between processes.
If set to `polling`, no CV's are used, meaning that blocking
writes have to be implemented using polling, leading to
performance improvements at a cost of unnecessary CPU usage.
exec:
description: >
Optional name and command-line arguments (as passed to `execve`)
of a command to be executed during node startup.
This can be used to start the external program directly from
VILLASNode. If unset, no command is executed.
type: array
items:
type: string
in:
type: object
properties:
name:
type: string
description: >
Name of the POSIX shared memory object.
Must start with a forward slash (/).
The same name should be passed to the external program
somehow in its configuration or command-line arguments.
out:
type: object
properties:
name:
type: string
description: >
Name of the POSIX shared memory object.
Must start with a forward slash (/).
The same name should be passed to the external program
somehow in its configuration or command-line arguments.
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_shmem:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/shmem'
signal_node:
allOf:
- type: object
required:
- signal
properties:
signal:
type: string
enum:
- random
- sine
- square
- triangle
- ramp
- counter
- constant
- mixed
- pulse
description: >
The type of signal which should be generated:
- `random`: a random walk with normal distributed step sizes
will be generated.
- `sine`: a sine signal will be generated.
- `square`: a square / rectangle wave will be generated.
- `triangle`: a triangle wave will be generated.
- `ramp`: the generator will produce a ramp signal in the
interval `[ 0, 1 / f ]`.
- `counter`: increasing integer counter is generated.
- `constant`: a constant value generated.
- `mixed`: the signals of of each sample are generated by
cycling over all remaining signal types.
- `pulse`: generates pulses with a set frequency, phase and
width
values:
type: integer
default: 1
description: >-
The number of signals which each of the generated samples should
contain.
rate:
type: integer
description: The rate at which sample should be generated by the node.
default: 10
amplitude:
type: number
description: >-
The amplitude of the signal when the `signal` setting is one of
`sine`, `square` or `triangle`.
default: 1
frequency:
type: number
description: >-
The frequency of the signal when the `signal` setting is one of
`sine`, `square`, `triangle`,`pulse` or `ramp`.
default: 1
phase:
type: number
default: 0
description: >-
Tha pase of the signal when the `signal` setting is one of
`sine` or `pulse`.
pulse_width:
type: number
default: 1
description: The width of the pulse, with respect to the rate
pulse_low:
type: number
default: 0
description: The low value of the pulse signal.
pulse_high:
type: number
default: 1
description: The high value of the pulse signal.
stddev:
type: number
default: 0.2
description: >-
The standard deviation of the normal distributed steps if the
`signal` setting is set to `random`.
offset:
type: number
default: 0
description: Adds a constant offset to each of the generated signals.
limit:
type: integer
default: -1
description: |
Limit the number of generated output samples by this node-type.
A negative number disables the limitation.
realtime:
type: boolean
default: true
description: Wait `1 / rate` seconds between emitting each sample.
monitor_missed:
type: boolean
default: true
description: >
If `true`, the `signal` node-type will count missed steps and
warn the user during every iteration about missed steps.
Especially at high rates, it can be beneficial for performance
to set this flag to `false`.
Warnings would namely cause system calls which will slow the
node down even more, and thus cause even more missed steps.
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_signal_node:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/signal_node'
signal_v2_signal:
allOf:
- type: object
required:
- signal
properties:
signal:
type: string
enum:
- random
- sine
- square
- triangle
- ramp
- counter
- constant
- mixed
- pulse
description: >
The type of signal which should be generated:
- `random`: a random walk with normal distributed step sizes
will be generated.
- `sine`: a sine signal will be generated.
- `square`: a square / rectangle wave will be generated.
- `triangle`: a triangle wave will be generated.
- `ramp`: the generator will produce a ramp signal in the
interval `[ 0, 1 / f ]`.
- `counter`: increasing integer counter is generated.
- `constant`: a constant value generated.
- `mixed`: the signals of of each sample are generated by
cycling over all remaining signal types.
- `pulse`: generates pulses with a set frequency, phase and
width
amplitude:
type: number
description: >-
The amplitude of the signal when the `signal` setting is one of
`sine`, `square` or `triangle`.
default: 1
frequency:
type: number
description: >-
The frequency of the signal when the `signal` setting is one of
`sine`, `square`, `triangle`,`pulse` or `ramp`.
default: 1
phase:
type: number
default: 0
description: >-
Tha pase of the signal when the `signal` setting is one of
`sine` or `pulse`.
pulse_width:
type: number
default: 1
description: The width of the pulse, with respect to the rate
pulse_low:
type: number
default: 0
description: The low value of the pulse signal.
pulse_high:
type: number
default: 1
description: The high value of the pulse signal.
stddev:
type: number
default: 0.2
description: >-
The standard deviation of the normal distributed steps if the
`signal` setting is set to `random`.
offset:
type: number
default: 0
description: Adds a constant offset to each of the generated signals.
- $ref: '#/components/schemas/signal'
signal_v2_node:
allOf:
- type: object
properties:
realtime:
type: boolean
default: true
description: Pace the generation of samples by the `rate` setting.
limit:
type: integer
default: 0
description: Stop the node after the provided number of samples.
rate:
type: number
description: >-
The rate at which the samples are generated if operating in
real-time mode (See `realtime` option).
monitor_missed:
type: boolean
default: false
description: >-
Raise warnings if the signal generator fails to operate in
real-time due to missed deadlines.
in:
type: object
required:
- signals
properties:
signals:
type: array
items:
$ref: '#/components/schemas/signal_v2_signal'
- $ref: '#/components/schemas/node'
_signal_v2_node:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/signal_v2_node'
socket:
allOf:
- type: object
properties:
format:
$ref: '#/components/schemas/format_spec'
layer:
type: string
enum:
- udp
- ip
- eth
default: udp
description: >
Select the network layer which should be used for the socket.
Please note that `eth` can only be used locally in a LAN as it
contains no routing information for the internet.
verify_source:
type: boolean
default: false
description: >
Check if source address of incoming packets matches the remote
address.
in:
type: object
required:
- address
properties:
address:
type: string
description: >
The local address and port number this node should listen
for incoming packets.
Use `*` to listen on all interfaces: `local = "*:12000"`.
out:
type: object
properties:
address:
type: string
description: >
The remote address and port number to which this node will
send data.
netem:
$ref: '#/components/schemas/netem'
multicast:
type: object
properties:
enabled:
type: boolean
default: true
description: |
Weather or not multicast group subscription is active.
group:
type: string
description: |
The multicast group. Must be within 224.0.0.0/4
ttl:
type: integer
min: 0
description: |
The time to live for outgoing multicast packets.
loop:
type: boolean
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_socket:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/socket'
stats_signal:
allOf:
- type: object
required:
- stats
properties:
stats:
type: string
- $ref: '#/components/schemas/signal'
stats_node:
allOf:
- type: object
properties:
rate:
type: number
description: A rate in Hz at which the statistics are generated by this node.
in:
type: object
required:
- signals
properties:
signals:
type: array
items:
$ref: '#/components/schemas/stats_signal'
- $ref: '#/components/schemas/node'
_stats_node:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/stats_node'
temper:
allOf:
- type: object
properties:
calibration:
type: object
properties:
scale:
type: number
default: 1
description: A scaling factor for calibrating the sensor.
offset:
type: number
default: 0
description: An offset for calibrating the sensor.
bus:
type: integer
description: >-
A filter applied to the USB bus number for selecting a specific
sensor if multiple are available.
port:
type: integer
description: >-
A filter applied to the USB port number for selecting a specific
sensor if multiple are available.
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_temper:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/temper'
test_rtt:
allOf:
- type: object
required:
- cases
properties:
format:
$ref: '#/components/schemas/format_spec'
prefix:
type: string
description: >-
A prefix which is prepended to the output file name of the RTT
test result file.
example: test_1
output:
type: string
default: .
description: A directory path at which the RTT test result files be placed.
cooldown:
type: number
default: 0
description: >
A cool-down time between consecutive test cases.
The node will insert a pause between the tests to avoid any
network effects of the previous test-case to influence the
upcoming test-case.
cases:
type: object
description: >
A list of test-case specifications.
The values from the `rates` and `values` settings of each-test
case specification will be used to form a cross-product.
properties:
rates:
description: >
A list of sending rates in Hz.
The resulting test-case will generate samples at the given
rate.
example:
- 10
- 100
- 1000
- 10000
type: array
items:
type: number
values:
description: >
A list of sample length.
The resulting test-case will generate samples with the given
number of signals.
type: array
items:
type: integer
example:
- 10
- 100
limit:
description: >
The resulting test-case will send the number of samples
specified by this setting.
This setting is exclusive with the `duration` setting.
type: integer
example: 10000
duration:
description: >
The resulting test-case will be stopped after the configured
duration in seconds.
This setting is exclusive with the `limit` setting.
type: number
example: 60
- $ref: '#/components/schemas/node'
_test_rtt:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/test_rtt'
uldaq_signal:
allOf:
- type: object
properties:
range:
type: string
description: The range for a specific channel. See `range` for allowed values
input_mode:
type: string
description: >-
The input mode for a specific channel. See `input_mode` for
allowed values
channel:
type: integer
example: 5
description: The channel input number of the device.
- $ref: '#/components/schemas/signal'
uldaq:
allOf:
- type: object
required:
- sample_rate
properties:
interface_type:
type: string
enum:
- usb
- bluetooth
- ethernet
- any
description: >-
The interface to which the ADC is connected. Check manual for
your device.
device_id:
type: string
example: 10000
description: The used device type. If empty it is auto detected.
in:
type: object
description: Configuration for the ul201
properties:
signals:
type: array
items:
$ref: '#/components/schemas/uldaq_signal'
sample_rate:
type: integer
min: 0
example: 10000
description: The default sampling rate of the input signals.
range:
type: string
enum:
- bipolar-60
- bipolar-30
- bipolar-15
- bipolar-20
- bipolar-10
- bipolar-5
- bipolar-4
- bipolar-2.5
- bipolar-2
- bipolar-1.25
- bipolar-1
- bipolar-0.625
- bipolar-0.5
- bipolar-0.25
- bipolar-0.125
- bipolar-0.2
- bipolar-0.1
- bipolar-0.078
- bipolar-0.05
- bipolar-0.01
- bipolar-0.005
- unipolar-60
- unipolar-30
- unipolar-15
- unipolar-20
- unipolar-10
- unipolar-5
- unipolar-4
- unipolar-2.5
- unipolar-2
- unipolar-1.25
- unipolar-1
- unipolar-0.625
- unipolar-0.5
- unipolar-0.25
- unipolar-0.125
- unipolar-0.2
- unipolar-0.1
- unipolar-0.078
- unipolar-0.05
- unipolar-0.01
- unipolar-0.005
description: >
The default input range for signals. Check manual for your
device.
## Supported ranges
| Value | Min | Max |
| :--------------- | :------ | :----- |
| `bipolar-60` | -60.0 | +60.0 |
| `bipolar-60` | -60.0 | +60.0 |
| `bipolar-30` | -30.0 | +30.0 |
| `bipolar-15` | -15.0 | +15.0 |
| `bipolar-20` | -20.0 | +20.0 |
| `bipolar-10` | -10.0 | +10.0 |
| `bipolar-5` | -5.0 | +5.0 |
| `bipolar-4` | -4.0 | +4.0 |
| `bipolar-2.5` | -2.5 | +2.5 |
| `bipolar-2` | -2.0 | +2.0 |
| `bipolar-1.25` | -1.25 | +1.25 |
| `bipolar-1` | -1.0 | +1.0 |
| `bipolar-0.625` | -0.625 | +0.625 |
| `bipolar-0.5` | -0.5 | +0.5 |
| `bipolar-0.25` | -0.25 | +0.25 |
| `bipolar-0.125` | -0.125 | +0.125 |
| `bipolar-0.2` | -0.2 | +0.2 |
| `bipolar-0.1` | -0.1 | +0.1 |
| `bipolar-0.078` | -0.078 | +0.078 |
| `bipolar-0.05` | -0.05 | +0.05 |
| `bipolar-0.01` | -0.01 | +0.01 |
| `bipolar-0.005` | -0.005 | +0.005 |
| `unipolar-60` | 0.0 | +60.0 |
| `unipolar-30` | 0.0 | +30.0 |
| `unipolar-15` | 0.0 | +15.0 |
| `unipolar-20` | 0.0 | +20.0 |
| `unipolar-10` | 0.0 | +10.0 |
| `unipolar-5` | 0.0 | +5.0 |
| `unipolar-4` | 0.0 | +4.0 |
| `unipolar-2.5` | 0.0 | +2.5 |
| `unipolar-2` | 0.0 | +2.0 |
| `unipolar-1.25` | 0.0 | +1.25 |
| `unipolar-1` | 0.0 | +1.0 |
| `unipolar-0.625` | 0.0 | +0.625 |
| `unipolar-0.5` | 0.0 | +0.5 |
| `unipolar-0.25` | 0.0 | +0.25 |
| `unipolar-0.125` | 0.0 | +0.125 |
| `unipolar-0.2` | 0.0 | +0.2 |
| `unipolar-0.1` | 0.0 | +0.1 |
| `unipolar-0.078` | 0.0 | +0.078 |
| `unipolar-0.05` | 0.0 | +0.05 |
| `unipolar-0.01` | 0.0 | +0.01 |
| `unipolar-0.005` | 0.0 | +0.00 |
input_mode:
type: string
enum:
- differential
- single-ended
- pseudo-differential
description: The default sampling type. Check manual for you device.
- $ref: '#/components/schemas/node'
_uldaq:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/uldaq'
webrtc:
allOf:
- type: object
properties:
format:
$ref: '#/components/schemas/format_spec'
wait_seconds:
type: integer
default: 0
description: >
Suspend start-up of VILLASnode for some seconds until the
connection with the remote peer has been established.
ordered:
type: boolean
default: false
description: >
Indicates if data is allowed to be delivered out of order.
The default value of false, does not make guarantees that data
will be delivered in order.
max_retransmits:
type: integer
default: 0
description: >
Limit the number of times a channel will retransmit data if not
successfully delivered.
This value may be clamped if it exceeds the maximum value
supported.
session:
type: string
title: Session identifier
description: >-
A unique session identifier which must be shared between two
nodes
server:
type: string
title: Signaling Server Address
description: Address to the websocket signaling server
default: wss://villas.k8s.eonerc.rwth-aachen.de/ws/signaling
ice:
type: object
title: ICE configuration settings
properties:
servers:
title: ICE Servers
description: A list of ICE servers used for connection establishment
type: array
items:
type: string
format: uri
title: STUN & TURN server URI
description: >
A valid Uniform Resource Identifier (URI) identifying a
STUN or TURN server.
See
[RFC7064](https://datatracker.ietf.org/doc/html/rfc7064)
and
[RFC7065](https://datatracker.ietf.org/doc/html/rfc7065)
for details.
As an extension to the URI format specified additional
username & password can be specified as shown in the
examples
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_webrtc:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/webrtc'
websocket:
allOf:
- type: object
properties:
format:
$ref: '#/components/schemas/format_spec'
destinations:
description: >
During startup connect to those WebSocket servers as a client.
Each URI must use the following scheme:
```
protocol://host:port/nodename
```
It starts with a protocol which must be one of `ws`
(unencrypted) or `wss` (SSL).
The host name or IP address is separated by `://`.
The optional port number is separated by a colon `:`.
The node name is separated by a slash `/`.
type: array
items:
type: string
format: uri
description: A WebSocket URI
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_websocket:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/websocket'
zeromq:
allOf:
- type: object
properties:
format:
$ref: '#/components/schemas/format_spec'
filter:
type: string
enum:
- pubsub
- radiodish
publish:
type: string
format: uri
subscribe:
oneOf:
- type: string
format: uri
- type: array
items:
type: string
format: uri
ipv6:
type: boolean
default: false
curve:
title: CurveZMQ cryptography
description: >
**Note:** This feature is currently broken.
You can use the [`villas
zmq-keygen`](../usage/villas-zmq-keygen.md) command to create a
new keypair for the following configuration options:
type: object
properties:
enabled:
type: boolean
description: Whether or not the encryption is enabled.
public_key:
type: string
description: |
The public key of the server.
private_key:
type: string
description: |
The private key of the server.
out:
type: object
properties:
netem:
$ref: '#/components/schemas/netem'
- $ref: '#/components/schemas/node_signals'
- $ref: '#/components/schemas/node'
_zeromq:
allOf:
- $ref: '#/components/schemas/node_obj'
- $ref: '#/components/schemas/zeromq'
path:
type: object
title: The first anyOf schema
description: An explanation about the purpose of this instance.
required:
- in
properties:
in:
description: >
The in settings expects the name of one or more source nodes or
mapping expressions.
Checkout the [input mapping
section](/docs/node/config/paths#input-mapping) for more details.
oneOf:
- type: string
- type: array
items:
type: string
out:
description: >
The out setting expects the name of one or more destination nodes.
Each sample which is processed by the path will be sent to each of
the destination nodes.
oneOf:
- type: string
- type: array
items:
type: string
enabled:
type: boolean
default: true
description: >
The optional enabled setting can be used to temporarily disable a
path.
reverse:
type: boolean
default: false
description: >
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.
mode:
type: string
default: any
enum:
- any
- all
description: >
The mode setting specifies under which condition a path is
triggered.
A triggered path will multiplex / merge samples from its input nodes
and run the configured hook functions on them.
Afterwards the processed and merged samples will be send to all
output nodes.
Two modes are currently supported:
- `any`: The path will trigger the path as soon as any of the masked
(see `mask`) input nodes received new samples.
- `all`: The path will trigger the path as soon as all input nodes
received at least one new sample.
mask:
description: >
This setting allows masking the the input nodes which can trigger
the path.
See also `mode` setting.
type: array
items:
type: string
description: A node-name
rate:
type: number
minimum: 0
default: 0
description: >
A non-zero value will periodically trigger the path and resend the
last sample again.
A value of zero will disable this feature.
original_sequence_no:
type: boolean
default: false
description: >
When this flag is set, the original sequence number from the source
node will be used when multiplexing the nodes.
hooks:
$ref: '#/components/schemas/hook_list'
uuid:
description: >
A globally unique ID which identifies the path for the use via the
API.
type: string
format: uuid
affinity:
description: |
A mask which pins the execution of this path to a set of CPU cores.
poll:
description: >
A boolean flag which enables the poll-based mode for reading samples
from multiple path sources.
**Note:** This is an advanced setting.
Most users should use the the default value which will always do the
right thing based on the number and type of input nodes for this
path.
type: boolean
builtin:
description: >
If enabled, the path will start with a set of default and builtin
hook functions.
type: boolean
default: true
queuelen:
description: >
The length of the path queue. It limits how many samples can be _in
flight_ at any point in time.
If you see queue or pool underrun warnings, try to increase this
value.
type: number
http:
type: object
properties:
port:
type: integer
default: 80
title: Listening port
description: |
The TCP port number on which HTTP & WebSocket server.
ssl_cert:
type: string
title: SSL Certificate Path
description: |
The public x509 certificate used for server-side SSL encryption.
example: /etc/ssl/certs/mycert.pem
ssl_private_key:
type: string
title: SSL Private Key Path
description: |
The private x509 key used for server-side SSL encryption.
example: /etc/ssl/private/mykey.pem
logging:
type: object
title: Logging configuration
properties:
level:
title: The log level
description: >
This setting expects one of the allowed strings to adjust the
logging level.
Use this with care! Producing a lot of IO by enabling the debug
output might decrease the performance of the server.
type: string
default: info
enum:
- trace
- debug
- info
- warning
- error
- critical
- 'off'
file:
type: string
title: Log file name
description: |
Write all log messages to a file.
syslog:
type: boolean
default: false
title: Enable syslog logging
description: >
If enabled VILLASnode will log to the [system
log](https://en.wikipedia.org/wiki/Syslog).
expressions:
title: Logging expressions
description: >
The logging expression allow for a fine grained control of log
levels per individual logger instance.
Expressions are provided as a list of logger name pattern and the
desired level.
**Note:** The expressions are evaluated in the order of their
appearance in the list.
type: array
items:
type: object
required:
- name
- level
properties:
name:
type: string
title: Logger name filter
description: >-
The
[glob](https://man7.org/linux/man-pages/man7/glob.7.html)-style
pattern to match the names of the loggers for which the level
should be adjusted.
level:
type: string
title: Log level
description: |
The level which should be used for the matched loggers.
enum:
- trace
- debug
- info
- warning
- error
- critical
- 'off'
global:
type: object
properties:
hugepages:
type: integer
default: 100
title: Number of reserved hugepages
description: |
The number of hugepages which will be reservered by the system.
See: https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt
A value of zero will disable the use of huge pages.
stats:
type: number
default: 1
title: Statistics interval
description: >
Specifies the rate at which statistics about the active paths will
be periodically printed to the screen.
Setting this value to 5, will print 5 lines per second.
A line includes information such as:
- Source and Destination of path
- Messages received
- Messages sent
- Messages dropped
affinity:
type: integer
default: 0
title: Task/Process affinity mask
description: >
Restricts 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.
A value of `0` will not change the affinity of the process.
priority:
type: integer
default: 0
description: >
Adjusts the scheduling priority of the deamon processes.
By default, the daemon uses a real-time optimized FIFO scheduling
algorithm.
A value of `0` will not change the priority of the process.
idle_stop:
type: boolean
default: false
uuid:
type: string
format: uuid
title: Super-node UUID
default: randomly generated
description: >
Each VILLASnode instance is identified by a globally unique
indentifier / UUID.
This UUID can be queried by the API.
If the setting is not provided, a UUID will be generated by hashing
the active VILLASnode configuration.
This ensures that restarting the VILLASnode instance with the
identical configuration will yield always the same UUID.
config:
title: VILLASnode configuration file
description: Schema of the VILLASnode configuration file.
allOf:
- type: object
required:
- nodes
additionalProperties: false
properties:
nodes:
type: object
title: Node list
description: >
A list of nodes to/from which this instance sends/receives
sample data.
additionalProperties:
x-additionalPropertiesName: node-name
$ref: '#/components/schemas/node_obj'
paths:
title: Path list
description: >
A list of uni-directional paths which connect the nodes defined
in the `nodes` list.
type: array
default: []
items:
$ref: '#/components/schemas/path'
http:
$ref: '#/components/schemas/http'
logging:
$ref: '#/components/schemas/logging'
- $ref: '#/components/schemas/global'
edgeflex:
title: PMU measurements as used in the EdgeFlex project by Manuel
description: |
VILLASnode does not support deseralization (yet).
type: object
required:
- created
properties:
created:
title: Sampling timestamp
description: A timestamps in miliseconds since 1970-01-01 00:00:00
type: number
minimum: 0
additionalProperties:
description: Key-value pairs of measurements
anyOf:
- type: number
- type: integer
- type: boolean
- type: object
description: A complex number represented in real and imaginary components
properties:
real:
type: number
imag:
type: number
example:
- created: 1633791645123
signal0: 123.456
signal1: true
signal2: 1234
signal3:
real: 1234.4556
imag: 23232.12312
igor:
title: PMU format used by Igor
example:
device: device1
timestamp: '2020-05-20T10:27:57.980802+00:00'
readings:
- channel: BUS1-VA
magnitude: 9.171
phase: 0.8305
frequency: 50.1
rocof: 0.11
- channel: BUS1-IA
magnitude: 9.171
phase: 0.8305
frequency: 50.1
rocof: 0.11
- channel: BUS1-VB
magnitude: 9.171
phase: 0.8305
frequency: 50.1
rocof: 0.11
- channel: BUS1-IB
magnitude: 9.171
phase: 0.8305
frequency: 50.1
rocof: 0.11
- channel: BUS1-VC
magnitude: 9.171
phase: 0.8305
frequency: 50.1
rocof: 0.11
- channel: BUS1-IC
magnitude: 9.171
phase: 0.8305
frequency: 50.1
rocof: 0.11
- channel: BUS1-VN
magnitude: 9.171
phase: 0.8305
frequency: 50.1
rocof: 0.11
- channel: BUS1-IN
magnitude: 9.171
phase: 0.8305
frequency: 50.1
rocof: 0.11
type: object
required:
- device
- timestamp
- readings
properties:
device:
description: ID for measurement device
type: string
timestamp:
description: Timestamp of measurement in ISO 8601 format
type: string
pattern: >-
^\d{4}(-\d\d(-\d\d(T\d\d:\d\d(:\d\d)?(\.\d+)?(([+-]\d\d:\d\d)|Z)?)?)?)?$
readings:
type: array
items:
type: object
properties:
channel:
type: string
description: Name of the monitored bus
magnitude:
type: number
description: Amplitude of the measured signal [V]
phase:
type: number
description: Phase of the measured signal [radian]
frequency:
type: number
description: Frequency of the line signal [Hz]
rocof:
type: number
description: Rate of change of frequency [Hz/s]
sogno-old:
title: Original PMU sensor data format as used in the SOGNO EU project
type: object
required:
- device
- timestamp
- component
- measurand
- phase
- data
properties:
device:
description: ID for measurement device
type: string
timestamp:
description: Timestamp of measurement in ISO 8601 format
type: string
pattern: >-
^\d{4}(-\d\d(-\d\d(T\d\d:\d\d(:\d\d)?(\.\d+)?(([+-]\d\d:\d\d)|Z)?)?)?)?$
component:
description: ID (uuid) from CIM document
type: string
format: uuid
measurand:
type: string
enum:
- voltmagnitude
- voltangle
- currmagnitude
- currangle
- activepower
- reactivepower
- apparentpower
- frequency
phase:
type: string
enum:
- A
- B
- C
data:
type: number
description: >
Measurement value as in the following format depending on value of
measurand:
- voltmagnitude: phase-to-ground RMS value, unit volts
- voltangle: unit radian
- currmagnitude: RMS value, unit ampere
- currangle: unit radian
- activepower: single phase power, unit watts
- reactivepower: single phase power, unit voltampere reactive
- apparentpower: single phase power, unit voltampere
- frequency: unit hertz
example:
device: pmu-abc0
timestamp: '2021-10-07T10:11:12.1231241+02:00'
component: 7a30b61a-2913-11ec-9621-0242ac130002
measurand: voltagemagnitude
phase: A
data: 123124
sogno:
title: PMU format used in SOGNO LF project
example:
device: device1
timestamp: '2020-05-20T10:27:57.980802+00:00'
readings:
- component: BUS1
measurand: voltmagnitude
phase: A
data: 123
- component: BUS2
measurand: voltmagnitude
phase: A
data: 123
type: object
required:
- device
- timestamp
- readings
properties:
device:
description: ID for measurement device
type: string
timestamp:
description: Timestamp of measurement in ISO 8601 format
type: string
pattern: >-
^\d{4}(-\d\d(-\d\d(T\d\d:\d\d(:\d\d)?(\.\d+)?(([+-]\d\d:\d\d)|Z)?)?)?)?$
readings:
type: array
items:
type: object
properties:
component:
description: ID (uuid) from CIM document
type: string
format: uuid
measurand:
type: string
enum:
- voltmagnitude
- voltangle
- currmagnitude
- currangle
- activepower
- reactivepower
- apparentpower
- frequency
phase:
type: string
enum:
- A
- B
- C
data:
type: number
description: >
Measurement value as in the following format depending on
value of measurand:
- voltmagnitude: phase-to-ground RMS value, unit volts
- voltangle: unit radian
- currmagnitude: RMS value, unit ampere
- currangle: unit radian
- activepower: single phase power, unit watts
- reactivepower: single phase power, unit voltampere reactive
- apparentpower: single phase power, unit voltampere
- frequency: unit hertz
parameters:
node-uuid-name:
name: uuid-or-name
description: Either a UUID or node-name
in: path
required: true
schema:
oneOf:
- type: string
format: uuid
- type: string
pattern: '[a-z0-9_-]{2,32}'
path-uuid:
name: uuid
description: A globally unique identifier for each path.
in: path
required: true
schema:
type: string
format: uuid