Table of Contents
- Run Platypush in a virtual environment
- Run Platypush in a container
- Writing your plugins
- Writing your backends
The base components are:
Messages: requests, responses or events. The main difference between a request and an event is that the former specifies an explicit action to be executed through a plugin (and the sender will usually wait for a response), while an event only notifies that something happened on a connected data source and can either be ignored or trigger some custom actions specified in the configuration.
The Bus: An internal queue where all the other components exchange messages.
Backends: Components that poll other data sources (a local queue, a remote websocket, a Kafka instance, or even a vocal assistant, a programmable button or a sensor) and post either requests or events on the bus when something happens on the data source. Some of them can have a full-duplex integration with the bus, i.e. post requests and events on the bus as they come and deliver responses from the bus back to the sender (examples: PushBullet, Apache Kafka, HTTP services, sockets), while some are pure data sources that will only post events on the bus (examples: sensors, buttons, vocal assistants). Check our documentation for a complete reference of the available backends.
Plugins: Configurable components which expose actions that can be triggered by requests or events. Examples: smart lights, music controls, YouTube or torrentcast features, text-to-speech, generic shell commands, etc.). They would usually deliver output and errors as responses on the bus. Check our documentation for a complete reference of the available plugins.
Procedures: Pre-configured lists of actions that can be triggered by requests or events.
Event Hooks: Pre-configured actions that will be executed when certain events are processed. They include:
- A condition, which can be fuzzly compared against an event. The matching logic will also return a match score if the condition is met. The score is a function of the number of atomic matches (string tokens, scalars, key-values etc.) in the condition that are satisfied by a certain event. If multiple hooks are satisfied by a certain event, the algorithm will only run the ones with the highest score.
- One or more actions to be executed in case of event match (e.g. "turn on the lights", "send a Messenger message to my s.o.", "turn on the heating", "play the radio" etc.)
Check our documentation for a complete reference of the available events.
First install Redis, as it's used as a bus for delivering messages to platypush. On Debian/Ubuntu for example:
apt-get install redis-server
# Start and enable the service
systemctl start redis.service
systemctl enable redis.service
Then install platypush:
pip install platypush
git clone https://github.com/BlackLight/platypush
python setup.py build install
There are four possible ways to install extra dependencies for the plugins and backend that you want to run on your instance.
Upon installation, Platypush provides two utilities (
platydock) that allow you to easily create
respectively a virtual environment or a Docker image for your Platypush application from a
config.yaml file, including all the plugins and backends that you want to enable. You can also include
external YAML files through the
include directive (as long as they are in the same folder as your
and also custom Python scripts in the
Make sure to define a
device_id field in your
config.yaml. It defines the name that
platydock use to
identify and manage the service.
Building the environment/image
platyvenv build -c /path/to/your/config.yaml
platydock build -c /path/to/your/config.yaml
Starting the environment/image
platyvenv start <device_id>
platydock start <device_id>
Stopping the environment/image
platyvenv stop <device_id>
platydock stop <device_id>
Removing the environment/image
platyvenv rm <device_id>
platydock rm <device_id>
You can easily install the optional dependencies for the extra plugins you want to use by using the PEP-508 extras syntax. For example, if you want to run the HTTP server then you can install it through:
pip install "platypush[http]"
You can check the supported extras in the
setup.py file. Installation of comma-separated lists of extras is also supported.
The official documentation provides manual installation steps for all the supported extensions.
Copy the example
/etc/platypush/config.yaml (global installation, discouraged) or
(user installation, recommended).
Explore it to get a grasp of the basic components of Platypush and their configuration and change it according to your needs.
After configuring the server, start it by simply running
python -m platypush. You can also a systemd service by copying the example
platypush.service to either
/usr/lib/systemd/user/platypush.service (global installation) or
~/.config/systemd/user/platypush.service (user installation).
NOTE: Platypush is only compatible with Python 3 and higher.
After installing the application, you're ready to start configuring it according to your needs.