Visual Productions KIOSC User manual

KIOSC
MANUAL
© VISUAL PRODUCTIONS BV WWW.VISUALPRODUCTIONS.NL

Revision History
Revision Date Author(s) Description
1 07.06.2018 ME Initial version.
2 14.06.2019 BZ Added Kiosc Touch chapter, added
info on elements, expanded the index
section
2

Contents
1 Introduction 5
2 Kiosc App 8
3 Kiosc Touch 18
4 Kiosc Editor 23
5 File Locations 33
3

c
2019 Visual Productions BV. All rights reserved.
No parts of this work may be reproduced in any form or by any means - graphic,
electronic, or mechanical, including photocopying, recording, taping, or infor-
mation storage and retrieval systems - without the written permission of the
publisher.
While every precaution has been taken in the preparation of this document,
the publisher and the author assume no responsibility for errors or omissions,
or for damages resulting from the use of information contained in this docu-
ment or from the use of programs and source code that may accompany it. In
no event shall the publisher and the author be liable for any loss of profit or
any other commercial damage caused or alleged to have been caused directly or
indirectly by this document.
Due to the dynamic nature of product design, the information contained in
this document is subject to change without notice. Revisions of this informa-
tion or new editions may be issued to incorporate such changes.
Products that are referred to in this document may be either trademarks and/or
registered trademarks of the respective owners. The publisher and the author
make no claim to these trademarks.
4

Chapter 1
Introduction
Thank you for choosing Kiosc. Kiosc (see figure 1.1) is a simple app for creating
custom user-interfaces. These user-interfaces are typically used for controlling
lighting and AV equipment. Kiosc communicates with the external equipment
via OSC and UDP; protocols that run over the Ethernet network.
Kiosc is accompanied by the Kiosc Editor. This software tool enables you
to design a simple control dashboard in a few minutes. While it also carries
the features required to create complex multi-page interactive user-interfaces.
Importantly, the Kiosc Editor allows you to personalise the dashboard; you are
free to add logos, images and change colours.
5

Figure 1.1: Kiosc
The Kiosc app works well with the Visual Productions range of lighting
controllers, in fact, it is compatible with any OSC and/or UDP capable 3rd
party device or software.
Kiosc is available on many operating systems: iOS, Android, Windows, ma-
cOS & Ubuntu Linux. The Kiosc Editor is available on Windows, macOS &
Ubuntu.
This manual covers the functionality of the Kiosc app in chapter 2. The
Kiosc Touch device is discussed in Chapter 3. Chapter 4 explains how to design
custom layouts by using the Kiosc Editor. Finally, chapter 5 discusses the
locations where the apps save and load the files on disk.
At the time of writing this manual the Kiosc app is at version 1.8.5, the
Kiosc Editor is at version 1.8.0.
1.1 Features
Kiosc has the following features.
•Generic control elements like buttons, sliders and check-boxes
•Lighting control elements like colour wheels and spectrums
•Feedback
6

•Multiple pages
•Available on 5 operating systems
•OSC and UDP
•PIN lock
1.2 Compatibility
Kiosc is compatible with the following devices.
•Visual Productions CueCore2
•Visual Productions CueCore1
•Visual Productions QuadCore
•Visual Productions IoCore2
•Visual Productions IoCore1
•Visual Productions Cuety LPU-2
•Visual Productions B-Station
•Visual Productions TimeCore
•Any OSC or UDP compatible device
1.3 Further Help
If, after reading this manual, you have further questions then please consult
the online forum at http://forum.visualproductions.nl/forum/ for more
technical support.
7

Chapter 2
Kiosc App
The Kiosc app will present the customised dashboard to the user, typically
running on a touch screen device. The Kiosc app itself has no editing capability
in order to prevent the user from making accidental changes.
2.1 Modes
The Kiosc app operates in two modes, Remote and File.
2.1.1 Remote
The Remote mode serves two purposes. It allows you to quickly connect to a
Visual Productions device and control it directly. Secondly, in this mode, Kiosc
can connect to a Kiosc Editor and receive live updates as the user works on his
design. This way it provides a real-time preview on the actual target device.
Although quick to set up, a Remote connection to a CueCore2 or similar de-
vice does not enable to user to make elaborate designs. The editing capabilities
inside the CueCore2 are basic. In order to create more demanding user-interface
designs it is recommended to use the File mode.
Figure 2.1: Kiosc connected to a IoCore2
8

Kiosc can only be connected to a single external device when using Remote
mode. It is using a propriety protocol that is only supported by the Visual
Productions range of devices. This protocol is uni-directional and thus provides
no means for giving feedback to the Kiosc app. No OSC or UDP is used in this
mode.
The Remote mode makes Kiosc compatible with VisualTouch, the previous-
generation touch screen software from Visual Productions.
Figure 2.1 shows an example of Kiosc being connected to a IoCore2. By
using the Remote mode, a simple dashboard can be created in a few mouse
clicks. In this example Kiosc is used for setting DMX values, transmitting a
RS-232 message and toggling GPO relays.
(a) Selecting the IoCore2 remote
server
(b) Actions inside the IoCore2
Figure 2.2: Connecting Kiosc to an IoCore2
Figure 2.2 shows how to select the IoCore2 in the remote options. Once
connected, the dashboard is created by adding a ’Kiosc’ actionlist inside the
IoCore’s show control page. Buttons, sliders and other controls can be added to
this actionlist. The order of the actions determines the position of the controls
in the Kiosc screen. Empty positions can be created adding Dummy actions. If
there are more controls then fits in the screen, then extra pages will be created
automatically. How many controls do fit in the screen is dictated by the Grid
Size setting.
Figure 2.2 displays the actions created for this example. Programming ac-
tions is discussed in more detail in the IoCore2’s user manual.
2.1.2 File
In File mode Kiosc renders a layout designed with the Kiosc Editor. The file
generated by the Editor needs to stored locally on the device running Kiosc.
The Editor enables you to make custom control screens and personalise it
with logos and colours.
In File mode it is possible to control multiple external devices on the net-
work. By using OSC or UDP these devices can also send data back to the Kiosc
app, providing it with feedback that could update the status of GUI controls.
9

Figure 2.3: Kiosc connected to a media player
Figure 2.3 shows an example of Kiosc controlling a Brightsign, a 3rd party
media player. Kiosc is using UDP messages to trigger the playback of different
media files inside the Brightsign.
2.2 Protocols
Kiosc can communicate with external equipment via two protocols, OSC and
UDP. Both protocols run over the Ethernet network. This chapter describes
these protocols.
2.2.1 OSC
Open Sound Control (OSC) is a protocol for communicating between software
and various multi-media type devices. OSC uses the network to send and receive
messages.
2.2.2 UDP
User Datagram Protocol (UDP) is a simple protocol for sending messages across
the network. It is supported by various media devices like video projectors and
Show Controllers. It does not incorporate error checking, making it an easy and
fast protocol.
2.2.3 OSC vs UDP
There are many similarities between OSC and UDP. In fact, OSC uses UDP
packets under the hood.
There is one difference between these protocols that is significant when choos-
ing the right protocol for the job. OSC has a fixed syntax and UDP does not.
Although UDP’s technical characteristics are specified in the protocol, the syn-
tax is not. This means that the UDP capable equipment from two different
vendors will be able send each other technically correct UDP messages. What
they write into the messages is left to the discretion of the developers. As it
turns out, different developers come up with different syntaxes. Even though
10

the two devices say ’UDP’ on the box, they might not be able to speak to each
other.
This problem can be illustrated by an example. Let’s assume a device from
vendor X wants to send a message to a device from vendor Y. The message
should set a parameter inside device Y to 50%. Device X could send something
like:
•parameter=50% assuming a range from 0% to 100%
•parameter=0.5 assuming a range from 0.0 to 1.0
•parameter=128 assuming a range from 0 to 255
•parameter=0x80 assuming a single hexadecimal byte
There are even more variations possible. The point being that whatever
syntax vendor X has chosen, the chance that vendor Y choose the same is not
that great.
OSC solves this problem by incorporating rules on syntax in its protocol
specification. Each OSC compatible device uses exactly the same syntax. This
is a strong reason to prefer OSC over UDP when possible. Of course, there are
many devices out there that do not support OSC, leaving UDP an important
asset inside your protocol toolbox.
2.3 Options
The options screen presents a few settings for customising the Kiosc behaviour.
2.3.1 Modes
The modes selector allows you to choose between Remote and File mode. Modes
are discussed on page 8.
2.3.2 Remote
This menu (see figure 2.4) is only enabled when in Remote mode. It allows you
to select the remote server. E.g. a CueCore or Kiosc Editor.
11

Figure 2.4: Remote options
2.3.3 File
This menu is only enabled when in File mode. It presents a list of the layout
files. It also has buttons for saving, deleting and renaming files.
Figure 2.5: File options
The Folder buttons opens a file browser at the path where the files are
stored.
2.3.4 Grid Size
In Remote mode the size of the buttons and other controls are determined by
the Grid Size setting. A smaller Grid Size results in larger controls. A larger
Grid Size will allow more controls to fit on one page.
12

Figure 2.6: Grid Size options
The Grid Size menu is only available in Remote mode.
2.3.5 OSC
The settings in this screen (see figure 2.7) determine to which IP addresses the
OSC messages are sent to. Multiple IP addresses can be added to the list. With
each IP address there also needs to be specified a port number. Add the port
number in the following fashion: XXX.XXX.XXX.XXX:PORT. Where the XXXs
denote the IP address and PORT is a decimal number.
Figure 2.7: OSC options
The incoming port field specifies the port number on which Kiosc will receive
OSC messages. External equipment that will send feedback information to Kiosc
need to know this incoming port number. By default this port number is set to
8000.
13

2.3.6 UDP
The settings in this screen (see figure 2.8) determine to which IP addresses the
UDP messages are sent to. Multiple IP addresses can be added to the list.
With each IP address there also needs to be specified a port number. Add
the port number in the following fashion: XXX.XXX.XXX.XXX:PORT. Where the
XXXs denote the IP address and PORT is a decimal number.
Figure 2.8: UDP options
The incoming port field specifies the port number on which Kiosc will receive
UDP messages. External equipment that will send feedback information to
Kiosc need to know this incoming port number. By default this port number is
set to 7000.
2.3.7 PIN
Although the Kiosc app has no editing capabilities (all editing is done in the
Kiosc Editor), it does have several settings that, if erroneously changed, can
stop the system from working. To restrict access to the settings a PIN code can
be engaged. See figure 2.9.
14

Figure 2.9: Enabling the PIN
2.3.8 About
Apart from the ubiquitous copyright notice, the about screen in figure 2.10
indicates the current software version.
Figure 2.10: The About screen
Furthermore, it also details a list of local IP addresses used by the device
running Kiosc. This information can be useful when trouble shooting network
issues.
2.4 Installation
The Kiosc app is available on a wide range of operating systems, both mobile
and desktop.
The software is distributed through app-stores; there are no stand-alone
installation packages (e.g. EXE, APK, DMG or DEB files) available. One of
15

Figure 2.11: Kiosc on macOS, Windows and Ubuntu
the major advantages of installing an app via an app store is to receive future
software updates automatically.
•iOS Kiosc can be downloaded from the Apple iOS app-store at:
https://itunes.apple.com/us/app/kiosc/id1131605366.
•Android Kiosc can be found on the Google Play store at
https://play.google.com/store/apps/details?id=nl.visualproductions.
kiosc.
Android 5.0 or higher is required.
•Windows Kiosc can be downloaded from the Microsoft store at:
https://www.microsoft.com/store/apps/9nblggh4s74f.
Windows 10 or higher is required.
•macOS Visit the Apple macOS app store at:
https://itunes.apple.com/us/app/kiosc/id1131605497
macOS 10.13 is recommended.
•Ubuntu You can acquire the Kiosc app from the snap store:
https://snapcraft.io/kiosc.
Alternatively, it can be installed by using the command-line:
snap find kiosc
snap install kiosc
To update the apps later on via the command-line type:
snap refresh kiosc
16

Ubuntu 18.04 LTS is recommended. The app is only available for the
amd64 architecture.
17

Chapter 3
Kiosc Touch
The Kiosc Touch is a Touch screen solution created by Visual Productions. It
is a standalone PoE-powered device running the Kiosc app.
Figure 3.1: Kiosc Touch
3.1 Specifications
The Kiosc Touch has the following specifications.
•PoE (Power-over-Ethernet) Class III.
•7 Inch full colour display
•Viewable screen size: 155mm x 86mm
•Capacitive multitouch
18

•Resolution of 800 x 480 pixels
•Wall mountable
•VESA 75
•460 gram (1 lbs)
•Operating temperature -20C to +50C (-4F to 122F)
•Compliance EN55103-1 EN55103-2
3.2 Mounting
Figure 3.2: Kiosc Touch mounting bracket
The Kiosc Touch is wall-mount, it is compatible with European and Amer-
ican gang boxes. If no gang box is available then the Kiosc Touch can also be
surface mounted. The mounting bracket of the Kiosc Touch suggests where you
can create a hole for the cable to enter.
3.3 vManager
A free-of-charge software tool called vManager has been developed to manage
the devices. vManager allows for:
•Discovering any Kiosc on the Network
•Perform firmware updates
19

Figure 3.3: vManager
3.4 Network
The Kiosc Touch is a network device. A network connection between between
a computer running Kiosc Editor and the unit is required to program the Kiosc
Touch. More information on this can be found in chapter 4.
There are multiple arrangements possible for connecting the computer and the
Kiosc Touch. They can be connected peer-to-peer, via a network switch or via
a Wi-Fi bridge device. Figure 3.4 illustrates these different arrangements.
20