Manual_1p3p5a Manual

User Manual: Pdf

Open the PDF directly: View PDF PDF.
Page Count: 111

DownloadManual_1p3p5a Manual
Open PDF In BrowserView PDF
Version 1.3.5a, 1 May 2018

Track changes base is 1.3.4c

Pi Presents
A Multi-media Interactive Display and Animation Toolkit
for Museums, Visitor Centres and more…..
Running on the Raspberry Pi
Ken Thompson

http://pipresents.wordpress.com

Page 1

Version 1.3.5a, 1 May 2018

Contents
1

Introduction ...................................................................................................... 6
1.1

Acknowledgements ..................................................................................... 8

2

Installation ........................................................................................................ 9

3

Try Some Examples ......................................................................................... 9
3.1

4

Terminating Pi Presents ............................................................................ 13

The Pi Presents Profile Editor ....................................................................... 14
4.1
Using the Editor......................................................................................... 14
4.1.1
The Displays ...................................................................................... 14
4.1.2
Profile Menu ....................................................................................... 15
4.1.3
Show Menu ........................................................................................ 15
4.1.4
Medialist Menu ................................................................................... 15
4.1.5
Track Menu ........................................................................................ 15
4.1.6
OSC Menu ......................................................................................... 16
4.1.7
Tools Menu ........................................................................................ 16
4.1.8
Options Menu ..................................................................................... 16
4.1.9
Editor Command Line Options ........................................................... 17
4.2
Making Profiles ......................................................................................... 17
4.2.1
Making Profiles Portable .................................................................... 17
4.2.2
Using the SD Card for Profiles ........................................................... 18
4.2.3
Using the Editor on a Windows PC .................................................... 18
4.2.4
Using a USB Stick for Profiles ............................................................ 18
4.2.5
Developing Profiles using a Monitor with Different Pixel Dimensions.. 19

5

The Components of Pi Presents ................................................................... 19
5.1
Introduction ............................................................................................... 19
5.2
Shows ....................................................................................................... 21
5.2.1
Mediashow and Artmediashow........................................................... 21
5.2.1.1
Controls and Commands............................................................. 23
5.2.1.2
Triggers....................................................................................... 25
5.2.1.3
Fields .......................................................................................... 26
5.2.2
Menu .................................................................................................. 33
5.2.2.1
Controls and Commands............................................................. 33
5.2.2.2
Fields .......................................................................................... 33
5.2.3
Liveshow and Artliveshow .................................................................. 34
5.2.4
Radiobuttonshow ............................................................................... 35
5.2.4.1
Controls and Commands............................................................. 36
5.2.4.2
Fields .......................................................................................... 36
5.2.5
Hyperlinkshow.................................................................................... 38
5.2.5.1
Controls and Commands............................................................. 39
5.2.5.2
Touchscreens and Soft Buttons .................................................. 40
5.2.5.3
Fields .......................................................................................... 41
5.2.6
Start Show ......................................................................................... 43
5.3
Medialists .................................................................................................. 43
5.4
Tracks ....................................................................................................... 44
5.4.1
Track Location Names ....................................................................... 44
5.4.2
Anonymous and Labelled tracks ........................................................ 45
5.4.3
Show Track ........................................................................................ 45
5.4.4
Image Track ....................................................................................... 45

Page 2

Version 1.3.5a, 1 May 2018

5.4.4.1
Image Window ............................................................................ 47
5.4.5
Video Track ........................................................................................ 49
5.4.5.1
Video Playout .............................................................................. 51
5.4.6
Audio Track ........................................................................................ 51
5.4.7
Web Tracks ........................................................................................ 53
5.4.7.1
Browser Commands.................................................................... 55
5.4.7.2
Full screen Integrated Browser Displays ..................................... 56
5.4.8
Message Tracks ................................................................................. 57
5.4.9
Show Track ........................................................................................ 59
5.4.10 Menu Track ........................................................................................ 59
6

Black Box Operation ...................................................................................... 63
6.1
6.2
6.3
6.4
6.5
6.6
6.7
6.8

Command Line Options............................................................................. 63
Specify a Profile ........................................................................................ 65
Specify a Home Directory .......................................................................... 65
Using GPIO to Control Pi Presents............................................................ 65
Disable Screen Blanking ........................................................................... 66
Start Pi Presents when Power is applied to the Pi ..................................... 66
Shutdown the Raspberry Pi from the GPIO ............................................... 67
Controlling the Monitor .............................................................................. 67

7

Exiting Pi Presents and Shutdown of the RPi .............................................. 67

8

Controlling Shows.......................................................................................... 68
8.1
Controlling Track Movement in Individual Shows ...................................... 68
8.2
Opening and Closing Shows and Show Control ....................................... 69
8.2.1
Opening and Closing Shows .............................................................. 69
8.2.2
Sending Events between Shows ........................................................ 70
8.2.3
Other Uses of Show Controls ............................................................. 70
8.3
Time Of Day Scheduler ............................................................................. 70
8.4
Concurrent Shows..................................................................................... 72
8.4.1
Control with Concurrent Shows .......................................................... 72
8.4.2
Limitations on Concurrency ................................................................ 73

9

Touchscreens and Soft Buttons ................................................................... 73
9.1
9.2
9.3

Controlling Shows with a Touchscreen...................................................... 73
Click Areas ................................................................................................ 74
Soft Buttons .............................................................................................. 74

10

Run-Time Commands ................................................................................. 75

11

Providing Dynamic Content in a Liveshow ............................................... 76

12

Counters ...................................................................................................... 76

13

Animation Control ...................................................................................... 77

14

Input/Output (I/O) Plugins .......................................................................... 78

14.1
Enabling a Standard I/O Device ............................................................. 79
14.2
Configuring Inputs and Output Drivers ................................................... 80
14.2.1 Interfacing with GPIO using pp_gpiodriver.py..................................... 80
14.2.2 Interfacing with a Remote Control or Keypad using
pp_inputdevicedriver.py ................................................................................... 82
14.2.3 Interfacing with a Serial Link using pp_serialdriver.py ........................ 82
14.2.4 Interfacing with I2C devices using pp_i2cdriver.py ............................. 84
14.2.5 Configuring Tkinter Keyboard Keys using pp_kbdriver.py .................. 85
14.2.6 Advanced Interfacing with a Keyboard using pp_kbddriver_plus.py .. 86
14.2.7 Configuring Touch/Click Areas ........................................................... 87
Page 3

Version 1.3.5a, 1 May 2018

14.3
Writing I/O Plugins ................................................................................. 88
14.3.1 Configuring and Registering an I/O plugin .......................................... 88
14.3.2 Class .................................................................................................. 88
14.3.3 Methods ............................................................................................. 89
14.3.4 Example ............................................................................................. 91
15

Remote Control using OSC ........................................................................ 91

15.1
15.2
15.3
15.4

Sending and Receiving Commands via OSC ......................................... 92
OSC Fundamentals ............................................................................... 92
Configuring OSC ................................................................................... 94
oscremote and oscmonitor..................................................................... 95

16

Track Plugins .............................................................................................. 96

17

Remote Management .................................................................................. 98

17.1
17.2
17.3
18

Setting up for Remote Use..................................................................... 98
.Using the Manager ............................................................................. 100
Using the Web Editor ........................................................................... 102

Email Alerts ............................................................................................... 102

18.1
18.2

Setting Up Email Alerts ........................................................................ 102
Using Email Alerts ............................................................................... 103

19

Hardware Requirements........................................................................... 103

20

Updating Pi Presents ................................................................................ 104

20.1
20.2
21

Updating Profiles ................................................................................. 104
Updating Pi Presents ........................................................................... 104

Debugging, Statistics, Bug Reports and Feature Requests .................. 104

21.1
21.2

Statistics Production ............................................................................ 104
Debugging Profiles .............................................................................. 105

22

Gotchas and Known Problems ................................................................ 106

23

Converting Version 1.2 to 1.3................................................................... 108

Page 4

Version 1.3.5a, 1 May 2018

Copyright Notice
This manual and the Pi Presents software are copyright Ken Thompson. For licence
conditions see:
https://github.com/KenT2/pipresents-gapless/blob/master/licence.md
Raspberry Pi is a trademark of the Raspberry Pi Foundation
http://www.raspberrypi.org

Page 5

Version 1.3.5a, 1 May 2018

1 Introduction
Pi Presents is a toolkit for creating and deploying multi-media interactive displays
with animation control facilities. It was originally intended for Museums and Visitor
Centres but has already found uses in hospitals, shops, schools, art installations,
libraries and more…..
Until the Raspberry Pi arrived buying or constructing something even as simple as an
interactive audio player was expensive. The Raspberry Pi with its combination of
Linux, GPIO and a powerful GPU is ideal for black box multi-media applications; all it
needed was a program to harness its power in a way that could be used by nonprogrammers.
There are a number of digital signage applications for the Raspberry Pi which are
limited to slideshows and must take their media from the internet. Pi Presents is
different; it is a toolkit which allows construction of many types of interactive
presentation applications by using a simple to use editor running on a browser either
on a Pi or remotely.
The Pi Presents toolkit supports the types of show commonly seen in museums;
each of these can be configured to meet your individual requirements.
Some uses:


Animation or interpretation of exhibits by triggering a sound, video, or
slideshow from a button, keyboard or other GPIO input.



While playing media, GPIO outputs can be used to control external devices
such as lights, animatronics etc.



A multimedia slideshow for a visitor centre. Images, videos, audio tracks, and
messages can be displayed. Repeats can be at intervals or at specified times
of day.



Slideshows to be interrupted by the visitor and a menu of further content
presented.



A show for kiosks where content can be initiated by pressing one of a number
of buttons.



Facilities to construct ‘hyperlinked’ shows commonly seen on touch screens
in museums.



Construct a 'powerpoint' like multi-media presentation where progress
through slides is manually controlled by buttons or keyboard.



Basic digital signage with the ability upload image, video or audio tracks over
a network for display in a repeating show.



Multi-window displays, displaying several types of content on a single screen

Page 6

Version 1.3.5a, 1 May 2018



Run a selection of shows at different times, days of the week, and special
days in a year.



Construct a network of Pi Presents applications controlled through the Open
Sound Control (OSC) protocol or control Pi Presents from remote computers,
tablets or smartphones.



Manage Pi Presents and edit profiles remotely using any browser (Local Area
Network required). Receive email alerts reporting the status of deployed Pi
Presents applications.



Foreign language support. All text shown to the audience is configurable.

Once set up Pi Presents is easy to use and does not require a network:


Shows can be prepared using a simple to use editor.



Will operate on a Model A or A+ Raspberry Pi (but see hardware
requirements).



No need to modify the Pi’s SD card after initial installation. All media and
configuration options can be kept on a removable USB stick. Installing an
updated application can be as simple as inserting the USB stick.



Video output can use HDMI or composite video selected using the normal Pi
setup procedure. As Pi Presents can be started and shutdown without a
keyboard a monitor is not required.



Audio track output is selectable between HDMI and analogue and can be
output from left, right or stereo speakers on a per track basis. A number of
tracks can be played simultaneously to different speakers each with
presettable volume.

Pi Presents, out of the box, runs as a desktop application on the Raspberry Pi using
the keyboard for control. However with a little bit of Linux magic, which is explained in
this manual, it can be made to run as a black box application with control from GPIO
or remotely via OSC. Black box features include:


Disabling screen blanking and the mouse pointer.



Full screen operation without window decorations



Completely headless operation without a keyboard, mouse or buttons (except
perhaps a shutdown button if you do not want to risk SD Card corruption)



Black box control can be by buttons, PIR, or any source of digital inputs. It is
straightforward to make your own controls.



Mouse compatible touchscreens are supported if drivers are available for the
Raspberry Pi. Alternatively a keyboard and mouse can be used. Pi Presents

Page 7

Version 1.3.5a, 1 May 2018

has been designed such that it is possible to add drivers written in Python for
other forms of input and output such as RS232 and I2C.


Automatic start up when power is applied to the Pi



Safe shutdown without using keyboard or mouse



Automatic opening and closing of shows and shutdown of the Pi at specified
times of day. The time of day scheduler is programmable for different
schedules on different days of the week, or month, or for special days in the
year.



Remote control of a Pi Presents application using Open Sound Control from
another Pi Presents or any computer with a suitable OSC application.

1.1 Acknowledgements
Douglas Otwell for dbus control of omxplayer
https://github.com/Douglas6/omxcontrol
Davide Rosa for RemI – Remote Interface, a toolkit for writing browser based gui’s in
Python
https://github.com/dddomodossola/remi
Johannes Baiter (jbaiter) for pyomxplayer based on Noah's pexpect
Numerous people on the Raspberry Pi forum and websites, particularly
StackOverflow, who have unwittingly provided me with solutions to many technical
problems and taught me Python.
Bullets from http://www.enterprise-dashboard.com/tag/red-green-yellow-alert/
Icons from http://www.fatcow.com/free-icons
Buttons from http://www.freewebsitebuttons.com
The Raspberry Pi Foundation for the first affordable machine that plays video, audio
and has GPIO.
Having been introduced to open source software through the Raspberry Pi I was
amazed at the time and effort which so many people put in to produce software for
others, so I thought it worthwhile to do the same with Pi Presents. I am glad I did
because the feedback I have had from users and potential users has given me so
many good ideas for extensions to Pi Presents. Needless to say I have been so busy
producing Pi Presents that I have not had time to use it for my own intended projects,
however one day I am sure I will ( I now have two three) .

Page 8

Version 1.3.5a, 1 May 2018

2 Installation
The installation instructions are in the README.md file. Pi Presents requires
Raspbian Stretch and should always use the latest Foundation Raspbian release and
MUST BE INSTALLED AND RUN FROM THE PIXEL DESKTOP.

3 Try Some Examples
Download the examples from the pipresents-gapless-examples github repository as
described in the README.md file.
N.B. Pi Presents must be run from the PIXEL desktop (you must have executed
startx either from the command line or set ‘boot to desktop’ in raspi-config) . From a
terminal window opened in the pipresents directory type:
python pipresents.py –p pp_mediashow_1p3
You will see a continuous looping show in a small window. The small window is
useful for development purposes; you can adjust its size by editing pipresents.py,
around line 45. You can expand the display to nearly full screen by using the
appropriate window decoration. If however you want to see the show truly full screen
without borders then use the -f command option and –b to disable screen blanking:
python pipresents.py –p pp_mediashow_1p3 –f -b
The mediashow example and all the other examples are designed for a 1920*1080
display. If you have a smaller resolution display some of the text and part of the
larger images will disappear off the edges of the display. Pi Presents does not
automatically adjust for screen resolution; you will need to use the Pi Presents editor
to adjust text position and font sizes , and to resize images external to Pi Presents.
The pipresents-gapless-examples repository has examples of how to use Pi
Presents.
You can use the bash script examples.sh to execute the examples, just type
./examples.sh from a terminal window open in the /pipresents directory or copy the
examples.desktop file from /pipresents to your desktop. You will need to make
examples.sh executable.
The examples use the following keys:








Up or Down Cursor- move through a menu.
Up or Down Cursor - Move through a mediashow show. Can also be used to
skip to the next or previous track in an automatic mediashow. The movement
circles around at the start and end of a show.
Return – Play the selected menu entry or a child track.
Escape – Stops the current track/show in an intuitive manner.
Spacebar - in an image, video, or audio track, toggle pause.
CTRL-BREAK always exits Pi Presents. (Duplicated by the Close window
icon or Alt+F4)

All examples use a selection of media tracks which are in /home/pi/pp_home/media.
The profiles are in /home/pi/pp_home/pp_profiles. In each profile the

Page 9

Version 1.3.5a, 1 May 2018

pp_showlist.json file specifies the look and feel of each show; other files specify the
media to use. The files can be viewed in a text editor but it is much better to edit
them using Pi Present's own editor described in Section 4.
Other optional files in the profile, screen.cfg, gpio.cfg, keys.cfg, osc.cfg and
schedule.json customise other aspects of Pi Presents.
How the profiles work is explained in detailed later so do not worry if you do not
understand them, just enjoy what Pi Presents is capable of.
The examples:


pp_mediashow_1p3
The profile you have just run. The show will start immediately, progress
automatically, and then repeat. Use the Up and Down cursor keys to skip
tracks. The example demonstrates the types of track and additional
information that can be added to the primary content.



pp_menu_1p3
The example demonstrates all the menu formats available in Pi Presents. The
second level menus, and any show which runs from another show are called
subshows. Use the Up and Down cursor keys to traverse the menu then
press Return to Start a track or sub-menu, and Escape to terminate it.



pp_exhibit_1p3
This demonstrates how to trigger a mediashow from a PIR. When started, the
screen will be blank. Triggering the PIR input (opening a contact connected to
0 volts on P1-11) or pressing a button (closing a contact connected to 0 volts
on P1-18) will start a one shot mediashow and then wait for the trigger in
order to repeat the show.
The example uses the gpio.cfg file in the profile which has pins P1-18 and P111 bound to the symbolic name PIR. This name is then associated with
Trigger for Start in the mediashow.
The example also uses the Return key as a trigger input so you can see the
effect without using the GPIO pins. The keys.cfg file in the profile overrides
the default keys.cfg and binds the Return key to the symbolic name PIR.
BEWARE: Do not use the GPIO pins until you have read Section 6.4



pp_openclose_1p3 (New in Version 1.3)
A single shot mediashow with a different method of triggering. Useful if you
want a track to play when opening a box or door, and stop when it is closed.
gpio.cfg in the profile uses p1-18 for this task.



pp_onerandom_1p3 (New in Version 1.3)
When triggered plays a single track randomly chosen from the medialist .



pp_magicpicture_1p3 (Rewritten in Version 1.3.2a)
A still picture of a person is seen in a picture frame. When a button is pressed
the picture comes to life as a video is played. The effect is achieved by
pausing the video just after the first frame. I don’t have a video of a person so
Suits will have to do!

Page 10

Version 1.3.5a, 1 May 2018



pp_interactive_1p3
This combines a mediashow and a menu. The mediashow is run continuously
but every track has a hint showing that a menu can be triggered by the Return
key. Pressing Escape from the menu returns to the mediashow. A track or
show which is accessible from any track in a mediashow is called a child.



pp_presentation_1p3
The mediashow is configured as a manually controlled presentation. Use the
Up and Down cursor keys to traverse through it. Pi Presents cannot use
Powerpoint presentations but Powerpoint presentations can be saved as jpeg
images.



pp_liveshow_1p3
While the Liveshow is running place some video files, audio files, or images
into the directory /home/pi/pp_home/pp_live_tracks and watch them
miraculously appear. A liveshow is a mediashow without pre-defined media.



pp_liveshowempty_1p3 (new in 1.3.2a)
Demonstrates the increased flexibility in handling liveshows with an empty
tracks directory. An empty live tracks directory will play a ‘list empty’ track and
execute the ‘on empty’ and ‘on not empty’ Show Control commands.



pp_radiobuttonshow_1p3
Think of the navigation method in a Radiobuttonshow as being like a car radio
channel changer. Press keys 1-4 or GPIO buttons to play a track and Escape
to return to the main screen.
Controls defined in the Radiobutttonshow profile allow for both keyboard keys
and buttons to be used to select a track. A gpio.cfg file is included in the
profile to bind four GPIO pins to entries and one to the Stop Operation.



pp_hyperlinkshow_1p3
The Hyperlinkshow works something like a set of web pages with links
between them and Back and Home buttons. All of the ‘story telling’
applications in museums appear to use this navigation technique.
The show is aimed at touchscreens. The on screen buttons are touch
sensitive areas which, for testing purposes, are also sensitive to mouse
clicks. The file screen.cfg in the profile defines the buttons and the symbolic
names of their input events. If using ‘Soft Keys’ the show could be controlled
by GPIO pins by binding pins to the symbolic names in a gpio.cfg file.



pp_audio_1p3
This mediashow demonstrates the capabilities of the audioplayer. You will
need speakers connected to hdmi and analogue ports to fully appreciate it. It
plays tracks to different speakers; it also demonstrates the use of Run-Time
controls to control volume from keyboard (8 and 9) or GPIO pins and mute
(keys 1 and 2). For this reason it has keys.cfg and gpio.cfg files in the profile,



pp_web_1p3
A demonstration of the web browser capabilities. Ideally an internet
connection is required. Because the integration between Pi Presents and the
browser is not good, it will take a long time for the browser to open and, if you

Page 11

Version 1.3.5a, 1 May 2018

need to interact with Pi Presents when the browser is displayed you will need
to click on its window first.


pp_concurrent_1p3
This application demonstrates concurrent show playing capabilities. There are
two mediashows running simultaneously. The mediashow showing images
must be controlled from the keyboard while the concurrent mediashow
containing audio tracks has its controls disabled and is played continuously.



pp_multiwindow_1p3 (New in Version 1.3)
This application demonstrates concurrent show playing capabilities where
many shows display content. There are 4 mediashows and a menu running
simultaneously. The menu must be controlled from the keyboard while the
concurrent mediashows have their controls disabled and are played
continuously. The number of concurrent shows is limited only by the power of
the Pi. In the example:
• background - provides the static background
• audio - plays the background audio
• text - is a changing text only mediashow
• slideshow – multimedia automatic slideshow
• menu – interactive menu
The show is set up for remote control by OSC, see Section 15.4



pp_artmediashow_1p3(New in Version 1.3)
A mediashow which features gapless transitions without freezing the picture
at the end of video tracks. Has limited features but could be useful for ‘artistic’
applications.



pp_artliveshow_1p3(New in Version 1.3)
A liveshow which features gapless transitions without freezing the picture at
the end of video tracks. Has limited features but could be useful for ‘artistic’
applications.



pp_subshow_1p3
Demonstrates how to use subshows to segment a larger mediashow.



pp_timeofday_1p3 (Greatly enhanced from Version 1.2)
Opens and closes two mediashows at different times of day and then exits Pi
Presents. This is all controlled by the schedule.json in the profile. To make
this demonstration work whatever the day and time you test it the date and
time is simulated by setting “simulated-time” to “yes” in schedule.json. Make
a backup copy of schedule.json and then alter the date and time to see the
effects. Note morning opening only on Xmas day, just like English pubs!



pp_plugin_1p3 (Plugin API has been modified for Version 1.3)
Demonstrates the operation of track plugins. Track plugins are Python
modules with a defined API which allow you to produce dynamic displays
particularly clocks and from data scraped from the web. Before using the
liveshow copy the .cfg files from the /media directory to the /pp_live_tracks
directory.



pp_showcontrol_1p3

Page 12

Version 1.3.5a, 1 May 2018

Demonstrates the use of Show Control to start and stop one concurrent show
from another. The show is set up to control another Pi by OSC, see Section
15.4


pp_showcontrolevent_1p3
Demonstrates the use of the Show Control Event command to pause and unpause a track using pause-on and pause-off commands



pp_clickarea_1p3
Demonstrates use of click areas in each type of show and the use of Soft
Buttons. In the Radiobuttonshow click areas are selectively disabled by
individual tracks. Soft Buttons has a keys.cfg file which allows keys 1 and 2 to
select the two tracks. When deployed properly there would be two GPIO
buttons mounted adjacent to the left edge of the screen and a gpio.cfg file to
associate the buttons with the symbolic names.



pp_animate_1p3 (Animation commands have changed for version 1.3)
Demonstrates the use of Animation Control by setting P1-11 to On at the start
of a track and to Off at the end. To achieve this it has a gpio.cfg file in the
profile. BEWARE: Ensure P1-11 can safely be used as an output before
running this.



pp_shutdown_1p3
A mediashow that demonstrates how to use Show Control to shut down the Pi
It displays a message track and then when the Down Cursor is pressed starts
a track that shuts down the Pi immediately.



pp_videoplayout_1p3
A demonstration of three types of show that can be used as a video playout
system in theatres or television stations. The key aspect is that videos are
loaded and paused just before the first frame so that pressing the g key which
executes the Go command causes the video to start immediately. Audio files
can be similarly played provided they are implemented as video tracks. See
Section 5.4.5.1



pp_counters_1p3 (new for version 1.3.3a)
Demonstrates the commands for control of counters and use the track plugin
which can access and display values of counters



pp_quiz_1p3 (new for version 1.3.3a)
Demonstrates the use of counters and a Hyperlinkshow to implements a quiz



pp_osc_1p3 (new for version 1.3.3c)
Demonstrates the show control commands for remote control via OSC

3.1 Terminating Pi Presents
You can terminate Pi presents by pressing Ctrl+Break or Alt+F4, or clicking on the
'Close' icon. Terminate is aimed at aborting Pi Presents even in abnormal situations.
For other ways of closing Pi Presents or shutting down the RPi see Section 7

Page 13

Version 1.3.5a, 1 May 2018

Some keyboards do not have a BREAK key; it is possible to configure another key to
exit Pi Presents by editing the keys.cfg file to bind another key to the pp-terminate
symbolic name as described in Section 14.2.5

4 The Pi Presents Profile Editor
This manual is for the new web based editor which replaces the Pi only editor in Pi
Presents - Next. The web based editor is browser based so can be used from a
remote computer in addition to local use. Using the web based editor remotely and
details of the minor differences to look and feel are described in Section 17.3
Profiles can be created and edited using the Pi Presents editor. For use on the Pi the
command is:
python pp_web_editor.py
This will open the Chrome browser and display the editor gui.
When using the editor you will need to supply show references, track references and
file names. It is advisable not to create names beginning with pp- or pp_ to avoid
clashes with names used by Pi Presents.

4.1 Using the Editor
4.1.1 The Displays
Select one of the example profiles using the Profile>Open menu. In the directory
browser click on the text of the example (e.g. pp_mediashow_1p3) and press OK.
Unlike the previous editor do not open the directory.




The top left panel displays the shows in the profile
The bottom left panel shows the medialists in the profile, click on one of the
entries to select it.
The right-hand panel shows the tracks in the selected medialist.

The selected entries are shown with a red background. Click the 'Edit Show' button
adjacent to the left-hand panel to edit the selected show and the 'Edit' button
adjacent to the right-hand panel to edit the selected track.
Edits are saved to disc when OK is pressed, use Cancel if you want to exit without
saving.
You can run pipresents.py and pp_web_editor.py concurrently from two terminal
windows so the effect of any edits can quickly be seen. You will need to restart
pipresents.py to see the effect of the updates made by the editor.
If you are going to edit the examples then first make a copy of them by using the
PCManFM File Manager to access
/home/pi/pp_home/pp_profiles

Page 14

Version 1.3.5a, 1 May 2018

and to copy a profile directory.

4.1.2 Profile Menu
Profile>Open - displays a directory viewer to select a profile for editing. The profiles
displayed are those in the home + offset directory defined in the Options>Edit menu.
Profile>Validate - Validate the Profile. Font and Colour fields are currently not
validated and if you edit the .json files with a text editor you are on your own!
Profile>Copy To – Copies a profile
Profile>Delete – Delete a profile
Profile>New from Template - lists templates for all types of show. The templates
have example tracks so they will run un-edited but some will be missing configuration
files. Examples of these can be copied from:
and

/home/pi/pipresents/pp_io_config
/home/pi/pipresents/pp_resources/pp_templates

4.1.3 Show Menu
Show>Add - Add a new show, and a medialist with the same name. The show type
of an existing show cannot be edited.
Show>Copy To - Copy the show, creating an empty medialist for the show
Show> Edit - Duplicates the Edit Show button
Show>Delete - Deletes the show from the profile, no going back!

4.1.4 Medialist Menu
Medialist>Add - Add a new medialist. The .json extension is added if not included.
Medialist>Copy To – Copy the medialist
Medialist>Delete - Deletes the medialist from the profile, no going back!

4.1.5 Track Menu
Track>Add File
Adds one or more track entries containing media files to the end of the medialist.
These may be images, videos or audio tracks. The editor automatically calculates the
file location and track type. If either of these is unacceptable or the media file
extension is rejected then use Track>New to add a blank track of the required type.
The list of extensions that are used to select track type is in the first few lines of the
pp_definitions.py source. Please raise a bug report if these are inadequate.
Track>Add Dir

Page 15

Version 1.3.5a, 1 May 2018

Similar to Add File, except that all eligible tracks in the directory are added to the
medialist.
The list of eligible extensions that is used to select tracks and their types is in the first
few lines of the pp_definitions.py source. Please raise a bug report if these are
inadequate.
Track>New
Adds a blank track of the selected type to the end of the medialist.
Track>Edit
Duplicates the Edit Button
Track>Copy
Copies a track
Track>Delete
Deletes the track from the medialist, no going back!

4.1.6 OSC Menu
OSC>Create
Creates an empty osc.cfg file in the profile in the directory pp_io_plugins
OSC>Edit
Edits osc.cfg.

4.1.7 Tools Menu
Tools>Update All
Update the version of all profiles in the current home + offset directory, see Section
20.

4.1.8 Options Menu
Options>Edit
Edit the editor options:


Pi Presents Home Directory
This is an important option which must be set to the directory in which any
profile directories and relative media is to be assembled. Out of the box it is
set to /home/pi/pp_home. If you choose an alternative setting for this then
ensure that the directory /pp_profiles is created inside the chosen /pp_home.



Initial Media Directory
This is just a helper setting to define where 'Add Track' and 'Add from Dir'
start their browsing.



Offset for current profiles
This advanced option allows profiles to be separated into directories under
/pp_home/pp_profiles and readily accessed so an offset of /1p3_examples
defaults ‘open’ to /pp_home/pp_profiles/1p3_examples

Page 16

Version 1.3.5a, 1 May 2018

4.1.9 Editor Command Line Options
one of :

If none of these are specified then -l is assumed.

-r --remote
-l --local
-n --native

local – the editor server is run and a browser is opened on the
RPi (ip=127.0.0.1)
remote – the editor server is run with the IP address of the RPi
(e.g. 192.168.1.67) it can be accessed remotely from a browser
on another computer using http://192.168.1.67:8082
native – the editor is run natively on the RPi without a browser.
Requires qt5 and pyview to be installed (which I failed to achieve)

4.2 Making Profiles
Application data is kept is a directory called /pp_home. /pp_home must contain a
directory /pp_profiles in which profiles are stored.
A profile is a directory which contains the information needed to configure a single
application of Pi Presents. It must contain a pp_showlist.json file and one or more
medialist (.json) files. The pp_showlist.json file contains a number of sections, a
'start' show section and a number of sections each defining a user generated show.
Each section in the pp_showlist.json file defines the look and feel of a show and how
they link together. Medialist (.json) files in a profile define the content each show and
some per track look and feel information.
To make profiles portable all media is best kept either under the directory /pp_home
or alternatively inside a profile. In both cases it is recommended that media is stored
in a sub-directory, by convention named media. Media stored like this is referenced
by relative file paths in a profile e.g. +/media/myimage.jpg or @/media/myimage.jpg
The default location of /pp_home is /home/pi; this will need to be overridden by
command line options if you are using a USB stick.
A profile may optionally contain other configuration files such as schedule.json also
an optional directory /pp_io_config which contains Input/output configuration files
such as gpio.cfg. A readme.txt file can be included to allow the profile to be
documented.

4.2.1 Making Profiles Portable
Profiles and their media can be moved between different drives without breaking the
references between shows and their media tracks. This is necessary if a profile is
prepared on a Pi on a SD card and moved to a USB Stick for operational use.
To achieve portability media tracks should be stored under the /pp_home directory,
preferably in sub-directories or alternatively in a profile, by convention in a directory
called media. If tracks are stored in these locations before the profile is prepared then
the Profile Editor will automatically compute the appropriate track reference:

Page 17

Version 1.3.5a, 1 May 2018

If the file is below the home directory (…../pp_home), as defined in the
Options>Edit menu then the file reference will look like '+/track_to_play.mp4'
If the track is in the profile then the file reference will look like
'@/media/track_to_play.mp4’


Otherwise the reference will look like '/home/pi/mymedia/track_to_play.mp4';
an absolute reference.

Absolute references do have their uses, for example in specifying internet url's e.g.
http://www.mysite.com/ track_to_play.mp4

4.2.2 Using the SD Card for Profiles
This is very useful for developing applications on a Pi. To use the SD card for
developing and running profiles:


Create a directory /pp_home in the User Pi's home directory and inside that
create a directory called pp_profiles. You can also create a directory in
/pp_home called say, media, to hold media files.



In the Editor Options set the Pi Presents Data Home directory to
/home/pi/pp_home and the Initial Directory for Media to
/home/pi/pp_home/media



Copy media files to the /media directory



Using the editor create a new profile, call it myprofile, and edit it.



To run the profile type:
python pipresents.py -p myprofile
from a terminal window open in the pipresents directory.

When running Pi Presents from a desktop shortcut, or from an autostart file it is best
to specify the full path of pipresents and also the full path of the data home directory.
e.g.
python /home/pi/pipresents/pipresents.py -o /home/pi -p myprofile

4.2.3 Using the Editor on a Windows PC
Note: This applies to the old editor which is discontinued.

4.2.4 Using a USB Stick for Profiles
To run profiles from a USB stick copy /pp_home to the top level of a USB stick from
its location either on a Pi.

Page 18

Version 1.3.5a, 1 May 2018

Insert the USB stick into a Pi and run Pi Presents with the -o option set to
/media/pi/STICKNAME. STICKNAME is the drive name.

4.2.5 Developing Profiles using a Monitor with Different Pixel
Dimensions
The –s –screensize command line option assists with developing applications on a
host monitor that has different pixel dimensions to the target monitor. Use of this
option will cause Pi Presents to use the provided dimensions instead of the host
screen dimensions that it obtains from Raspbian.


All layout operations such as centring and warping images will use the
provided target dimensions.



If fullscreen mode is not in use a yellow rectangle will show the dimensions of
the target screen.



If fullscreen mode is in use then the display will be the size of the target
monitor placed at the top left of the host monitor. If the target dimensions are
greater than the host dimension then parts of the display will disappear.

5 The Components of Pi Presents
5.1 Introduction
Shows and Tracks
The Pi Presents toolkit has two building blocks - shows and tracks.
A show plays tracks; the list of tracks to be played is contained in a medialist which is
associated with the show, think of the medialist as an enhanced playlist.
The toolkit currently has seven types of show each optimised for a different purpose:


Mediashow - plays a sequence of tracks, usually automatically, but progress
can be manually controlled. Transitions between tracks are gapless but this is
achieved by freezing videos and images at the end of the track while the next
track is loaded.



Artmediashow – plays a sequence of tracks as in Mediashow with full gapless
capability. The next track is loaded while the previous track is playing hence
the tracks do not freeze at their end. The Artmediashow has no triggering
capability and does not support Child tracks or Subshows



Hyperlinkshow - Implements the touchscreen functionality that you see in
many museums.

Page 19

Version 1.3.5a, 1 May 2018



Radiobuttonshow - A simple kiosk show showing a navigation screen - press
one of many buttons to play a track.



Menu - Similar to a Radiobuttonshow but the track selection is by traversing a
menu using 'cursor' keys or a single button.



Liveshow - A Mediashow like show with dynamic remotely sourced content.



Artliveshow – uses remote content as in Liveshow and has full gapless
capability. The next track is loaded while the previous track is playing hence
the tracks do not freeze at their end. The Artliveshow has no triggering
capability and does not support Child tracks or Subshows

The toolkit currently has 'players' for five types of track each playing a different type
of media. All 'players' allow the primary media to be displayed in a window with an
optional background of plain colours, images, and text annotations. Players allow
animation to be controlled, track plugins to be written in Python, and for other
concurrent shows to be opened and closed.






video - plays videos using omxplayer
audio - plays audio tracks using mplayer
image - displays images in many different formats (.jpg etc.) (uses Python
Imaging Library)
message - a quick way to display text.
Web – runs an embedded web browser (uses uzbl)

Subshows and Child Tracks
In Pi Presents a show can be a track of its parent show; this is called a subshow.
Subshows have a number of uses which include:


Dividing a long mediashow into segments. Each segment is a show and a
parent mediashow contains the segment shows in its medialist.



A menu or radiobuttonshow might have mediashows as entries rather than
single tracks



Multi-level menus

Subshows can be nested to any depth; the limit is probably the confusion that it will
cause the audience when using them. Subshows are tracks so appear in the
medialist as Show tracks.
Child tracks are tracks used in a special way by mediashows and liveshows. If a child
track is specified in the profile it can be initiated while running any track in the parent
show returning to the next track in the parent when finished. Child tracks, like any
track can be a show and are sometimes referred to as Child Shows..
The Egg Timer
In all shows transitions between tracks are gapless (no black gaps between tracks).
This is achieved by freezing videos and images at the end of the track while the next

Page 20

Version 1.3.5a, 1 May 2018

track is loaded. For manual operation this means there is a delay of up to 2 seconds
after a control is pressed. The ‘Egg Timer’ can be used cover this delay by displaying
text while the loading takes place. The text appears above the track display so its
content, format, and position is configurable in the show profile.
Concurrent Shows
Pi Presents can run two or more shows concurrently, see Section 8.4. The
concurrent shows appear to run in parallel. This has many uses which include:


Providing a background audio track to a slideshow.
Use two mediashows, one with the slideshow and the other with the audio
tracks. The latter will need the controls disabled if there is customer
interaction with the former.



Dividing the screen into areas (Show Canvases) each showing a different
Show. Perhaps an automatic slideshow in one area, time of day provided by a
show with a track plugin in another, and a user controlled menu of pictures in
a third. Controls may need to be disabled for all but one of the shows. For
more advanced applications Pi Presents can be configured so that each
concurrent show and each subshow has their own sets of controls.



Being really thrifty and doing two completely different tasks with the same Pi,
perhaps a slideshow in the Reception and a dummy talking in a museum
exhibit triggered by a PIR

Each concurrent show can have subshows.

5.2 Shows
Shows have fields which control the sequencing and look of the show. They also
have a number of fields which provide default values for all the tracks in the show
e.g. Duration, Transition, OMXPlayer Audio; tracks will use the values in the show if
their corresponding fields are left blank.
All shows have the following fields:


Title - Text displayed in the editor and in the entries of a menu show



Show Reference - A label which allows other shows to reference this show.
Can be any alpha-numeric string without spaces.



Medialist - this is the name of a file which appears in the medialist panel. It
must have the extension .json. Every show must have a medialist to define
the tracks in the show. The same medialist can be used by more than one
show.

5.2.1 Mediashow and Artmediashow
Think of a mediashow as a slideshow that can play tracks of different types - videos,
audio tracks, images, and even animation control sequences.

Page 21

Version 1.3.5a, 1 May 2018

Mediashows have a number of fields to define the control of the show, e.g. Trigger
for Start, Repeat/Single and Sequence.
A track can be associated with a mediashow such that the track is accessible from
any track in the show. These are termed 'child tracks'. The Child Track parameter
specifies the track reference of the child track, which may be a track or a show.
Associated with the use of a Child Track is ‘Hint Text’ that is displayed only when the
Child Track field is not blank.
The Repeat/Single field control how mediashows run:


repeat - the mediashow repeats until it is stopped.



single-run - the mediashow runs once and then exits. Single run is primarily
for use in subshows and with Show Control

Other fields allow mediashows to the customised for many applications. The table
below shows the Trigger and other field settings for common uses of mediashows
and liveshows.
Task

Repeat

Trigger for
Start

Trigger for
End

Continuous show
repeat
Continuous show that repeats repeat
the medialist until a period of
time has elapsed, then it
ends.
Continuous show that repeats repeat
the medialist at intervals

start
start

none
none

start

none

Run a medialist triggered by
an input (was single shot)
Run a medialist triggered by
an input. Inhibit re-triggering
for a period of time after the
medialist completes.
Play a track triggered by an
input. If sequence = shuffle a
random track will be played
each time.
Start and stop playing a
medialist when an input is
pressed and released

repeat

input

none

repeat

input

none

repeat

input

repeat

input

Other
Fields
(where
non-zero)
Show
Timeout =
h:m:s
Repeat
Interval =
h:m:s

Repeat
Interval =
h:m:s
Track
Count Limit
= tracks

input

In gpio.cfg
use rising
edge and
falling
edge of a
pin for the
two
triggers.

Page 22

Version 1.3.5a, 1 May 2018

‘Magic Picture’. Start a video
and pause it after its first
frame. Unpause using the go
command and then repeat.

repeat

start

none

Use a mediashow as a
subshow or as an item of a
menu, radiobuttonshow etc.

single-run

start

none

Video
requires
‘freeze at
start’ and
‘after first
frame’.
Also the go
command
to be used

Mediashows and Liveshows can also be controlled by the user using Commands
such as Up, Down and Stop. The association of these with the Symbolic names of
Input Events is in the Controls field.
Artmediashow
Artmediashows provide full gapless playback; there is no gap between tracks and
tracks do not freeze at their end to cover loading of the next track. Artmediashows
have some limitations and do not have the fields and commands which are shown in
brackets in the Table below:
 Subshows
 Child Tracks
 Start, Next and End Triggers.
 Web Tracks
5.2.1.1 Controls and Commands
The first means of controlling mediashows and liveshows is by using their
Commands. Out of the box these Commands are bound to a set of symbolic names
and these in turn are bound to a set of keyboard keys. In addition control of Pi
Presents by GPO with a useful set of bindings can be enabled easily by copying a
prepared gpio.cfg file to a profile from /pipresents/pp_resources/pp_templates:
The out of the box settings are:
'Out of the box'

Effect

For GPIO Pin see Section 14.2.1

Command
up

Symbolic
Name
pp-up

down

pp-down

Cursor
Down

play

pp-play

Return

pause

pp-pause

Spacebar

pause-on

Key
Cursor Up

GPIO Pin.
Previous track in mediashow or
liveshow, or up for menu
Next track in mediashow or
liveshow, or down for menu
Start an entry in a menu, or start
a child show.
toggle pause for tracks that
support pause.
pause for tracks that support
pause.

Page 23

Version 1.3.5a, 1 May 2018

pause-off
mute
unmute
stop

pp-stop

Escape

(go)










exit

pp-exit





omx-*













null

mplay-*
(uzbl-*)

unpause for tracks that support
pause.
mute for tracks that support
mute.
unmute for tracks that support
mute.
Stop playing a track and, if a
show is in its quiescent state and
is not a top level show, return to
the parent show.
Quiescent state:
 Liveshow/Mediashow –
at all times
 Menu – displaying menu.
If it is in its quiescent state and a
top level show then stop closes a
single-run show but moves to the
next track for a repeating show.
unpause a video track that is
‘frozen at start’
inhibits the control with the same
symbolic name that has been
defined in the show.
Stop playing a track and exit to
the parent show or, if a top level
show, close the show.
execute a runtime commandl for
the video player (Section 10)
execute a runtime command for
the audio player (Section 10)
execute a runtime command for
the web browser (Section 10)

The 'out of the box' key for each operation is set in /pipresents/pp_io_config/keys.cfg
and the GPIO pin in gpio.cfg. The bindings can be modified as described in Section
14.2. The binding of the Command to the symbolic name is specified in the Controls
field of the show. It is unlikely you will want to modify these but you may wish to
override them for an individual show as described below.
Remember that if more than one show is running concurrently the input event is
passed to and potentially executed by each concurrent show. This may be
undesirable, for example if a mediashow of audio tracks is running as a background
to a manually advanced slideshow; we do not want the up and down operations to
change audio track, so Disable Controls is used with the audio show.
If Disable Controls = yes for the show then all Commands are disabled for the show
and it must run automatically or be controlled by triggers as described in the next
section. For more advanced situations individual Commands can be deleted or
bound to alternative symbolic names for a specific show by using the Controls field of
a show.
Commands can be placed in the Controls field of the tracks in addition to the
Controls field of the mediashow. The controls in a track are merged with and override
those in the show. This is generally not required but could be used where, for
example it is required that the audience watches the whole of a video. In this case
using the null commands would inhibit up/down/stop for the track

Page 24

Version 1.3.5a, 1 May 2018

5.2.1.2 Triggers
Mediashows and liveshows have triggering facilities. The facilities are designed for
use when the show is played without the full user interaction provided by their
Commands
Immediately after a mediashow is run, or it repeats, the show uses the Trigger For
Start field to decide what to do next, After each track Trigger For Next can be
employed to control movement to the next track. Trigger for End determines when
the mediashow finishes
Triggers can be applied to sub-shows and child shows. Triggers are not inhibited by
‘Disable Controls’.
5.2.1.2.1

Trigger for Start

Trigger For Start can take the following values:


start
The mediashow continues to the first track.



input /input-persist
The mediashow waits for an input event before running the first track of the
show. The symbolic name of the input event must be included in the Trigger
for Start Parameter field. Input-persist is a way of implementing ‘magic
pictures’ now replaced by the better Freeze at Start, After First Frame in a
video track.
Text to display while waiting for a Star Trigger is in the Notices Tab of a
mediashow or liveshow.

5.2.1.2.2

Trigger for End

Trigger for End causes the show to exit (single-run) or repeat (repeat). It can take the
following values:


none
The end trigger is not operative the show will exit or repeat at the end of the
medialist/live tracks directory.



input – the end trigger is generated when an input with a symbolic name
matches that in the Trigger for End Parameter field.

5.2.1.2.3

Trigger for Next

The Trigger For Next field allows individual tracks in a mediashow to be triggered by
an input event:

Page 25

Version 1.3.5a, 1 May 2018



None - The trigger is not operative the show will continue to the next track at
the end of the previous.



Input - The show moves to the next track when it is triggered by the input
event having the symbolic name specified in Trigger for Next Parameter field.
The track duration can be used to set a longstop on the trigger, or if set to 0 to
allow forward movement by trigger only.

5.2.1.3 Fields
Fields for Mediashow and Liveshow. Fields not used for Artmediashow and
Artliveshow in brackets
Field
Show Tab
Type
Title
Show
Reference
Medialist

Examples

(art)mediasho
w
My First Show
show1
show1.json

(Trigger For
Start)

start

(Trigger for
Start
Parameter)

PIR

(Trigger for
Next)

continue

(Trigger for
Next
Parameter)

Values

Cannot be edited
Text describing the show. Displayed in the editor
and on menus
A ‘label’ by which the show is referenced by
other shows. Any text without spaces
Filename of the medialist file containing the
tracks for the mediashow. By default it is the
same as the Show Reference but can be
changed.
How the media show proceeds after it is started
and at the beginning of a repeat:
 start - continue without waiting
 input - wait for an input event.
 input-persist – wait for an input event.
Input-persist displays the immediately
previous track while waiting (providing
videos are frozen at their end)
If Trigger For Start is 'input', or ‘input-persist’:
A symbolic name that is bound to an
input event as described in Section 14.2
How to trigger the next track
 input - respond an input event
 continue – continue without waiting
Input can be used in one of two ways:
If the duration of a track is zero the mediashow
will move forward only when the trigger is
received.
If the duration of a track is non-zero then the
mediashow will move forward automatically and
also when the trigger is received.
If Trigger For Next is 'input':
A symbolic name that is bound to an
input event as described in Section 14.2

Page 26

Version 1.3.5a, 1 May 2018

Field
Sequence

Repeat/Single

Examples

repeat

Values
sequence of tracks:
 ordered - played in the order of the
medialist
 shuffle - play tracks in a random order.
For liveshow this is a true shuffle so a
track will not be replayed until all the
tracks in the live tracks directories have
been played. For mediashow the next
track is chosen randomly.

How the media show is repeated:
 repeat – Wait for Trigger for Start. Tracks
in the medialist are then played once and
then the medialist repeats by waiting for
Trigger for Start.
 single-run – Waits for Trigger for Start.
Tracks are then played once and then the
show closes.
Note: There is no natural end to a shuffled set of
tracks.
How the end of a show can be triggered. See the
table above for more detail.
 none – the end trigger is not operative
 input – Ends after an input event as
described in Section 14.2
 duration – end the show after a period of
time.

(Trigger For
End)

none

(Trigger for End
Parameter)

5:00

If Trigger For End =:
 input – A symbolic name that is bound to an
input event as described in Section 14.2

(Track Count
Limit)

1

(Repeat
Interval)

30

If non-zero the show closes or repeats after
Count tracks have been played. Intended fo use
where the Track Count Limit is less than the
number of anonymous tracks in the medialist.
h:m:s
The show repeats/ends at Repeat Interval or at
the end of the medialist, whichever is last. If the
medialist ends before Repeat Interval then a
blank screen is displayed.
Interval = 0 always repeats/ends when medialist
is complete. Repeat Interval=0 does not work for
shuffle as a shuffled medialist never finishes.
For shuffle and Repeat Interval>0 the show
always continues until Repeat Interval as a
shuffled medialist does not finish

Page 27

Version 1.3.5a, 1 May 2018

Field
(Show Timeout)

Examples
1:30:20

Show Canvas

100 100 400
600

Values
h:m:s If non-zero end the show after the
specified period if nothing else has ended it.
The top left and bottom right coordinates of the
show canvas. Show canvas helps the user divide
the screen when displaying more than one
concurrent show. If the field is not blank the
Show Canvas dimensions controls the placing
and size of images and videos taking the place
of the dimensions of the screen. The Show
Canvas determines the origin of the images (top
left) however it is not a window and does not
crop the image or video so, if the bottom right coordinates of the image are larger than the Show
Canvas it can overlap other show canvases.
Instead of 2 x,y, pairs x1+y1+w*h can be used

Child Track
Tab
(Child Track)
(Hint Text)
(Hint Font)

child-track
Press Play to..
Helvetica 30
bold

Non-blank to enable a Child Track and to specify
the track reference of the track.
A single line of text
Use the Font Chooser to select a font, or type
one in:
See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm

(Hint Colour)

white

(Hint Justify)
(Hint x)

right
500

(Hint y)

900

Eggtimer Tab
EggTimer Text
Eggtimer Text
Font

Loading….
Helvetica 30
bold

Use the Colour Chooser to select a colour which
will return a six digit hex number, or type in a
colour name.
See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
left, right, center – Justify lines in a block of text
Position of left of text. If blank then the text is
centred on the show canvas
Position of top of text. If blank then the text is
centred on the show canvas
Eggtimer text is displayed when the next track is
being loaded
A single line of text
Use the Font Chooser to select a font, or type
one in:
See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm

Page 28

Version 1.3.5a, 1 May 2018

Field
Eggtimer Text
Colour

Examples
white

Values
Use the Colour Chooser to select a colour which
will return a six digit hex number, or type in a
colour name.

Eggtimer Text x
Position

100

Eggtimer Text y
Position

100

Eggtimer Justify

right

See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
distance of the start of the text from the left of the
screen (pixels) If blank then the text is centred on
the show canvas
distance of the top of the text from the top of the
screen (pixels) If blank then the text is centred on
the show canvas
left, right, center – Justify lines in a block of text

Waiting…

Text to show when Waiting for Trigger

Notices Tab
(Trigger Wait
Text)
Notice Text x
Position

distance of the start of the text from the left of the
screen (pixels) If blank then the text is centred on
the show canvas
distance of the top of the text from the top of the
screen (pixels) If blank then the text is centred on
the show canvas
Use the Colour Chooser to select a colour which
will return a six digit hex number, or type in a
colour name.

Notice Text y
position
Notice Text
Colour

Notice Text
Font

See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
Use the Font Chooser to select a font, or type
one in:

Notice Justify

right

See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
left, right, center – Justify lines in a block of text

Show
Background
and Text Tab
Background
Image

+/media/image
.jpg

If not blank the file name of an image which is
used as the background for any tracks in the
show. The image is warped to fit the Show
Canvas. If you do not want background images
to be warped then edit them in advance to be the
size of the Show Canvas.

Page 29

Version 1.3.5a, 1 May 2018

Field
Background
Colour

Show Text
Show Text Font

Show Text
Colour

Examples

Pictures from
my holiday
Helvetica 30
bold

white

Show Text x
Position

100

Show Text y
Position

100

Show Text
Justify

right

Track Defaults
Tab
Duration

10

Pause Timeout

5

Track Text Font

Helvetica 30
bold

Track Text
Colour

white

Values
Use the Colour Chooser to select a colour which
will return a six digit hex number, or type in a
colour name.
See http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
The background colour is set to black when Pi
Presents starts. The value in this field is used by
a track in the show if the value in the track’s field
is blank.
If the resulting Background Colour is blank the
background colour is not changed.
Show text is overlayed on all tracks in the show.
If not blank the text to be displayed.
Use the Font Chooser to select a font, or type
one in:
See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
Use the Colour Chooser to select a colour which
will return a six digit hex number, or type in a
colour name.
See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
distance of the start of the text from the left of the
screen (pixels) If blank then the text is centred on
the show canvas
distance of the top of the text from the top of the
screen (pixels) If blank then the text is centred on
the show canvas
left, right, center – Justify lines in a block of text

Tracks played in the show need some
configuration if not supplied in the individual
tracks
seconds. How long a track having no natural end
is displayed. A value of 0 displays continuously.
seconds. If not blank and greater than 0 a
paused track will automatically unpause after the
timeout.
Use the Font Chooser to select a font, or type
one in.
See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
Use the Colour Chooser to select a colour which
will return a six digit hex number, or type in a
colour name.
See: http://effbot.org/tkinterbook/tkinter-widget-

Page 30

Version 1.3.5a, 1 May 2018

Field

Examples

Track Text x
Position

100

Track Text y
Position

100

Track Text
Justify
Transition

right
cut

Image Rotation
Image Window

90
original 10 100

Values
styling.htm
distance of the left end of the text from the left of
the screen (pixels) If blank then the text is
centred on the show canvas
distance of the top of the text from the top of the
screen (pixels) If blank then the text is centred
on the show canvas
left, right, center - Justify lines in a block of text
cut. Type of transition between tracks.
Currently not used.
Rotates the image
For any image track in the show a viewport in
which to show the image. See section 5.4.4.1

fit
fit 1010 40 40

Video Audio

Video Audio
Volume
Video Window

fit ANTIALIAS
hdmi

0
original

hdmi/local/both/alsa . Sound output
channel for any video track played by omxplayer
from the show. If blank then the channel is set
automatically by the presence of a hdmi monitor.
(can be forced in raspi-config) (both is
hdmi+local)
Volume of audio for the video track (-60 -> 0 dB).
For any video track in the show a viewport in
which to show the video.

warp


original – use OMXPlayer default
behaviour



warp – scale to the size of the screen
without maintaining aspect ration

warp 10 100
200 700

warp followed by two x,y, pairs (top left,
bottom right) – the viewport window. The
video is scaled to this size without
preserving the aspect ratio. Instead of 2
x,y, pairs x1+y1+w*h can be used
Freeze a video at the start of the track
 no – no freeze
 before-first-frame – the video is paused
before the first frame is shown
 after-first-frame - the video is paused
after the first frame is shown
To continue after the freeze use the ‘go’
command.


Freeze at Start

before-firstframe

Audio tracks can be ‘frozen at start’ by playing

Page 31

Version 1.3.5a, 1 May 2018

Field
Freeze at End

Video Player
Options
Audio Player
Audio
Audio Player
Speaker
Audio Player
Volume
Audio Player
Options
(Web Window)

Examples
yes

local
stereo
0

warp
warp 10 100
200 700

Controls Tab
Controls

pp-play play
pp-up up

Values
them as video tracks.
yes/no If yes the video will be frozen near the
last frame until the next track is ready to be
displayed.
Other options for omxplayer (care required to
avoid have a nice day!)
hdmi/local. Sound output channel for any audio
track played by MPlayer from the show.
left/right/stereo. Speaker for any audio track
played by MPlayer in the show.
Volume of audio track (-60 -> 0dB) played by
MPlayer in the show.
Other options for MPlayer (care required to avoid
rejection!)
For any web track in the show a viewport in
which to show the web page.


warp - scale to the size of the screen
without maintaining aspect ration



warp followed by two x,y, pairs (top left,
bottom right) - the viewport window. The
web page is scaled to this size without
preserving the aspect ratio. Instead of 2
x,y, pairs x1+y1+w*h can be used

Defines the bindings between symbolic names of
input events and commands
See Table above and Section 6.4
One binding per line each with the format:
symbolic-name command

Disable
Controls

Show Control
Tab
Show Control at
Beginning
Show Control at
End

no

Bindings are NOT inherited by subshows.
yes/no
If 'yes' Commands (e.g. play, pause, up, down,
stop) are disabled. This is a quick way to inhibit
all controls for a concurrent show. For more
selective control use the Controls field

open audio1

See Section 8.2

close audio1

See Section 8.2

Page 32

Version 1.3.5a, 1 May 2018

5.2.2 Menu
A menu show uses the Title and Thumbnail fields of tracks and of shows to
automatically generate a menu on the screen. The Up and Down Commands can
then be used to scroll the menu and the Play Command to play the track or show.
A menushow needs an associated menu track in its medialist which defines the
layout of the menu:


Display, thumbnails, bullets or Titles in many combinations



Align the menu vertically or horizontally



Create multi-column, multi-row menus



Alter the separation, colours and font of the menu items

5.2.2.1 Controls and Commands
Menu Commands are the same as those for Mediashow and are described in details
in Section 5.2.1.1
5.2.2.2 Fields
Field
Show Tab
Type
Title
Show
Reference
Show Canvas
Medialist

Examples

menu
mymenu

Show Timeout

mymenu.json
59

Track Timeout

20

Menu Track

menu-track

Values
Essential information
Cannot be edited
Text describing the show, displayed in the editor.
A ‘label’ by which the show is referenced by other
shows. Any text without spaces
See Mediashow
Filename of the medialist file containing the tracks
for the menu.
h:m:s, If there is no activity on the menu Pi
presents automatically close the show. 0 for no
timeout.
h:m:s, If non-zero tracks launched from the menu
will be stopped after this time and control will
return to the menu.
The track reference of the track that will display the
menu content. Must be of type Menu Track

Eggtimer Tab

Eggtimer text is displayed when the next track is
being loaded.
See mediashow

Show
Background
and Text Tab

Show text is overlaid on all tracks other than
message tracks opened from the menu.

Page 33

Version 1.3.5a, 1 May 2018

Field

Examples

Values
See mediashow

Track Defaults
Tab

pp-down down
Controls Tab

Tracks played from a menu need some
configuration if not supplied in the individual
tracks
See Mediashow
Defines the bindings between symbolic names of
input events and commands
One binding per line each with the format:
symbolic-name command
Bindings are not inherited by subshows.

Disable
Controls

no

See Table above and Section 5.2.1.1
yes/no
If 'yes' the commands are disabled. This is a
quick way to inhibit all controls for a concurrent
show. For more selective control use the
Controls field

Show Control
Tab
See Mediashow

5.2.3 Liveshow and Artliveshow
A Liveshow is identical to a Mediashow except that the content is dynamically
supplied from directories of media, the Live Tracks directories, and is therefore
limited to video, image, and audio tracks, and their track plugins. The tracks from the
two directories are merged and, if sequence = ordered, sorted by the leaf of the file
name.
See Section 5.2.1 for details of commands, triggers and fields.
A medialist must be associated with a Liveshow. It is used for the Child Track, List
Empty Track, and Escape Track all other tracks in it will be ignored.
Actions on the list of tracks being empty:
a. List Empty/Escape


If the liveshow’s repeat field is ‘Single Run’ then the liveshow exits.



If the liveshow’s repeat field is ‘Repeat‘ and List Empty Track’ is blank then an
error will be generated.



If the liveshow’s repeat field is ‘Repeat’ and the ‘List Empty Track’ is not a
show it is run whenever the list of tracks to be played is empty. The track is
played once and then the content of the list of tracks is re-evaluated.

Page 34

Version 1.3.5a, 1 May 2018



The List Empty Track may be a show. If so the show should be ‘single run’ or
there should be some other method of exiting from the show so that the list of
liveshow tracks can be re-evaluated. If the list is then empty the Escape track
is run once. This track must not be a show. Its purpose is to allow the
liveshow to be stopped or exited if it is a subshow of another show.



The limitation of this method is that the empty track/show uses the same
Show Canvas as the liveshow.

b. Show Control


The ‘Show Control on Empty’ and ‘Show Control on Not Empty’ fields allow
other shows to be opened or closed depending on whether there are tracks to
be played.

It is unlikely that both methods will be required in the same application.
Artliveshow
Artliveshows provide full gapless playback; there is no gap between tracks and tracks
do not freeze at their end to cover loading of the next track. Artliveshows have some
limitations and do not have the fields which are shown in brackets in the Table in
Section 5.2.1.3:
 Start, Next and End Triggers.
 Child Tracks
The Liveshow has the following fields additional to those of the Mediashow:
Field
Live Tracks
Directory 1

Examples

Live Tracks
Directory 2
(List Empty
Track)
(Escape Track)

Show Control
Tab
Show Control
on Empty
Show Control
on Not Empty

Values
The full path of a Directory containing tracks for
this show. If blank the tracks are taken from the
pp_live_tracks directory in pp_home
The full path of a Directory containing tracks for
this show. If blank the tracks are taken from
directory specified in the –l command line option.
Not ArtLiveshow. Run when the list of tracks in a
liveshow is empty. See text
Not ArtLiveshow. Run when returning from an
Empty Track which is a show. See text.

open show1

See Section 8.2

close show1

See Section 8.2

5.2.4 Radiobuttonshow
A Radiobuttonshow provides the sort of show facilities that are in many kiosks
namely:
'Start with an initial display which might include some text inviting the user to
press buttons or touch the screen to initiate a track. While playing the track

Page 35

Version 1.3.5a, 1 May 2018

pressing another button will play another track. At the end of a track or when
Stop is pressed revert to the initial display.'
In Pi Presents the initial display can be an image, message, video or audio track, or a
show. Playing of other tracks is by means of commands in the Controls field of the
Radiobuttonshow e.g.
but1 play myimagetrack
but2 play myvideotrack
5.2.4.1 Controls and Commands
Each control has three fields separated by spaces:
 symbolic name - the symbolic name of the input event that will play the show
or track.
 command – see below
 track - the Track Reference or Show Reference of the track or Show to be
played.

Command
play
return
stop

Argument
track-ref



go



unpause a video track that is ‘frozen at start’

exit
null




pause
pause-on
pause-off
mute
unmute
omx-*








close the Radiobuttonshow
inhibits the control with the same symbolic name
that has been defined in the show.
toggle pause on video, audio, or image tracks
pause for tracks that support pause
unpause for tracks that support pause
mute for tracks that support mute
unmute for tracks that support mute
execute a runtime control for the video player

Play the track specified by track-ref
return to the first track of the show
stop the current track and, if show is the quiescent
state and this is not a top level show, then close
the show.
The quiescent state is when the first track is
showing.

(Section 10)

mplay-*



execute a runtime control for the audio player

uzbl-*



execute a runtime control for the web browser

(Section 10)
(Section 10)

Commands can be placed in the Controls field of the tracks in addition to the
Controls field of the radiobuttonshow. The controls in a track are merged with and
override those in the show. This is generally not required but could be used where,
for example it is required that the audience watches the whole of a video. In this case
using the null command would inhibit the symbolic names that play other tracks or
stop the track.
5.2.4.2 Fields

Page 36

Version 1.3.5a, 1 May 2018

Field
Show Tab
Type
Title

Examples

radiobuttonshow
My Show

Show
Reference
Show
Canvas
Medialist

myradioshow

First Track

myfirsttrack

Show
Timeout

1:59

Track
Timeout

20

Controls in
Subshows

no

mymedia.json

Values

Cannot be edited
Text describing the show displayed in the Editor
and menu
A ‘label’ by which the show is referenced by
other shows. Any text without spaces
See Mediashow
Filename of the medialist file containing the
tracks for the Radiobuttonshow. All tracks should
have a Track Reference.
The Track Reference of the track that will form
the initial display for the show.
h:m:s, If there is no activity on the First Track Pi
Presents automatically returns to the previous
show. 0 for no timeout.
h:m:s If non-zero tracks launched from the
radiobuttonshow will be stopped after this time
and control will return to the show.
yes/no
If no (normal Radiobuttonshow operation )
pressing a button or key while a track is playing
will start playing the selected track.
If yes and the track is a show then input events
will be passed down to the show. This allows the
show to be controlled but it will not be possible to
select another track while a track is playing.

Eggtimer
Tab
See Mediashow
Show
Background
and Text
See Mediashow
Track
Defaults
Tab
See mediashow
Controls
Tab

Page 37

Version 1.3.5a, 1 May 2018

Field
Controls

Examples
myname play
mytrack

Values
Defines the bindings between symbolic names of
input events and commands
One binding per line each with the format:
symbolic-name command [arg]
Bindings are NOT inherited by subshows.

Disable
Controls

no

See Table above for list of commands
yes/no
If 'yes' all Commands are disabled. This is a
quick way to inhibit all controls for a concurrent
show. For more selective control use the
Controls field.

Show
Control Tab
See
Mediashow

5.2.5 Hyperlinkshow
A Hyperlinkshow provides the type of show facilities that are used in touchscreen
displays in museums:
'Start with an initial page with some introductory text, video or image and a
selection of on screen buttons which allow the user to move to another page.
Each page can have a different selection of buttons to link to other pages.
When in any page other than the initial page additional buttons allow the user
to go back to the previous page or to return to the initial page.
All of the touchscreen displays that I have tried in my researches seem to work this
way, or are Radiobuttonshows.
Every page in the example above is a track in a Hyperlinkshow. Each has a Controls
field which contains commands implementing the movement between tracks and
back.
e.g.track ‘story1b’ might contain the following controls:
next-name call story1c
alternative-name call alternative1
back-name return
home-name home
xxx-name is the symbolic name of an input event. This example says either go
forward to ‘story1c’ or to ‘alternative1’, return to the previous track (which was
probably ‘story1a’), or return to the home track which probably means going back
through ‘story1a’ without displaying it.

Page 38

Version 1.3.5a, 1 May 2018

When executing the call command Pi Presents remembers where it has come from in
the ‘path’ (essentially a stack) so the return command can go back one removing the
current track from the path. Think of nested call and return of subroutines in a
programming language.
There is a special track called the Home Track. The home command can skip back
along the path until it arrives at the Home Track so it is not necessary to know how
far you have gone to get back to a known starting point.
Each control has three fields separated by spaces:
 symbolic name - the symbolic name of the input event that will trigger the
command
 command - call, return, goto, jump, exit, null, repeat, pause, no-command,
and runtime controls
 track - the Track Reference of the track to be played
5.2.5.1 Controls and Commands

Command
call

Effect
play Track Reference and add it to the path

return

Argument
Track
Reference


return

number

return n tracks back up the path removing the
track from the path, stops at Home Track.

return



return to Track Reference removing tracks from
the path, goes through Home Track if necessary.

home



jump





Return up the path to Home Track removing tracks
from the path
play Track Reference forgetting the path back to
Home Track
play Track Reference, forget the path

goto
repeat

return 1 back up the path removing the track from
the path, stops at Home Track.

Repeat the current track without resetting the
timeout.

go



unpause a video track that is ‘frozen at start’

null



exit
pause
pause-on
pause-off
mute
unmute
no-command









omx-*



inhibits the Link with the same symbolic name that
has been defined in the show.
end the Hyperlinkshow
toggle pause on video, audio, or image tracks
pause for tracks that support pause
unpause for tracks that support pause
mute for tracks that support mute
unmute for tracks that support mute
Clicking it has no effect. Use for legends for ‘soft
keys’ to display a ‘Click Area’ that is not enabled.
execute a runtime control for the video player
(Section 10)

mplay-*



execute a runtime control for the audio player

Page 39

Version 1.3.5a, 1 May 2018

(Section 10)

uzbl-*



execute a runtime control for the web browser
(Section 10)

Commands can be placed in the Controls field of the Hyperlinkshow in addition to the
Controls field of tracks. This is a convenience to save typing because the commands
from the show are used in every track and the commands from the track are merged
with them. Sometimes this is not desirable and using the null command in the track
will cancel the command with the same symbolic name in the show.
The goto command does not remember where it has come from. It is used in special
circumstances such as timeout. It is also an alternative way to call/return for
implementing a back button. If used every back has to be a goto. It is not a good idea
to mix call/return and goto in the same part of a Hyperlinkshow.
If a track, such as a video or a timed image, ends naturally there needs to be a way
for Pi Presents to execute a Command in order to determine what to do next. This is
achieved by Pi Presents generating an internal input event with the symbolic name
pp-onend; the Links field can then have a command to service it e.g.
pp-onend goto mynextpage
or
pp-onend repeat
Commands associated with pp-onend cannot be pause, no-command, omx-, mplay-,
or uzblThere is a second special track the First Track. Pi Presents always starts the show
here. In many applications Home Track and First Track will have the same Track
Reference. They may however be different. This was designed such that First Track
would start the show with an image or video to entice the user to touch a button to
move to the Home Track in order to start the interactive sequence of tracks. Once
past the Home Track pressing home, return, or jump would not return him to First
Track. However the timeout would.
To ensure that the screen goes back to the First Track if the user leaves the screen
there is a timeout. If activated the Hyperlinkshow goto’s the Timeout Track. This
could have the same Track Reference as the First Track but a separate Timeout
Track allows for reset of, say, animation before goto’ing the First Track.
Tracks in Hyperlinkshows can be shows. These shows have their own set of
commands including stop which will return to the hyperlinkshow.
When developing a hyperlinkshow application it is sometimes useful to see the path
of pages that Pi Presents has remembered. To enable this use Debug Path.
5.2.5.2 Touchscreens and Soft Buttons
The nature of Hyperlinkshows is such that a different set of controls is needed for
each track of the show. Pi Presents has two ways to provide these controls:


Click Areas

Page 40

Version 1.3.5a, 1 May 2018

Click areas are aimed at touchscreens. A ‘click area’ is an area of the screen
which is mouse click sensitive. Although they are called ‘click areas’ they can
best be used with touchscreens and might better be called touch areas.
Touching the area of a touchscreen or clicking with a mouse in the area will
cause an input event with a symbolic name defined in screen.cfg.
Optionally associated with a click area is an image, maybe of a button, which
is displayed when the click area is enabled. Alternatively a click area can be
transparent and the area defined as a polygon to encompass the shape of the
object behind.


Soft Buttons
Soft buttons are a poor man’s touchscreen. They were used a lot in real time
control applications before touchscreens were developed.
Soft buttons are a row of unmarked keys or buttons arranged along the edges
of a display screen. The legends for the buttons are software controlled and
appear adjacent to the button on the edge of the display area of the screen.
Thus different button positions and legends can be applied to each track of a
Hyperlinkshow.

Pi Presents will allow both of these techniques to be used to control Hyperlinkshows
as describes in Section 9
5.2.5.3 Fields
Field
Show Tab
Type
Title

Examples

hyperlinkshow
My Hyperlink Show

Show
Reference
Medialist

myhyperlinkshow

First Track

myfirsttrack

Home Track

myhometrack

Timeout
Track

mymedia.json

Values

Cannot be edited
Text describing the show displayed in the
editor and menu.
A ‘label’ by which the show is referenced
by other shows. Any text without spaces
Filename of the medialist file containing
the tracks for the Hyperlinkshow. All
tracks should have a Track Reference
The Track Reference of the track that will
form the initial display for the show.
The Track Reference of the track that will
form the root of the call/return path.
The track displayed when a timeout
occurs. Pi Presents does not return
directly to the Home track as there may
be a need to reset animation or stop
concurrent shows.
Usually this track will do whatever is
required and 'goto' the First or Home
Track after a short time. If the track is an
audio track it can have no sound and zero
duration.

Page 41

Version 1.3.5a, 1 May 2018

Field
Show
Timeout
Track
Timeout

Examples
60

30

Show
Canvas

Values
h:m:s, If there is no activity on the Home
Track Pi Presents automatically returns to
the previous show. 0 for no timeout.
h:m:s. When playing a track if no user
input is received or the track does not
naturally finish before the timeout then
goto the Timeout Track. A value of 0
disables the timeout function.
See Mediashow

Eggtimer
Tab
See mediashow
Show
Background
and Text
Tab
See Mediashow
Track
Defaults
Tab
See mediashow
Controls
Tab
Disable
Controls

no

Controls

name call mytrack

See Mediashow
yes/no
If 'yes' Internal Operations (play, pause,
up, down, stop) and Run Time controls
are disabled. This is a quick way to inhibit
all controls for a concurrent show. For
more selective control use the Controls
field.
Defines the bindings between symbolic
names of input events and commands
One binding per line each with the
format:
symbolic-name command
Bindings are NOT inherited by subshows.
See Table above for a list of commands

Show
Control Tab
See
Mediashow

Page 42

Version 1.3.5a, 1 May 2018

5.2.6 Start Show
Do not delete the Start Show. The Start show is not a show; it is a part of the profile
that specifies things that are common to all shows:
The shows to be run when Pi Presents starts. Each show will run concurrently with
other shows. Input events will be passed to all concurrent shows. The Start shows
field may be blank in which case shows must be started by other means.
Whether the time of day scheduler is enabled and the schedule for things that are
common to shows (See Sect. ???)
Controls for simulated time that can be used to test the time of day scheduler (See
Sect. ???).
The colour of the background that is displayed behind shows.
Field
Schedule
Tab
Start Shows

Enable
Scheduler

Examples

show1 show2

no

Simulate
Time Tab
Simulate
Time

A list of Show References separated by spaces.
These are shows that are started when Pi
Presents starts.
yes/no Enables the time of day scheduler.
Leave as No unless you want have set up the
time of day scheduler. See Section ????
See Section ?? for additional fields

yes/no Use a simulated time and date when
testing the time of day scheduler.
Leave as No unless you want have set up the
time of day scheduler. See Section ????
See Section ?? for additional fields

Background
Tab
Background
Colour
Show Tab
type
start
title
Start Show
Show
Reference

Values

start

The colour of the background where no shows
are displayed.
Must always be start, not editable.
Text describing the show, displayed in the
editor.
must be 'start', not editable

5.3 Medialists
Medialists are similar to playlists in a media player in that they define the tracks to be
played. How they are played is defined by the show that the list is associated with.
Each entry in a medialist is a 'track'. Tracks can be of various types:

Page 43

Version 1.3.5a, 1 May 2018









image - a still image
video - a track played by OMXPlayer.
audio - an audio track played by MPlayer
message - displays lines of text
web – runs a browser to display a URL
show - shows can be used as tracks allowing nesting to any depth.
menu-track – a special track to define the format of a menu

A medialist is generally associated with a single show. However in Pi Presents they
have been kept separate from the remainder of the show specification so that the
same medialist could be used in two different shows.

5.4 Tracks
Each type of track has fields describing how to display the track, some of these
override the corresponding fields in the associated show.
The type of track describes the primary content of the track; primary content can be
displayed in front of an image or plain coloured background and have text
annotations.


image - a still image. Image types are those that can be rendered by the
Python Imaging Library. For performance reasons image size is best limited
to the 1 megapixel region.



video - a track played by OMXPlayer. Playable video formats depend on the
codec licences purchased from the Foundation.



audio - an audio track played by MPlayer. Any track type playable by MPlayer
should be playable. The audio track type is very flexible as it has extended
duration handling features which makes them useful for sequencing
animation or shows.



message - displays lines of text. Can also used to display a blank screen. It
provides a simple slide preparation facility. If you want something better use
Powerpoint or similar and export as .jpg displaying as an image.



web- displays a URL in a browser. Browser integration into Pi Presents is not
optimal and this type of track should be used with care. There are many other
browser based digital signage systems.



show - shows can be used as tracks allowing nesting to any depth.



menu – used to specify the layout of a menu for the Menu Show.

5.4.1 Track Location Names
Track locations which specify files can be relative or absolute. Relative file names
allow profiles to be portable. See Section 4.2.1


The leading + sign in file paths allows tracks to be specified relative to the
/pp_home directory. If a plus sign is not present then the path must be

Page 44

Version 1.3.5a, 1 May 2018

absolute. It is recommended that media files be stored under /pp_home if the
profiles are to be portable.


Absolute references do have their uses, for example in specifying internet
url's e.g. http://www.mysite.com/track_to_play.mp4

5.4.2 Anonymous and Labelled tracks
Some medialist entries will have labels defined by the field Track Reference. If the
Track Reference is blank then the track is included in a Menu, Mediashow or
Liveshow, these are called anonymous tracks. If the label is not blank then the track
can be referenced by Commands used in Radiobuttonshows and Hyperlinkshows, or
for a special purpose. Special purposes include:




The Child of a mediashow or liveshow.
The Menu Track of a Menu
First, Home and Timeout tracks in Hyperlinkshow or Radiobuttonshow

The field definitions for each type of medialist track follow in the next section.

5.4.3 Show Track
The tracks in a show can themselves be shows. These are called sub-shows. Show
tracks allow sub-shows to be included in a medialist. The Show To Run field
specifies the Show Reference of the show.

5.4.4 Image Track
Image tracks are rendered by the Python Imaging Library. (See hardware
requirements for recommended image size). Image tracks can be paused with the
Pause Command. Images can appear in a window, be rotated, can have an image or
colour as a background, can be overlaid with text; Track Text is overlaid on a per
track basis, Show Text per show.
Field
Track Tab
Type
Title

Example

image
Displayed on a menu and in the editor

Track
Reference

Location

Duration

+/media/sarenam
e.gif
+/media/sarenam
e_tn.jpg
5

Transition

cut

Thumbnail

Values

A label for the track - blank if the track is to be
included in a menu or mediashow. Non-blank if
the track is to be triggered from a symbolic name
or is special.
The filename of the track which may be blank.
The optional filename of a thumbnail image to be
displayed by a menushow.
Seconds. If 0 then image is displayed until
terminated by user input. If blank then the value
in the parent show is used.
cut. (Not used)

Page 45

Version 1.3.5a, 1 May 2018

Field
Rotation
Image
Window

Example
90
original 10 100
fit

Values
degrees. If blank then the value in the parent
show is used.
A viewport in which to show the image. If blank
then the value in the parent show is used. See
section 5.4.4.1

fit 1010 40 40

Background
Image
Display
Show
Background
Image

Background
Colour

Plugin
Configuratio
n File
Pause
Timeout

Controls
Tab
Controls

Text Tab
Track Text
Track Text
Font

Track Text
Colour

fit ANTIALIAS
+/media/image.jpg The file name of an image which is used as the
background for the main image. If blank then the
value in the parent show is used.
yes
yes,no
yes - the background image of the parent show
is displayed if the track Background Image is
blank
no - the background image of the parent show is
not displayed
Use the Colour Chooser to select a colour which
will return a six digit hex number, or type in a
colour name.

+/media/krttime.cfg

See http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
If blank then the value in the parent show is
used.
File which specifies the name and parameters of
the Track Plugin.

5

seconds. If not blank and greater than 0 a
paused track will automatically unpause after the
timeout.

myname null

Bindings of symbolic names to commands. The
bindings defined here for the track are merged
with and override bindings for the associated
show. See Section 8.1

Picture of Taj
Mahal
Helvetica 30 bold

If not blank the text displayed with the image,
overlaying it if necessary.
Use the Font Chooser to select a font, or type
one in.

white

See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
Use the Colour Chooser to select a colour which
will return a six digit hex number, or type in a
colour name.
See: http://effbot.org/tkinterbook/tkinter-widget-

Page 46

Version 1.3.5a, 1 May 2018

Field

Example

Track Text x
Position

100

Track Text y
Position

100

Track Text
Justify
Display
Show Text

right

Pause Text
Pause Text
Font

Pause Text
Colour

yes

Paused…..
Helvetica 30 bold

white

Values
styling.htm
distance of the left end of the text from the left of
the screen (pixels) If blank then the text is
centred on the show canvas
distance of the top of the text from the top of the
screen (pixels) If blank then the text is centred
on the show canvas
left, right, center - Justify lines in a block of text
yes,no
Allow or inhibit the display of show text for this
track
Text displayed when track is paused
Use the Font Chooser to select a font, or type
one in.
See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
Use the Colour Chooser to select a colour which
will return a six digit hex number, or type in a
colour name.

Pause Text x
Position

100

Pause Text y
Position

100

Pause Text
Justify

right

See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
distance of the left end of the text from the left of
the screen (pixels) If blank then the text is
centred on the show canvas
distance of the top of the text from the top of the
screen (pixels) If blank then the text is centred
on the show canvas
left, right, center - Justify lines in a block of text

open audio1

See Section 8.2

close audio1

See Section 8.2

1 out1 state on
2 out1 state off
1 out2 state on
6 out3 state off
no

See Section 13

yes/no See Section 13

0 out2 state off

See Section 13

Show
Control Tab
Show Control
at Beginning
Show Control
at End
Animation
Tab
Animation at
Beginning

Clear
Animation
Animation at
End

5.4.4.1 Image Window

Page 47

Version 1.3.5a, 1 May 2018

The Image Window controls how an image is presented spatially. It contains a
number of fields separated by spaces. If Image Window is blank then the value from
the show is used.
The first field is one of original, shrink, fit or warp


original
The image is displayed at its original size. The command has optionally two
arguments the x,y, coordinates of the top left corner of the displayed image.
If the arguments are omitted then the image is displayed centred on the
screen.
e.g. original, original 100 100



fit
The image is displayed such that it fits in the specified window maintaining its
aspect ratio. The image is shrunk or expanded as required. The command
has optionally four arguments the x,y, coordinates of the top left corner and
bottom right corners of the displayed image. If the arguments are omitted then
the image is displayed centred on the screen.
e.g. fit, fit 100 100 1000 500. Instead of 2 x,y, pairs x1+y1+w*h can be used



shrink
As fit except that the image is not expanded if it is smaller than the window.
e.g. shrink, shrink 100 100 1000 500. Instead of 2 x,y, pairs x1+y1+w*h can
be used



warp
The image is displayed such that it fits in the specified window without
maintaining its aspect ratio. The image is shrunk or expanded as required.
The command has optionally four arguments the x,y, coordinates of the top
left corner and bottom right corners of the displayed image. If the arguments
are omitted then the image is warped to be displayed full screen.
e.g. warp, warp 100 100 1000 500, warp 100 100 1000 500 BICUBIC
Instead of 2 x,y, pairs x1+y1+w*h can be used

For fit, shrink and warp an optional filter, one of NEAREST, BILINEAR, BICUBIC,
ANTIALIAS can be specified as the fifth argument, see
http://effbot.org/imagingbook/image.htm
thumbnail and resize sections. If the argument is omitted NEAREST is used.
e.g.fit 100 100 1000 500 BICUBIC

Instead of 2 x,y, pairs x1+y1+w*h can be used

Page 48

Version 1.3.5a, 1 May 2018

5.4.5 Video Track
A track played by OMXPlayer. Pi Presents should play any track that OMXPlayer can
play (but see hardware requirements Section19). Video tracks can be paused with
the Pause Internal Operation. Videos can appear in a window, can have an image or
colour as a background which can be overlaid with text; Track Text is overlaid on a
per track basis, Show Text per show. The video itself cannot be overlaid with text
because of OMXPlayer limitations.

Field
Track Tab
Type
Title

Example

video
The Film

Track
Reference

Location
Thumbnail
Freeze at
Start

+/myvideos/film.
mp4
+/media/film
_tn.jpg
before-first-frame

Freeze at
End

Values

Displayed on a menu and in the editor
A label for the track - blank if the track is
included in a menu or mediashow. Non-blank if
the track is to be triggered from a symbolic name
or is special.
The filename of the track.
The optional filename of a thumbnail image to be
displayed by a menushow.
Freeze a video at the start of the track
 no – no freeze
 before-first-frame – the video is paused
before the first frame is shown
 after-first-frame - the video is paused
after the first frame is shown
To continue after the freeze use the ‘go’
command.
yes/no
If yes, the last frame of the track is displayed
when the track ends (the video is paused just
before its end). If no, the video ends normally.
If blank the value is taken from the show.

Video Player
Audio

local

hdmi/local/both/alsa. If blank then the value in
the parent show is used. (both is hdmi+local).

Video Player
Volume
Video Player
Options

0

Video
Window

original

Volume of video track (-60 -> 0 dB). If blank then
the value in the parent show is used.
Additional command line options for omxplayer.
If blank then the value in the parent show is
used.
A viewport in which to show the video. If blank
then the values are taken from the parent show.

-t 1

warp
warp 10 10 500
1000



original - use OMXPlayer default
behaviour

Page 49

Version 1.3.5a, 1 May 2018



warp - scale to the size of the screen
without maintaining aspect ratio

warp followed by two x,y, pairs (top left,
bottom right) - the viewport window. The
video is scaled to this size without
preserving the aspect ratio. Instead of 2
x,y, pairs x1+y1+w*h can be used
Use the Colour Chooser to select a colour which
will return a six digit hex number, or type in a
colour name.


Background
Colour

red

See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm.

Background
Image

+/images/back.jp
g

Display
Show
Background
Image

yes

Plugin
+/media/weather_
Configuration ny.cfg
File
Seamless
Loop

If blank then the value in the parent show is
used.
The filename of an optional image that is
displayed in the background, can be blank. The
video, Show Text and Track text is displayed
above the image. If blank then the value in the
parent show is used.
yes,no
yes - the background image of the parent show
is displayed if the track Background Image is
blank
no - the background image of the parent show is
not displayed
File which specifies the name of and parameters
for the Track Plugin
yes/no. yes enables the omxplayer –loop option
to repeat the track continuously. For
(art)liveshow Seamless Loop is always ‘no’.
An artmediashow with one track might perform
better than using Seamless Loop.

Pause
Timeout

Controls
Tab
Controls

5

myname null

Note: a looping track has no end.
seconds. If not blank and greater than 0 then a
paused track will automatically unpause after the
timeout.

Bindings of symbolic names to commands. The
bindings defined here for the track are merged
with and override bindings for the associated
show. See Section 8.1

Text Tab
See Image Track. Does not have Pause Text
Show

Page 50

Version 1.3.5a, 1 May 2018

Control Tab
See Image Track
Animation
Tab
See Image Track

5.4.5.1 Video Playout
The ‘freeze at start’ field set to ‘before first frame’ opens the way to use Pi Presents
as a simple video playout system. Some methods of achieving this are shown in the
pp_videoplayout_1p3 example (Section 3).
For full operation two displays are required, one display for the controller displaying
text and images and another (the RPi’s local HDMI display) for the videos. This can
be achieved by:


The controlling display is implemented using RealVNC and a virtual display
as described below.



Using two Pi displays, a HDMI display to show the videos and a DSI display
as the controlling display. ( This was suggested by a PP user)

Using RealVNC
 Follow the instructions here https://www.realvnc.com/docs/raspberrypi.html#raspberry-pi-setup to create a Virtual Desktop on a remote computer.
Run Pi Presents from this remote computer. Everything but the videos will be
displayed.


The videos will be displayed on the RPi’s monitor. They will be displayed
above the Pi’s native desktop. By adjusting Display Appearance and Panel
settings it is possible to make the desktop black. Unclutter removes the
cursor.

5.4.6 Audio Track
A track played by MPlayer. Pi Presents should play any audio track that MPlayer can
play. Sound can be directed to HDMI or analogue and to either of the analogue
speakers. Audio tracks can be paused with the Pause Command.
Audio tracks can have an associated display. The display can have a coloured or
image background; Track Text is overlaid on a per track basis, Show Text per show.
The audio track has enhanced duration control making it suitable as a 'dummy' track
for controlling animation or concurrent shows. It can have zero duration and run
without playing any media.

Page 51

Version 1.3.5a, 1 May 2018

Field
Track Tab
Type
Title

Example

audio
The Music

Track
Reference

Thumbnail
Location

Duration

+/media/sarena
me_tn.jpg
+/tracks/music.
mp3
5

Values

Displayed on a menu and in the editor
A label for the track – blank if the track is
included in a menu or mediashow. Non-blank if
the track is to be triggered from a symbolic
name or is special.
The optional filename of a thumbnail image to
be displayed by a menushow.
The filename of the track. The location is
optional. If blank the timing of the track is taken
from the Duration field which must not be blank.
Seconds.
If duration is blank then the track ends when
the audio file ends or is stopped. The track
must be stopped by the user if there is no audio
track.
If zero the Location field should be left blank so
no audio track is played. Animation and Show
Control are executed. Zero duration is aimed at
use of the track for show or animation control.
If greater than zero the ‘track’ ends at the
stated time. If a file has been specified in
Location the playing of the track may be cut
short or there may be period of silence after the
audio file. This is primarily aimed at Animation
and Show Control

Audio Player
Speaker
Audio Player
Audio
Audio Player
Volume
Audio Player
Options
Background
Colour

left
local
0

red

For (art)liveshow Duration is always Blank.
left/right/stereo. If blank then the value in the
parent show is used.
hdmi/local. If blank then the value in the parent
show is used.
Volume of audio track (-60 -> 0 dB). If blank
then the value in the parent show is used.
Additional command line options for mplayer. If
blank then the value in the parent show is used.
Use the Colour Chooser to select a colour
which will return a six digit hex number, or type
in a colour name.
See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm. ).

Background

+/images/back.j

If blank then the value in the parent show is
used.
The filename of an optional image that is

Page 52

Version 1.3.5a, 1 May 2018

Image

pg

Display Show
Background
Image

yes

Plugin
Configuration
File
Pause Timeout

+/media/weathe
r_ny.cfg

Controls Tab
Controls

displayed in the background. The video, Show
Text and Track text is displayed above the
image. If blank then the value in the parent
show is used.
yes,no
yes – the background image of the parent show
is displayed if the track Background Image is
blank
no – the background image of the parent show
is not displayed
File which specifies the name of and
parameters for the Track Plugin

5

seconds. If not blank and greater than 0 a
paused track will automatically unpause after
the timeout.

myname null

Bindings of symbolic names to commands. The
bindings defined here for the track are merged
with and override bindings for the associated
show. See Section 8.1

Text Tab
See Image Track
Show Control
Tab
See Image Track
Animation Tab
See Image Track

5.4.7 Web Tracks
Web tracks are rendered by the Webkit based uzbl browser.
You will have installed the uzbl browser when installing Pi Presents. You can use it in
from the desktop like an ordinary program.
Web pages can be played from the internet or from the local file system. They can
appear in a window or be fullscreen, can have an image or colour as a background
and Track and Show Text. Track Text is overlaid on a per track basis, Show Text per
show.
The integration of uzbl into Pi Presents is not as good as the other players; it is best
used in non-interactive displays:


The browser is loaded each time a web track is played; this can take up to 15
seconds and is not properly handshaked with Pi Presents. If you want to
display a succession of web pages the Web Player in Pi Presents has a
Browser Command script which allows a sequence of web pages to be
displayed, with optional looping.

Page 53

Version 1.3.5a, 1 May 2018



Unlike other players, when the browser is in use ‘focus’ is on the browser
window and not on Pi Presents. This means that keyboard inputs are sent to
uzbl and not to Pi Presents until the Pi Presents window is clicked on. GPIO
inputs are not affected.



The browser window has scrollbars and title bar. Use of the browser affects
the display of the task bar. Section 5.4.7.2 describes how to correct these.

Field
Track Tab
Type
Title
Track
Reference

Location

Thumbnail
Duration

Example

web
Displayed on a menu and in the editor
A label for the track - blank if the track is to be
included in a menu or mediashow. Non-blank if
the track is to be triggered from a symbolic name
or is special.
The filename of the track:
www.google.co.uk
 an internet url
 a full pathname to a file
+/media/mywebpa
 a relative path to a file located under
ge.html
pp_home
+/media/sarenam
e_tn.jpg
5

Web Window warp
warp 10 100 200
700

Background
Image

Values

+/media/image.jp
g

The optional filename of a thumbnail image to be
displayed by a menushow.
Seconds. If 0 then the web page is displayed
until terminated by user input. If blank then the
value in the parent show is used.
A viewport in which to show the web page. If
blank then the value in the parent show is used
otherwise:


warp - scale to the size of the screen
without maintaining aspect ration



warp followed by two x,y, pairs (top left,
bottom right) - the viewport window. The
web page is scaled to this size without
preserving the aspect ratio. Instead of 2
x,y, pairs x1+y1+w*h can be used

The file name of an image which is used as the
background for the web page. If blank then the
value in the parent show is used.

Page 54

Version 1.3.5a, 1 May 2018

Field
Display
Show
Background
Image

Example
yes

Background
Colour

Plugin
+/media/weather_
Configuration ny.cfg
File

Values
yes,no
yes - the background image of the parent show
is displayed if the track Background Image is
blank
no - the background image of the parent show is
not displayed
Use the Colour Chooser to select a colour which
will return a six digit hex number, or type in a
colour name.
See http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
If blank then the value in the parent show is
used.
File which specifies the name of and parameters
for the Track Plugin

Text Tab
See Image Track. No Pause text
Browser
Commands
Tab
Browser
Commands

wait 10
refresh

Commands which load URL’s etc. See Section
5.4.7.1

Controls
Tab
Controls

myname null

Bindings of symbolic names to commands. The
bindings defined here for the track are merged
with and override bindings for the associated
show. See Section 8.1

Text Tab
See Image Track
Show
Control Tab
See Image Track
Animation
Tab
See Image Track
5.4.7.1 Browser Commands
The Browser commands field contains 0 or more browser commands. Each
command is on a new line. Some commands have an argument which is separated
from the command by a space
Command

Description

uzbl Command
used

Page 55

Version 1.3.5a, 1 May 2018

load 

refresh
wait 
exit

loop

uzbl 

Load the web page specified by .
 may be:
 an internet URI
 a full pathname to a file
 a relative path to a file located under
pp_home preceeded by +
refresh the currently loaded web page
wait  seconds
Normally the script loops after the last
command is executed. Exit, as the last
command, will end playing of the track.
A single loop command is allowed. If a loop
command is present execution will resume
here after the last command of the script.
Execute a uzbl browser command. The
commands are defined here:

uri

reload_ign_cache
-

-

http://www.uzbl.org/readme.php
 is the uzbl command together with its
arguments.
These commands will allow tailoring of the
display of individual web pages
Example: repeating two web pages. Looping will continue until the track duration is
exceeded.
wait 20
load www.google.co.uk
wait 20
load www.museumoftechnology.org.uk
Example: display two pages then exit to the next track.
wait 20
load www.google.co.uk
wait 20
load www.museumoftechnology.org.uk
wait 20
exit
Example: Refresh the initially loaded web page at 20 second intervals
wait 20
refresh

5.4.7.2 Full screen Integrated Browser Displays
Out of the box uzbl will show a title bar. To remove this, edit the file
/home/pi/.config/openbox/lxde-rc.xml to include the following just before the
statement 

no

Page 56

Version 1.3.5a, 1 May 2018


A reboot of the Pi is necessary for the edit to take effect. NOTE: This requires
confirmation if using a Raspbian release of 25/12/2014 or later (new UI).
When the browser is displayed the underlying Pi Presents window changes to reveal
the task bar. To correct this, adjust the Taskbar and minimize it:






Right click on the Taskbar and select Panel Setting
Select the Appearance Tab. Select Solid colour and, choose black with 100%
opacity.
Select the Advanced Tab
Set 'minimise panel when not in use' to On
Set 'Size when minimized' to 2 pixels

Scrollbars are displayed when the content of a web page is larger than the window.
These can be removed as described here. (not tested)
http://www.uzbl.org/wiki/hide-scrollbars
Alternatively use the uzbl zoom_out command in a Browser Command script to
adjust the size of the page so scrollbars are not required.

5.4.8 Message Tracks
Message tracks display text against a coloured background or optional image. They
do not need a media file to be specified as the text is contained in the Message Text
field.
Field
Track Tab
Type
Title

Example

Values

message
A Message

Displayed on a menu and in the editor

Message Text

Welcome

A label for the track - blank if the track is
included in a menu or mediashow. Non-blank if
the track is to be triggered from a symbolic name
or is special.
The text to be displayed.

Thumbnail

+/media/sarena
me_tn.jpg
5

Track
Reference

Duration

Text Font

Text Colour

Helvetica 30
bold

white

The optional filename of a thumbnail image to be
displayed by a menushow.
Seconds. If 0 then message is displayed until
terminated by user input. If blank then the value
in the parent show is used.
Use the Font Chooser to select a font, or type
one in:
See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
Use the Colour Chooser to select a colour which
will return a six digit hex number, or type in a

Page 57

Version 1.3.5a, 1 May 2018

colour name.

Justification
Message x
Position

left
100

Message y
Position

500

Background
Colour

red

Background
Image

+/images/back.j
pg

Display Show
Background
Image

yes

Plugin
Configuration
File

+/media/weather
_ny.cfg

Controls Tab
Controls

myname play
track34

See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
left/center/right. Text justification.
If blank then the message is centred in the
screen.
If non-blank the distance of the left end of the
text from the left of the screen (pixels)
If Message x Position is specified then distance
of the top of the text from the top of the screen
(pixels)
If blank then the message is centred in the
screen.
Use the Colour Chooser to select a colour which
will return a six digit hex number, or type in a
colour name.
See: http://effbot.org/tkinterbook/tkinter-widgetstyling.htm
If blank then the value in the parent show is
used.
The filename of an optional image that is
displayed instead of a plain background. The
message is displayed on top of the image.
If blank then the value in the parent show is
used.
yes,no
yes - the background image of the parent show
is displayed if the track Background Image is
blank
no - the background image of the parent show is
not displayed
File which specifies the name of and parameters
for the Track Plugin

Bindings of symbolic names to commands. The
bindings defined here for the track are merged
with and override bindings for the associated
show. See Section 8.1

Text Tab
See Image Track. Does not have Pause Text
Show Control
Tab
See Image Track
Animation
Tab
See Image Track

Page 58

Version 1.3.5a, 1 May 2018

5.4.9 Show Track
A show can be a track in another show. Uses might be:
 A mediashow made up of smaller mediashows
 A menu of mediashows
 Menus with sub-menus
 A Liveshow run from a Mediashow which provides an initial screen.
Field
Type
Title

Example
show
My Other Show

Track
Reference

Show to Run myothershow
Thumbnail

+/media/sarename_t
n.jpg

Values
Displayed on a menu and in the editor
A label for the track - blank if the track is
included in a menu or mediashow. Non-blank
if the track is to be triggered from a symbolic
name or is special.
Show Reference of the show to be run
The optional filename of a thumbnail image to
be displayed by a menushow.

5.4.10 Menu Track
A menushow needs an associated menu track in its medialist which defines the
layout of the menu. A menu track provides it. Its Track Reference should appear in
the Menu Track field of a Menu show.
The menu formats that can be produced are extensive:


Display, thumbnails, bullets or Titles in many combinations



Align the menu vertically or horizontally



Create multi-column, multi-row menus



Alter the separation, colours and font of the menu items

Page 59

Version 1.3.5a, 1 May 2018

ICON
Text
Height

TEXT

Icon Width

Text Width

Vertical
Separation

ICON
Icon
Height

TEXT
Stipple
Background
Padding
Horizontal
Padding

ENTRY

STIPPLE
BACKGROUND

Menu Geometry Definitions

Field

Example

Use

Track Tab
Type
Title

menu
Menu Track

Displayed on a menu and in the editor

Track Reference
Background
Colour
Background
Image
Display Show
Background
Image

menu-track

Entry Font

Helvetica 30
bold

Entry Colour

white

Selected Entry
Colour
Plugin
Configuration File

+/media/image.j
pg
yes

A label for the track.
see mediashow - Background Colour for
menu
If not blank The file name of an image which
is used as the background for the menu.
yes,no
yes - the background image of the parent
show is displayed if the track Background
Image is blank
no - the background image of the parent show
is not displayed
Use the Font Chooser to select a font, or type
one in:
see: http://effbot.org/tkinterbook/tkinterwidget-styling.htm
Use the Colour Chooser to select a colour
which will return a six digit hex number, or
type in a colour name.

red

see: http://effbot.org/tkinterbook/tkinterwidget-styling.htm
colour when the entry selected

+/media/krttime.cfg

File which specifies the name and parameters
of the Track Plugin.

Page 60

Version 1.3.5a, 1 May 2018

Geometry Tab
Menu Window

fullscreen, one or two pairs of x,y, coordinates
fields are separated by spaces.


fullscreen - the menu is displayed full
screen.



one x,y, coordinate - the menu's top
left corner

two x,y, coordinates - the second pair
of coordinates specifies the bottom
right corner of a bounding box for the
menu. Instead of 2 x,y, pairs
x1+y1+w*h can be used
vertical, horizontal - the direction of laying out
and traversing the menu.
If Direction = vertical the number of rows in
the menu.
If Direction = horizontal the number of
columns in the menu.
thumbnail,bullet,none


Direction

vertical

Rows

5

Columns

1

Icon Mode

Text Mode



thumbnail - if the track has a thumbnail
then this is displayed otherwise,
if it is an image track the image is
warped to the icon size otherwise
a thumbnails is displayed which
depends on the type of track.



bullet- the icon specified in Bullet is
displayed.



none - the menu displays only text .

none,right,below


right - the text is displayed to the right
of the icon

below - the text is displayed below the
icon
The filename of the bullet. Absolute or
relative.
Width of the icon. Images will be warped to fit
into the defined size.
Height of the icon. Images will be warped to fit
into the defined size.
When Text Mode is Right the horizontal
distance between the Icon and the Text
When Text Mode is Below the vertical
distance between the Icon and the Text


Bullet
Icon Width

+/media/bullet.jp
g
100

Icon Height

100

Horizontal
Padding
Vertical Padding

10
10

Page 61

Version 1.3.5a, 1 May 2018

Text Width

200

Text Height

50

Horizontal
Separation
Vertical
Separation
Stipple
Background
Stipple
Background
Padding
Guidelines

20
20

Width of the text. The text is wrapped to fit
into this width.
Height of the text. Used to calculate the
positions of entries. However text is not
constrained to fit into this height. The user
must adjust he font size to suit.
The distance between the bottom of one
menu entry and the top of the next.
The distance between the right edge of one
menu entry and the left edge of the next.
yes/no. Display a stippled rectangle
decoration behind the menu entry.
The distance that the stipple background
extends from the menu entry.
never,auto,always
If Menu Window has two x,y pairs then
coloured rectangles are displayed on the
screen to help design the menu.
 White rectangles are the menu entry.
 The Blue rectangle is the calculated
extent of the menu.
 The Red rectangle is the bounding box
as defined by Menu Window
Auto displays the rectangles only when the
extent of the menu is outside the bounding
box.

Text Tab
Track Text
Track Text Font

This menu
Helvetica 30
bold

Multi-line text
Use the Font Chooser to select a font, or type
one in:

white

See: http://effbot.org/tkinterbook/tkinterwidget-styling.htm
Use the Colour Chooser to select a colour
which will return a six digit hex number, or
type in a colour name.

Track Text x

100

See: http://effbot.org/tkinterbook/tkinterwidget-styling.htm
distance of the start of the text from the left of
the screen (pixels) If blank then the message
is centred in the screen.

Track Text y

800

distance of the top of the text from the top of
the screen (pixels) If blank then the message
is centred in the screen.

Track Text justify

right

left, right, center – Justify lines in a block of
text

Track Text
Colour

Page 62

Version 1.3.5a, 1 May 2018

Hint Text

To Play, press
return

Hint Font

Helvetica 30
bold

Menus do not have children; the hint is a
general purpose field which might be used for
displaying instructions.
Use the Font Chooser to select a font, or type
one in:

white

See: http://effbot.org/tkinterbook/tkinterwidget-styling.htm
Use the Colour Chooser to select a colour
which will return a six digit hex number, or
type in a colour name.

Hint x

100

See: http://effbot.org/tkinterbook/tkinterwidget-styling.htm
distance of the start of the text from the left of
the screen (pixels) If blank then the message
is centred in the screen.

Hint y

800

distance of the top of the text from the top of
the screen (pixels) If blank then the message
is centred in the screen.

Hint justify

right

left, right, center – Justify lines in a block of
text

Controls Tab
Controls

myname null

Bindings of symbolic names to commands.
The bindings defined here for the track are
merged with and override bindings for the
associated show. See Section 8.1

Hint Colour

Show Control
Tab
See Image Track
Animation Tab
See Image Track

6 Black Box Operation
There are a number of things to set up to make Pi Presents into a full screen, auto
starting, GPIO controlled application. You do not need to use them all.

6.1 Command Line Options
python pipresents.py -h will show the command line options

Options
-p --profile 

Name of the profile to be used. e.g. pp_mediashow_1p3

-b --noblank

If this is not specified then an error message will be shown.
Disable screen blanking.

Page 63

Version 1.3.5a, 1 May 2018

-f --fullscreen

Run Pi Presents in full screen mode.

-o --home 

Location of the Pi Presents 'data home' directory
e.g. /media/pi/USBSTICK or /home/pi/my_data
If this option is not specified it defaults to the users home
directory.

-d –debug

Fatal (system) errors and Profile errors produce alerts on the
display. On acknowledgment Pi Presents exits because it
cannot continue.
Profile errors are errors detected in the profile.
Fatal errors are errors in the Pi Presents software.
These could be a side effect of an undetected Profile
error.
The pp_editor validate menu option will detect many Profile
Errors. Tell me about ones that are not detected by the editor.



Log output is also displayed in the terminal window if Pi
Presents is started from one, and is also reported in the file
/pipresents/pp_log/pp_log.txt
If the –d option is not used then the Log output is Fatal Errors,
Profile errors, and Warnings. if the –d option is used then log
output also includes a log of the operation of Pi Presents
suitable for debugging profiles.
Warnings are detected intermittent problems that Pi Presents
can recover from. Most of them are due to random crashes by
omxplayer.

-d –debug 
-v –validate
-l –liveshow 

Using the debug option with  gives finer control of logging,
see Section 21
Not supported,use the editor.
Liveshow tracks are always played from the directory
pp_live_tracks in the data home specified in the –o option
defaulting to
/home/pi/pp_home/pp_live_tracks
If the –l option contains a directory path this is used as a
second source for liveshow tracks.
e.g. /home/pi/mylivetracks

-s –screensize


This command line option allows shows to be developed using
a monitor which has a different pixel dimensions than the target
monitor.  is width*height where width and height are
positive integers. See Section 4.2.5 for use of this option.

Page 64

Version 1.3.5a, 1 May 2018

--manager
-n --nonetwork

Used by Manager for Pi Presents to disable terminal messages.
Should not be used by users.
When the Time of Day Scheduling is required and this option is
omitted Pi Presents will wait up to 5 seconds for the LAN
(network) to be available. If the option is included with no
argument then it will not wait, this is useful of you have a RTC
and do not require ntp time.
Non-intuitively if you need to wait for a different time then
use --nonetwork n to wait n seconds.

6.2 Specify a Profile
The --profile (-p) command line option specifies the profile to use. This is the name of
the profile directory in the pp_profiles directory. If the option is omitted an error will be
produced.
The prefix pp_ means nothing special other than denoting files provided by the
developer.

6.3 Specify a Home Directory
The --home (-o) command line option specifies the location of Pi Presents data
home. If the option is omitted it will default to the users home directory.
USB sticks can be used to hold profiles and media. They will be assigned mount
points in the /media directory.
e.g. /media/pi/KINGSTON
Raspbian will auto mount USB sticks if they are present at power on, or plugged in
afterwards. If Pi Presents is started at power on it takes up to 10 seconds for the
drive to be mounted; Pi Presents allows for this.
Raspbian will compute the mount point from the name of the drive on the stick. If
preparing the USB Stick on a Windows machines it appears Windows converts all
entered drive names to upper case.

6.4 Using GPIO to Control Pi Presents
GPIO control is enabled when a gpio.cfg file is present in the /pp_io_config directory
in a profile.
sudo need not (and must not) be used.
If the gpo.cfg file from /pipresents/pp_resources/pp_templates is copied to a profile,
then pins of the P1 connector are bound to the following symbolic names. These
names are used in examples by mediashows, menus and special commands. The
bindings can be modified as described in Section 14.2.1
Pin of P1
connector
P1-15

Symbolic Name
pp-down

Command
down

Page 65

Version 1.3.5a, 1 May 2018

P1-16
P1-18
P1-22
P1-7
P1-11

pp-up
pp-play
pp-pause
pp-stop
PIR

P1-12

pp-shutdownnow

up
play.
pause
stop
Used as a mediashow Start Trigger in
some examples
Configured in gpio.cfg such that a press
for 5 seconds is required. Closes Pi
Presents and shuts down the Pi.

Using this file the GPIO pins are configured as edge triggered inputs with internal
pull-up resistors and require the following device characteristics:


Push buttons should be mechanical, push to make (normally open), and be
connected between the GPIO pin and 0 volts. The contact will close when the
button is pressed so it is set to falling edge trigger.



I have based the PIR entry on PIR’s used in UK burglar alarms. These have
Normally Closed relay contacts which should be connected between the
GPIO pin and 0 volts. The relay contact will open when movement is detected
so the entry is set to rising edge trigger and, because it is a relay contact, the
a pull up resistor is configured to avoid radio signals causing false triggering.

Inputs can be changed from normally open to normally closed and vice versa by
changing the edge which is used for triggering as described in Section 14.2.1
A 330 ohm resistor is series with the button or PIR is recommended to protect the Pi
should the inputs inadvertently be used as outputs.
GPIO Pin ----- 330R ----- contact ---- 0 volts
Be very careful not to connect a GPIO pin to the +5volt pin; it is likely to fry your Pi
There is software contact de-bouncing which is set with a small hysteresis. If you
have problems with contact bounce increase the THRESHOLD of the appropriate pin
by modifying gpio.cfg (See Section 14.2.1).

6.5 Disable Screen Blanking
To disable screen blanking you must first install xset which is part of the x server
utilities package, this should already be installed in Raspbian.
sudo apt-get install x11-xserver-utils
You can then use the --noblank command option to disable screen blanking.

6.6 Start Pi Presents when Power is applied to the Pi
This will function only if you have set 'boot to desktop' using raspi-config.

Page 66

Version 1.3.5a, 1 May 2018



If you are using Raspbian Jessie edit the file
/home/pi/.config/lxsession/LXDE-pi/autostart
Note: The directory .config is already present in the image but you will need to
select 'Show Hidden Files' in the File Manager to see it.
Add the following line below the last line to start Pi Presents with the required
options:

/usr/bin/python /home/pi/pipresents/pipresents.py -o /home/pi -p
myprofile

6.7 Shutdown the Raspberry Pi from the GPIO
Press the Shutdown button for more than 5 seconds. Pi Presents will exit and safely
shut down the Pi.
The RPi can also be shut down immediately in other ways as described in Section 7

6.8 Controlling the Monitor
Show control commands (Section 8.2.3) can be used to control the power to a
monitor
Command
monitor on
monitor off

Action
Sends the vcgencmd display_power 1 command to the
monitor
Sends the vcgencmd display_power 0 command to the
monitor

7 Exiting Pi Presents and Shutdown of the RPi
There are many ways to exit PI Presents and shut down the Pi from Pi Presents:


Bind a key, pin or click area to the internally defined symbolic name ppshutdownnow as described in Section 14.2. An input event with this symbolic
name will cause the Pi to shut down immediately. For gpio the appropriate
pin can also be configured such that the event is not sent unless the pin is
held in one state for a period of time. (See below)



Use the Show control command 'shutdownnow' to shut down the Pi
immediately from within a show, or reboot to reboot the RPi, See Section 8.2



Use the Time of Day Scheduler



Remotely via an OSC command

There are many ways to exit Pi Presents

Page 67

Version 1.3.5a, 1 May 2018



Bind a key, GPIO pin, or click area to the internally defined symbolic name
pp-exitpipresents. (see below)



Use the Show control 'exitpipresents' command to exit Pi Presents from within
a show.



Use the Time of Day Scheduler



Remotely via an OSC command



When developing use Ctrl+Break, Alt+F4 or the Close icon on the Pi Presents
window

Symbolic name
pp-exitpipresents
pp-shutdownnow

Use
Exits Pi Presents having closed all shows.
Exits Pi Presents and the safely shuts down the
Raspberry Pi.

8 Controlling Shows
8.1 Controlling Track Movement in Individual Shows
Control of an individual show uses commands such as up, down, play and stop call
return to control the movement between individual tracks in a show. There needs to
be some method of connecting these commands to the physical input devices such
as keys and GPIO buttons. This is a two stage ‘binding’ or association process:


In configuration files associated with a particular input device (e.g keys.cfg,
gpio.cfg) the physical keys are bound to symbolic names. e.g. for gpio
falling_name = myname



In the Controls field of shows and tracks the symbolic name is bound to the
command e.g. myname up.

To re-iterate in more technical detail. In Pi Presents the physical devices that are
employed are separated from the core operations on shows and tracks. The physical
devices have drivers which take the physical inputs and produce input events which
are identified by symbolic names. The shows and tracks receive these input
events and convert them into the Commands that control the show.
The two associations (bindings) take place in:


Configuration files associated with the drivers, e.g. gpio.cfg. These define
which inputs produce input events and their symbolic names.



The Controls field in shows and tracks. These associate symbolic names of
input events with the Commands, Run-Time Controls, and Triggers used by
shows and tracks.

Page 68

Version 1.3.5a, 1 May 2018

Each type of show has a set of commands which are defined in the section
describing the show. Mediashows and Menus have commands such as play, pause,
up and stop. Hyperlinkshows have commands such as call and return.
In addition to Commands, Mediashows and Liveshows have Triggers which are used
in some shows as an alternative to commands. These are generally used by gpio to
trigger simple responses to buttons or PIR’s
All shows also have Run-Time controls which are used by tracks when they are
running to allow user control of volume etc.
For outputs a similar system is employed. Animation commands include symbolic
names. Output device drivers use configuration files such as gpio.cfg to convert the
symbolic names to physical outputs.
Controls and Subshows
A show can have sub-shows; input events are passed down from show to subshow
so they affect the currently lowest level show and its tracks.
A top level show is started when Pi presents starts, from Show Control commands,
from the time of day scheduler or remotely via OSC; it has no parent. In version 1.2
the bindings in the Controls field of a top level show were inherited by its subshows.
In version 1.3 this is not the case and each show must have its own set of Control
bindings.

8.2 Opening and Closing Shows and Show Control
8.2.1 Opening and Closing Shows
There are four methods to open and close shows:


Start one or more shows by including their show references in the Start
Shows field of the Start Show. All shows specified in the Start Shows field of
the Start Show will be run when Pi Presents starts.



Open or close shows using the Time of Day Scheduler.



Use a Show Control command in the Show Control field of a track to open or
close a show e.g.
open myothershow
close myothershow



Open and Close a show remotely using the Open Sound Control protocol

Shows opened by one method can be closed by any other method.

Page 69

Version 1.3.5a, 1 May 2018

Only one instance of a show can be running at a time. Attempts to open a show that
is already running will be ignored.
It is possible to start Pi Presents with no shows running. Additionally if all shows are
closed Pi Presents will continue running with a blank black screen to allow remote
control or time of day scheduler to open further shows.
Show Control Commands are placed in the Show Control fields of tracks.
Command
open 
close 
closeall
openexclusive


Use
Opens the specified show. The command will be ignored
if the show is already running
Closes the specified show. The command is ignored of
the show is not running.
Closes all shows. Pi Presents is still running.
Closes all shows (including the show that the command
was sent from, if applicable) and opens the specified
show.

8.2.2 Sending Events between Shows
The Event show control command allows a show to generate input events which are
sent to all running shows. As for user generated events in Section 8.1 the shows and
tracks receive these input events and convert them into the Commands that control
the show/track.
Command
event 

Use
send and input event with the symbolic name to all
running shows.

8.2.3 Other Uses of Show Controls
Other Uses are:


Closing Pi Presents , shutdown or reboot the RPi (Section 7).



Sending remote control commands using the OSC protocol (Section 15)



Control the power of the monitor using the vcgencmd commands (Section
6.8)



Controlling counters (Section 12)

8.3 Time Of Day Scheduler
The time of day scheduler opens and closes shows at a specified time and date. It
will also trigger any other Show Control command at a specified time and date.. The
scheduler is enabled and controlled by a profile using the Schedule tab in the Start
Show and the Schedule tab in every other show.

Page 70

Version 1.3.5a, 1 May 2018

The Schedule tab of the Start Show allows the Time of day scheduler to be enabled.
It also controls functions of Pi Presents common to all shows replacing the pp-core
section in the legacy .json file.
Every other show in a profile has a Schedule Tab which controls the schedule for that
show. Each has 4 fields - everyday, weekday, monthday and specialday. Each has
zero or more match criteria (day) with an associated list of times (times) There is an
example in the example profile pp_timeofday_1p3. The aim is to eliminate the need
to type in the date of every day of the year, instead everyday is used as a base and
then exceptions to thos are added either for days, of the week, days of the month, or
special days.
Pi Presents prepares a list of tasks for today when Pi Presents is started and at every
midnight. For each show it considers each field in the order below and each set of
day/time lines, matching today’s date with the match criteria:





everyday always matches. (the day line must have the word everyday)
weekday – matches if today’s day of the week is in the list of weekdays
monthday – matches if today’s day of the month is in the list of numbers
specialday – matches if the todays date is in the list of dates

When a match occurs the times are remembered and their associated open and
close commands are remembered. If a later set of day/time lines or field also
matches it overrides the previous matches for the specified show. A set of day/time
lines with a day line but an empty list of times can be used to delete times from a
previous match. When all matches are done the list of tasks for today is prepared by
sorting the times.
Times can be hh:mm:ss or hh:mm using a 24 hour clock. Commands are open and
close and are associated with the show-ref of the show.
The Start Show is different; it is used to control Pi Presents. The matching process is
the same and a schedule for today is produced. The commands that can be used
only in this section are all the Show Commands with parameters. (It is possible to
use open and close show commands in this section specifying the show-ref instead
of in individual shows.)
If Pi Presents is started in the middle of a day then it will try to catch up by going
through today’s list of tasks for each show (not for the Start show) and starting the
show immediately should the show need to be running at the current time. There is
no catchup for the Start show, all previous tasks for the day are just ignored.
Gotchas:


When using the Time of Day scheduler it is best not to include shows in the
Start Shows field of the Schedule Tab of the Start Show or to use Show
Control commands to open or close shows. These are not taken account of
by catch up and can result in unexpected results.



Any commands in the Schedule tab of the Start show are not subject to catch
up

Page 71

Version 1.3.5a, 1 May 2018



The scheduler should be time zone agnostic. Be careful with shows that run
across midnight. I have not investigated the effect of changing to/from
Daylight Saving Time.

There is a logging option specifically for testing the schedule (See Section 6.1). This
shows time as Time of Day and events that are of interest.
To test the schedule with a real clock is difficult thus the Simulate Time tab in the
Start Show can be used to enable a simulated time for exercising the schedule (and
only the schedule). If enabled then the simulated time you wish to start the test
should be specified. The date need not have consistent day/month/year as each of
the match criteria are independent.
The scheduler requires that time of day be available when Pi Presents starts; to this
end Pi Presents waits for up to 5 seconds for the LAN network and hence for time
from a ntp server to be available. This primarily allows wifi to connect. You can
control this wait with the –nonetwork command line option.

8.4 Concurrent Shows
Pi Presents can run two or more shows concurrently. The shows appear to run in
parallel. All concurrent shows use the same screen area but the Show Canvas field
of a show can help to separate shows to different parts of a screen. There are some
limitations on concurrent shows due to the power of the RPi and limitations of the
operating system. Some uses of concurrent shows:


Providing a background audio track to a slideshow.
Use two mediashows, one with a manually controlled slideshow and the other
with the audio tracks. The latter will need the controls disabled using Disable
Controls if there is any customer interaction with the former.



Using a single display for a number of independent shows, maybe a
slideshow to the left, a user controlled menu to the right and a strip showing
the current time and date at the top.



Being really thrifty and doing two completely different tasks with the same Pi,
perhaps a slideshow in the Visitor Reception with Child show facilities, and a
dummy talking in a museum exhibit triggered by a PIR using a single shot
mediashow.

8.4.1 Control with Concurrent Shows
Pi Presents can run two or more shows concurrently. The concurrent shows appear
to run in parallel and Input Events are passed to all concurrent shows. This is
essential but if not managed carefully can lead to some undesirable effects. Most of
the common situations can however be addressed by Disable Controls.
For example, if running a manually controlled mediashow displaying images in
parallel with a mediashow providing background music; using Up and Down to move

Page 72

Version 1.3.5a, 1 May 2018

through the images should not skip audio tracks. The solution is to set Disable
Controls = Yes in the audio show.
More complicated scenarios can be addressed by editing or deleting the bindings of
the Controls for a specific show. Using the Controls field of a show a Command can
be bound to a different symbolic name for each show and hence be triggered by a
different input. Alternatively individual Commands can be deleted for that show.

8.4.2 Limitations on Concurrency
Concurrent shows have some limitations due to limits built into Linux, MPlayer and
OMXPlayer:


If two show display overlapping images or text the last object to be displayed
will overlay older objects.



Video tracks will always overlay images and text



If two video tracks overlap then there is likely to be flickering.



If there is more than one audio or video track to be played that might overlap
in time then local audio must be used. This is because omxplayer does not
use the alsa mixer. The problem is particularly severe for the artmediashow
and artliveshow as the next track is loaded during the playing of the previous
track, not at its end. The problematic combinations are complex, the only safe
way is to direct all audio to the local headphone socket.



HD videos may stutter while an audio track is being played.



Animation outputs are delayed if they are coincident with the start of an audio
track or image. The output event will not be missed but will be delayed.



If CPU load is high omxplayer can take so long to load a video that it times
out.

9 Touchscreens and Soft Buttons
9.1 Controlling Shows with a Touchscreen
All types of show can be controlled by touchscreens and use soft buttons.
Touchscreens or soft buttons are almost essential for Hyperlinkshows, a useful
alternative to gpio buttons in Radiobuttonshows and can be used to replace cursor or
gpio button control in mediashows, liveshows and menus.


Click Areas
Click areas are aimed at touchscreens. A ‘click area’ is an area of the screen
which is mouse click sensitive. Although they are called ‘click areas’ they can
best be used with touchscreens and might better be called touch areas.

Page 73

Version 1.3.5a, 1 May 2018

Touching the area of a touchscreen or clicking with a mouse in the area will
cause an input event.
Optionally associated with a click area is an image, maybe of a button, which
is displayed when the click area is enabled. Alternatively a click area can be
transparent and the area defined as a polygon to encompass the shape of the
object displayed as part of the background image.


Soft Buttons
Soft buttons are a poor man’s touchscreen. They were used a lot in real time
control applications before touchscreens were developed.
Soft buttons are a row of unmarked keys or buttons arranged along the edges
of a display screen. The legends for the buttons are software controlled and
appear adjacent to the button on the edge of the display area of the screen.
Thus different buttons and legends can be applied to each track of a
Hyperlinkshow.

Pi Presents allows both of these techniques to be used to control any type of show.

9.2 Click Areas
In its screen.cfg file Pi Presents allows the definition of click areas. These are
polygonal areas of the screen which are touch or mouse click sensitive. A touch or
click will produce an input event identified by a symbolic name.
Click areas can have text, coloured backgrounds, outlines and images.
The presence of a screen.cfg file in the /pp_io_config directory in a profile enables
click areas and contains the click areas to be used for every show and track in the
application. The click areas to be displayed on each track and show are determined
by the symbolic names in the Controls field of the track or show. Configuration of
Click Areas is described in Section 14.2.7.

9.3 Soft Buttons
Soft buttons need both a gpio button to be associated with the required Command as
described elsewhere and a passive on screen legend for the button configured as
described here. The passive legend must appear only on the track that requires it so
it needs to be included in screen.cfg as a click area and included in the Controls field
of the track with a special command to disable it.
For example to set up a soft button to control movement from a page in a
Hyperlinkshow:


Use the symbolic name bound to a gpio button in the Controls field of the
Track.
my-button call pig-video

Page 74

Version 1.3.5a, 1 May 2018



Mount the button next to the screen and set up a ‘click area’ in screen.cfg,
with the symbolic name my-button-legend. Specify its ‘points’ such that it is
displayed next to the button. This click area will display the legend, say ‘See a
Pig’, but must not be clickable.



To make the click area appear when the track is being displayed but for it not
to respond to clicks use it in the Controls Field of the track and give it the
command ‘no-command’
my-button-legend no-command

10 Run-Time Commands
OMXPlayer, Mplayer and the uzbl browser have a number of run-time commands
which are defined for omxplayer and mplayer in:
https://github.com/popcornmix/omxplayer
The following mapping is used by Pi Presents (see pp_omxdriver.py line 60)
KEY_MAP = {'<':3,'>':4,'z':5,'j':6,'k':7,'i':8,'o':9,'n':10,'m':11,'s':12,
'-': 17, '+': 18, '=':18,'x':30,'w':31}
http://www.mplayerhq.hu/DOCS/man/en/mplayer.1.html#INTERACTIVE%20CONTR
OL
Only operations with a single character from the list of operations in the references
are allowed. The single character must be preceded by omx- or mplay- respectively.
Multi-character operations are not currently supported.
For example:
videovolup omx-+
videovoldown omx-included in the controls field of a show or track adds volume control to omxplayer.
videovolup is a symbolic name which can be bound to a key, gpio pin etc. Keyboard
keys naturally have repeats; for GPIO pins gpio.cfg can enable repeating for buttons.
For the uzbl browser used to display web tracks the commands useable for run-time
controls are defined here:
http://www.uzbl.org/readme.php
The command strings should be preceded by uzblFor example:
largerweb = uzbl-zoom_in
will make the content of the browser larger.

Page 75

Version 1.3.5a, 1 May 2018

11 Providing Dynamic Content in a Liveshow
Pi Presents was not intended for the dynamic supply of media however by popular
demand I have included a facility where a 'Liveshow' can play a set of tracks which
change during the running of the show .
The New> Liveshow template and New>Artliveshow are working Liveshows. The
tracks to be played should be placed in the Live Tracks Directory1 which out of the
box is /home/pi/pp_home/pp_live_tracks
Liveshows play audio, video and image tracks. The media file types that a Liveshow
recognises are in the first few lines of the file pp_definitions.py.
The Pi Presents Manager Section 17 can upload or import tracks; alternatively
tracks could be ftp'ed into the Live Tracks Directory1 using Filezilla or some such.
Advanced Use
Using the -l command line option of Pi Presents it is possible to have a second
location containing live tracks; the Live Tracks Directory2. The location of this
directory is specified by the -l command line option. The files in the two live tracks
directories are combined and sorted by their leaf name.
The directory could be on a remote fileserver (I have not tried this). Alternatively the
complete profile for a show could be held on a remote fileserver.
From Version 1.3.1 concurrent shows are allowed hence it is necessary for allow
each liveshow to access its own directory. The liveshow profile now has two fields for
this purpose, Live Tracks Directory1 and Live Tracks Directory2. If these are not
blank their location overrides the default location.

12 Counters
Counters are intended for quizzes but could have other uses. All types of track have
facilities to create, set, increment, decrement and delete counters. Currently the
value of counters is displayable only by writing track plugins which requires a little
knowledge of Python (or some copy and paste of the examples).
Counter commands are stored in the ‘Show Control Begin’ and ‘Show Control End’
fields of tracks and shows. Counter commands are of the form:
counter [name] [command] [parameters]
The counter field must be present to differentiate counter commands from other
types of command in Show Control fields
The commands are:
command
set

parameters
name value

example
counter fred set 0

use
Create a counter
called name and

Page 76

Version 1.3.5a, 1 May 2018

inc

name value

counter fred inc 1

dec

name value

counter fred dec 2

delete

name

counter fred delete

set its value to
value. If the
counter already
exists just set its
value.
increment name by
value (which must
be positive)
decrement name
by value (which
must be positive)
delete the counter
name

Counters are stored in a Python dictionary called counters in the Python Class
CounterManager which is defined in the file pp_countermanager.py
There are two examples of track plugins which use methods in this class to display
counters, these are in /pipresents/pp_track_plugins:


krt_counters.py
This track plugin shows the use of all the display methods exposed by
CounterManager


get_counter(name) – return the value of counter name as a string



str_counters() – returns a string with the name/value of all currently
defined counters.



print_counters() – print the name/value of all currently defined counters to
the terminal window.

The example profile pp_counters_1p3 uses this plugin


krt_quiz.py
Used by the example profile pp_quiz_1p3 to provide its prettier output.

13 Animation Control
All types of track have facilities to control animation. Using commands included in the
'Animation at Beginning' and 'Animation at End' fields an external output can be
turned on or off synchronised with the start or end of tracks, with optional delay.
An example of animation commands is shown below.
animate at
beginning

Clear
Animation

1 out1 state on
2 out1 state off
1 out2 state on
6 out3 state on
no

Page 77

Version 1.3.5a, 1 May 2018

Animation at
End

0 out2 state off

A command has four or more fields separated by spaces and terminated with a
newline:





Delay - seconds as a positive integer or 0.
Symbolic Name - The name of the output as defined in the gpio.cfg file in the
profile (Section14.2.1).
Parameter Type
Parameter - 1 or more fields compatible with Parameter Type.

Commands in Animation at Beginning are executed at the beginning of a track and
Animation at End at the end of a track. When the commands are executed the
required commands are put in a queue for firing at the appropriate time. The time is
not affected by pausing a track.
Every command is offered to every active I/O plugin. If the Symbolic Name and
Parameter Type matches any of those implemented by the plugin then the command
will be executed using the provided parameters.
Animation commands in the queue are not forgotten at the end of a track so
animation can be extended over multiple tracks. A side effect of this is that it is
possible for an output to happen at the wrong time if the duration of a track is
indeterminate . If you want to avoid this and ensure outputs are in a defined state at
the end of a track set Animate Clear to yes. If yes then, before Animation at End is
executed, the queue will be cleared of those events that were commanded by the
track but not fired.

14 Input/Output (I/O) Plugins
In Pi Presents Input and Output is independent of the core execution of shows and
tracks. From version 1.3.3 developers can interface to their own input/output devices
by writing additional I/O plugins. These plugins have a standard API and will use
configuration files to enable and configure them.
An input plugin accepts an input from a physical device, pre-processes it and
produces an input event with a symbolic names, some also allow input values to be
accessed by track plugins. An output plugin takes output commands (e.g. out1 state
on) having a symbolic name and parameters which it uses to generate the physical
output.
I/O plugins are python modules that should be in the directory
/pipresents/pp_io_plugins. An I/O plugin needs to be configured with a .cfg file.
These files are stored in the /pp_io_config directory in a profile. There can be more
than one .cfg for a plugin, for example pp_inputdevicedriver.py may have a .cfg file
for each make of remote control.
Most I/O plugins have a standard API and standard .cfg files. There are currently I/O
plugins with standard configuration files and standard API for:
Device

Provided
Configuration

Direction

I/O Plugin

Use

Page 78

Version 1.3.5a, 1 May 2018

Tkinter
Keyboard

File
keys.cfg

Input

pp_kbddriver.py

GPIO

gpio.cfg

Input/Outp
ut

pp_gpiodriver.py

Input
Device

osmcremote.cf
g

Input

pp_inputdevicedriv
er.py

Serial
device

serialdriver.cfg

Input/Outp
ut

pp_serialdevicedriv
er.py

I2C devices

i2c.cfg

Input/Outp
ut

pp_i2cdriver.py

Interfaces with a
keyboard using
the Tkinter API,
not a totally
standard API
Interfaces the
GPIO general
purpose pins
using RPI.GPIO
Interfaces with a
specific remote
controls, keypads
etc. using evdev
Interface with
serial devices
usually using a
USB to RS232
convertor
Interfaces with
I2C devices

There are two I/O plugins that have a non-standard configuration file and a nonstandard API, however their elements are stored as above:
touchscreen

screen.cfg

Input

-

Enables touch/click
sensitive areas on a
touchscreen/monitor
and configures the look
of the touch sensitive
areas.

remote
control
using OSC

osc.cfg

Input/Output

-

Allows Pi Presents to
control or be controlled
by other units.
Configuration file is
generated using the
editor.

14.1 Enabling a Standard I/O Device
To enable an I/O device a configuration file must be placed in a /pp_io_config
directory in a profile. There are sample configuration files in
/pipresents/pp_resources/pp_templates which can be copied and edited. These files
also contain information, additional to that here, on how to use them.
When Pi Presents starts it will look in the /pp_io_config directory in the profile and will
use any .cfg files found there. It will then look in /pipresents/pp_io_config and will use
a .cfg files found there if a .cfg file with the same name has not been found in the
profile.

Page 79

Version 1.3.5a, 1 May 2018

Out of the box keys.cfg is present in /pipresents/pp_io_config so that the Tkinter
keyboard is enabled.
The .cfg files are all text files which can be edited by Leafpad. Do not edit the files
inside /pp_templates; if you wish to change their content then copy the file to a
profile.
e.g. inside /home/pi/pp_home/pp_profiles/myprofile/pp_io_config
or if you want them to be used by all profiles to /pipresents/pp_io_config
If editing these files be aware that there is little checking of the content of these files
by Pi Presents. If you modify the file run pipresents.py from a terminal window first so
that any Python error messages can be displayed.

14.2 Configuring Inputs and Output Drivers
Section 8.1 describes the input system of Pi Presents and how external physical
events are converted to input events with symbolic names. Most of the responses are
configurable using the files described in this section.
When editing I/O configuration files you will need to supply symbolic names. It is
advisable not to create names beginning with pp- to avoid clashes with names used
by Pi Presents.
All I/O configuration files must have a section called [DRIVER]. This must contain the
following fields:
Field
title
enabled

module

Example
GPIO

Use
Text which is used when reporting activity of the I/O
plugin in error reports and logs.
yes
yes/no. An I/O plugin becomes active if it has a .cfg file
in the appropriate directory and enabled = yes . This field
enables an I/O plugin to be made inactive without
removing its configuration file.
pp_gpiodriver The name of the python module which implements the
I/O plugin, without .py. The file must be in
/pipresents/pp_io_plugins
There can be more than one .cfg file referring to the
same module, for example if there are two remotes with
different key bindings.

The [DRIVER] section can contain other fields used by a specific I/O plugin.

14.2.1 Interfacing with GPIO using pp_gpiodriver.py
BEWARE: Accidentally using a pin as an output with the output shorted to ground or
+3.3 volts might fry your Pi, use a series resistor on every input and output for
protection.

Page 80

Version 1.3.5a, 1 May 2018

The configuration of the GPIO used by Pi Presents out of the box is defined in the file
gpio.cfg.
The file in /pipresents/pp_resources/pp_templates/gpio.cfg is an example which,
when copied to the/ pp_io_config directory in a profile, configures Pi Presents for the
buttons and the PIR described in this manual and used by the examples.
The .cfg file maps physical P1 connector GPIO input and output pins to the symbolic
names of inputs and outputs used by the Pi Presents examples. It also configures the
input pins.
A section for every pin must be present in the file. A pin with direction=none is
ignored .
Inputs
Each pin can generate an event having the specified symbolic name in any of four
ways:


rising edge - An event with the symbolic name specified in 'rising-name' is
generated when the input changes from 0 to 1 (0 volts to 3.3 volts)



falling edge - An event with the symbolic name specified in 'falling-name' is
generated when the input changes from 1 to 0 (3.3 volts to 0 volts)



one state - An event with the symbolic name specified in 'one-name' is
generated at 'repeat' intervals while the input state is '1' (3.3 volts). The first
event happens after 'repeat' interval. If you want the input to respond
immediately set the rising edge event to the same symbolic name.



zero state - An event with the symbolic name specified in 'zero-name' is
generated at 'repeat' intervals while the input state is '0' (0 volts). The first
event happens after 'repeat' interval. If you want the input to respond
immediately set the falling edge event to the same symbolic name.

If you do not want the event to be generated leave the symbolic name blank
For the purposes of this manual and the examples gpio.cfg is set up to allow normally
open push buttons connected to ground (0 volts) and a PIR with a normally closed
relay contact connected to ground.
Linked Outputs
The optional linked-output and linked-invert fields allow a gpio output to be directly
connected to a gpio input. See /pp_resources/pp_templates/gpio.cfg for details
Outputs
The logical 'ON' state produces +3.3 volts. The logical 'OFF' state produces 0 volts
Pi Presents initialises GPIO outputs to 0 volts so it is best to design relays etc. for
positive logic (which many of those on the market are not). The outputs are reset to 0
volts when Pi Present exits.

Page 81

Version 1.3.5a, 1 May 2018

When sending the animation command:
delay output_name parameter_type parameter_value


The output_name is compared against the name field of all pins having
direction = out



The parameter_type field should be state as this is Parameter Type
supported by pp_gpiodriver.py. The animation command will be ignored for
any other state even if the ouput_name matches.



the parameter value must be on or off, if not an error will be flagged.

14.2.2 Interfacing with a Remote Control or Keypad using
pp_inputdevicedriver.py
Remote controls etc. that interface with Linux userland by providing a file in
/dev/input and which provide key presses should be able to interface with Pi Presents
using the pp_inputdevicedriver.py I/O plugin. The template file osmcremote.cfg
configures this plugin to work with the official OSMC remote.
https://osmc.tv/store/product/osmc-remote-control/
The [DRIVER] section must contain the following additional fields:
Field
device-name

key-codes

tick-interval

Example
Content
HBGIC
Technology Co.,
Ltd. USB
Keyboard Mouse

KEY_STOP,KEY
_PLAYPAUSE,K
EY_DOWN, ….

50

Use
The name of the device producing the inputs.
Only inputs from this device will cause an input
event to be generated. (But see Duplicate Events
below).
Run the program input_device.py to find this
name for your remote.
The list of key codes that Pi Presents is to
respond to.
Run the program input_device.py to find the key
codes for your remote.
The interval between polls of the remote in mS.

There are also sections for each button, the content of which is similar the gpio.cfg.
Details in /pipresents/pp_resources/pp_templates/osmcremote.cfg
NOTE: if you are getting two input events from some remote control buttons read the
Tkinter Keyboard Section 14.2.5

14.2.3 Interfacing with a Serial Link using pp_serialdriver.py

Page 82

Version 1.3.5a, 1 May 2018

Serial links such as RS232 are often used for the control of projectors. The RPi
provides an inbuilt serial link which is configured for factory debugging. It is difficult to
use and will almost certainly require voltage level convertors. A better way is to use a
USB to RS232 adaptor. Adaptors such as this are exposed to Linux as files like
/dev/ttyUSB0 and can use the pyserial python library.
The pp_serialdriver.py I/O plugin uses the pyserial library to drive serial devices. It
has been tested with a usb connected device interfacing with a Windows XP machine
and Windows 98 machine. The template file serialdriver.cfg in
/pipresents/pp_resources/pp_templates is an example of using the I/O plugin. In the
example the serial link is used to drive a projector but the configuration will require
modification and validation for your projector.
Details for using the configuration data are in the file:
/pipresents/pp_resources/pp_templates/serialdriver.cfg
The driver allows both input and output.
Input
Characters received from the link are matched against characters and strings defined
in the configuration file. If a match occurs an input event with a symbolic name, also
defined in the configuration file, is generated:


As each character is received it is matched against the configuration data to
generate and input event.



When an end of line character is detected the characters received after the
previous end of line are matched against the configuration data to generate
an input event.

Events can be generated from any-character, specific-character, any-line and
specific-line
Output
Output to the serial link uses animation commands. There are two ways to use the
command, determined by the value field in the configuration data:


preset – the characters to be output are defined in the configuration data. The
configuration data defines the message to be sent for each combination of
name, parameter type and parameter value and the driver translates this into
the message to be sent.
For example the command ‘0 projector state on’ will be translated into a
sequence of bytes 02 00 00 00 01



explicit – the characters/bytes to be output are in the animation command.
Examples are:
0 serial-send bytes “02 00 00 00 01”
0 serial-send string “the cat sat on the mat”

Page 83

Version 1.3.5a, 1 May 2018

14.2.4 Interfacing with I2C devices using pp_i2cdriver.py
Many devices can interface with the RPi using the I2C bus. pp_i2cdriver.py supports
a number of devices which may be of use to Pi Presents users. However the main
use of this driver is to provide an example of how to interface your own device with Pi
Presents.
To use the provided pp_i2cdriver.py it will be necessary to enable I2C in RPI
Preferences menu.
The following devices are supported by pp_i2cdriver.py
Device
Adafruit
MCP4725
DAC

Input/Output Symbolic
Parameter Type
Name
Output
dac
set – set the DAC to a ‘percentage’*** of 3.3
volts
mirror – mirror the named ADC input
(analog1,analog2,analog3)

Pimoroni
Four Letter
Phat

Output

fourletter

fade – ramp the output from a to b in t
seconds. a and b are expressed as
‘percentages’***.
string – display a four letter string
num-string – display a 4 digit number with
decimal point
blank – blank
mirror-voltage – display the voltage applied
to the adc input
mirror-percentage – display the
percentage*** value of the ADC input

Pimoroni
Scroll HD
LED matrix
display

Output

scrollhd

countdown – countdown in minutes and
seconds from the seconds specified.
scroll - scroll single or multiple lines of text.
static – display static text
static-high – a high brightness variant of
static
blank - blank

Page 84

Version 1.3.5a, 1 May 2018

Pimoroni
Input
Automation
Phat
(ADS1015
ADC)

The three analog input channels of the
HAT are read continually at 100mS
intervals. The results are used in the mirror
methods and are available to track plugins
using the I/O plugin manager’s get_input
method. The keys are:
analog-1volts
analog2-volts
analog3-volts
analog1-percentage
analog2-percentage
analog3-percentage
Note: The digital inputs, digital outputs and
relay of the HAT are GPIO based and
controlled using pp_gpiodriver.py

***Percentage – A number between 0 and 100 which is the percentage of 3.3 volts
applied to the ADC input.
The file /pipresents/pp_resources/pp_templates/i2c.cfg has details of implemented
commands and methods.
Libraries used by I2C I/O plugin.
The Scroll HD and Four Letter PHats use the Pimoroni libraries. Some of the
methods are just adaptions of the Pimoroni examples of using these devices. The
libraries are already in the Raspbian image.
The Automation PHAT and Adafruit DAC libraries are not required as Pi Presents
uses its own libraries for these which are in in pp_i2cdevices.py, however it may be
necessary to install the smBus module.

14.2.5 Configuring Tkinter Keyboard Keys using pp_kbdriver.py
Pi Presents is implemented using Tkinter. This has a native keyboard/mouse
interface which is implemented in Pi Presents by pp_kbddriver.py and configured by
keys.cfg. This interface is the only interface enabled out of the box so it has a file in
/pipresents/pp_io_config/keys.cfg
The [DRIVER] section of the .cfg file should have the following additional fields:
Field
bind-printing

content
yes/no

use
If yes then all printing keys automatically bound to
symbolic names as described below

Keyboard keys are bound to symbolic names in the .cfg. file The file has a number of
lines with the format
condition = symbolic name

Page 85

Version 1.3.5a, 1 May 2018

The conditions are defined in effbot.org/tkinterbook/tkinter-events-and-bindings.htm
in the , a, and  sections. The conditions and the symbolic names
are case sensitive.
In addition to these bindings the printing characters on the keyboard, (the ones
obeying the  condition in the reference), are automatically bound to the
symbolic name pp-key-x if ‘bind-printing’ = yes
e.g the 'a' key produces pp-key-a
Automatic binding of a printing key can be added or overridden by a line such as a =
pp-pause.
The default keys.cfg in /pipresents/pp_io_config has the following bindings:
Symbolic
Name
pp-down

Bound Key

Command

Cursor Down

down

pp-up
pp-play
pp-pause
pp-stop
pp-terminate

Cursor Up
Return
Spacebar
Escape
CTRL-BREAK

up
play
pause
stop
Abort Pi Presents.

Duplicate Events
The Tkinter device driver has a quirk in that it accepts inputs from all devices in
/dev/input. As a result a remote control button press that causes an event from
pp_inputdevicedriver.py may also generate an event from pp_kbddriver.py. It may be
necessary to remove bindings in one or other of the .cfg files or to set bind-printing to
no.
The duplicate events can be seen by enabling debugging in Pi Presents with the –d
command line option.

14.2.6 Advanced Interfacing with a Keyboard using
pp_kbddriver_plus.py
This I/O plugin enhances the standard pp_kbddiver.py I/O plugin by allowing Pi
Presents to:


allow strings, in addition to single characters, to trigger events



allow lines of text to be provided to track plugins

The operation of the plugin is almost identical to the serial port driver (Section 14.2.3)
Details for using the configuration data are in the file:
/pipresents/pp_resources/pp_templates/keys_plus.cfg

Page 86

Version 1.3.5a, 1 May 2018

The use of pp_kbddriver_plus.py conflicts with pp_kbddriver.py. If using the driver
then disable pp_kbddriver.py by one of the following:




Add a keys.cfg file to the profile with enabled = no
Disable the driver in /pipresents/pp_io_config/ keys.cfg
Remove keys.cfg from /pipresents/pp_io_config

The example pp_kbddisplay_1p3 demonstrates the use of the driver to accept lines
of text as events and to display the text using a track plugin.
Characters received from the link are matched against characters and strings defined
in the configuration file. If a match occurs an input event with a symbolic name, also
defined in the configuration file, is generated:


As each character is received it is matched against the configuration data to
generate and input event.



When an end of line character is detected the characters received after the
previous end of line are matched against the configuration data to generate
an input event.

Events can be generated from any-character, specific-character, any-line and
specific-line

14.2.7 Configuring Touch/Click Areas
The file screen.cfg defines the areas of the screen that will become mouse click or
touch sensitive. Click areas are not limited to Hyperlinkshows; they can be used for
all types of show.
The file consists of a number of sections each with a unique name. The name can be
anything but must be unique within the file.
All fields in each section must be present. The fields of each section are used as
follows:


name - The symbolic name of the click area. Each command in the Controls
field of a track or show has a symbolic name. When the track in a show is
played the click areas in the Controls field are displayed on the screen and
when an area is clicked the symbolic name will identify an input event.



points - this is a set of x y pairs that defines the points of a polygon bounding
the area. The polygon is automatically closed so a quadrilateral will have 4
(not 5) x,y pairs. There must be at least three pairs of points. For details of
this and other attributes see http://effbot.org/tkinterbook/canvas.htm
create_polygon For rectangular click areas the points may be specified as
x1+y1+w*h

Page 87

Version 1.3.5a, 1 May 2018

where xi, y1 are the coordinates of the top left corner of the click area and w,h
are the width and height, all in pixels.


fill-colour, outline-colour
Specifies the look of the polygon. Use a blank field for transparent



text, text-font, text-colour
If text is not blank then the text is written centred in the polygon.



image, image-width, image-height
An image to be used as a button. Paths relative to pp_home are supported
(+/) or specify the complete path. The image will be warped to fit - imagewidth and image-height and centred on the polygon.

14.3 Writing I/O Plugins
An I/O plugin is a python module which:


For inputs translates physical inputs to the RPi into events with symbolic
names



For outputs translates animation commands having symbolic names and
parameters into physical outputs

I/O plugins should be placed in the directory /pipresents/ pp_io_plugins where they
will be available to all profiles.

14.3.1 Configuring and Registering an I/O plugin
I/O plugins will be registered if there is an I/O plugin configuration file in the
pp_io_config directory of a profile. Registration is implemented by
pp_iopluginmanager.py. The module reads the [driver] section of the configuration
file and if enabled = yes imports the module specified in module = .
The I/O configuration file can also be used to configure an I/O plugin module. This
allows one module to be used with different devices, e.g. different wireless remote
controls. Configuration data can be added to the [driver] section or further sections
can be created if desired.
The path to the plugin configuration file is passed to the I/O plugin module so that the
module can read the additional parameters.

14.3.2 Class
The class name must be the same as the name of the file

Page 88

Version 1.3.5a, 1 May 2018

The I/O plugin output method may be called from many different objects hence
variables used by the output side should be class variables.

14.3.3 Methods
init
def init(self,filename,filepath,widget,button_callback=None)
init() is called once by the I/O plugin manager when Pi Presents starts. The method
should:






read configuration data from the [driver] section of the I/O configuration file in
the profile
initialise the physical device
indicate using a state variable that initialisation is successful and the plugin is
active.
if activation is successful return ‘normal’,’a message for the log’
if activation fails return ‘error’,’a message for the error pop up and log’

Arguments:
filepath – the path to the I/O plugin configuration file.
filename - leaf of filepath, used for logging
widget - the instance of an object onto which to hang the Tkinter after and
after_cancel calls
callback- the remote function to be called to generate an event from a
physical input. callback has two parameters:



symbolic name of the event
a text string identifying the source of the event. The plugin should read it
from the [driver] section

start
def start(self):
start() is called once by the I/O plugin manager when Pi Presents starts. The method
should:



If appropriate enable any interrupt action
If the input is polled scan the inputs once and then call widget.after() to
schedule a further scan.

Scanning the physical inputs must not be blocking because Pi Presents use
cooperative scheduling.

Page 89

Version 1.3.5a, 1 May 2018

Reception of an interrupt or detection of a physical input when polling should execute
the callback function:
self.button_callback(symbolic_name,source)
get input
get_input(self,key)
get_input is used by track plugins to obtain values of inputs. The key will be a string
which can be used to identify the input required.
The method returns 2 arguments:
 Found – True/False
 Value – the value
terminate
def terminate(self)
terminate is called by the main program when Pi Presents closes for any reason. It
should shut down any interrupts and cancel any polling timers
is active
allows PI Presents to determine the whether the plugin is active
def is_active(self):
returns whether the i/O plugin is active (True/False)
handle output event
This method uses animation commands of the form:
name param_type param_value_1 “param value 2”
to generate physical outputs
def handle_output_event(self, name, param_type, param_values, req_time)
name – the symbolic name specified in the animation command
param_type – the parameter type specified in the animation command
param_values – a list of parameter values specified in the animation
command. There may be 0 or more parameter values. If a parameter has
embedded spaces then it must be contained in “”
req_time – the time at which the command was required to be executed, Use
for logging only, the animation manager ensures the output is made at the
correct time.

Page 90

Version 1.3.5a, 1 May 2018

Every animation command is offered to this and every other active I/O plugin. If the
name and param_type matches any of those implemented by the plugin then the
command should be executed using the provided parameters and ‘normal’ returned
The parameter values should be checked for correctness (e.g. state is on or off). If
illegal parameter values are provided then ‘error’ should be returned.
The function returns two parameters - status,message
status – ‘normal’/’error’
message – a text string which will be displayed in the error pop up and used
for logging.

14.3.4 Example
Components:




pp_exampledriver.py in the pp_io_plugin directory
exampledriver.cfg in /resources/templates directory
pp_ioplugin_1p3 example profile in the Pi Presents examples github
repository

The example plugin has all the elements of a plugin but does not do any physical I/O:


The input generates an event with the symbolic name tick at an interval
defined in the exampledriver.cfg configuration file.



The output prints the message contained in the animation command to the
terminal window.

15 Remote Control using OSC
Version 1.3.1 allows Pi Presents to control instances of Pi Presents on other
computers or to control or be controlled by a computer that supports the Open Sound
Control protocol, including smartphones and tablets.
OSC is a lightweight flexible protocol which was originally intended to control musical
instruments. It can do much more than this and is supported by many multi-media
equipments. For Pi Presents a Master is a unit that sends commands to control
Slaves so:



A Master Unit (OSC Client) sends commands to Slaves
A Slave Unit (OSC Server) receives commands from Master Units and acts
on them.

Depending on its configuration Pi Presents may be both a Master and a Slave.
The implementation in this version of the software (1.3.1c) is much improved from
the initial experimental version. Improvements include:

Page 91

Version 1.3.5a, 1 May 2018





Many slaves per master
A particular unit can be both a master and a slave
A slave can be controlled by many masters, replies are returned to the master
sending the commands.



It continues to use the UDP protocol not TCP. This makes it fast and
compatible with more third party systems but UDP is what is called an
unreliable protocol – messages are not guaranteed to arrive or be in the order
they were sent; whether this matters for small systems on a local LAN
remains to be seen.



Commands now use Pi Presents Show Command syntax, converting them
internally to the messages required by OSC.



Configuration is much simplified

The implementation does not support:
 Pattern matching language to specify multiple recipients of a single message
 High resolution time tags
 "Bundles" of messages whose effects must occur simultaneously

15.1 Sending and Receiving Commands via OSC
In Pi Presents terms OSC commands are sent by Master units and received by Slave
units. To send an OSC command, place the appropriate command in the Show
Control field of a track or show. Other than configuring OSC, receiving messages is
automatic.
Other than the send, loopback, and server-info commands, all OSC commands have
the same effect as they would have if used on the local machine.
An OSC Show Control command has three or more fields:



osc – all osc commands have osc or OSC as a first field
unit – the OSC name of the unit to which the command is to be sent, the
name should also appear in the ‘OSC Names of slaves’ field of the configuration
file.




command – open, openexclusive, close, closeall, event, monitor, animate,
exitpipresents, shutdownnow, reboot, send, loopback, server-info
parameters – zero or more parameter values
e.g. osc unit1 open myshow

15.2 OSC Fundamentals
OSC commands are converted by Pi Presents into messages. The OSC software
does a further conversion into an efficient binary format for transmission. The
messages have an OSC address field and zero or more data fields. e.g.
/pipresents/unit1/core/open myshow

Page 92

Version 1.3.5a, 1 May 2018

The OSC address is hierarchical, for example:
/pipresents/unit1/core/open
This means:
 /pipresents - the message is for equipments that can understand Pi Presents
type OSC messages. All other units will ignore this message.


/unit1 - message is for Pi Presents unit1 and will be ignored by any other
units. unit1 must appear in the list of slave units in the configuration file.



/core - the message is for the core of Pi Presents, the part that controls
shows and controls tracks via input events.



/open is the command to open a show. The complete message will have a
show-ref as an argument.

Pi Presents Show
Command

OSC Command

osc unit1 open myshow

/pipresents/unit1/core/open
myshow
/pipresents/unit1/core/close
myshow
/pipresents/unit1/core/opene
xclusive myshow
/pipresents/unit1/core/closea
ll
/pipresents/unit1/core/event
pp-stop
/pipresents/unit1/core/exitpip
resents
/pipresents/unit1/core/shutdo
wnnow
/pipresents/unit1/core/reboot
/pipresents/unit1/core/animat
e out1 state on

osc unit1 close myshow
osc unit1 openexclusive
myshow
osc unit1 closeall
osc unit1 event pp-stop
osc unit1 exitpipresents
osc unit1 shutdownnow
osc unit1 reboot
osc unit1 animate out1
state on

osc unit1 monitor on
osc unit1 monitor off
osc anyunit send
/myprotocol/anything/you
/like arg1 2

/pipresents/unit1/core/monito
r on
/pipresents/unit1/core/monito
r off
/myprotocol/anything/you/lik
e arg1 2

osc unit1 loopback

/pipresents/unit1/system/loo
pback

osc unit1 server-info

/pipresents/unit1/system/ser
ver-info

Use
Open the referenced show
Closes the referenced show
Close all running shows then
open the referenced show
Closes all running shows
Generates an input event with
the referenced symbolic name
Exits Pi Presents
Shut down the RPi
Reboot the RPi
This provides an output passthrough system. The arguments
are any data used by Animation
commands without the leading
delay parameter.
Turn the monitor on.
Turn the monitor off
Send the osc message
specified to ‘anyunit’. Can be
used to send commands to
types of unit other than Pi
Presents units. All arguments
are sent as strings.
Causes the slave to return a
blank loopback-reply message
to the master.
The reply appears in the
terminal window.
Causes the slave to report
information about itself in a

Page 93

Version 1.3.5a, 1 May 2018

server-info-reply message. The
reply appears in the terminal
window.

15.3 Configuring OSC
OSC is enabled and configured by the presence of an osc.cfg file in the directory
/pp_io_config in a profile. The file is a non-standard I/O plugin configuration file.
pp_web_editor.py has a menu option to create, and edit osc.cfg files in the profile.
This Unit
Field
OSC Name of this
unit
IP of This Unit

Example
my-pi

Use
The /unit part of the address of this unit. Used in
matching messages sent to this unit.
Normally this field should be blank and Pi Presents
will obtain this value from the network. If this fails an
IP can be specified here.
If your Pi is connected to two networks it may be
necessary to choose a preferred network in web.cfg
(Section 17.1).
The IP used to listen for messages from a master
when slave is enabled, and replies when master is
enabled.

Fields for a Master Unit
Field
Master Enabled
Listening Port for
replies from slaves.

Example
yes
9001

OSC Names of
slaves

slave1 slave2

IP’s of Slaves

myhostname
192.168.1.102

Use
yes/no, Enable/disable this unit as a Master
Port used to listen for replies from the slave units.
Slaves reply on the same port as they listen hence
the Listening port of the Master must be the same
as the Listening Port of all its Slaves
A space separated list of OSC names that is used
as a lookup table to determine the IP’s of slave
units from the OSC command.
A space separated list of IP’s of the slave units
having the same order as the OSC Names of
slaves.
The IP may be the numerical IP of the unit. I have
also found the hostname, or hostname.lan also
works. hostname.local may work.

Fields for a Slave Unit

Page 94

Version 1.3.5a, 1 May 2018

Field
Slave Enabled
Listening Port for
commands from a
master

Example
yes
9001

Use
Enable/disable this unit as a slave
Port that the slave listens to for commands from a
master unit.
All slaves must listen for commands on the same
port which must be the same as the Listening port of
the Master Unit.

15.4 oscremote and oscmonitor
pp_oscremote.py and pp_oscmonitor.py are two stand-alone programs which I
developed to test the OSC interface of Pi Presents. They run on Windows (requires
python to be installed), Linux, or Raspbian. They contain code which could be used
as the basis for other applications. Anyone interested in writing an IOS or Android
App for controlling Pi Presents?
oscremote sends commands to Pi Presents while oscmonitor monitors and displays
OSC messages that Pi Presents has sent. Out of the box oscremote is configured to
send commands to the unit /pipresents using port 9001 and oscmonitor to listen to
master units on port 9002. When first running these programs you will need to
complete other configuration fields.
By running them from different RPi’s you can run Pi Presents, a remote, and a
monitor. (or just 2 of them). Three example profiles have been set up as
demonstrations of OSC that can be run in this way out of the box.


pp_osc_1p3 is a simple profile to demonstrate some of the key points. Its
osc.cfg sets up Pi Presents as a master and a slave. The show mediashow is
in the Start show and sends a number of different commands from the show
control fields of the track which can be monitored by oscmonitor. Replies to
the loopback and server-info commands can be seen in the terminal window
running Pi Presents. Use oscremote to close and open the show mediashow.



pp_multiwindow_1p3 has an osc.cfg file which allows it to be controlled by
oscremote.py; just remove all the shows from the Start Show and control
them from oscremote.py using open show and close show commands.



pp_showcontrol.py has an osc.cfg file which allows it to send output
commands from the show control field of the two image tracks to mirror
control of the audio show. These can be monitored by oscmonitor.py

By changing the configuration you can run oscremote and oscmonitor as a pair. You
can also run oscmonitor and oscremote on one machine and Pi Presents on a
second.
pp_oscremote.py
Before using oscremote.py it needs to be configured using the options>edit menu to
configure the communication. Out of the box it is set up to communicate with the osc
unit pipresents with the hostname raspberrypi using port 9001.

Page 95

Version 1.3.5a, 1 May 2018

The buttons each generate all or part of an OSC message in the Message to Send
field; you will need to add show refs, and animation commands and press Send.
Messages sent and any replies appear in the status field.
The profile>select menu option allows a Pi Presents profile to be selected. To do this
a /pp_home/pp_profiles directory containing the profile will need to be presents and
the – o command line option of pp_oscremote.py used to set the path to pp_home
(default is /home/pi).
The shows in the profile are shown in the Shows tab; selecting one of these before
the open or close button saves you remembering or typing the show-ref, nothing
more.
pp_oscmonitor.py
Just displays messages it receives in the Status window. Out of the box it is
configured to receive messages on port 9002.

16 Track Plugins
Track plugins are python code modules with a documented interface specification
that can be coded by the user to enhance the displays of Pi Presents. Track Plugins
allow dynamic display of information such as time, weather, and tickers. It is likely
that information will be scraped from web sites or from RSS feeds.

Track plugins are executed by Players. Their primary use is to display dynamic
content. This can be achieved in two ways:



By modifying or replacing the media to be played.
By writing dynamic information direct to the Pi Presents display

Track plugins are stored in the directory /pipresents/pp_track_plugins in .py files. It is
recommended that the plugin file name is preceded by your initials so that there are
no clashes with python modules (e.g. time.py will clash with the standard time
module.)
Using Plugins
If the plugin is required for a track then the 'Plugin Configuration File' field of a Player
should contain the name of a Plugin Configuration File e.g.
+/media/krt_image_text.cfg.
Relative paths are allowed. The media produced by the plugin must match the type
of the track to be played.
The Plugin Configuration File allows the same plugin to be called with different
parameters. It must contain at least
[plugin]
plugin = pluginname
type = image
# required if the plugin is to be used in a liveshow

Page 96

Version 1.3.5a, 1 May 2018

pluginname is the name of the python module containing the plugin (the filename
without .py).
The configuration file may define further parameters which will be available to the
plugin code via the dictionary plugin_params:
e.g.
[plugin]
plugin = krt _image_text
type = image
# required if the plugin is to be used in a liveshow
# optional
text = text to display
The plugin code can read the value of text so by using a number of configuration files
all calling the same krt _image_text plugin you can have a different text in each track.
You can use plugins in Liveshows. To do this the plugin must be specially written. To
use a plugin in a liveshow just copy the plugin configuration file to pp_live_tracks. To
be used in liveshows plugin configuration files must specify the track type so that Pi
Presents knows which type of track to play.
Writing Plugins
As of Version 1.3.1 the track plugin API has changed and improved. The changes
are necessary so that the plugin way of displaying information matches the preloading required for gapless transitions. API details are in pp_example_plugin.py
I have provided three examples of plugins
 pp_example_plugin.py
This contains the API documentation. The example is long as it addresses all
the types of track that a plugin might be used for, and also liveshows.


krt_image_text.py
An example that adds text to an image.



krt_time.py
Modifies the screen directly to display the current time.

The examples use:


The Python Imaging Library (PIL). The handbook is at
http://effbot.org/imagingbook/pil-index.htm.



Tkinter canvas operations are documented at
http://effbot.org/tkinterbook/canvas.htm

The functional interface varies slightly depending on the type of the track:


image - the plugin will be supplied with the path to a file containing an image
(e.g picture.jpg). An image track file must be returned and must be able to be
displayed using PIL and Tkinter.

Page 97

Version 1.3.5a, 1 May 2018



audio - the plugin will be supplied with a file containing audio. An audio track
can optionally be returned that is playable by mplayer. Blank is allowed and
no audio will be played.



video - the plugin will be supplied with a file containing a video. A video track
must be returned that is playable by omxplayer. The plugin can also write
directly to the canvas but be aware that the video will appear over the top of
the text so use Video Window to window it.



web - the plugin will be supplied with a file containing html code (whatever
uzbl supports for rendering). A html file should be returned that is playable by
uzbl. The plugin can also write directly to the canvas but be aware that the
browser will appear over the top of the text so use Web Window to window it.



message - the plugin will be supplied with the text that would have been
displayed, this can be modified and returned. The plugin can also write
directly to the canvas.

17 Remote Management
The programs pp_manager.py and pp_web_editor.py are used for the remote
management of Pi Presents from a web browser running on any computer on the
same network as Pi Presents. Each program runs a web server serving an interactive
web page that, for the editor, looks similar to the normal gui of the Pi Presents editor.


Manager - pp_manager.py provides facilities to select and run Pi Presents
profiles. It is also possible to upload and download profiles, media and
livetracks.
The Manager can also replace the normal autostart mechanism (Sect. 6.6)
with a mechanism that can remotely choose the profile to be auto-started.
The presumed workflow of the manager is that you will upload media or
livetrack files from a remote computer to the Pi, or import them from a USB
stick. Once in the Pi media and livetracks can be deleted or renamed. Profiles
can similarly be uploaded or imported; in addition they can be created or
edited on the Pi and then downloaded to the remote computer.



Web Editor - pp_web_editor.py is a near clone of the Pi Presents Profile
editor.

17.1 Setting up for Remote Use
Before first using the two programs:

Page 98

Version 1.3.5a, 1 May 2018



The file /pipresents/pp_config/pp_web.cfg must be edited using a text editor.
Entries in the section [manager-editable] can subsequently be edited by the
Manager.

Field
[manager-editable]
media_offset

livetracks_offset

Example
/media

/pp_live_tra
cks

profiles_offset

Description
The offset from the pp_home directory to which media
will be imported or uploaded. So /media will store media
in home/pi/pp_home/media
The offset from the pp_home directory to which livetracks
will be imported or uploaded. So /pp_live_tracks will store
media in /home/pi/pp_home/ pp_live_tracks the default
live tracks directory.
The offset from the pp_profiles directory to which profiles
will be imported or uploaded. Generally left blank.
This offset also determines the directory for the
Manager’s profile selection list.
e.g. Specifying an offset e.g. /test_profiles will store
profiles in /home/pi/pp_home/pp_profiles/test_profiles
When starting Pi Presents from the Manager append the
specified options. Sect 6.1
The –p and –o options should not be specified. The
Manager automatically adds these.

options

autostart_path

/my_profile

If not blank the Manager will autostart Pi Presents when it
is started and before its web server is started.
The field specifies the profile to be used when
auotstarting Pi Presents..So /my_profile will start the
profile in

autostart_options

[manager]
home
import_top

port

-fb

/home/pi/p
p_home
/media/pi

8081

username

/home/pi/pp_home/pp_profiles/my_profile
When autostarting Pi Presents appends the specified
options. (Sect 6.1)
The –p and –o options should not be specified. The
manger automatically adds these.

The path of the Pi Presents Home Directory. It must end
in pp_home.
This field limits the files for the following actions to those
in this directory and below:
 Source for importing media and livetrack files.
 Source for importing profiles
As a security measure this option limits the files that can
be seen to those below the top. It also determines the
starting point for the import File Selection dialog.
The port used by the editor. Should not need to be
changed.
If a username and password is specified then to use the
Manager it will be necessary to login

password
Configure the Web Editor
[editor]
port

8082

The port used by the editor. Should not need to be

Page 99

Version 1.3.5a, 1 May 2018

changed.
If a username and password is specified then to use the
Web Editor it will be necessary to login

username
password

These fields are also used by the email system.
[network]
unit

My Pi

force_ip

A name which appears on the Manager’s screen and on
emails. Useful if you have more than one Pi under
management.
The ip address of Raspberry Pi that is running the Editor
or Manager.
For normal use this field can be left blank as the IP
address of the Pi is automatically determined. If this field
is specified auto detection will not be used.

preferred_interface

If wifi and wired Ethernet are both connected the Pi will
have two IP addresses. If you have two interfaces and
wish to specify which one should be used populate this
field. Values on my Pi are wlan0 and eth0.

17.2 .Using the Manager
Start the Manager by the command python pp_manager.py from a terminal window
opened in the pipresents directory. This will start the Manager’s server.
The Manager can be accessed from a browser using the server’s IP address and
port e.g. 192.168.1.108:8081
The manager will show a list of profiles from the profiles directory.
Buttons
 Start button – Starts the profile selected from the displayed list of profiles.
 Exit button – Exits Pi Presents
 Refresh List button – Refreshes the list of profiles; required if a profile is
added or deleted from the Pi rather than from the Manager.
The line above the buttons displays the Unit and the run state of Pi Presents. When
Pi Presents has exited an exit code is displayed in brackets:




100 – Normal Exit
101 – Pi Presents Closed by external event (usually from the Pi)
102 – Pi Presents exited due to a runtime error. The error message can be
accessed by downloading the log.

Menus
 media>import - Copy media files from the selected directory into pp_home
into the sub-directory defined by media_offset.


media>upload - Upload media files from the browser into pp_home into the
sub-directory defined by media_offset.



media>manage - delete or rename media files

Page 100

Version 1.3.5a, 1 May 2018



livetracks>import - Copy livetrack files from the selected directory into
pp_home into the sub-directory defined by livetracks_offset.



livetracks>upload - Upload liverack files from the browser into pp_home into
the sub-directory defined by livetracks_offset.



livetracks>manage - delete or rename livetracks files



profile>import – Copy a profile directory into pp_home/pp_profiles into the
sub-directory defined by profiles_offset.



profile>upload - upload a profile directory into pp_home/pp_profiles into a
directory defined by profiles_offset. The profile directory must be archived into
a .zip file before upload. The Manager will automatically unzip the archive.



profile>download – download the selected profile to the browser. The profile
is downloaded as a zip archive.



profile>manage – delete or rename a profile.



editor>run – Run the Web editor. This will start the editor’s server on the Pi.
Click the link to access the editor which will open a new browser tab at the IP
address and port of the editor e.g. 192.168.1.108:8082



editor>exit – Exit the Web Editor



options>manager/ options>autostart – Edit the Manager’s configuration



options>email – edit the Email Alert options (see Sect. 18.1)



logs>Download Log – Download the Pi Presents log file



logs>Download Stats – Download the Pi Presents statistics file



Pi>Reboot/Pi>Shutdown - reboot or shutdown the RPi

Using Autostart
If the Manager’s autostart_path configuration entry is not blank then, when the
Manager is started, Pi Presents will be run with the configured profile and options.
To achieve this Raspbian’s autostart file (Sect. 6.6) should have the command:
usr/bin/python /home/pi/pipresents/pp_manager.py
instead of a command to run Pi Presents.
After the profile has been run the Manager’s server will be started and can be
accessed in the normal way via a browser. It will show that the auto-started profile is
running.

Page 101

Version 1.3.5a, 1 May 2018

It is intended that the Manager be run continually in parallel with Pi Presents. If this is
consuming too much processor power then edit update_interval=0.1 (secs) to say 0.5
in the last line of pp_manager.py

17.3 Using the Web Editor
When managing Pi Presents remotely the Web Editor is normally started and
stopped from the Manager however it can be run independently :


Use the command python pp_web_editor.py -r from a terminal window
opened in the /pipresents directory. This will start the Web Editor’s server.

In either case the Editor can be accessed from a browser using its IP address and
port e.g. 192.168.1.108:8082
The Web Editor provides more functions than the Pi hosted editor. There are a few
minor differences:


Navigation when selecting files and directories. To open a directory click on
its icon. To select a directory click on its name, to select a file click on its
name.



Colour names can be used but if the colour chooser is used the name will be
converted to the rgb hex code.



The colour chooser is not supported by Internet Explorer



Various browsers layout pages differently. IE seems to be the main culprit for
showing different layouts. The Manager and Editor have been developed
using Firefox and Chromium (The current Pi browser).

18 Email Alerts
Pi Presents and the Manager can send alerts by email.
email_with_ip

Sent by the Manager when it starts. The email contains the
IP address of the Pi for use by the remote browser.
email_at_start
Sent by Pi Presents when it starts.
email_on_error
Sent when Pi Presents exits when a Fatal or Profile error is
detected. The message contains the error text.
email_on_terminate Sent when Pi Presents exits either by it being terminated
from the Pi or pressing Exit on the Manager
log_on_error
(not implemented) Attach the log file to the error email.

18.1 Setting Up Email Alerts
Before first using email alerts:


The file /pipresents/pp_config/pp_web.cfg must be edited using a text editor.
The [network] section fields preferred_interface and force_ip need to be set.
For normal use they should be blank.
Page 102

Version 1.3.5a, 1 May 2018



The file /pipresents/pp_config/pp_email.cfg must be edited using a text editor.
Entries in the section [email-editable] can subsequently be edited by the
Manager.
Field

Example

[email]
server

port
username
password
[email_editable]
email_allowed
to
email_with_ip
email_at_start
email_on_error
email_on_terminate
log_on_error

Description
url of the server to be used to send the emails. The
software has been tested only with gmail. Since the
username and password is not encrypted it is better not
to use your normal email account. Set up a gmail account
especially for the purpose. You will need to disable the
advanced security feature in the gmail account.
port of the server used to send the emails
username and password for the server used to send the
emails.

A global enable. yes to enable all types of email alert,
otherwise no
A list of email addresses to which the emails will be sent,
one address per. line.
set to yes to enable the alert, otherwise no.

Not implemented.
Set to yes to enable the log as an attachment, otherwise
no.

18.2 Using Email Alerts
having set up the pp_email.cfg file alerts will be sent automatically. The editable part
of pp_email.cfg can be modified using the Manager.

19 Hardware Requirements
Pi Presents can be used with either Model 1, Model 2 or Model 3 Pi's. However for a
better performance for videos or images a Model 2 or Model 3 Pi is preferred. The
GPIO pins have been chosen such that they are version agnostic.
If you wish to play videos 256MB of GPU memory must be used.
Display of images is slow with earlier Pi’s. A one megapixel images takes a couple of
seconds to display. The one 10 megapixel image I tried took 10 seconds to display
and crashed a 256MB Pi. Larger images, greater than the screen pixel dimensions,
will do nothing to improve the picture and will take longer to display even on 512MB
machines; I use the brilliant Faststone Photo Resizer
http://www.faststone.org/FSResizerDetail.htm to reduce the size of images on a
Windows PC.
Use the HDMI or headphone output for audio. Amplification and volume control will
need to be provided in external hardware to suit the application.

Page 103

Version 1.3.5a, 1 May 2018

20 Updating Pi Presents
20.1 Updating Profiles
As Pi Presents develops new fields are added to the profile definition and others
deleted. To control this, the three elements - Pi Presents, the editor and the profiles must have the same version. Pi Presents will warn if a profile with the wrong version
is used. To correct this open the profile in the editor, it will automatically update the
version of the profile and its fields and leave a backup in pp_profiles.bak. There may
be a few residual update tasks that cannot be automated; read the Release Notes to
identify these.
If you have many profiles to update in the same directory then you can use the
'Tools>Update All' menu option of the editor to update them.
The profiles in the pipresents-gapless-examples github repository will be kept
compatible with the latest version of Pi Presents. Beware, re-installing these may
overwrite profiles you have made.

20.2 Updating Pi Presents
For safety take a copy of the pipresents directory and any data before doing updates.
Download Pi Presents from github and install it as described in the README.md file.
Data stored in /home/pi/pp_home will not be affected. Do not store your data or
modify any files in the pipresents directories as they may be overwritten.
When updating Pi Presents read the release notes. You may need to update the
configuration files and carry out a few tasks that cannot be done automatically.

21 Debugging, Statistics, Bug Reports and Feature
Requests
21.1 Statistics Production
Pi Presents will output events to the file /pipresents/pp_logs/pp_stats.txt. The content
of the file is suitable for analysing to produce statistics on the use of an application.
The file contents CSV and suitable for reading into a spreadsheet. The separator is ;
it can be changed in pp_utils.py.
Statistics logging is enabled by the –d command line option as described in Section
21.2.
When Pi Presents starts, if the file pp_stats.txt does not exist it will be created and a
header line written. If the file exists it will not be deleted, further event rows will be
appended to those from the previous run of Pi Presents.

Page 104

Version 1.3.5a, 1 May 2018

There are four forms of event lines denoted by the command field:


Start – Indicates the Pi Presents has been started. Date/time and the name of
the profile are written.



start trigger, next trigger – Indicates that a mediashow or liveshow has
received a start or next trigger. The date/time and show details are written.



play child – Indicates that a mediashow or liveshow has received and event to
play a child track. Content is as for the events below.



other commands such as play, call – Menushows, Radiobuttonshows and
Hyperlinkshows write date/time, show details and track details when user
instigated events are detected.

Show details are show type, show reference, show title. Track details are track type,
track reference, track title and location.
Example:
"Date";"Time";"Show Type";"Show Ref";"Show Title";"Command";"Track Type";"Track
Ref";"Track Title";"Location"
"2016-02-01";"15:02:43";"";"";"";"start";"";"";"";"/1p3_examples/pp_interactive_1p3"
"2016-02-01";"15:02:53";"mediashow";"mediashow";"Mediashow";"play
child";"menu";"mymenu";"Menu";""
"2016-02-01";"15:02:58";"menu";"mymenu";"Menu";"play";"image";"";"A Stunning
River Scene";"+/media/river.jpg"

21.2 Debugging Profiles
The –d command line option allows a trace of the operation of Pi Presents to be
output to the terminal window and to a log file as described in Section 6.1. The –d
option has an argument which allow fine control of the log output
Value
(Binary)
1
10
100
1000
10000
100000
1000000
10000000
1000000000

Value
(decimal)

Log Output
1
2
4
8
16
32

Fatal (System) Errors
Profile Errors
Warnings
A log suitable for debugging profiles
A log suitable for debugging Pi Presents.
A log suitable for debugging Pi Presents with
instances of Player and Shower
64 Memory leak monitoring for debugging Pi Presents
128 Write events suitable for statistics production to
stats.txt. See Section 21.1
256 A log that is suitable debugging Time of Day
scheduling.

Without the –d option Pi Presents uses a value of 7. With the d option but no value
specified a value of 15 is used.

Page 105

Version 1.3.5a, 1 May 2018

Reporting of uncollectable garbage is permanently on. This may result in a message
being reported to the terminal when Pi Presents is closed. They indicate that Pi
Presents software is not deleting tracks or shows correctly. I am interested in these
reports.
In addition to the trace most of my debugging is by the use of Print statements in the
python code. I may have inadvertently left some of these statements in the code
resulting in messages on the terminal even if debugging is turned off.
Bug Reports and Feature Requests
Please use the Github Issues Tab https://github.com/KenT2/pipresentsgapless/issues to report bugs and ideas for extensions.
I am keen to improve Pi Presents and your input on real world experiences and
requirements would be invaluable to me, both minor tweaks to the existing
functionality and major improvements.

22 Gotchas and Known Problems
When not fullscreen the Pi Presents window is too small or too large
Edit the following lines in pipresents.py (around line 40).
self.nonfull_window_width = 0.6 # proportion of width
self.nonfull_window_height = 0.6 # proportion of height
self.nonfull_window_x = 0 # position of top left corner
self.nonfull_window_y=0 # position of top left corner
When using autostart, or running from a desktop shortcut my profile is not
found.
In any of these situations it is best to use the full path of pipresents and the data
home in commands e.g.
/usr/bin/python /home/pi/pipresents.py -o /home/pi -p myprofile
Also be aware that the location of the autostart file changed at the 25/12/2014
release of Raspbian Wheezy and its content is different for Raspbian Jessie.

Pi Presents locks up in full screen, how do I escape.
This is usually caused by Python reporting an exception due to incorrect
configuration data. To avoid this use validation in the editor and try the show, not full
screen, and running from a terminal window so you can Ctrl+C out if Ctrl+Break fails.
If this fails, try Ctrl+Z then closing the terminal window.
When Pi Presents crashes it sometimes leaves omxplayer mplayer or uzbl running.
You can see this using top. To remove these processes use:
killall omxplayer omxplayer.bin mplayer uzbl-core

Page 106

Version 1.3.5a, 1 May 2018

This may leave zombie processes. To remove these it seems necessary to close the
terminal window.
Pulling the power has potential for corruption, so the ideal solution to a seemingly
complete lockup is to SSH into the Pi from another machine, run top ( top -upi) and
kill the python process with the k xxxx command. You may need to kill an omxplayer
process as well.
My video/audio track does not play with Pi Presents
Try playing it using OMXPlayer or MPlayer from the command line.
Unclutter does not hide the cursor at all times
Azizar reported that he edited /etc/default/unclutter, adding
-grab
-noevents

I have built a gpio input or output device and it is not working with Pi Presents.
There are two stand alone GPIO test programs in the pipresents directory
input_test.py and output_test.py so you can test you I/O before blaming Pi Presents!
For B+ and 2b you will need to modify the python code to add the additional pins
(just uncomment the second definition of pins)

Pi Presents crashes after playing videos for a few hours
There seems to be some timing problem in the interface with OMXPlayer or with
OMXPlayer itself. I have tried to detect these crashes and allow Pi Presents to
continue. If you have such problems and can reliably reproduce them without using
Pi Presents please report them on the omxplayer github.

Page 107

Version 1.3.5a, 1 May 2018

23 Converting Version 1.2 to 1.3
There are significant changes between the versions. pp_editor,py will insert and
delete fields in the profile but the following will require manual intervention

Change
Pi Presents
It is now not necessary to use the –o command
line option when using sudo (from 1.3.1h sudo is
not required)
The –g command line option has been removed.
GPIO is enabled by the presence of a gpio.cfg file
in the profile (not in data home or
/pipresents/pp_home).
Shows
Links field and Controls Field have been combined
into a field called Controls. The functionality is
unchanged. Controls bind Symbolic Names to
Commands, the words Internal Operation and Link
are not used any more, both are called
Commands.
In Version 1.2 Subshows and Child Shows
inherited their Controls from their parent show.
All shows now require their own set of Controls.
Newly created mediashows and liveshows have a
useful set pre-defined but you will need to insert
the following into existing mediashows, liveshows
and menus:
pp-down down
pp-up up
pp-play play
pp-stop stop
pp-pause pause
The Show and Track Background are now
‘warped’ to the size of the Show Canvas

Reason

Pi Presents detects the use of
sudo and compensates
Enables future user coded I/O
plugins.

Make all shows operate in the
same way to ease
understanding.

In 1.2 the parent and subshow
could not have different types
of control (e.g. links and
internal operations) so a
mediashow called from a
Hyperlinkshow could not be
controlled.

Makes it easier to modify the
size of show canvas windows in
multi-window applications

The Interval, Show Timeout and Track Timeout
fields now use hh:mm:ss instead of secs.
Currently >59 seconds is allowed but this might
change.
Commands and Symbolic Names
pp-exit pre-defined symbolic name is now ppexitpipresents
In keys.cfg pp-exit is now pp-terminate

avoid clashes of terminology
avoid clashes of terminology

Mediashow

Page 108

Version 1.3.5a, 1 May 2018

The triggers and other show control fields have
been re-organised and expanded
• interval and singleshot needs to be replaced
by repeat.
• Time of Day Triggers are replaced by the Time
of Day Scheduler.
• Review all mediashows and liveshows for
correct functioning as there are many
modifications.
The has-child field has been removed. Instead
there is a Child field that contains the trackreference of a track in the medialist if a child is
required.
Will require the child field to be completed.
Manual progress has been removed. Use tracks
with 0 duration instead. Use freeze at end if you do
not want videos to auto advance.
The input-quiet trigger type has been removed.
Instead delete the trigger text in the notices tab.
Some fields have been moved between tabs
Start Trigger cannot now be triggered by Play or
Down commands. If trigger by a key is required
then bind start trigger to a key.
Liveshow
In version 1.2 the liveshow and mediashow had
completely different code. In version 1.3 much of
the code is common which means all the features
of mediashow are available.

Much improved mediashow
triggering and control.

Recognition that a ‘child show’
is actually just a track that is
accessible from all tracks in a
mediashow. Being a track in
can be a Show Track.
Manual made the code even
more complex and
presentations not a high priority
for Pi Presents.

Make shows consistent.

Enhancement

Review liveshows to ensure they function correctly
Menu
In version 1.2 the layout of the menu was
determined by the Show Profile.
In Version 1.3 there is a Menu Type track in the
medialist which determines the layout of the menu.
pp_editor will do the conversion and insert a ‘menu
track’ into a copy of the medialist called xxx –
menu1p3. The conversion retains the old medialist
file which can be deleted.
The menu background is now specified in the
show profile. The menu background track can be
deleted.
The location of default bullet is now
/pipresents/pp_resources/bullet.png
Click Areas
screen.cfg has additional mandatory fields allowing
a click area to have an image.
Add to each section is screen.cfg:
image =

All shows are structured the
same making software
maintenance easier.

All shows are structured the
same making software
maintenance easier.

Click areas can have button
images.

Page 109

Version 1.3.5a, 1 May 2018

image-width =
image-height=
Track Plugins
The API has changed significantly. They will need
a rewrite.
Show Control
The order of fields in the Show Control field has
been reversed and the names of the commands
changed.

Be compatible with gapless
transitions and multi-windows

Allows OSC commands.
Names changed to avoid
confusion caused by command
clashes.

‘myshow start’ > ‘open myshow’
‘myshow stop’ > ‘close myshow’
‘gobdegook exit’ > ‘exitpipresents’
Animation
The order of fields in animation commands has
been changed and the command fields expanded

Provision for additional I/O
plugins with more complex
command formats.

‘out1 on 10’ > ’10 out1 state on’
The delay field is now mandatory.

GPIO
Whether to use GPIO is now determined by the
presence of a gpio.cfg file in the /pp_io_config
directory in a profile. The –g command line option
is not now used.
Pins for B+ and 2B will need to be added to
gpio.cfg. If not a warning is given.

Configuration Files
In a profile keys.cfg, gpio.cfg, and screen.cfg need
to be moved to a subdirectory /pp_io_config. The
new osc.cfg will reside there as well.
schedule.json is in the profile not in the
subdirectory.

/pipresents/pp_home has been removed

Required to allow users to add
I/O plugins (see below)

These are configuration files for
I/O device drivers. When the
I/O plugin API is implemented a
plugin will be enabled by the
existence of a configuration file
in the /pp_io_config directory in
a profile.
Having a pp_home in two
places could be confusing.

The fields of resources.cfg are now in the show
profile. These fields will require re-populating with
your choice of text.

Allows different concurrent
shows to have different
messages.

Fallbacks of gpio.cfg,, screen.cfg, and keys.cfg are
now not allowed in /pp_home and in
/pipresents/pp_home. They must be in the profile.

These are configuration files for
I/O device drivers. When the
I/O plugin API is implemented a
plugin will be enabled by the
existence of a configuration file

If necessary copy gpio.cfg and screen.cfg into the

Page 110

Version 1.3.5a, 1 May 2018

profile (in a pp_io_config directory). keys.cfg still
has a fallback in /pipresents/pp_io_config; only
need to copy this if you have modified it.
NOTE: In keys.cfg pp-exit is now pp-terminate
There are templates for screen.cfg, gpio.cfg and
schedule.json in /pp_resource/pp_templates, and
for keys,cfg in /pp_io_config. These can be copied
to profiles and modified.
controls.cfg has been removed.
Limited other resources used as fallbacks by Pi
Presents are in /pp_resources.. It is best to put
resources for an application in the profile or in
pp_home and not modify /pipresents subdirectories.

in the /pp_io_config directory in
a profile.
There is one exception, to
make it easy for beginners
there is a fallback keys.cfg in
/pipresents/pp_io_config

It is replaced by every show
having its own set of controls.
Updating of Pi Presents is less
likely to cause you problems.

Editor
Validation has not caught up with the changes to
the profiles. There should be no correct profiles
that fail but there could be undetected profile errors

Page 111



Source Exif Data:
File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.3
Linearized                      : No
Page Count                      : 111
Producer                        : Nitro PDF PrimoPDF
Create Date                     : 2018:05:01 19:58:40-01:00
Modify Date                     : 2018:05:01 19:58:40-01:00
Title                           : Microsoft Word - manual_1p3p5a.doc
Creator                         : PrimoPDF http://www.primopdf.com
Author                          : Ken
EXIF Metadata provided by EXIF.tools

Navigation menu