6.7 KiB
Berkely BSD Sockets
The socket node-type is the most comprehensive and complex one. It allows to send and receive simulation data over the network. Internally it uses the well known BSD socket API.
Please note that only datagram / packet, connection-less based network protocols are supported. This means that there's currently no support for TCP!
The implementation supports multiple protocols / OSI layers:
- Layer 1: Raw Ethernet Frames (no routing!)
- Layer 2: Raw IP (internet / VPN routing possible)
- Layer 3: UDP encapsulation
Configuration
Every socket node supports the following special settings:
local ("ip:port" | "mac:protocol")
remote ("ip:port" | "mac:protocol")
netem (dictionary)
Enables and configures the network emulation qeueing discipline. See below for a more detailed description of this feature.
netem = { # Network emulation settings
# Those settings can be specified for each node invidually!
delay = 100000, # Additional latency in microseconds
jitter = 30000, # Jitter in uS
distribution = "normal", # Distribution of delay: uniform, normal, pareto, paretonormal
loss = 10 # Packet loss in percent
duplicate = 10, # Duplication in percent
corrupt = 10 # Corruption in percent
}
layer ("udp" | "ip" | "eth")
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.
header ("default" | "none" | "fake")
The socket node-type supports multiple protocols:
- The
defaultVILLASnode header includes a couple of fields like the origin timestamp, number of values and the endianess of the transported data. The packet format is described in the following section called "Packet Format". - It is also possible to just send raw data by omitting the header completely (
none). Each value is expected to take 4 bytes. It can be either a single precission floating point number (float) or a 32 bit unsigned integer (uint32_t). This protocol is used by RTDS' GTNET-SKT card. - The
fakesetting is very similar to thenonesetting. Only the first three values will have a special interpretation:- Sequence no. (
uint32_t) - Timestamp seconds (Unix epoch,
uint32_t) - Timestamp nano-seconds (Unix epoch,
uint32_t)
- Sequence no. (
endian ("big" | "network" | "little")
This setting is only valid for the none and fake protocols.
It select the endianes which is used for outgoing and incoming data.
Example
nodes = {
udp_node = { # The dictionary is indexed by the name of the node.
type = "socket", # Type can be one of: socket, opal, file, gtfpga, ngsi
# Start the server without arguments for a list of supported node types.
### The following settings are specific to the socket node-type!! ###
layer = "udp" # Layer can be one of:
# udp Send / recv UDP packets
# ip Send / recv IP packets
# eth Send / recv raw Ethernet frames (IEEE802.3)
header = "gtnet-skt:fake", # Header can be one of:
# default | villas Use VILLASnode protocol (see struct msg) (default)
# none | gtnet-skt Use no header, send raw data as used by RTDS GTNETv2-SKT
# fake | gtnet-skt:fake Same as 'none', but use first three data values as
# sequence, seconds & nanoseconds timestamp
# In this mode values are uint32_t not floats!
endian = "network", # Endianess of header and data:
# big | network Use big endianess. Also know as network byte order (default)
# little Use little endianess.
local = "127.0.0.1:12001", # This node only received messages on this IP:Port pair
remote = "127.0.0.1:12000" # This node sents outgoing messages to this IP:Port pair
vectorize = 30 # Receive and sent 30 samples per message (multiplexing).
}
}
Packet Format
The on-wire format of the network packets is not subject to a standardization process. It's a very simple packet-based format which includes:
- 32bit floating-point or integer values
- 32bit timestamp (integral seconds)
- 32bit timestamp (integral nanoseconds)
- 16bit sequence number
- 4bit version identified
- and several flags...
Message
A message contains a variable number of values. Usually a a simulator sends one message per timestep.
Simulation data is encapsulated in UDP packages in sent over IP networks like the internet. We designed a lightweight message format (or protocol) to facilitate a fast transmission.
@diafile msg_format.dia
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.
Except for the simulation data, all values are sent in network byte order (big endian)! The endianess of the simulation data is indicated by a single bit in the message header. This allows us to reduce the amount of conversions during one transfer.
@see msg for implementation details.
Example
@todo add screenshot of wireshark dump
Network Emulation
VILLASnode supports the emulation of wide-area network characterisics.
This emulation can be configured on a per-node basis for outgoing (egress) data only. Incoming data is not processed by the network emulation!
This network emulation is handled by Linux' netem queuing discipline which is part of the traffic control subsystem. Take a look at the following manual page for supported metrics: tc-netem(8).
VILLASnode only takes care of setup and initalizing the netem queuing discipline inside the kernel.
For this the iproute2 software package (ip & tc commands) must be installed.
The configuration is done via the config file.
Look at etc/example.conf for a section called netem or tc-netem(8) for more details.
Custom delay distribution
Netem supports loading custom delay distributions.
- Load and compile the netem tools from: https://git.kernel.org/cgit/linux/kernel/git/shemminger/iproute2.git/tree/netem
- Create a custom distribution by following the steps described here: https://git.kernel.org/cgit/linux/kernel/git/shemminger/iproute2.git/tree/README.distribution
- Put the generated distrubtion with the suffix
.distin thetclib directory:/usr/lib/tc/. - Load the distribution specifying the basename in the server config.