Overview

Omni is a communication server that connects applications over WebSockets. Today, Omni is used to connect mobile devices in an audience to a WisDome show, and to connect stationary user interfaces to exhibitions.

This page details why Omni is used, how it works, and how you can use it.

Purpose

WisDome is the peak of digital visualization and offers an immersive experience like none other. The theater is not only capable of showing 3D movies, but real time applications that showcase live data, allowing the speaker to transform the experience to the audience's interest. However, there is a large interest in technology that allows visitors to engage directly with the show, turning it into a complete interactive experience.

For visitors to be able to influence the dome application, they need some sort of controller. A simple solution is to provide a website that audience members can connect to using their smartphones. To support this, instead of setting up a web server for every dome application, Omni was created as a third party service that allows applications to connect to each other over the internet.

How does Omni work?

Omni is used to connect applications over the internet, allowing them to send messages between each other. Applications can reach Omni by setting up a WebSocket connection, sending JSON messages to communicate. Initially, the application must provide a token to identify which "service" the connection belongs to, after which all subsequent messages are directly passed between the connected "host" and "client" channels.

Services

Omni allows applications to communicate with each other through a service. Upon connecting, the application must provide a service token to authenticate it as a host or client. A guest application may connect by providing a public code instead of a token.

Terminology

Host: A host is the application acting as the exhibition - the star of the show. The host channel can be connected to using the service's host token.

Client: A client is a single user interface that interacts with the host. It can either be a touch table for visitors or a remote control for the speaker. Clients may connect to Omni before the host is online. The client channel can be connected to using the service's client token.

Guest: A mobile website where multiple visitors can connect to the host using a public code. Guests are kicked when the host disconnects. The guest channel can be connected to using the service's public code, which is received upon connecting as a host.

Creating a new service

New services are handled by administrators at https://omni.itn.liu.se/admin/. Contact Måns Gezelius if you need a new service.

Channels

Each application that connects to Omni will be placed into a channel. Every channel can serve multiple consumers (connected devices) and broadcast messages to all connected devices within it. For instance, if a host application sends a message to Omni, it will transmit the message from the host channel to all consumers in the client channel.

How to connect

Following is a general guide how to connect to Omni along with a flowchart for how the communication works. Once connection is established, any further messages will be directly transmitted from the host to all clients and vice versa.

If a service has public code enabled, an additional message will be sent to the host upon connecting, providing the temporary code. Any guest application that connects using the code will be assigned to the service's client channel.

Prerequisites

• A framework that can initiate a WebSocket connection.
• A host or client token belonging to a service registered at Omni.

Checklist

• Connect your WebSocket to wss://omni.itn.liu.se/ws/
  • Server response
    • {"type": "server_connect", "message": "Welcome! Please provide a token."}
• Authenticate as host
  • Send: {"token": <HOST_TOKEN>}
  • Server response:
    • {"type": "server_authorized", "message": "Authorized as host"}
    • {"type": "server_code", <PUBLIC_CODE>}
• Authenticate as client
  • Send: {"token": <CLIENT_TOKEN>}
  • Server response:
    • {"type": "server_authorized", "message": "Authorized as client"}
• Authenticate as guest
  • Send: {"token": <PUBLIC_CODE>}
    • Server response {"type": "server_authorized", "message": "Authorized as guest"}

Flowchart

This is an example of communication between a dome application, omni and a website on a phone.

Additional responses

Omni provides additional messages for certain events. For normal JSON messages, Omni appends additional information to each message to idenfity the sender.

• user - the user id of the application the message was sent from. The username is a 6 letter hexadecimal string.
• role - the role of the application the message was sent from. There are three roles: host, client and guest.

Following is a list of all event driven messages that Omni sends:

• {"type": "server_connect", "message": "..."}
  • Upon connecting successfully
• {"type": "server_disconnect", "message": "..."}
  • Upon forced disconnect, such as guests being kicked after host disconnects
• {"type": "server_authorized", "message": message}
  • Upon authorizing successfully
• {"type": "server_code", "code": <PUBLIC_CODE>}
  • Upon new public code being generated (when host authenticates)
• {"type": "server_join", "role": "host/client/guest", "user": <USER_ID>}
  • Upon new application connecting.
• {"type": "server_leave", "role": "host/client/guest", "user": <USER_ID>}
  • Upon application disconnecting.
• {"type": "server_error", "message": "..."}
  • Errors including non-json message sent or invalid token.