xcape-io / pyprops

Library to make MQTT props Python applications for Escape Room 2.0 with Raspberry Pi.

PyProps library

Library for escape room Raspberry props written in Python.

With the PyProps library you can start coding a Raspberry prop for you escape room 2.0 in a few minutes.

PyProps core library:

• hide the code to publish / subscribe messages with MQTT
• hide the complexity to create non-blocking asynchronous code
• expose a rotating file logger
• code is robust to work 24/7

PyProps examples:

• show how to code a prop in a few lines
• provide code for common sensors / actuators

Read RASPBERRY_PI_PROPS.md to prepare your Rasbpberry Pi board ready for PyProps installation.

Read INSTALLATION.md for PyProps installation and usage.

Props unified coding

PyProps supports different Python frameworks to write any kind of props providing a base class for your props:

• AsyncioProp
• PygameProp
• QtProp
• GuizeroProp
• KivyProp

Each props base class extends the base class MqttApp which handles messaging and the base class PropApp which handles the periodic actions and the simple Room Outbox protocol protocol.

PropData is a base class that manages the prop data variables sent to the outbox.

Singleton class will guarantee that only one instance of the prop program runs on the Raspberry board.

Each prop must have its own constants.py and definitions.ini configuration files related to the escape room MQTT topics and to the prop flavor.

logging.ini is the logger configuration file which can be used as is.

main.py is the main prop script to:

• ensure only one instance of the prop program is running
• initialize GPIO
• create the Paho MQTT client
• create the prop class
• start MQTT client event loop
• start prop framework event loop
• cleanup GPIO at end
• stop MQTT client event loop at end

Props flavors

The PyProps library takes advantage for many Python frameworks available on the Raspberry Pi running Raspbian to meet the requirements of any prop created for escape rooms.

Asyncio framework: AsyncioProp

With AsyncioProp flavor, you code props that do not need a graphical interface:

• sensors and actuators (GPIO and I2C shieds)
• sound (playsound, pydub, aplay, mplayer, mpg123)
• examples:
  • educational example which echoes messages and make a LED blinking (PyBlinkEcho)
  • detect vibrations to trigger a crying doll (PyCryingDollProp)

The asyncio framework allows writing non-blocking Python programs that multitask seamlessly.

AsyncioProp prop hides the complexity of the asyncio framework and adds MQTT asynchronous messaging to facilitate your coding.

Pygame framework: PygameProp

The Pygame framework is easy to use and is powerful for:

• audio and video output
• simultaneous sounds
• keyboard, mouse and joystick input
• video games
• sensors and actuators (GPIO and I2C shields)
• examples:
  • educational blink example (PygameBlinkProp)
  • piano prop with a mechanic piano (PygamePianoProp)
  • podium with linear jack (PygamePodiumProp)
  • hacker intrusion puzzle (contact me)
  • Tetris hacked (contact me)

The Pygame framework (see pygame.org) is very popular and very easy to learn so the PygameProp flavor may be your preferred choice most of the time.

Pygame has its own event loop to multitask seamlessly.

PygameProp adds MQTT asynchronous messaging to the Pygame framework to facilitate your coding.

PyQt5 framework: QtProp

PyQt5 brings the power of Qt to Python and is well supported on Raspberry Pi.

Console and GUI props with PyQt5:

• multimedia playback
• graphics effects
• sensors and actuators (GPIO and I2C shieds)
• Bluetooth support,
• printing support,
• styled GUI (Qt Style Sheets)
• Qt Signals & Slots mechanism
• the power of Qt (GUI widgets, styled GUI, multimedia, Bluetooth, printing support, etc.)
• easy to reuse the props code in a control panel (necessary for complex props such as fingerprint biometric props with 2 Raspberry boards)
• reuse the props code for its associated control applet
• use the associated control applet as a Room plugin
• examples:
  • educational blink example (QtEducationalProp)
  • fortune teller table (FortuneTellerTableProp)
  • game countdown in the escape room on Raspberry TV screen (QtCountdownProp)

PyQt5 has its own event loop to multitask seamlessly.

QtProp extends either QCoreApplication or QApplication object to add MQTT asynchronous messaging to the PyQt5 framework to facilitate your coding.

Guizero (Tkinter GUI) framework: GuizeroProp

Guizero is a very simple and easy GUI framework built over Tkinter so if you need a simple GUI for your prop it's a reasonable choice and if you need more features you have access to Tkinter via the _gui.tk property.

GuizeroProp is suitable for:

• simple graphical interface for a Raspberry with a TV display
• sensors and actuators (GPIO and I2C shieds)
• sound (playsound, pydub, aplay, mplayer, mpg123)
• example:
  • display text on the prop TV monitor (PyTeletextProp)

See Guizero Gettings Started and the Guizero widgets from the same web page.

GuizeroProp extends Guizero App object to add MQTT asynchronous messaging to the Guizero framework to facilitate your coding.

Kivy framework: KivyProp

Kivy is a very powerful framework but is not that simple therefore more particularly recommended for advanced Python developers.

KivyProp is suitable for:

• powerful graphical interface for a Raspberry with a TV display
• video effects
• video games
• audio
• camera, keyboard, mouse and joystick input
• multi-touch app
• sensors and actuators (GPIO and I2C shieds)
• example:
  • display text on the prop TV monitor (PyWaterWellProp)

To learn the Kivy framework, a goods start is Kivy Guides.

KivyProp extends KivyApp object to add MQTT asynchronous messaging to the Kivy framework to facilitate your coding.

Compatible hardware

PyProps library supported hardware:

• Raspberry Pi boards
• Any computer or IoT board supporting Python 3

For GPIO support, PyProps library comes with code for Raspberry Pi 3 and Pi 4.

Eric IDE or PyCharm Professional

You can use any Python IDE for your props development, however we recommend:

• Eric IDE to code and debug directly on the props via the VNC viewer
• PyCharm Professional on your PC to code and debug remotely

Eric IDE is free, powerful particularly for debugging and its installation is easy:

$ sudo apt-get install qt5-default pyqt5-dev pyqt5-dev-tools
$ sudo apt-get install eric

Author

Faure Systems (Apr 18th, 2020)

• company: FAURE SYSTEMS SAS
• mail: dev at faure dot systems
• github: xcape-io
• web: xcape.io