15 Home
Fabio Manganiello edited this page 11 months ago

Platypush

Architecture

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.

Installation

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

Manual Installation

git clone https://github.com/BlackLight/platypush
cd platypush
python setup.py build install

Extra dependencies

There are four possible ways to install extra dependencies for the plugins and backend that you want to run on your instance.

platyvenv and platydock

Upon installation, Platypush provides two utilities (platyvenv and platydock) that allow you to easily create respectively a virtual environment or a Docker image for your Platypush application from a config.yaml.

Write your 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 config.yaml), and also custom Python scripts in the scripts directory.

Make sure to define a device_id field in your config.yaml. It defines the name that platyvenv/platydock use to identify and manage the service.

Building the environment/image
platyvenv build -c /path/to/your/config.yaml
# or
platydock build -c /path/to/your/config.yaml
Starting the environment/image
platyvenv start <device_id>
# or
platydock start <device_id>
Stopping the environment/image
platyvenv stop <device_id>
# or
platydock stop <device_id>
Removing the environment/image
platyvenv rm <device_id>
# or
platydock rm <device_id>

pip extras

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.

Plugins/backends documentation

The official documentation provides manual installation steps for all the supported extensions.

Configuration

Copy the example config.yaml to /etc/platypush/config.yaml (global installation, discouraged) or ~/.config/platypush/config/config.yaml (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.

Start up

After configuring the server, start it by simply running platypush, 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.