Skip to main content

WebRTC

The webrtc node-type exchanges messages via the WebRTC protocol. It allows peer-to-peer data exchange with minimal configuration between two VILLASnode instances or a VILLASnode instance and a web-browser.

The node-type uses WebRTC data-channels to transport the sample data which can be formatted in any of the supported format-types. Data-channels establish an encrypted transport using the SCTP and DTLS protocols. DTLS itself is transported over UDP and therefore benefits from the same advantages as UDP for low-latency real-time communication.

In addition, WebRTC fully automates the process connection establishment. Users do not have to exchange IP addresses or port numbers as for the socket node-type. Instead just a common session name needs to be agreed on between the two nodes. Under the hood a signaling server is used for exchanging address and session information.

To summarize

The WebRTC node-type allows you to couple simulators and labs as easy as a Zoom/Skype video conference 📺.

Lab exercise

For a hands-on exercise, please have a look at Lab 18: WebRTC.

See also: The WebSocket node-type is a related but older node-type.

Prerequisites​

This node-type requires libdatachannel > v0.18.4. We recommend building libdatachannel with libnice to support ICE connections via TCP by passing the -DUSE_NICE=ON to CMake.

WebRTC Signaling Server​

A publicly reachable signaling server is required. RWTH-ACS operates such a signaling server at https://villas.k8s.eonerc.rwth-aachen.de/ws/signaling which is used by default.

caution

If two VILLASnode instances are connected, the names of the webrtc nodes must be different between the configuration files.

If a local signaling server can be easily started for testing purposes using this Docker image:

docker run -p 8080:8080 --privileged registry.git.rwth-aachen.de/acs/public/villas/signaling

The source code is available here: https://github.com/VILLASframework/signaling

Implementation​

The source code of the node-type is available here: https://github.com/VILLASframework/node/blob/master/go/pkg/nodes/webrtc/

Limitations​

note

WebRTC only supports is limited to the bi-directional exchange of data between two peers. Exchanging data between a group of more than two peers is not possible.

Please refer to the websocket, mqtt or amqp node-types for exchanging data between a of nodes using a publish/subscribe message pattern.

Web Demo​

caution

This demo is currently broken. Please follow this issue for updates: https://github.com/VILLASframework/node/issues/725

There exists an example WebRTC peer implementation running in a web-browser:

Configuration​

Format Object (object) or Format Name (string) (format_spec)
wait_seconds
integer
Default: 0

Suspend start-up of VILLASnode for some seconds until the connection with the remote peer has been established.

ordered
boolean
Default: false

Indicates if data is allowed to be delivered out of order. The default value of false, does not make guarantees that data will be delivered in order.

max_retransmits
integer
Default: 0

Limit the number of times a channel will retransmit data if not successfully delivered. This value may be clamped if it exceeds the maximum value supported.

session
string (Session identifier)

A unique session identifier which must be shared between two nodes

server
string (Signaling Server Address)
Default: "wss://villas.k8s.eonerc.rwth-aachen.de/ws/signaling"

Address to the websocket signaling server

object (ICE configuration settings)
object (Input configuration (received by VILLASnode))
vectorize
integer
Default: 1

This setting allows to send multiple samples in a single message to the destination nodes.

The value of this setting determines how many samples will be combined into one packet.

Array of Hook Object (object) or Hook Name (string) (hook_list)
builtin
boolean (Builtin hook functions)
Default: true

By default, each node and paths has a couple of default hooks attached to them. With this setting the attachment of built-in hooks can be disabled.

object (Output configuration (sent out by VILLASnode))
{
  • "format": "villas.human",
  • "wait_seconds": 0,
  • "ordered": false,
  • "max_retransmits": 0,
  • "session": "string",
  • "server": "wss://villas.k8s.eonerc.rwth-aachen.de/ws/signaling",
  • "ice": {},
  • "in": {
    },
  • "vectorize": 1,
  • "hooks": [
    ],
  • "builtin": true,
  • "out": {
    }
}

Example​

node/etc/examples/nodes/webrtc.conf
nodes = {
    webrtc_node = {
        type = "webrtc"

        format = "json"

        # A unique session identifier which must be shared between two nodes
        session = "my-session-name"

        # Address to the websocket signaling server
        server = "https://villas.k8s.eonerc.rwth-aachen.de/ws/signaling"

        # Limit the number of times a channel will retransmit data if not successfully delivered
            # This value may be clamped if it exceeds the maximum value supported
        max_retransmits = 0

        # Number of seconds to wait for a WebRTC connection before proceeding the start
        # of VILLASnode. Mainly used for testing
        wait_seconds = 10 # In seconds

        # Indicates if data is allowed to be delivered out of order
            # The default value of false, does not make guarantees that data will be delivered in order
        ordered = false

        # Setting for Interactive Connectivity Establishment
        ice = {
            # List of STUN/TURN servers
            servers = (
                "stun:stun.0l.de:3478",
                "turn:villas:villas@turn.0l.de:3478?transport=udp",
                "turn:villas:villas@turn.0l.de:3478?transport=tcp"
            )
        }
    }
}

Further reading​