Readme.md
1This signaling server defines a very simple protocol to allow the establishing
2of a WebRTC connection between clients and devices. It should only be used for
3development purposes or for very simple applications with no security, privacy
4or scalability requirements.
5
6Serious applications should build their own signaling server, implementing the
7protocol exactly as defined below (any modifications would likely require
8modifications to the client and/or device which will then not be maintained by
9the cuttlefish team).
10
11The signaling server MUST expose two (different) websocket endpoints:
12
13* wss://<addr>/register_device
14* wss://<addr>/connect_client
15
16Additional endpoints are allowed and are up to the specific applications.
17Extending the messages below with additional fields should be done with extreme
18care, prefixing the field names with an applciation specific word is strongly
19recommended. The same holds true for creating new message types.
20
21Devices connect to the *register_device* endpoint and send these types of
22messages:
23
24* {"message_type": "register", "device_id": <String>, "device_info": <Any>}
25
26* {"message_type": "forward", "client_id": <Integer>, "payload": <Any>}
27
28The server sends the device these types of messages:
29
30* {"message_type": "config", "ice_servers": <Array of IceServer dictionaries>,
31...}
32
33* {"message_type": "client_msg", "client_id": <Integer>, "payload": <Any>}
34
35* {"error": <String>}
36
37Clients connect to the *connect_client* endpoint and send these types of
38messages:
39
40* {"message_type": "connect", "device_id": <String>}
41
42* {"message_type": "forward", "payload": <Any>}
43
44The server sends the clients these types of messages:
45
46* {"message_type": "config", "ice_servers": <Array of IceServer dictionaries>,
47...}
48
49* {"message_type": "device_info", "device_info": <Any>}
50
51* {"message_type": "device_msg", "payload": <Any>}
52
53* {"error": <String>}
54
55A typical application flow looks like this:
56
57* **Device** connects to *register_device*
58
59* **Device** sends **register** message
60
61* **Server** sends **config** message to **Device**
62
63* **Client** connects to *connect_client*
64
65* **Client** sends **connect** message
66
67* **Server** sends **config** message to **Client**
68
69* **Server** sends **device_info** message to **Client**
70
71* **Client** sends **forward** message
72
73* **Server** sends **client_msg** message to **Device** (at this point the
74device knows about the client and cand send **forward** messages intended for
75it)
76
77* **Device** sends **forward** message
78
79* **Server** sends **device_msg** message to client
80
81* ...
82
83In an alternative flow, not supported by this implementation but allowed by the
84design, the **Client** connects first and only receives a **config** message
85from the **Server**, only after the **Device** has sent the **register** message
86the **Server** sends the **device_info** messaage to the **Client**.
87