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