DICE Web Kiosk for Scientific Linux 6

Note: This document describes the SL6 version of the DICE web kiosks and the associated lcfg-webkiosk component. For information on the original SL5 version of the same, please refer to https://wiki.inf.ed.ac.uk/DICE/WebKioskSL5.


1. Introduction

This note documents what's been done to set up and configure the 'touchscreen' information panels which are located on all floors of the Information Forum.

2. What the system looks like

The general functional idea is that, from start-up, the touchscreen should display a full-screen, undecorated (*) web browser which initially points to a website or page relevant to the location of the screen. The intention is that each screen provides an interactive 'help kiosk'. Users are expected to navigate the kiosk display using the touchscreen only, although equally, in other circumstances, exactly this same software configuration could be used to provide a kiosk navigated by a mouse.

Each touchscreen is driven by a separate DICE box mounted in some (unobtrusive) way nearby. The DICE box should not normally have a keyboard or mouse attached, though a keyboard will be needed at the time of initial machine installation.

(* 'undecorated' means no window frame, and no browser menus. The intention is that the web page content takes up the entire page.)

3. How the system works

The software and configuration files necessary to drive the kiosk are provided by the lcfg-webkiosk component, along with LCFG resource settings and auxiliary packages specified in the dice/options/webkiosk.h header file. (See Appendices B and C below.)

The DICE box driving the kiosk is configured to be a normal DICE desktop (doing so ensures that we have all of the base X and Firefox packages that are needed) but is configured to boot to run level 3, rather than 5. At the completion of the usual LCFG boot sequence, the following /etc/init Upstart job definition file starts a full-screen web browser under the auspices of an unprivileged kioskuser account:


# Job configuration file for the display manager provided by the lcfg-webkiosk component 
# (The intention is to start this job only after LCFG booting is completely finished)
# ** Generated file : do not edit **
description "The display manager provided by the lcfg-webkiosk component"
start on stopped rc3
stop on runlevel [S016]
exec /usr/bin/webkiosk-dm

/usr/bin/webkiosk-dm - the web kiosk 'display manager' - is provided by lcfg-webkiosk. Its job is first to empty, and then appropriately repopulate, the home directory of kioskuser, and then to hand over to the .xinitrc file of kioskuser. If a screensaver has been configured by lcfg-webkiosk resources (which will be the normal case), .xinitrc then starts xscreensaver appropriately, and then finally starts a web browser (currently, Firefox v3.0.9), both under the auspices of the user kioskuser. Note that no window manager is started: this application doesn't require one.

Should the browser process be killed or otherwise exited for any reason, then:

  • .xinitrc will exit;
  • /usr/bin/webkiosk-dm will exit;
  • /usr/bin/webkiosk-dm will be respawned by Upstart;
and the entire cycle described above will repeat.

Both /usr/bin/webkiosk-dm and the .xinitrc file used do enough error checking that any misconfiguration should not result in a wildly-spinning respawn cycle.

Note that the home directory of kioskuser is completely cleared at the start of each cycle. The intention is to start each web 'session' in a completely known state, and also to empty any caches or otherwise that might have been building up.

lcfg-webkiosk code and methods

The lcfg-webkiosk code itself is very minimal; all that are implemented are the configure and run methods.

The configure method optionally creates an appropriate X input driver configuration file which contains touchscreen calibration values (this is only supported for the evdev X input driver), and then kills the running X server. In terms of the above cycle, this means that .xinitrc and /usr/bin/webkiosk-dm will exit, and the latter will then be respawned. Since /usr/bin/webkiosk-dm and .xinitrc themselves make configuration decisions based on the values of lcfg-webkiosk resources, the usual LCFG conventions work as expected: any change in lcfg-webkiosk resources means that the web kiosk display will reconfigure itself appropriately.

The run method runs whichever touchscreen calibration program has been specified by lcfg-webkiosk resources; this should obviously be a suitable calibration program for the touchscreen in use. Such calibration should need to be done once only after a web kiosk machine has been installed; the calibration parameters will be retained on disc thereafter. Note that careful calibration is very important - it will determine how practical the touchscreen is in later use - so the calibration should be done using a pointed stylus rather than, say, a finger.

Screen saver

In order to prevent screen burn, the lcfg-webkiosk resources allow for a screensaver program to be specified and run within the framework provided by xscreensaver. The lcfg-webkiosk component itself supplies one such screen saver - webkiosk-screensaver-floattext (see Appendix B) - which displays a 'floating' configurable text message; this should be suitable for, at least, initial deployments. Should alternative screensavers be wanted then they will need to either be written from scratch, or adapted from the many existing such programs.

4. Specific implementation issues

Touchscreen drivers

The LCD panels assigned for this project are of type 'NEC MultiSync LCD 175VXM+', and investigations show that these have been fitted with USB touchscreens manufactured by eGalax. Under SL6, the usbhid kernel module correctly recognises the touchscreen and assigns an input event to it. (Refer to /usr/bin/lsusb, cat /proc/bus/usb/devices and cat /proc/bus/input/devices.)

So the USB device driver aspect of these screens more-or-less 'just works' in SL5.3 - as can be demonstrated by typing cat /dev/input/event<n> (where n is the number that's been assigned by the kernel module) and dragging your finger across the screen.

The remaining issues are therefore:

  1. How to assign a fixed input event to the USB touchscreen, irrespective of what other USB devices might be attached to the PC.
  2. How to configure an appropriate X input driver.

Under SL6, both of these are solved by using the evdev X input driver (a completely distinct thing from the kernel module of the same name, note!) as supplied by default with the OS. This is a good simplification of the setup which was necessary for SL5.

'Canned' Firefox configuration

As explained in Section 3 above, the /usr/bin/webkiosk-dm display manager completely refreshes the home directory of kioskuser at the start of every cycle. It does this by emptying the directory, and then unpacking 'pre-canned' .mozilla subdirectory along with a couple of other files.

Why this approach? The answer is that it seems virtually impossible - or it would at least be very difficult - to construct the necessary .mozilla subdirectory in any other way, e.g. via the more usual LCFG templating mechanisms: the .mozilla subdirectory is fearsomely complex.

The manual process of producing the canned image is detailed in Appendix E. Note that this 'canning' of the .mozilla. directory will need to be redone if either the required Firefox configuration changes (e.g. a new extension is required), or the version of Firefox used in the web kiosk is changed - which is why I've spelled out the details at some length. On the other hand, there should be no reason to routinely change either the configuration of Firefox, or the version of Firefox in use: the expectation is that this will only generally happen at the time of a complete DICE operating system upgrade.

5. Possible problems, and suggestions for further work

Better 'canned' Firefox configuration

The 'pre-canned' Firefox configuration described in Section 4 and Appendix E is undoubtedly a messy hack. It would be very nice to replace this with a complete template-driven configuration, but that appears to be very difficult. An opinion from a Firefox expert regarding the minimal set of files necessary for a working .mozilla subdirectory might be helpful.

Earlier versions of the dice/options/webkiosk.h header installed the lcfg-ffox component: the intention was that this may have proved useful were alterations to the running Firefox configuration ever required. (That is, the lcfg-ffox component would have allowed changes to be made which would otherwise require the generation of a new 'canned' Firefox configuration.)

In order to reduce inter-dependencies, the current version of the dice/options/webkiosk.h header no longer installs the lcfg-ffox component. This can be reviewed in future if necessary.

The entire issue of how best to use the web browser in the web kiosk could be revisited; a lighter weight web browser than Firefox might be a very good idea.

Problems caused by software upgrades

As mentioned above in Section 4 if the version of Firefox used in the web kiosk application is changed, the 'canned' .firefox configuration will need to be regenerated. In an attempt to minimise the need for this, the dice/options/webkiosk.h header (see: Appendix C) explicitly ties down the version of Firefox, as well as xscreensaver.

There should be no reason to routinely change the versions of either Firefox or xscreensaver; the expectation is that this might happen only at the time of a complete DICE operating system upgrade.


A. Typical web kiosk machine profile

B. Man pages



C. Header files




D. Creating the 'canned' Firefox configuration

(Re)creating the 'canned' Firefox configuration doesn't require access to a touchscreen, but it does require access to a development machine with an attached screen and keyboard whose profile can be altered.

Of necessity, creating the canned configuration is a slightly messy process - and a completely manual one. For these reasons, the process is spelled out in detail below. Note that some of the details below will almost certainly change if either the version of Firefox in use (currently, firefox-10.0.12-1.el6_3), or the Firefox extensions in use, are changed.

The underlying problem here is that Firefox is not designed for programmatic customisation or configuration; a good solution might be to use a different browser entirely.

In any case, proceed as follows:

  1. Allocate a development machine and install it with a profile as follows:

      #include <dice/os/sl6_64.h>
      #include <dice/hw/dell_optiplex_gx745.h>
      #include <dice/options/desktop.h>
      #include <live/wire_forum.h>
      dhclient.mac            nn:nn:nn:nn:nn:nn
      #include <dice/options/webkiosk.h>

    The significance of the DICE_OPTIONS_WEBKIOSK_CREATING_FIREFOX_CONFIG macro is that the machine will be set up with the software and user configuration appropriate to a webkiosk, but will not actually run as a webkiosk.

  2. Login on the machine's console as your normal DICE user.
  3. Become the kiosk user:
    su - kioskuser
  4. Clear out any existing filestore (there probably won't be any):
    rm -rf .[a-z]* .[A-Z]* *
  5. Start a normal Gnome session:
  6. Start an xterm and, from within it, start Firefox: firefox&
  7. Now 'can' the .mozilla directory as follows:


  1. Configure Firefox as follows:

    1. about:config
        browser.sessionstore.resume_from_crash = FALSE

      Comment: we want this setting in order to avoid the 'Your last Firefox session closed unexpectedly ...' dialogue at browser start-up.

    2. Edit> Preferences> Privacy
        Tracking>  Select 'Tell websites I do not want to be tracked'
         History>  Select 'Firefox will never remember history'
    3. Edit> Preferences> Security
        All options should be deselected

      Comment: we don't want any checking: it isn't necessary for our purposes where we're displaying a 'closed' website, and it seems to result in large (and growing!) files like .mozilla/firefox/*.default/urlclassifier3.sqlite.

    4. Install the 'Grab and Drag' extension by navigating to https://addons.mozilla.org/en-US/firefox/addon/1250 and following the instructions

      Comment: this extension is useful for touchscreens: it allows Adobe-style scrolling pressing by _anywhere) on the screen; it can also be used to hide the mouse cursor.

      Configure the extension thus:

      • In 'General', disable 'TextToggle' (Momentum and Flick enabled).
      • In 'More Options', set Mouse Cursor to 'Invisible', and Grabbing Cursor to 'Don't change'.

      Accept the invitation to 'Restart Firefox to complete your changes'.

      Comment: Have tried the above configuration under sl6 and it doesn't quite work as intended so will need to revisit.

    5. Install the 'R-Kiosk' extension by navigating to https://addons.mozilla.org/en-US/firefox/addon/1659 and following the instructions.

      Comment: this extension enables automatic fullscreen, disables the right-click menu (which can otherwise be activated on the touchscreen by keeping a finger depressed on the screen, etc.

      Accept the invitation to 'Restart Firefox to complete your changes'.

      On restart, the browser will go fullscreen. It now needs to be carefully closed down as follows:

      • Use ALT-TAB to cycle through the active windows, make the Firefox 'Add-ons' window the focus window, and explicitly close it down.
      • Close the main Firefox window by typing ALT-F4.

      Comment: In sl5, this tidy closedown was very necessary: if it wasn't done, then the underlying Firefox configuration remembered the 'Add-ons' window, and that window would be (permanently!) displayed on the final touchscreens! The ALT-TAB step doesn't look to be necessary in sl6 but there is no harm in checking.

  2. Do some final manual fix-ups:
    cd ~/kioskuser/.mozilla/firefox/*.default
    rm urlclassifier3.sqlite

    Comment: this particular file can grow quite large, so, as an ad-hoc measure, we want to remove it before 'canning' the configuration. There might be other files within the .mozilla directory that could use the same treatment; an opinion from a Firefox expert might be helpful ...

    Edit localstore.rdf and set the browser window width and height thus:

    <RDF:Description RDF:about="chrome://browser/content/browser.xul#main-window"

    Comment: this hardcodes a standard (?) browser width and height, really just for neatness. At runtime, the appropriate browser width and height will be inserted into the actual localstore.rdf file via the LCFG templating mechanism.

  3. Take a copy of localstore.rdf to a safe location

  4. Can the resulting configuration ...
    cd ~/kioskuser
    tar cf dot.mozilla-1280x1024.tar .mozilla
    gzip dot.mozilla-1280x1024.tar

    ... and copy the resulting file to your working SVN version of the lcfg-webkiosk component as dot.mozilla-1280x1024.tar.gz.

  5. Edit the copy of localstore.rdf to set the browser window width and height thus:
    <RDF:Description RDF:about="chrome://browser/content/browser.xul#main-window"

    ... and copy the resulting file to your working SVN version of the lcfg-webkiosk component as templates/localstore.rdf.tmpl.

    Comment: this is the template localstore.rdf file referred to above.

  6. Finally, make the new 'canned' Firefox configuration live:
    1. Use svn commit to commit the changed files to the LCFG source repository.
    2. Use lcfg-reltool to make a new microversion of the lcfg-webkiosk component.
    3. Use pkgforge submit -B lcfg to build and submit the new version of lcfg-webkiosk to our RPM repositories.
    4. Make the new version active by amending the header file lcfg/options/webkiosk.h and packages/dice/dice_defaults.rpms to contain the new release number.
      (Comment: it's not strictly necessary to amend packages/dice/dice_defaults.rpms, but it makes things less confusing if the version numbers of lcfg-webkiosk are kept in sync throughout our configuration, unless there's a good reason not to do so.)

E. Calibrating the touchscreen

The calibration parameters of any touchscreen are the property of the touchscreen itself, rather than any PC it might be connected to at the time. So, once a touchscreen has been successfully calibrated for any particular X input driver, the resulting calibration parameters should remain valid should, for example, the PC which operates it be replaced.

To calibrate a touchscreen to be used with the evdev X input driver (which is the input driver in use for SL6), proceed as follows:

  1. Install the touchscreen machine as a webkiosk using the <dice/options/webkiosk.h> header.

  2. Ensure that the LCFG resource webkiosk.evdevoptioncalibration is not currently defined in the LCFG profile of the touchscreen machine, and that the profile has compiled without errors and has been accepted by the machine.

  3. You will now need to be standing in front of the touchscreen, so, using a laptop:
    • ssh to the touchscreen machine, and run:
      om webkiosk configure (this sets the evdev X input driver to a known good initial state)
      om webkiosk run (this runs the calibration program)

    • Using a pointed plastic stylus, touch the screen in the exact locations (there are four) indicated by the calibration program.

  4. On completion of the calibration, om webkiosk run will emit the calibration constants appropriate for the touchscreen in use. Example:
    [grangemouth]idurkacz: om webkiosk run
    eGalax touchscreen calibration resource:
    webkiosk.evdevoptioncalibration 256 1653 298 1613

  5. Add the indicated calibration resource (in this example, the line webkiosk.evdevoptioncalibration 256 1653 298 1613, where the four figures refer to xmin, xmax, ymin and ymax, respectively) verbatim to the end of the LCFG profile of the touchscreen machine. Allow the profile to recompile and to propagate to the touchscreen machine. The touchscreen machine will automatically reconfigure, and its touchscreen should now be calibrated.

  6. Check that the calibration is successful and accurate by touching various points of the active screen using a pointed plastic stylus, confirming that the mouse cursor correctly follows the stylus, and that touch navigation is correct, accurate, and usable from a user's point of view

  7. If the calibration seems correct, that ends the process. If the calibration is not accurate, repeat the calibration process starting from step 2 above.

-- IanDurkacz - 31 Jan 2013

Topic revision: r12 - 08 Mar 2017 - 13:13:16 - IanDurkacz
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
This Wiki uses Cookies