The NOAA SOS Public Kiosk (“Public Kiosk”) software initially debuted with the
SOS 5.0 release. It provides a touch screen controller intended for a general
public audience to interact with a Science On a Sphere® (SOS) exhibit when there
is no docent present. It has some similarities with other third party kiosks
created in the past for SOS, such as the Bishop Museum’s kiosk. The motivation
for building the Public Kiosk was to provide a flexible and easy-to-administer
public controller that can be localized to native languages by using standard
The Public Kiosk is fully supported by its NOAA software developers and is
included as part of the normal SOS customer support. Suggestions for new
features and submissions of bug reports is highly encouraged to keep improving
the Public Kiosk into the future, so please email
The Public Kiosk software is available to all current SOS customers at no cost
upon request by emailing email@example.com.
Instructions will be provided on how to download the software, which is provided
as a standard Windows setup.exe program that unpacks and installs the software
as well as the default configuration files on the PC. Most of the files reside
under C:\shared\sos\kiosk, so the Windows user must have privileges
to write to the C: drive. The kiosk software doesn’t use the
Windows registry. Approximately 80MB of disk space is required for the software
and data files.
Once installed, the hostname or IP address of the SOS machine must be changed
in the kiosk_server property for the Kiosk to
operate. See the Administration User Interface section for more
information. To tell if the Public Kiosk is correctly connected to the SOS
machine, look at the colored dot in the lower left corner of the Public User
Interface. If it is green, the connection is working correctly, but if it is
red, they are not connected and either the settings or the networking must be
The Public Kiosk software may occasionally crash, leaving the Windows PC with
the desktop showing. To remedy this situation, you can install an application
that will automatically detect that the kiosk is no longer running and restart
it automatically. One free application that does this is called Restart On
Crash and it has been successfully used with the Public Kiosk. Instructions on
how to download and install this utility are described in Appendix
D. There are many other Windows restart applications available that
may work with the Public Kiosk and NOAA is not specifically endorsing the use of
Restart On Crash.
The Public Kiosk has two main user interfaces (UIs), one for public interaction
with SOS and another for administration of the kiosk. The public UI is normally
the one displayed and is described in this section, while the latter is
described in the Admin UI section.
Located at the top. This area includes a logo image at the left, title and
subtitle text, an information button (“i” symbol), and a group of language
buttons. The language buttons transform the language of the UI to the selected
choice. The supported languages are preselected by each venue (see the
Localization/Translations to Non-English Languages section for
information on how to set up translations).
Located on the left side. This is a scrollable set of rectangular buttons, each
of which defines a related set of datasets. By default, these are largely the
same as the Major Categories in the SOS Data Catalog, but can be changed to fit
each venue’s needs (see the Group and Dataset Configuration
Located on the bottom. This is a scrollable set of circular buttons, each of
which defines a dataset for the currently selected group. By default, these are
NOAA’s selection of the best and most popular datasets for each group, but can
be changed to fit each venue’s needs (see the Group and Dataset Configuration
Located on the right side. This is a scrollable set of circular buttons, each of
which defines an overlay dataset that may be shown on top of the current
dataset. By default, these are all of NOAA’s set of overlay datasets, but fewer
may be shown to can fit with the venue’s needs.
Located left of center. This is a text area that usually displays a brief
description of the currently selected dataset. When the information button is
selected, this area displays an introduction to SOS and instructions on how to
use the Public Kiosk.
Located right of center. This is a collection of controls to manipulate the
sphere. A spherical trackball controller is used to drag the sphere horizontally
and vertically with curved arrow next to it used to tilt the sphere (by tapping
or dragging it). Below the sphere are buttons to reset the sphere position, play
or pause it, turn globe rotation on/off for animations, step one frame
backward/forward, and a frame slider.
Located lower right corner. The “gear” button is used to access the user
interface for kiosk administration controls. It includes the ability
to lock the kiosk UI when a presenter is using the iPad controller.
The Public Kiosk is highly configurable using the Administration User Interface
(Admin UI), which is launched by pressing the gear icon in the lower right
corner of the Public UI. A numeric keypad appears to enter a 4-digit
administration passcode (the default is 1234, which should be changed!). The
back-arrow key is used to delete a mistyped digit. Note that if the kiosk was
previously locked, a 4-digit lock code must be entered (the default is 4321,
which should also be changed).
The Admin UI has five tabs (described below) and a set of common buttons, Apply
and Close at the bottom right and X at the top right, that are used
for all options. Apply must be pressed for changes to be saved. Pressing either
Close or X simply dismisses the Admin UI without saving changes made.
The Properties tab presents a table of kiosk properties and controls to change
their settings. Colors are represented with hexadecimal characters for
red-green-blue that are set using a popup Color Chooser. Numbers are set using a
graphical Numeric Keypad or a dropdown Number Chooser, and text is set using a
Graphical Keyboard. Examples of each of these controls are given after the
property list. Note that for more extensive editing, a regular keyboard may be
attached to the kiosk machine and used instead of the graphical keyboard and
A comma separated list of localization strings for the languages supported in
the kiosk. It must include the locale_default value in the list. These are used
to specify the language buttons shown. If only one locale is specified, the
language buttons are hidden. Set using the Graphical Keyboard.
For example, to use American English, Mexican Spanish, and Traditional Chinese
in Taiwan, the value would be: en_US,es_MX,zh_TW. If new
locale_options are added, it is necessary to restart the kiosk for them to take
The localization string for the language in which the kiosk starts. The
localization string uses the ISO 639-1 two letter code for language
an underscore (“_”) and then the ISO 3166 for the country or region.
Set using the Graphical Keyboard.
The name or IP address of the machine configured for FTP (typically the SOS
machine, something like sos1). The default will not work and must
be changed to a valid value. Set using the Graphical Keyboard.
The password being used for FTP transfers on the SOS machine (typically the
password used for the sos user). The default will not work and must be changed
to a valid value. Set using the Graphical Keyboard.
Analogous to the SOS Autorun mode, this property controls the behavior for
automatically playing datasets in the kiosk. Set using the Numeric Keypad.
manual mode only
cycles repeatedly through all the datasets in the Group specified by the
value of the autoPlayGroup property
cycles randomly through all the datasets in the kiosk
When autoplay is on, each dataset plays for the length of time
specified by the duration property. If autoplay is
interrupted by a person manually selecting a dataset, the autoplay
will restart again after a length of time specified by the timeout property
Length of time in seconds that a dataset will be displayed when
autoplay is turned on (value = 1 or 2)
before switching to the next dataset. Datasets that are narrated movies will
play to the end even if they are longer than the duration time.
The length of time in seconds that the kiosk waits after a dataset has been
selected before it will allow another dataset to be selected. This prevents a
user from rapidly selecting datasets in succession, which causes SOS to cycle
too quickly between datasets. Set using the Numeric Keypad.
Synchronize rotation of the trackball image with the SOS display. Use 0 to turn
this off if the kiosk computer or networking equipment used is unable to handle
the increased system load this feature may cause. Set using the Numeric Keypad.
The Color Chooser interface is used to set a color, such as for backgrounds,
text, and button borders. It provides a variety of options for picking a color,
including selecting 1 of 64 basic colors, making your own custom color by
clicking in a rectangular color grid, and entering numerical values into boxes
for Hue/Saturation/Value (HSV), Red/Green/Blue (RGB), or as a 6-digit
hexadecimal HTML number. The best way to learn how these controls work is to
experiment with them and try out different ways to create the colors you want.
The Color Chooser has the ability to remember particular colors you like with
the Add to Custom Colors button. These Custom colors can
then be picked and used for other kiosk color properties, but note that they
won't be remembered the next time the kiosk is restarted (however, any colors
saved as properties are definitely preserved).
When you are finished, press OK to accept the new color
or Cancel to keep the previous color.
The Numeric Keypad interface is used to set a numeric value, such as passcodes.
Use the Del button to delete that last typed digit. When
you are finished, press OK to accept the new numbers or
Cancel to keep the previous numbers.
The Number Chooser interface is used to set a numeric value from a dropdown list
of choices, such as font sizes. Select the desired value and use the
Apply button to change the value or the
Close button (next to Apply) to discard changes and keep
the old value.
The Graphical Keyboard interface is used to set text values and simulates a
physical keyboard. Use Clear to delete all the text, the
back arrow key to delete the last typed character, and the up arrow key to shift
to type alternative characters. When you are finished, press
OK to accept the new text or
Cancel to keep the previous text.
The FTP tab controls are used to transfer kiosk-related files between the
Windows Kiosk machine and the Ubuntu SOS Server using the industry standard File
Transfer Protocol (FTP). This functionality replaces the need to use external
file transfer tools. The properties in the upper left of the pane are all
defined in the Properties tab and are normally set only once
when the kiosk is first set up. The buttons on the right side are used to
initiate a transfer in the direction indicated. The progress bar shows the file
transfer activity as it occurs.
This option copies files from the SOS machine to the kiosk. This needs to be
used whenever the media2kiosk command line utility has
been run on the SOS machine to update which groups and datasets are shown on the
kiosk, along with related text including translations.
This option copies file from the kiosk to the SOS machine. This generally needs
to be done only once after the kiosk is installed and its purpose is to copy the
default kiosk configuration to the SOS machine so it can be customized. If there
are no files in the /shared/sos/kiosk directory on the
SOS machine, this option will copy those files from the kiosk as the initial
The Language tab controls are used to set the text for the small amount of text
in the Public user interface of the kiosk for each of the languages specified by
the locale_options property (described above). Note that this tab
is not used to translate groups, dataset names and descriptions, or text in the
Admin UI, which are described in the SOS Translations
The text appearing immediately above the Information Box. This text appears when
the autoplay property is set to 1 (cycles within a group). The
%0 symbol is a placeholder for the group specified by the
autoPlayGroup value and is automatically filled in by the software.
The text that appears in the Information Box when the information button
(i symbol) is pressed in the Title Area. Note that this
is actually a multi-line block of text with only the first line showing in the
Language tab. It contains an introduction to SOS and brief instructions on how
to use the Public Kiosk controls.
To edit the value of any of any text property, just click in the Setting field
space next to it and use the Graphical Keyboard to edit the text. If there are
characters you need that are not available in the Graphical Keyboard, you will
need to attach a physical keyboard and mouse, then copy and paste the text you
want from another source, such as a website or text document. If you add a new
language to the kiosk with the locale_options
property, the Language tab will show its text properties with blank lines for
the translations. If there are any blank values in the Language tab, the kiosk
will use default American English text.
The Function tab has buttons to close the kiosk application, to lock down its
operations, and reset the properties.
Exit Kiosk closes the kiosk interface and terminates
the program. This is typically used only when administrative work is needed on
the kiosk machine and normally the kiosk will always be up and running
Lock Screen locks the kiosk user interface so that
none of its controls can be operated and autoplay is suspended. This should be
done whenever a presenter is using the iOS Remote App to control SOS. A
separate 4-digit lockcode is entered to unlock the kiosk
Reset resets all the properties to their default
The default groups and datasets provided with the Public Kiosk setup may work
well for your venue, but are easily changed to better suit your intended SOS
viewers. The Public Kiosk defines which groups and datasets are displayed by
using standard SOS playlists that reside under
/shared/sos/kiosk/playlists on the SOS machine. General information
about SOS playlists is available in the Playlist Format
The groups/ directory contains all the group playlists included in
kiosk.sos. Each group playlist has include lines for each of the
datasets that appear in the kiosk when that group’s button is selected.
If this is the first time you are customizing your Public Kiosk groups or
datasets, it is necessary to transfer the default kiosk playlist files to your
SOS machine from the kiosk machine using the controls in the FTP tab
Admin UI. It is important to note that this step should only be done the first
time as a starting point for you to make your changes and will not be needed
Decide how you will be editing the kiosk text files. Currently the recommended
approach is to use a standard text editor such as vim or
gedit. In the future you may be able to use other tools such as the
Visual Playlist Editor to do your edits.
You can change the value of the icons property if you’d like to replace the
NOAA logo with one of your own. For best results, use a size similar to the NOAA
logo’s dimensions, which is 260x260 pixels. Copy your logo image file into the
/shared/sos/kiosk/images/ directory and change the icons value to
match its path.
Edit, remove, or add include lines to the dataset groups you plan to use in
the kiosk. Each include line refers to a group playlist that will appear in the
public UI represented with a rectangular group button. The groups will appear in
the kiosk in the same order (top-to-bottom) as they are listed in the
To create a new group, start by copying an existing group playlist file to a new
name. The filename stem (e.g., “air” for air.sos) will be
used as the group name in the kiosk.
For each group playlist, edit the value of the icons property if you wish to
change the image for that group’s button in the public UI. There are a number of
image files you may choose to use located in
/shared/sos/kiosk/images/groups/. You may also create your own, but
any images you use should have pixel dimensions about 500x417 and have empty
space at the bottom for where the group name will be displayed. We also suggest
that you copy your image files into the
For each group playlist, add, remove, or modify include lines for each dataset
you plan to use in the kiosk. Each include line refers to a dataset that will
appear in the public UI represented with a circular thumbnail button. The
datasets will appear in the kiosk in the same order (left-to-right) as they are
listed in the group files.
The sphere frame image that is displayed on the trackball control for each
dataset listed by an include line is usually derived directly from the dataset’s
image data itself, but there are a number of different ways that this image may
be generated for use in the kiosk. Here are the available options in priority
order of precedence:
If the icons keyword is set immediately following the dataset’s include
line in the group playlist, the trackball image will be set to the file path for
any existing image file anywhere on the SOS machine. This option overrides any
other source for the trackball image. Note that this is not the standard use of
the icons keyword in an SOS dataset playlist
For a movie file or directory of images, if the stopframe keyword is set
immediately following the dataset’s include line in the group playlist, the
trackball image is extracted using the frame index specified. This keyword is
ignored for a single frame image dataset. Note that this is not the standard use
of the stopframe keyword in an SOS dataset playlist
If there is a sphere_frame.jpg or sphere_frame.png
or sphere_frame.tiff file located in the dataset’s media
sub-directory (where the thumbnails are located), that will be used as the
trackball image. NOAA supplies these as part of some datasets and any site may
specify these files for their own datasets installed under the
The default option is to use the image itself as the trackball for single frame
datasets or by extracting the middle frame number as the index into the
dataset’s movie file or directory of images. In the latter case, for example, if
a dataset has 200 frames, then frame 100 would be used to generate the trackball
Test your kiosk playlists on SOS with the FileOpen Playlist
menu item in the SOS Stream GUI, by loading the file
/shared/sos/kiosk/playlist/kiosk.sos. Check for any dataset loading
errors that indicate invalid include paths to the datasets you selected and
correct them in the group playlists.
Verify that the directory /shared/sos/kiosk exists on your SOS
system. If it doesn’t, you can use the FTP tab of the Admin UI to
transfer the default kiosk-related files from the kiosk to the SOS machine. You
may also need to install and configure a simple FTP server on the SOS machine to
handle the FTP file transfers between the two systems. See Appendix
B for instructions on how to set up your FTP server.
Run the media2kiosk
command line utility in a terminal window (it is located in the
/shared/sos/bin directory of your SOS installation). This program
automatically generates the file hierarchy used by the kiosk for groups and
datasets. It automatically names the groups after the playlist filenames used to
define them, such as air for the group playlist
/shared/sos/kiosk/playlists/groups/air.sos. It also generates files
the kiosk uses to show each dataset in the public UI (Appendix
A has a full description of the kiosk file
hierarchy). By default, the dataset names and descriptions are obtained from the
SOS Data Catalog. The descriptions tend to be longer than desirable for a kiosk
user, so there is a way to replace those with your own text. This is done with
the same approach as for translating English to other languages, which is
covered in the next section.
Transfer the kiosk dataset and group file hierarchy using the controls in the
FTP tab of the Admin UI.
Restart the kiosk software (using the desktop or from the Start menu) and verify
that you are satisfied with how your changes appear in the public UI, including
group names and button images and dataset names, descriptions, and button
images. Test the kiosk with SOS to make sure all the datasets load and display
Repeat these steps until the kiosk is configured the way you want it.
The term localization refers to translating text into another language, with
possible variations for a particular country or region. A locale is defined as
xx_YY, where xx is the ISO 639-1 language code and YY is the ISO
3166 country or region code. The default locale is en_US, which is
English in the United States.
In the Public Kiosk, translations are created and edited in several different
ways depending on which part of the kiosk is being localized.
Administration UI text translations are made using a set of utilities run on the
Windows kiosk machine. This is a more advanced localization activity that may
require assistance from the SOS team. Steps to perform a translation of the
Admin UI are described in the Admin UI Translations
section of the SOS Translation Manual.
This appendix is a reference that describes the underlying file hierarchy used
in the Public Kiosk and its user interface. The Public Kiosk’s appearance and
operations are driven entirely by a local file structure in combination with SOS
Automation Control Protocol made from the kiosk
to the SOS machine. All media used in the kiosk software is locally resident and
set up in advance.
Most of the kiosk files are autogenerated on the SOS machine using the
media2kiosk utility found in the bin directory
of the SOS software installation. This utility must be run from the command
line. There are also some files that must be configured directly on the kiosk.
The files structure described below is relative to the kiosk root directory,
which is /shared/sos/kiosk on the SOS machine and
C:\shared\sos\kiosk on the kiosk machine.
Directories and Files Required Only on the Kiosk Machine
File transfer between the SOS machine and the kiosk is not trivial since these
two machines use very different operating systems, Ubuntu Linux and Microsoft
Windows, respectively. Beginning with version 5.1, the kiosk software supports a
direct transfer between the two systems from the FTP tab in the Administration
UI. This functionality uses the industry standard File Transfer Protocol (FTP)
software. On the SOS machine, the very secure FTP daemon (vsftpd)
server can be installed using the normal Ubuntu apt-get commands and
by editing a few configuration files.
The media2kiosk command-line utility is used in a terminal window on
the SOS machine to prepare files for use by the Public Kiosk. This utility
resides in the bin directory of the standard SOS installation, typically
/shared/sos/bin. It is normally used to generate the kiosk file
hierarchy as shown in Appendix A. The
generated files are then transferred from the SOS machine to the Windows kiosk
machine using the FTP tab in the Administration User Interface.
The most common use of media2kiosk is to generate the kiosk files
that are transferred to the kiosk machine after changing the main group file
(/shared/sos/kiosk/playlists/kiosk.sos, the group playlists under
(/shared/sos/kiosk/playlists/groups), or translation playlists
under (/shared/sos/kiosk/playlists/locale). Less commonly,
media2kiosk may be run when changes made to the SOS Data Catalog need
to be updated in the corresponding kiosk files.
The other options available in media2kiosk are not routinely used.
–verbose and –logging are helpful when troubleshooting
problems running media2kiosk
–root and –tr_root are used for developer testing
–ts_to_tsv, –tsv_to_ts, and –skip_datasets
are experimental and will become regular features in a future release
As mentioned in the Installation and Setup section, you may wish
to install a separate application that automatically restarts the Public Kiosk
if it crashes or a clever kiosk user finds a way to close it intentionally. One
free application that does this is called Restart On Crash. It has been
successfully used with the Public Kiosk is described in this appendix.
In a web browser, click on the link Download Restart on
Crash, which puts the file RestartOnCrash-v1.4.1.zip
in your Downloads folder (or a different download location, depending on your
To turn off Restart On Crash, first open it by right-clicking on its icon in the
icon tray (the lower right side of the Windows taskbar), then choosing
Show/Hide. In the window that opens, just uncheck the
box next to the Application name (C:\shared\bin\Kiosk.exe) in the
utility’s main window. The Status indicated by
Disabled means that the kiosk won’t be automatically restarted when
it’s not running. If you check the box again, then Restart On Crash will start
monitoring and restarting it when needed.