/PyTeletextProps

Connected Escape Room props to display messages received from MQTT server on Raspberry Pi display monitor.

Primary LanguagePythonMIT LicenseMIT

Teletext props

Display messages in the Escape Room with a Raspberry Pi.

Smiley face Discontinued, prefer PyTeletexProp in PyProps library

This props listens to MQTT messages and then displays the text on an HDMI display, rings a bell and turns on a light for 3 seconds.

Messages are sent by the game master with the Teletext Plugin or any application able to publish MQTT messages.

The Teletext Plugin can be used as a standalone applet, without the need of Room software. If you use Room software, you will find detailed installation help in the Room manual.

Installation

Download PyTeletextProps-master.zip from this GitHub repository and unflate it on your Raspberry Pi.

Install dependencies

pip3 install -r requirements.txt

Edit definitions.ini to set MQTT topics for your Escape Room:

[mqtt]
; mqtt-sub-* and app-inbox topics are subscribed by MqttApp
app-inbox = Room/My room/Props/Raspberry Teletext/inbox
app-outbox = Room/My room/Props/Raspberry Teletext/outbox
mqtt-sub-room-scenario = Room/My room/Control/game:scenario

Usage

Start teletext.py script:

usage: python3 teletext.py [-h] [-s SERVER] [-p PORT] [-d] [-l LOGGER]

optional arguments:
 -h, --help   show this help message and exit
 -s SERVER, --server SERVER
      change MQTT server host
 -p PORT, --port PORT change MQTT server port
 -d, --debug   set DEBUG log level
 -l LOGGER, --logger LOGGER
      use logging config file

To switch MQTT broker, kill the program and start again with new arguments.

Understanding the code

TeletextApp

Teletext props is built with the following files:

  • teletext.py main script to start the props
  • constants.py
  • definitions.ini
  • logging.ini
  • TeletextApp.py props related code

It depends on:

  • GuizeroApp.py base class to create a guizero event loop
  • MqttApp.py base class to publish/subscribe MQTT messages
  • MqttVar.ini base class to optimize network communications
  • Singleton.ini to ensure one instance of application is running
  • Sound.py simple aplay wrapper

Use TeletextApp as a model to create your own connected props if you need simple text display, sound playback. You can also add GPIO stuff.

About create-teletextprops-tgz.bat:

  • install 7-Zip on your Windows desktop
  • run create-teletextprops-tgz.bat to archive versions of your work

MQTT message protocol:

This props has been created for Live Escape Grenoble rooms, controlled with Room software so MQTT messages published in the props outbox implement the Room Outbox protocol.

IDE for hacking TeletextApp.py:

You can open a PyCharm Professional project to hack the code remotely, thanks to .idea folder. Or if you prefer to the code hack directly on the Raspberry, we suggest Eric6 IDE.

GuizeroApp base class

TeletextApp extends GuizeroApp, python base app for Raspberry connected props which require simple text display.

For more advanced text display (visual effects, True-Type fonts) you may see Kivi props below such as TelefxProps.

GUI is built with guizero library. If you don't need display, prefer Asyncio props.

Extend this base class to build a connected props which does simple text display, sound playback. Optionally you can GPIO stuff.

You might not modify GuizeroApp.py file.

MqttApp and MqttVar base classes

GuizeroApp extends MqttApp, the python base app for Raspberry connected props.

MQTT topics are defined in definitions.ini.

PubSub variables extend MqttVar, it is an helper to track value changes and to optimize publishing values in MQTT topic outbox.

You might not modify MqttApp.py an MqttVar.py files.

Notes about MQTT QoS:

Python script hangs have been reported when paho-mqtt is running asynchronously with QoS 2 on a network with significant packet loss (particularly Wifi networks).

We have choosen MQTT QoS 1 as default (see constants.py).

Other python frameworks for connected props

At Faure Systems we engineered connected props with several frameworks for many different needs:

  • Asyncio props
    • game automation
    • relay box control (room electricity and doors)
    • GPIO only automation
  • PyGame props
    • Tetris hacked
    • mechanic Piano sound player
    • hacker intrusion puzzle
  • PyQt5 props
    • fortune telling table (alphanum LED switching)
    • electric jack cylinder control
  • Guizero props
    • teletext
  • Kivy props
    • teletext with visual effects

You may follow on our GitHub repositories, props source code is planned to be published in year 2020.

Author

Faure Systems (Oct 9th, 2019)