search

FirstLegoLeague / displaySystem

Set of display tools
https://firstlegoleague.github.io/displaySystem/
4 stars 7 forks source link

readme

Display System, a FirstLegoLeague Module

FLL Modules

Display System can be a block in a larger framework of cooperating modules. Read more about it here

However, it can also be used standalone.

Display System

rednblue-plus theme

This is a general purpose, configurable system for data display. It currently contains 8 modules, which are explained further on.

All modules can be controlled via websockets. In particular, we support mhub, which was made for this purpose and supports a higher level of messaging, routing, relaying and clustering. In any case, ordinary websocket is supported, as long as it delivers messages in the format described in the modules.

Also, all modules can be controlled via a javascript interface, so you can write your own scripts to interface with them. Lastly, we provide a control panel that can be opened in a separate screen to control the modules.

Contents

generated with DocToc

Get it running

Test online

You can check out display system online, however, you can't really customize anything. It is a nice way to check it out though.

Everything is served over https, which allows the webcam to work. If you want to control the system via websockets, you can easily set up your own mhub. See Controlling the modules via websockets for a description to get that running.

Get it locally

Either:

There are a few ways to use this package

As a simple display in the browser

  1. Double click index.html. This shows a white screen. Don't worry.
  2. Open the console by pressing F12 and selecting the console tab.
  3. Type displaySystem.modules.time.show() and hit enter.

Ok, some clarification. All modules are hidden by default. Also, all modules are accessible to javascript, which makes it possible to control them. In step 3, you just executed some javascript to show the time. Let's do this some more:

You probably do not want to do this every time you load the display. So, open config.js and replace

'clock': {
    // visible: true
},

by

'clock': {
    visible: true
},

And reload the page. Voilà, the clock is visible by default. You can also do this with other modules.

Also, you probably always want to use the page in full screen mode. To enable full screen, press F11.

Using key bindings

A few key bindings are available by default, but they can be customized by adjusting the keybindings configuration

Using the control window

Since the display can be controlled by javascript, you could create a control window with buttons and such to control everything. You may set this up with two monitors, one facing the audience and one facing you. This way, you can control the screen without having buttons visible.

Luckily, we have already done this for you, but there is a catch. The control window does not work when you are using the display system directly from the file system (if this is the case, the address bar starts with file:///). There are a few ways to solve this:

So, the control window. To open it, press c

The control window shows buttons for all commands that the modules have. There are also input fields if the commands can take arguments. Try and use this to display the time or the clock (for instance in the online version).

Using as a video overlay system

If you want to use the display system as an overlay to a video feed (which is the original purpose), you need to get rid of the white background and replace it with live video. There are several ways to do this

Configuration

All basic configuration is done in the config.js file. The configuration options are:

Advanced usage

Controlling the modules via websockets

If the display system is configured to listen to a websocket server, which can be mhub or some other websocket server, it expects messages of the form:

{
    "topic": <module:action>,
    "data": {
        arg1:value1
    }
}

For example:

{
    "topic": "twitter:addMessage",
    "data": {
        "id": 123,
        "user": {
            "screen_name":"FLL"
        },
        "text": "FLL is great!"
    }
}

Since websockets only support text transfer, the above object should be serialized to JSON. It is automatically deserialized and passed to the apropriate module. To get mhub-server running, just read the instructions. In short:

Install:

npm install -g mhub

Configure sever.conf.json:

{
    "listen": {
        "port": 13900
    },
    "verbose": true,
    "nodes": ["default", "test", "overlay", "twitter"],
    "bindings": [
        { "from": "twitter", "to": "overlay", "pattern": "*" }
    ]
}

Start:

mhub-server

Send a message:

//*nix
mhub-client -n default -t twitter:addMessage -d '{"id":123,"user":{"screen_name":"FLL"},"text":"FLL is great"}'
//windows
mhub-client -n default -t twitter:addMessage -d "{""id"":123,""user"":{""screen_name"":""FLL""},""text"":""FLL is great""}"

In your config.js, make sure you have the following options:

wsHost: "localhost:13900",
mserverNode: "overlay"

Note that in the mhub-server config (server.conf.json), the twitter node is forwarded to the overlay node. That makes this setup work.

For the online version, mhub-server needs to run with tls enabled. To do this, add certificate files to server.conf.json:

{
    "listen": {
        "port": 13900,
        "key": "../certs/privkey.pem",
        "cert": "../certs/fullchain.pem"
    },
    "verbose": true,
    "nodes": ["default", "test", "overlay", "twitter"],
    "bindings": [
        { "from": "twitter", "to": "overlay", "pattern": "*" }
    ]
}

These files are created by the great folks at daplie, who provide certificates for the localhost.daplie.com domain, which just points to localhost (127.0.0.1). The files you need are these:

Note that in the default (online) config.js, we have:

wsHost: "wss://localhost.daplie.com:13900",
mserverNode: "default"

All api functions are automatically exposed as mhub topics. For example, where we used displaySystem.modules.clock.show() via the command line before, we can now do the same via websockets:

mhub-client -n default -t clock:show

When data needs to be added, for example when arming the clock via displaySystem.modules.clock.arm(30), we need to add a data segment to the mhub-client message:

mhub-client -n default -t clock:arm -d '{"countdown":30}'

Adding a twitter feed to your display

Being able to send messages via websockets is nice, but it would be even more nice to connect a twitter feed to the whole lot, right? Luckily there is a command line application to read a twitter stream: node-tweet-cli

Install it like so:

npm install -g node-tweet-cli

Login (see the instructions if it is not clear):

tweet login

Now test your twitter stream in the console:

tweet stream lego

This would start streaming live twitter messages in your console. You are now one step away from connecting everything:

tweet stream lego --json | mhub-client -n default -t twitter:addMessage -i json

This command uses pipes to take the output of the tweet utility and pipe it into mhub-client.

By the way... the hosted version listens to localhost:13900/ on the default node. So you can set up node-tweet-cli and mhub-server locally and still use the hosted version of the display system. Isn't that sweet?

Controlling time

If you have a number of displays, all showing the time, you may want to be sure every display is showing the correct time. By default, the time module shows the system time, but that may be different (if not configured properly) between systems.

Also, you may want to set another time altogether, for example number of minutes into a match.

To set the time, you could just use the control window, but you can also use the websockets interface.

A nice way to ensure a consistent time is to just pipe a timestamp into mhub-client.

First install the cli-time utility:

npm install -g cli-time

Then make sure that in the mhub-server config (server.conf.json), the time node is forwarded to the overlay node.

Then pipe it through to an mhub-client instance:

cli-time -m json -i | mhub-client -n default -t time:set -i json

To set the time to 0 and start counting:

//*nix
mhub-client -n default -t time:set -d '{"timestamp":"0"}'
//windows
mhub-client -n default -t time:set -d "{""timestamp"":""0""}"

Note that the "0" is quoted and it actually means setting the time to Jan 1 2000 at 00:00 in your local timezone.

Modules

This bit lists the available configuration options for the modules (that you can use in config.js). Also, it lists the available javascript functions you can call. Use the following code in the console (behind F12):

displaySystem.modules.<module>.<function>()

For example:

displaySystem.modules.time.show()

background

Background color of the application. Can be used for chromakeying. If not used, the background color is not defined, which can mean transparent in for instance a casparCG HTML producer

Configuration options:

Exposed api:

mhub topics:

camera

Shows attached camera stream as the background

Configuration options:

Exposed api:

mhub topics:

gallery

A gallery of images. Partially transparent images may be used to display for example some logos in corners of the screen. Note that in addition to displaying images, you can use a custom css stylesheet to completely customize your experience (this is somewhat of a more advanced usage though).

To store images online, use any image hosting service, like imgur, postimage or tinypic

Another option for gallery is to display arbitrary pages. These will be displayed in an iframe. Note that not all websites can be displayed this way. Some of them do not allow rendering in an iframe.

Configuration options:

Exposed api:

mhub topics:

sprite

Simple individual images or bits of text that can be placed anywhere on the screen. This is useful for displaying watermarks or logos.

To store images online, use any image hosting service, like imgur, postimage or tinypic

Configuration options:

Exposed api:

mhub topics:

clock

A simple countdown clock. This is the same clock as available on https://github.com/FirstLegoLeague/clock

Configuration options:

Exposed api:

mhub topics:

time

Shows the current system time. Or some other time if you wish

Configuration options:

Exposed api:

The time formatting if based on Steven Levithan's excellent dateFormat() function. For possible mask configuration, see his blog article

mhub topics:

list

Shows a list of things, for examples, rankings or schedules

Configuration options:

Exposed api:

mhub topics:

table

Shows a table of data, similar to list, but more generic in its data format

Configuration options:

Exposed api:

mhub topics:

lowThird

Configuration options:

Exposed api:

mhub topics:

twitter

Configuration options:

Exposed api:

mhub topics:

css

To include custom styling, create a custom stylesheet to override a default style. Use this for instance to customize fonts, text sizes, colors or background images. You can host it somewhere yourself or serve it up with npm start, as described above.

Configuration options:

Exposed api:

geometry

This module controls screen geometry. It allows you to rotate the display, control overscan parameters and zoom.

Configuration options:

Exposed api:

mhub topics:

keybindings

This is a module that handles key bindings. By default it can show and hide other modules and show the control window, as explained in the Using key bindings section above. However, this module is completely user configurable.

The module uses David Flanagan's keymap.js, which is kept in a repository by 鬼道 (luics)

The keybinding configuration takes a map of key bindings with handlers. The key bindings should be strings in the form:

alt-ctrl-f
v
shift-f3

That is:

The handlers could be strings, in which case they are prefixed by displaySystem.modules.. This causes a string like clock.show() to be correctly executed. This allows for a simple way to bind module functions to keys.

Alternatively, handlers could be functions,. In that case, you can do pretty much anything you want, for example define "display groups" under numeric keys, to toggle the visibility of a set of modules.

macro

This module lets you use the other modules exposed functions. It also includes a wait function. Each macro is a list of actions that are executed consecutatively.

Each macro is exposed as a function for this module. Therefor you get buttons for these in the console and you can use macros inside of other macros!

This is a powerfull tool to set scenes or animate sprites together.

controls

This is the actual control window (which you must have seen by now). Display Systems comes with a standard control window that just creates buttons for all api functions of all loaded modules. You can change this by specifying a custom url to open.

Configuration options:

Exposed api

mhub topics:

Theming

Themes can be used by pointing the css module configuration to a stylesheet. This stylesheet can be hosted anywhere. In particular, the following are available:

Included themes

For screenshots, see the themes folder

External themes

We will provide a yearly theme especially for the FIRST LEGO League. Currently, there is none.

Your own themes

You can add your own themes in two ways:

  1. Host them somewhere yourself, by setting up a server, or hosting it through a gh-pages branch in github (which we do for our themes).
  2. Create a GitHub "Gist". Add as many css files as you like, then copy the last bit of the url (the Gist id) and paste it into the gist field in the css module.

The second method creates a stylesheet that can be used to override a certain theme or make small adjustments to it.

Extensibility

You can write your own modules. The displaySystem API provides the following methods:

The registerModule method expects a definition object with the following keys:

For string input, you can use multiline which is included for convenience