Skip to main content
API docs by Redocly

VILLASnode API (0.10.0)

Download OpenAPI specification:Download

Steffen Vogel: post@steffenvogel.de URL: https://fein-aachen.org/contact/ License: Apache-2.0 Terms of Service

A HTTP/REST API for controlling VILLASnode remotely without the need to restart the daemon.

https://villas.fein-aachen.org/doc/node.html

Super Node

Global super-node related operations.

Get the current status of the VILLASnode instance.

Responses

Response samples

Content type
application/json
{
  • "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": {
    },
  • "kernel": {
    },
  • "system": {
    }
}

Get the capabilities of the VILLASnode instance.

Responses

Response samples

Content type
application/json
{
  • "hooks": [
    ],
  • "node-types": [
    ],
  • "apis": [
    ],
  • "formats": [
    ]
}

Get the currently loaded configuration.

Responses

Response samples

Content type
application/json
{
  • "nodes": {
    },
  • "paths": [
    ]
}

Restart the VILLASnode instance.

Request Body schema: application/json
URL (string) or VILLASnode configuration file (object)
One of
string (URL)

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

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Shutdown the VILLASnode instance.

Responses

Get a graph representation of the currently loaded configuration.

path Parameters
format
string
Enum: "ps" "eps" "txt" "svg" "svgz" "gif" "png" "jpg" "jpeg" "bmp" "dot" "fig" "json" "pdf"

The image format of the generated graph.

query Parameters
layout
string
Enum: "circo" "dot" "fdp" "neato" "nop" "nop1" "nop2" "osage" "patchwork" "sfdp" "twopi"

The Graphviz layout engine used for rendering the graph.

Responses

Nodes

Node related operations.

Get a list of all configure node instances.

Responses

Response samples

Content type
application/json
Example
null

Get the information of a specific node.

path Parameters
required
string or string

Either a UUID or node-name

Responses

Response samples

Content type
application/json
{
  • "name": "udp_node1",
  • "uuid": "b3df1d73-f483-f16c-5936-4ea48295615c",
  • "state": "running",
  • "affinity": -1,
  • "in": {
    },
  • "out": {
    },
  • "type": "socket",
  • "layer": "udp"
}

Get the statistics of a node.

path Parameters
required
string or string

Either a UUID or node-name

Responses

Response samples

Content type
application/json
{
  • "rtp.jitter": {
    },
  • "rtp.pkts_lost": {
    },
  • "rtp.loss_fraction": {
    },
  • "age": {
    },
  • "owd": {
    },
  • "gap_received": {
    },
  • "gap_sent": {
    },
  • "reordered": {
    },
  • "skipped": {
    }
}

Reset the statistics counters for a specific node.

path Parameters
required
string or string

Either a UUID or node-name

Responses

Start a node.

path Parameters
required
string or string

Either a UUID or node-name

Responses

Stop a node.

path Parameters
required
string or string

Either a UUID or node-name

Responses

Pause a node.

path Parameters
required
string or string

Either a UUID or node-name

Responses

Resume a node.

path Parameters
required
string or string

Either a UUID or node-name

Responses

Retart a node.

path Parameters
required
string or string

Either a UUID or node-name

Responses

Rewind the playback file to the beginning.

path Parameters
required
string or string

Either a UUID or node-name

Responses

Rewind the playback file to the beginning.

path Parameters
required
string or string

Either a UUID or node-name

Request Body schema: application/json

Sample position in file

position
required
integer

Skip the first nth samples in the file.

Responses

Request samples

Content type
application/json
{
  • "position": 123
}

Paths

Path related operations.

Get a list of all paths.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get details of a single path.

path Parameters
uuid
required
string <uuid>

A globally unique identifier for each path.

Responses

Response samples

Content type
application/json
{
  • "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": [
    ],
  • "out": [
    ]
}

Start a path.

path Parameters
uuid
required
string <uuid>

A globally unique identifier for each path.

Responses

Start a path.

path Parameters
uuid
required
string <uuid>

A globally unique identifier for each path.

Responses

VILLASnode configuration file

This section decribes the schema of the VILLASnode configuration file. Please use the > to expand the individual sub-sections.

required
object (Node list)

A list of nodes to/from which this instance sends/receives sample data.

Array of objects (Path list)
Default: []

A list of uni-directional paths which connect the nodes defined in the nodes list.

object (http)
object (Logging configuration)
hugepages
integer (Number of reserved hugepages)
Default: 100

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
number (Statistics interval)
Default: 1

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
integer (Task/Process affinity mask)
Default: 0

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
integer
Default: 0

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
boolean
Default: false
uuid
string <uuid> (Super-node UUID)
Default: "randomly generated"

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.

{
  • "nodes": {
    },
  • "paths": [ ],
  • "http": {
    },
  • "logging": {
    },
  • "hugepages": 100,
  • "stats": 1,
  • "affinity": 0,
  • "priority": 0,
  • "idle_stop": false,
  • "uuid": "randomly generated"
}

Edgeflex Format

created
required
number (Sampling timestamp) >= 0

A timestamps in miliseconds since 1970-01-01 00:00:00

additional property
number or integer or boolean or object

Key-value pairs of measurements

[
  • {
    }
]

Igor's Format

device
required
string

ID for measurement device

timestamp
required
string^\d{4}(-\d\d(-\d\d(T\d\d:\d\d(:\d\d)?(\.\d+)?...

Timestamp of measurement in ISO 8601 format

required
Array of objects
{
  • "device": "device1",
  • "timestamp": "2020-05-20T10:27:57.980802+00:00",
  • "readings": [
    ]
}

SOGNO Format

device
required
string

ID for measurement device

timestamp
required
string^\d{4}(-\d\d(-\d\d(T\d\d:\d\d(:\d\d)?(\.\d+)?...

Timestamp of measurement in ISO 8601 format

required
Array of objects
{
  • "device": "device1",
  • "timestamp": "2020-05-20T10:27:57.980802+00:00",
  • "readings": [
    ]
}

Old SOGNO Format

device
required
string

ID for measurement device

timestamp
required
string^\d{4}(-\d\d(-\d\d(T\d\d:\d\d(:\d\d)?(\.\d+)?...

Timestamp of measurement in ISO 8601 format

component
required
string <uuid>

ID (uuid) from CIM document

measurand
required
string
Enum: "voltmagnitude" "voltangle" "currmagnitude" "currangle" "activepower" "reactivepower" "apparentpower" "frequency"
phase
required
string
Enum: "A" "B" "C"
data
required
number

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
{
  • "device": "pmu-abc0",
  • "timestamp": "2021-10-07T10:11:12.1231241+02:00",
  • "component": "7a30b61a-2913-11ec-9621-0242ac130002",
  • "measurand": "voltagemagnitude",
  • "phase": "A",
  • "data": 123124
}