Synthese Kiosk

{{toc}}

Synthese Kiosk

Introduction

The Synthese Kiosk is a set of software that can be used to display Web pages that should be refreshed regularly on computer connected displays. Although it was developed to display content generated by Synthese, it can be used to display any Web pages.

Features

• Network failure tolerant: continue to display last page if the network is down. Switch to a fallback failure page after a configured amount of time.
• Service failure tolerant: if the page generation service generated an error page, detect this condition and don’t display it (show fallback after a while).
• Automatically launch the browser in full screen.
• Launch and restart the application at system startup and in case of issue.

There are two ways to refresh your page:

• The refresh of the page content is managed by your page itself by using Ajax calls. You must take care that is there is a netrwork issue it must fails silently until the fallback bage is triggered
• The refresh of your page is done periodically by the kiosk. In this case, you must use a browser supported by Selenium in order to have a smooth refresh. Without it, the browser is killed and restarted.

Architecture

A Python application that should be installed on the computer connected to the display. A local configuration file specify basically the browser to use, the page to display in normal mode and in fallback mode.

The Python client uses selenium’s WebDriver library to manage the browser. The client administration interface uses Flask on the server side, Twitter Bootstrap and Knockout on the client side.

Requirements

Tested on Linux and Windows.
Tested on Python 2.6 and Python 2.7.
Can use Firefox, Google Chrome, Opera or any browser launched from the command line.

Installation

Python client (generic)

Download the client from SVN:
svn co https://extranet.rcsmobility.com/svn/synthese3/trunk/utils/SyntheseKiosk

Run the install script, which will install all the required dependencies inside the checked out directory

cd SyntheseKiosk

python install.py

The synhtese-kiosk binary can now be found in env/bin/synthese-kiosk on Linux or env\Scripts\synthese-kiosk.exe on Windows.

To register the software to run on startup and configure the system, launch:

./env/bin/synthese-kiosk —system-install

NOTE: On Windows, paths with spaces in them can produce issues. To avoid this, you should install SyntheseKiosk in a path without spaces, and also use a path without spaces for the configuration. For instance:

C:\synthese_kiosk\SyntheseKiosk\env\Scripts\synthese-kiosk.exe -v -c c:\synthese_kiosk\config —system-install

Python client (Buildroot)

This section explains how to deploy SyntheseKiosk inside a Buildroot environment. See http://buildroot.uclibc.org/ for more information about Buildroot.
These instructions were tested with the official Buildroot version 2012.05.

The Buildroot sources below provide a shell script (run_synthese_kiosk.sh) that can be launched from the Buildroot environment.
This script copies a template configuration directory into /tmp (usually, only /tmp is writeable) and runs SyntheseKiosk.

Adding and configuring the package:

• Checkout the https://extranet.rcsmobility.com/svn/synthese3/trunk/utils/SyntheseKiosk/buildroot/synthese-kiosk directory into buildroot-2012.05/package/synthese-kiosk
• Edit package/Config.in and add the line:
  

  
  
  source “package/synthese-kiosk/Config.in”
  
  

  
  In the section that starts with:
  

  
  
  if BR2_PACKAGE_PYTHON
  
  menu “external python modules”
  
  

• SyntheseKiosk requires Python with a few options. In “Package Selection…” > “Interpreter languages and scripting”:
  • check “python”
  • then in “python module format to install”, select " .py sources and .pyc compiled"
  • in “core python modules”, add: “ssl” and “zlib”
  • in “external python modules”, select “python-setuptools”
• Then you can check “Package Selection for the target” > “Interpreter languages and scripting” > “external python modules” > “synthese-kiosk”.
• Before building, you can customize the template kiosk configuration file. It can be found in package/synthese-kiosk/kiosk_config_template/config.js
• Then you can launch the build as usual.

Running SyntheseKiosk inside the Buildroot

You can run the /usr/bin/run_synthese_kiosk.sh shell script.

Synthese package

Follow the package installation procedure explained on Packages.

Configuration

The Kiosk configuration happens at several levels. First, you need to configure the system.

Then, the configuration is split between the Kiosk server (kiosk specific settings) and Synthese (display specific settings).

System configuration

Make sure the system and display are “always on”:

• Disable screensavers and monitor power save function
• Disable automatic system stand-by and shutdown.

Start the Synthese Kiosk at system startup (this is taken care of by the instructions below, if available for your system)

System specific instructions

OpenSuse 12.1

• Disable screensaver / monitor turning off
  Suse Menu > Applications > Configure Desktop > Power Management > Power Profiles
  uncheck “Screen Energy Saving”
  Suse Menu > Applications > Configure Desktop > Display and Monitor > Screen Saver
  uncheck “Start automatically after”
• Auto login
  Yast > Users and Group Administration > Expert Options (top right) > check Auto Login.

Kiosk Configuration

A Web interface is available to configure and manage the Python client.

First, you should start the client by running the synthese-kiosk script.
You can open a terminal and type this (for Linux):

/path/to/SyntheseKiosk/env/bin/synthese-kiosk

Now, open the Administration interface: http://localhost:5000/

You will be asked a password. The password will be generated the first time it is launched, and is stored in the file ~/.synthese_kiosk/config.json. The password can be changed later from the admin interface (or by editing the config.json file).

From there, you can configure the Synthese the Kiosk. The following parameters can be configured (the configuration can also be specified in the config.json file. The name of the parameter in that file is specified next to the parameter):

• Kiosk Name (kiosk_name): Name of the Kiosk
• Synthese URL (synthese_url): URL of the Synthese server (e.g. http://example.com). This URL is used for fetching the kiosk_config.json configuration file and for resolving the URLs to the pages to display.
• Admin Password (admin_password): Password for the Web configuration interface (unused if accessed from localhost).
• Secret Key (secret_key): secret key used for signing the cookies.
• Browser (browser): id of the browser to use.
• Browser Path (browser_path): Optional browser path (if not using the system one).
• Browser Arguments (browser_args): Comma separated list of browser arguments. You MUST include one argument with the “URL” value that will be replaced with the url to load. For Midori, use: -a,URL,-e,Fullscreen
• Display Names (displays): Comma separated list of display names.
• Offline Cache Directory: The offline cache dir is a local persistent storage place used to save the fallback site.
• Auto Refresh Timeout: This is the period used to force a refresh of the browser. You must use a browser supported by Selenium and have installed the proper driver. If you don’t do so, the browser will be killed and restarted instead of being silently refreshed. Set the value to 0 to disable the refresh.
• Debug (debug): debug mode.

Synthese configuration (Kiosk configuration file)

You must create a page on the CMS accessible with the path /kiosk_config.json (You can specify a different file name in the kiosk config file under the key ‘kiosk_config’).
It must be served with an application/json mime type (also set “Ne pas utiliser le modèle” to NON).
Make sure the syntax is valid JSON, otherwise the Kiosk application won’t be able to parse it.

Here’s a configuration example:

{
  "__doc__": "See https://extranet.rcsmobility.com/projects/synthese/wiki/Synthese_Kiosk",
  "revision": 1,
  "defaults": {
    "configRefreshTimeout": 1200,
    "fallbackRefreshTimeout": 3600,
    "fallbackTimeout": 10, 
    "fallbackUrl": "/screen/screen_fallback"
  },
  "displays": {
    "display0": {
      "url": "/screen"
    }
  }
}

The “defaults” object contains parameters used by default for all displays (unless overridden in the display).
IMPORTANT: time units are in seconds.
“revision”: this field is just a marker. You can increase this number each time your site has changed and you want to force a browser refresh. The refresh is done at the period indicated by the field “configRefreshTimeout”.
“configRefreshTimeout”: time interval between checks to see if the configuration changed. The kiosk will reload if it detected a change.
“fallbackRefreshTimeout”: time period to refresh the local cache the fallback site as specified in ‘fallbackUrl’
“fallbackTimeout” : time period to check if SYNTHESE is online. If it is detected as offline, the locally downloaded fallback page is displayed in the browser
“fallbackUrl” : the URL of the fallback page on the SYNTHESE server

“displays” : specific parameter per display
“display0” : nom de la borne (même que celui dans le champ Display dans la documentation de la borne).
“url” : URL of the page to display in the normal mode for this display
“interactive”: if set to true: mouse interaction is possible on the page and the page is not refreshed automatically (refreshTimeout is ignored).

Requirements for the pages to display

IMPORTANT: These pages shouldn’t reload themselves (using location.reload in a setTimeout for instance). Doing so will cause an issue if the network goes down. The refresh must be done through ajax call and must fail silently until the fallback site is triggered.

Site that refreshes themselves

For site that handle their own refresh internally there is nothing to do, just specify it’s URL in the ‘url’ property.

Site that must be refreshed

If your site doesn’t refresh itself automatically, you can pass it to our page sequencer.

First install the sequencer on your SYNTHESE by using http://localhost:8080/?SERVICE=packages

Then in the ‘url’ property, instead of pointing to your static url, pass it through the sequencer like this:

      “url”: “/sequencer/sequencer.html#{%22target_url%22:%22../mystaticpage.html%22,%22refresh_timeout%22:10}”

• target_url: this is the url of your static site. You must put ../ in front of it to reference the root of your SYNTHESE instance. Take care to replace the quotes by their ASCII code %22.
• refreh_timeout: this is the refresh period in seconds.

Developer documentation

See Synthese_Kiosk_Dev.

Kiosk accessibility while offline.

When the python part of the kiosk detects that the SYNTHESE server is no more accessible, it redirects the browser to display the fallback site locally. The web site is server by the python part itself.

In order for this feature to work, the SYNTHESE server must have been accessible one time or we won’t have a local cache to serve.

FAQ / Howtos

How do I change the URL of the page to display?

1. Go on the SYNTHESE Server administration (http://server/admin)
2. Enter in the CMS Module
3. Enter in the website responding to the URL http://server/ (see Apache rewrite rules if necessary)
4. Find the page called /kiosk_config.json
5. Edit the variable url in the section corresponding to the display