Home
Welcome to the telemersive-gateway!
Here a short explanation of the problem the temersive-gateway tries to solve.
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.
The telemersive network tools solve this with two components:
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.
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.
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)
At the core of the system lies the telemersive-bus, a nodejs 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 connection to the mqttBroker, 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.
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. Currently only the first 200 ports in the allocated range are used:
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 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
The holepuncher is used for a special ultragrid connection: While it is possible to establish one to many connections via the switchboard, its also possible to create direct peer to peer connections without the rerouting over the router. Holepuncher is the service running on the router that makes this possible.
Currently the telemersive-gateway is implemented as a MaxMSP patch, which internally starts a nodejs-object running the client side of the telemersive-bus at the peer's location (also called busClient).
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.
The busClient is a more simplyfied solution with a reduced functionality compared to the gateway, but it doesn't require the access to a telemersive-router.
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.