Unified State Control System API

Overview

This document defines structure of USCS messages that are the cannonical protocol of state representation in Liquid Galaxy ROS software.

ROS is a pub-sub network that consists of ROS nodes that are talking to each other on ROS topics. While ROS network graph can be huge and complicated, there are some certain topics that should be considered more important by developers that want to develop Liquid Galaxy experiences. The most important topic that is used for publishing messages defining comprehensive state of all experiences loaded on an LG system is /director/scene. Type of these messages is interactivespaces_msgs

API

All messages have following structure and below attributes are static (e.g. they must be present in all interactivespaces messages):

{
  "description": "human readable description of the message",
  "duration": 0,
  "name": "human identifier of the message",
  "resource_uri": "/uri/of/the/message/without/host/part",
  "slug": "short_identifier_of_message",
  "windows": [
    {
      "activity": "browser",
      "activity_config": {
      },
      "assets": [
        "url or path that should be loaded into the activity"
      ],
      "height": 2160,
      "presentation_viewport": "wall",
      "width": 3840,
      "x_coord": 0,
      "y_coord": 0
    },
    {},
    {},
  ]
}

Key concepts:

• each experience or scene can be comprehensively defined by USCS message and set on the system by emitting it on /director/scene topic
• each experience consists of windows that have assets loaded into them
• each asset is a URL or path to content that should be loaded into activity - e.g. URL "loaded" into browser
• each window has an activity attribute that tells which application pool should show the window (e.g. show the browser on the screen or launch mplayer)
• each window has geometry defined by height, width, x_coord which is an x offset from point 0x0 relative to viewport as well as y_coord which is an y offset relative to point 0x0 of the viewport
• each window has a presentation_viewport which is a portion of Xorg virtual desktop - coordinates are always expressed relative to viewport
• presentation_viewport or viewport is a portion of Xorg desktop defined by widthxheight+x_offset+y_offset

Example messages

• one browser placed on the center screen
• browser on the center and browser on the right
• three browsers covering all viewports
• two browsers on central screen

Above setup consists of two linux boxes (called display nodes): 42-a and 42-b.

Viewports

Viewports are an abstraction layer over physical machines and their Xorg offsets. They notion of viewport is created so displaying content on screens can be defined in more human readable format. For example: in order to display a 100 by 100 image on the center screen, one would have to prepare a message with geometry of 100x100+2470+490. To simplify these numbers, you can use offsets relative to viewports. So with following viewports:

• touchscreen: 1920x1080+0+0
• left_one: 1080x1920+0+0
• center: 1080x1920+1920+0
• right_one: 1080x1920+1080+0

to display a window on center screen one will have to emit message containing window with attributes of "presentation_viewport": "center" and width: 100, height: 100, x_coord:490, y_coord: 910 attributes.

Preloading

Preloading mechanism follows the scenario:

• user is presented with a menu
• user browses thru experiences
• user chooses an experience on the touchscreen
• touchscreen turns into loading state
• chosen experience is being preloaded in the background while previous experience is still present on the touchscreen
• once new experience has been preloaded in the background, readiness ROS message is sent back to the launcher so it can stop showing loading state and progress to loaded. In the same time, old experience turns into HIDDEN state to be destroyed in the background and new experience is shown on the screens (VISIBLE state)

Above scenario is shown on below image:

Enabling preloading in USCS message

There exist two ways to decide on when application should be shown on the screen (e.g. send Ready ROS message upon acquiring "readiness"):

• by default, if preload: true is set, application will set its Ready message upon onDomReady. To enable such readiness, you must set preload attribute
• if onDomReady is not viable, one can decide when to send the message by setting custom_preload_event to true and modifying the application to send the custom event with following code:

window.postMessage({ type: "DIRECTOR_WINDOW_READY" }, "*");

it's documented in the ros_window_ready README file