Skip to main content

Configuration

The VILLASnode configuration consists of a a single file.

For a collection of example configuration files see: https://github.com/VILLASframework/node/tree/master/etc/.

File format​

VILLASnode currently supports two config file formats:

Note: Consider using the villas conf2json command to migrate your old configurations to JSON.

Top-level Structure​

At the top level, the configuration file consists of these sections:

OpenAPI / JSON Schema Specification​

There exists a formal description of the configuration file as a JSON Schema / OpenAPI 3.0 specification.

The remaining part of this subsection shows a HTML version of this schema rendered by Redoc:

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"
}

Example​

VILLASnode comes with a lot of existing configurations which can be used for inspiration: https://github.com/VILLASframework/node/tree/master/etc/examples

# Global configuration settings go here
stats = 2

# Webserver / API config
http = {
    port = 8081
}

# Logging
logging = {
    level = "debug
}

# Node definitions
nodes = {
    test_node = {
        in = {
            signals = {
                count = 12
                type = "float"
            }
        }
    }
}

# Path Mapping
paths = (
    {
        in = "test_node",
        out = "test_node"
    }
)

Tips & Tricks​

Use environment variables in your configuration​

VILLASnode substitutes any environment variables in you JSON and libconfig configuration files.

To replace environment variables you must use the following syntax within any string value of your config: ${MYENV_VAR}.

Note: Non-string values can currently not be substituted by environment variables!

Example​

nodes = {
    file_node = {
        uri = "${FILE_PATH}"
    }
}

Include other files into your configuration​

VILLASnode can include other files into you configuration. This allows you to better structure and reuse parts of your configuration (e.g. the node definitions).

File inclusion is handled via a special key in JSON objects named @include. The value of this key must point to an existing file on your file system.

Note: libconfig supports inclusion of other files out of the box via @include directives. So this tip is mostly useful for JSON configuration files.

Example​

params.json
{
  "gain": 1.45,
  "t_dt": 50e-6
}
nodes.json
{
  "test_node": {
    "type": "file",
    "in": {
      "signals": {
        "count": 12,
        "type": "float"
      }
    }
  },
  "signal_node": {
    "signal": "random",
    "in": {
      "hooks": [
        {
          "type": "lua",
          "script": "myscript.lua",
          "@include": "params.json"
        }
      ]
    }
  }
}
experiment1.json
{
  "nodes":{
    "@include": "nodes.json"
  },
  "paths": [
    {
      "in": "signal_node",
      "out": "test_node"
    }
  ]
}