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
optional
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
required

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: true
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.

seed
integer (Random number generator seed)
Default: 0

The seed for the random number generator used by the VILLASnode instance.

If the setting is not provided, a random seed of 0 will be used.

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

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
}