|
|
Welcome to the telemersive-gateway!
|
|
|
|
|
|
# The problem
|
|
|
|
|
|
Here a short explanation of the problem the temersive-gateway tries to solve.
|
|
|
|
|
|
![DiagramProblem.svg](svg/DiagramProblem.svg)
|
|
|
|
|
|
Let's assume you have three locations with three indivdual networks (LAN), each sitting behind a firewall whose administrators have no intention to make any changes whatsowever (for example inside a university).
|
|
|
|
|
|
You are challenged to share different data streams between these locations with as little latency as possible without messing up networking between the individual machines inside the individual LAN's.
|
|
|
|
|
|
# Overview
|
|
|
|
|
|
The telemersive network tools solve this with two components:
|
|
|
|
|
|
* The [telemersive-router](https://gitlab.zhdk.ch/telemersion/telemersive-router)
|
|
|
* The [telemersive-gateway](https://gitlab.zhdk.ch/telemersion/telemersive-gateway)
|
|
|
|
|
|
The **telemersive-router** is running on a server with a public IP address, and the **telemersive-gateway** is running on each peer/machine to help bridging the firewall.
|
|
|
|
|
|
Each **telemersive-gateway** can either join an existing room or create it's own room with password to control the access by other gateways.
|
|
|
|
|
|
![Diagram](svg/DiagramUserView.svg "UserView")
|
|
|
|
|
|
This diagram shows the situation from the perspective of a gateway user. Three gateways are connected to the router and have joined the same room. The joined gateways can now share their individual data sources.
|
|
|
|
|
|
Each gateway opens internally a device that helps to create the connection between the gateways mediated by the router.
|
|
|
|
|
|
# Details
|
|
|
|
|
|
A more detailed view shows that the communication between the components is a bit more complicated, though this complication is hidden from the user and a user doesn't need to know about this. (Unless he/she is curious)
|
|
|
|
|
|
![Diagram](svg/DiagramDetail.svg "Solution")
|
|
|
|
|
|
At the core of the system lies the [telemersive-bus](https://gitlab.zhdk.ch/telemersion/telemersive-bus), a [nodejs](https://nodejs.org/en/) library that helps to connect the individual clients (also called a busClient), coordinated by a manager (also called a busManager). It facilitates the creation of individual rooms into which clients can enter if they know the correct password.
|
|
|
|
|
|
Each gateway has a busClient that implements this library and opens a [MQTT](https://en.wikipedia.org/wiki/MQTT) connection to the [mqttBroker](https://mosquitto.org/), that is part of the router.
|
|
|
|
|
|
Also part of the router is the busManager which organizes the creation and access to rooms. It communicates with the [switchBoard](https://gitlab.zhdk.ch/telemersion/telemersive-switchBoard).
|
|
|
|
|
|
On the server the router is running each room gets a port-range allocated. For example: If the room number is 11, the port range allocated starts with 11'000 and ends with 11'999. The switchBoard is responsible for starting a set of proxyScripts inside that range.
|
|
|
|
|
|
Depending of the type of proxyScript, the script opens one or two ports on which the gateways can send and/or receive data. The scripts are relatively dumb and simply pass on the UDP packages they receive to the connected gateways, depending on their type:
|
|
|
|
|
|
* one to one bidirectional - receives and sends on the same port
|
|
|
* one to many monodirectional - receives on one and sends on another port
|
|
|
* one to many bidirectional - a port for the 'one' and a port for the 'many'
|
|
|
* many to many bidirectional - receives and sends on the same port
|
|
|
|
|
|
# Implementation
|
|
|
|
|
|
## telemersive-gateway
|
|
|
|
|
|
Currently the telemersive-gateway is implemented as a MaxMSP patch, which internally starts a nodejs-object running the client side of the [telemersive-bus](https://gitlab.zhdk.ch/telemersion/telemersive-bus) at the peer's location (also called busClient).
|
|
|
|
|
|
![Diagram](media/TG_device_ultragrid_2peers.png "matrix")
|
|
|
|
|
|
The gateway comes with an easy to use GUI to give an overview of all the peers participating inside the same room.
|
|
|
|
|
|
For each connection type it shows a matrix of all channels available, with icon indicators in which direction the data flows and framerates if available.
|
|
|
|
|
|
It is possible to remote control the connections of each peer from any other peer. If the connection is utilizing a CLI app like ultragrid or NatNet2OSC, it is possible to monitor the logout of these apps even from a remote peer to investigate problems.
|
|
|
|
|
|
The Userinterface makes the configuration of the CLI apps very simple and user friendly.
|
|
|
|
|
|
## busClient
|
|
|
|
|
|
![Diagram](svg/DiagramSimpleRouter.svg "Solution")
|
|
|
|
|
|
As previously mentioned, at the core of the telemersive-gateway lies the busClient, the nodejs client based on the telemersive-bus. The busClient can be running bare bones and thus give direct access to the more limited functionality the telemersive-bus provides, which includes
|
|
|
|
|
|
* chat
|
|
|
* mqtt
|
|
|
* OSC (lists*)
|
|
|
* connection speed test
|
|
|
|
|
|
*With OSC there is a caveat. Technically they are lists and not OSC. All the data is transmitted via MQTT, which only allows to send strings (or byte arrays). So the content of OSC messages are lists which are serialized to strings and deserialized upon receiving them. For MaxMSP users there is usually no difference to tell between a list and a OSC message, but technically they are not the same. |