Skip to main content

Custom VILLAS Binary

We designed a lightweight message format (or protocol) to facilitate a fast transmission with minimal (de-)serialization overhead. The on-wire format of the network datagrams is not subject to a standardization process.

In contrast to the villas.human format, this binary format is space efficient and commonly used for network communication.

Usually a a simulator sends one message per timestep. A message contains a variable number of values. Each message contains a header with the following fields:

  • 32 bit floating-point or integer values
  • 32 bit timestamp (integral seconds)
  • 32 bit timestamp (integral nanoseconds)
  • 16 bit sequence number
  • 4 bit version identifier

Timestamps are represented in Unix time.

The format of the packets is described by the following code struct Message structure.

VILLAS binary payload format
VILLAS binary payload format.

For now, only the first message type (data) is used. Therefore the complete protocol is stateless. Later we might want to support more complex simulation scenarios which require some kind of controlling.

All values are sent in network byte order (big endian)!

Implementation​

The source code of the format-type is available here: https://github.com/VILLASframework/node/blob/master/lib/formats/villas_binary.cpp

Configuration​

delimiter
string
real_precision
integer
Default: 17

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
boolean
Default: true

If set, include the origin timestamp in the output.

ts_received
boolean
Default: true

If set, include the received timestamp in the output.

sequence
boolean
Default: true

If set, include the sequence number in the output.

data
boolean
Default: true

If set, include the data in the output.

offset
boolean
Default: true

If set, include the offset between origin and received timestamp in the output.

{
  • "delimiter": "string",
  • "real_precision": 17,
  • "ts_origin": true,
  • "ts_received": true,
  • "sequence": true,
  • "data": true,
  • "offset": true
}

Example Configuration​

node/etc/examples/formats/villas-binary.conf
nodes = {
    node = {
        type = "file"
        uri = "/dev/null"

        format = {
            type = "villas.binary"

            source_index = 99
        }
    }
}

Example Payload​

Wireshark capture of UDP traffic
Wireshark capture of UDP traffic.