Customize using plugins
The pibooth
application is built on the top of
pluggy
that gives users the ability to extend or modify its behavior thanks to plugins.
Several plugins maintained by the community are available. They add extra features to
pibooth
. Have a look to the plugins on PyPI.
You can also easily develop your own plugin, and declare it in the [GENERAL][plugins]
key of the configuration.
What is a plugin?
A plugin is a set of functions (called hooks
) defined in a python module
and participating to the pibooth
execution when they are invoked.
The list of available hooks
are defined on this chapter. A plugin
implements a subset of those functions.
There are 2 families of hooks implemented in pibooth:
Pibooth state-independent hooks
State dependant hooks (see below)
Influencing states
The pibooth
application is built on the principle of states. Each state
is defined by a specific screen and possible actions available to the user.
The following states are defined:
wait
: wait for starting a new capture sequence
choose
: selection of the number of captures
chosen
: confirm the number of captures
preview
: show preview and countdown
capture
: take a capture
processing
: build the final picture
finish
: thank before going back to wait state
failsafe
: oops message when an exception occurs
There are four hooks defined for each state.
state_<name>_enter
Invoked one time when the state is activating.
state_<name>_do
Invoked in a loop until the state is switching to an other one.
state_<name>_validate
Invoked in a loop, returns the name of the next state if all conditions are met (else return
None
).
state_<name>_exit
Invoked one time when the state is exiting.
Code skeleton
A plugin is generally a Python module called pibooth_[...].py
. For a better
configuration management, it should have the constant __version__
set to the
plugin version:
__version__ = "1.0.0"
The pibooth_configure
hook permits to define some new configuration options.
At this step of the starting process, only the pre-loaded configuration is
available (application is not created yet).
@pibooth.hookimpl
def pibooth_configure(cfg):
cfg.add_option('CONTROLS', 'startup_led_pin', 29,
"Physical GPIO OUT pin to light a LED at pibooth startup")
The new objects, which should persist between states, can be created and attached
to the application instance in the pibooth_startup
hook:
@pibooth.hookimpl
def pibooth_startup(cfg, app):
app.led_startup = LED("BOARD" + cfg.get('CONTROLS', 'startup_led_pin'))