README.md 4.61 KB
Newer Older
maybites's avatar
maybites committed
1
2
3
4
5
6
7
8
9
10
11
# Telemersive Gateway 0.1.0

Telemersive Gateway is a peer application implementing the telemersive-bus protocol. It communicates with the telemersive-router to connect all peers inside a telemersive room.

## Installation

### Requirements
You need to have [MaxMSP](https://cycling74.com/) installed. There is no need for a license.


### Download
maybites's avatar
maybites committed
12
To install the Telemersive Gateway: clone the gitlab repository into a directory called 'telemersive-gateway'. It is important, that the directory is called this way, otherwise the MaxProject will not work:
maybites's avatar
maybites committed
13
14

```
maybites's avatar
maybites committed
15
git clone https://gitlab.zhdk.ch/telemersive-bus/telemersive-gateway.git
maybites's avatar
maybites committed
16
17
```

maybites's avatar
maybites committed
18
### Startup for the first time
maybites's avatar
maybites committed
19
1. open MaxMSP
maybites's avatar
maybites committed
20
2. Go to File > Open.. and navigate to 'telemersive-gateway.maxproj'
maybites's avatar
maybites committed
21
3. Inside the new Project Window locate 'TelemersiveGateway.maxpat' and double click it
maybites's avatar
maybites committed
22
4. You might be confronted with different popup windows mentioning missing dependencies:
maybites's avatar
maybites committed
23
24
25
26
27
    * Missing MaxPackages like
    ![Dependencies](/media/GUI_Dependencies.png "Dependencies")
      * Spout (on Windows) or Syphon (on OSX)
      * Sadam Libraries
      -> simply follow the 'install' button.
maybites's avatar
maybites committed
28
    * Missing NodeJS Libraries -> the [config] window should be already open > go to tab 'debug' and press 'script npm install'. Once the debug tool turns from blue to green, you are good to go.
maybites's avatar
maybites committed
29
30
    ![Debug](/media/GUI_Debug.png "Debug")

maybites's avatar
maybites committed
31
5. If you want to get videostreams or synchronize your files: set paths to externals > tab 'externals'.
maybites's avatar
maybites committed
32
33
    *  For enabling videostreams you need to download Ultragrid and point the app to the ultragrid app.
    * **Windows only:** For synching files on windows you need to have cygwin installed. During the installation process, make sure you install 'rsync', which is not installed by default. On OSX this is installed by default.
maybites's avatar
maybites committed
34
    * **Windows only:** If you want to send Mocap data from Motive (Optitrack), you need the NatNet2OSC apps. Motive 2.x will work with NatNet3. If you only want to receive data, there is no need for this external.
maybites's avatar
maybites committed
35
36
37
38
    ![Externals](/media/GUI_Externals.png "Externals")


### Login
maybites's avatar
maybites committed
39

maybites's avatar
maybites committed
40
![Login](/media/GUI_Login.png "Login")
maybites's avatar
maybites committed
41
42

1. Enter your credentials under the tab 'login'. This infos are confidential and are only provided on a need to know basis.
maybites's avatar
maybites committed
43
44
45
46
47
48
    * Router URL:  e.g. 'telematics.zhdk.com'
    * Router Port: e.g. '1883'
    * Router User: e.g. 'peer'
    * Router Pwd: e.g. '*******'
2. Network Card: If your machine has more than one network card available, you will have to choose which one you want to use.
3. press 'connect'
maybites's avatar
maybites committed
49
50
51

If the connection is successful, the red 'disconnect' button gets highlighted and the green 'connect' button greyed-out.

maybites's avatar
maybites committed
52
53
4. Once you are connected, you can now see all the available rooms to join.
5. Enter your room credentials.
maybites's avatar
maybites committed
54
55
56
    * Enter your PeerName
    * Select a room from the menu or enter a room name.
    * Enter the room password
maybites's avatar
maybites committed
57
58
59
60

If the room you enter doesn't exist, a new room will be created and the password will be set as the room password. The password cannot be changed anymore, only once every peer has left the room, the room manager (a service of the telemersive-router) removes the room and again a new room with the same name but with a new password can be created.

6. press 'join'
maybites's avatar
maybites committed
61
62
63

If the room join is successful, the red 'leave' button gets highlighted and the green 'join' button greyed-out.

maybites's avatar
maybites committed
64
65
66
67
68
69
70
71
72
73
7. press 'save' to save all the credentials for your next login. Save also stores your local device settings.

press 'close' to close the [config]-window.

### Closing the app
press the 'quit' button in the upper right corner

![Login](/media/GUI_Quit.png "Login")

You will be presented with a choice:
maybites's avatar
maybites committed
74

maybites's avatar
maybites committed
75
76
77
'cancel' will cancel the process.
'No' will quit the app **without** saving the current state.
'Yes' will quit the app **after** saving the current state.
maybites's avatar
maybites committed
78
79
80
81
82
83
84
85
86
87
88

### FAQ

* Using ultragrid, I want to send a Spout stream, but the receiver only gets a black texture.
  * Check the local Spout settings. The local machine needs to be able to share textures via GPU (a dedicated GFX-Card). In some instances it was enough to simply open the spout settings (located at C:\Program Files\SPOUT-2007\SPOUTSETTINGS) and confirm with 'OK'
* I am sending a stream, and one machine receives the stream and the other is not.
  * Check the firewall. Both Windows and OSX will request a confirmation if a network connection is started (usually only once for each channels).
    * Windows: Settings > Update & Security > Windows Security > Firewall and Network protection > Allow an app through the firewall
      * look for 'NatNetThree2OSC' and 'uv_tb0' .. 'uv_tb9'
    * OSX: System preferences > Security & Privacy > Firewall > Firewall Options
      * look for 'uv-qt'