A versatile and extensible platform for home and life automation with hundreds of supported integrations
Go to file
Fabio Manganiello 99de5318ff
Merge pull request #313 from BlackLight/snyk-upgrade-58f5a7acf019c661bec911d06f0bf10a
[Snyk] Upgrade core-js from 3.21.1 to 3.23.4
2022-08-05 13:26:25 +02:00
.gitlab Moved CI automation from Platypush hooks to Gitlab CI 2021-09-22 00:04:11 +02:00
assets Refactored documentation and changed theme 2021-07-17 14:41:35 +02:00
bin - Updated docs. 2021-09-16 23:28:00 +02:00
docs Updated wiki URLs and replaced Gitlab references with Gitea 2022-07-06 22:01:25 +02:00
examples Dockerfile should be part of the examples/ folder 2021-03-16 00:29:52 +01:00
platypush Merge pull request #313 from BlackLight/snyk-upgrade-58f5a7acf019c661bec911d06f0bf10a 2022-08-05 13:26:25 +02:00
tests Fix for #217 2022-04-28 00:57:49 +02:00
.gitignore gitignore 2022-02-21 22:23:40 +01:00
.gitlab-ci.yml Updated CI/CD pipeline - now using repo tokens to push new releases to pypi 2022-03-01 12:50:13 +01:00
.gitmodules No need to keep the wiki as a submodule 2021-02-02 01:26:54 +01:00
.pre-commit-config.yaml Added more pre-commit hooks 2022-04-04 17:21:47 +02:00
CHANGELOG.md Updated wiki URLs and replaced Gitlab references with Gitea 2022-07-06 22:01:25 +02:00
CONTRIBUTING.md Updated wiki URLs and replaced Gitlab references with Gitea 2022-07-06 22:01:25 +02:00
LICENSE.txt Copyright year update 2020-09-28 13:11:07 +02:00
MANIFEST.in [WIP] Default config.yaml in case a configuration file is missing in the default locations 2022-04-25 16:54:26 +02:00
README.md Updated wiki URLs and replaced Gitlab references with Gitea 2022-07-06 22:01:25 +02:00
generate_missing_docs.py Removed unused import 2022-03-27 22:01:25 +02:00
pyproject.toml Don't raise a pytest warning upon the asyncio "No event loop" warning 2022-04-27 23:25:14 +02:00
requirements.txt HTTP backend dependencies moved from optional to required 2022-04-27 14:52:41 +02:00
setup.cfg Bump version: 0.23.2 → 0.23.3 2022-06-01 23:08:32 +02:00
setup.py Bump version: 0.23.2 → 0.23.3 2022-06-01 23:08:32 +02:00

README.md

Platypush

Build Status Documentation Status pip version License Last Commit Join chat on Matrix Contributions Language grade: Python Language grade: JavaScript

  • Recommended read: Getting started with Platypush.

  • The blog is in general a good place to get more insights on what you can build with it and inspiration about possible usages.

  • The wiki also contains many resources on getting started.

  • Extensive documentation for all the available integrations and messages is available.

  • If you have issues/feature requests/enhancement ideas please create an issue.

  • A Reddit channel is also available for more general questions.

  • A Matrix instance is also available if you are looking for more interactive support.


Platypush is a general-purpose extensible platform for automation and integration across multiple services and devices.

It enables users to create their own self-hosted pieces of automation based on events (if this happens then do that) and it provides a comprehensive and customizable user interface that collects everything you need to visualize and control under one roof.

It takes some concepts from IFTTT, Tasker, Microsoft Flow, PushBullet and Home Assistant to provide an environment where the user can easily connect things together.

Its ideal home is a single-board computer like a RaspberryPi that you can configure to orchestrate any home automation and cloud automation in your own living room or garage, but it can easily run on any device that can run a Python interpreter, and the bar for the hardware requirements is very low as well - I use it to run pieces of automation on devices as powerful as a RaspberryPi Zero or an old Nokia N900 with Linux.

You can use Platypush to do things like:

Architecture

The architecture of Platypush consists of a few simple pieces, orchestrated by a configuration file stored by default under ~/.config/platypush/config.yaml:

Plugins

Full list

Plugins are integrations that do things - like modify files, train and evaluate machine learning models, control cameras, read sensors, parse a web page, control lights, send emails, control Chromecasts, run voice queries, handle torrent transfers or control Zigbee or Z-Wave devices.

The configuration of a plugin matches one-on-one that of its documented class constructor, so it's very straightforward to write a configuration for a plugin by reading its documentation:

light.hue:
  # Groups that will be controlled by default
  groups:
    - Living Room
    - Hall

Actions

Plugins expose actions, that match one-on-one the plugin class methods denoted by @action, so it's very straightforward to invoke plugin actions by just reading the plugin documentation. They can be invoked directly from your own scripts or they can be sent to the platform through any supported channel as simple JSON messages:

{
  "type": "request",
  "action": "light.hue.on",
  "args": {
    "lights": ["Entrance Bulb"]
  }
}

Backends

Full list

They are background services that either listen for messages on channels (like an HTTP backend, an MQTT instance, a Kafka instance, a Websocket service, Pushbullet etc.) or monitor a device or a service for events (like a sensor, a custom voice assistant, a bridge running on a Zigbee or Z-Wave, an NFC card reader, a MIDI device, a Telegram channel, a Bluetooth scanner etc.).

If a backend supports the execution of requests (e.g. HTTP, MQTT, Kafka, Websocket and TCP) then you can send requests to these services in JSON format. For example, in the case of the HTTP backend:

    # Get a token
curl -XPOST -H 'Content-Type: application/json' -d '
  {
    "username": "$YOUR_USER",
    "password": "$YOUR_PASSWORD"
  }' http://host:8008/auth

    # Execute a request

curl -XPOST -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $YOUR_TOKEN" -d '
  {
    "type": "request",
    "action": "tts.say",
    "args": {
      "text": "This is a test"
    }
  }' http://host:8008/execute

Events

Full list

When a certain event occurs (e.g. a JSON request is received, or a Bluetooth device is connected, or a Flic button is pressed, or some speech is detected on the voice assistant service, or an RSS feed has new items, or a new email is received, or a new track is played, or an NFC tag is detected, or new sensor data is available, or a value of a Zigbee device changes, etc.), the associated backend will trigger an event.

Hooks

Event hooks are custom pieces of logic that will be run when a certain event is triggered. Hooks are the glue that connects events to actions, exposing a paradigm similar to IFTTT (if a certain event happens then run these actions). They can declared as:

event.hook.SearchSongVoiceCommand:
  if:
    type: platypush.message.event.assistant.SpeechRecognizedEvent
    phrase: "play ${title} by ${artist}"
  then:
    - action: music.mpd.clear
    - action: music.mpd.search
      args:
        filter:
          artist: ${artist}
          title: ${title}

    - if ${len(output)}:
      - action: music.mpd.play
        args:
          resource: ${output[0]['file']}
  • Stand-alone Python scripts stored under ~/.config/platypush/scripts and will be dynamically imported at start time. Example:
from platypush.event.hook import hook
from platypush.utils import run
from platypush.message.event.assistant import SpeechRecognizedEvent

@hook(SpeechRecognizedEvent, phrase='play ${title} by ${artist}')
def on_music_play_command(event, title=None, artist=None, **context):
  results = run('music.mpd.search', filter={
    'artist': artist,
    'title': title,
  })

  if results:
    run('music.mpd.play', results[0]['file'])

Procedures

Procedures are pieces of custom logic that can be executed as atomic actions using procedure.<name> as an action name.

They can be defined either in the config.yaml or as Python scripts stored under ~/.config/platypush/scripts - provided that the procedure is also imported in ~/.config/platypush/scripts/__init__.py so it can be discovered by the service.

YAML example for a procedure that can be executed when we arrive home and turns on the lights if the luminosity is lower that a certain thresholds, says a welcome home message using the TTS engine and starts playing the music:

procedure.at_home:
    # Get luminosity data from a sensor - e.g. LTR559
    - action: gpio.sensor.ltr559.get_data

    # If it's lower than a certain threshold, turn on the lights
    - if ${int(light or 0) < 110}:
        - action: light.hue.on

    # Say a welcome home message
    - action: tts.google.say
      args:
        text: Welcome home

    # Play the music
    - action: music.mpd.play

Python example:

    # Content of ~/.config/platypush/scripts/home.py
from platypush.procedure import procedure
from platypush.utils import run

@procedure
def at_home(**context):
  sensor_data = run('gpio.sensor.ltr559.get_data')
  if sensor_data['light'] < 110:
    run('light.hue.on')

  run('tts.google.say', text='Welcome home')
  run('music.mpd.play')

In either case, you can easily trigger the at-home procedure by sending an action request message to a backend - for example, over the HTTP backend:

curl -XPOST -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $YOUR_TOKEN" -d '
  {
    "type": "request",
    "action": "procedure.at_home"
  }' http://host:8008/execute

Cronjobs

Cronjobs are pieces of logic that will be run at regular intervals, expressed in crontab-compatible syntax. They can be defined either in the config.yaml or as Python scripts stored under ~/.config/platypush/scripts as functions labelled by the @cron decorator.

Note that seconds are also supported (unlike the standard crontab definition), but, for back-compatibility with the standard crontab format, they are at the end of the cron expression, so the expression is actually in the format <minute> <hour> <day_of_month> <month> <day_of_week> <second>.

YAML example for a cronjob that is executed every 30 seconds and checks if a Bluetooth device is nearby:

cron.check_bt_device:
  cron_expression: '* * * * * */30'
  actions:
    - action: bluetooth.lookup_name
      args:
        addr: XX:XX:XX:XX:XX:XX

    - if ${name}:
        - action: procedure.on_device_on
    - else:
        - action: procedure.on_device_off

Python example:

    # Content of ~/.config/platypush/scripts/bt_cron.py
from platypush.cron import cron
from platypush.utils import run

@cron('* * * * * */30')
def check_bt_device(**context):
  name = run('bluetooth.lookup_name').get('name')
  if name:
    # on_device_on logic here
  else:
    # on_device_off logic here

The web interface

If backend.http is enabled then a web interface will be provided by default on http://host:8008/. Besides using the /execute endpoint for running requests, the built-in web server also provides a full-featured interface that groups together the controls for most of the plugins - e.g. sensors, switches, music controls and search, media library and torrent management, lights, Zigbee/Z-Wave devices and so on. The UI is responsive and mobile-friendly.

The web service also provides means for the user to create custom dashboards that can be used to show information from multiple sources on a large screen.

Installation

System installation

Platypush uses Redis to deliver and store requests and temporary messages:

    # Example for Debian-based distributions
[sudo] apt-get install redis-server

    # Enable and start the service
[sudo] systemctl enable redis
[sudo] systemctl start redis

Install through pip

[sudo] pip3 install platypush

Install through a system package manager

Note: currently only Arch Linux and derived distributions are supported.

You can either install the platypush package (for the latest stable version) or the platypush-git package (for the latest git version) through your favourite AUR package manager. For example, using yay:

yay platypush
# Or
yay platypush-git

The Arch Linux packages on AUR are automatically updated upon new git commits or tags.

Install from sources

git clone https://git.platypush.tech/platypush/platypush.git
cd platypush
[sudo] pip install .
    # Or
[sudo] python3 setup.py install

Installing the dependencies for your extensions

After installing the base platform, you may want to check the dependencies and configuration required by the extensions that you wish to use. There are a few ways to check the dependencies required by an extension:

Install via extras name

All the extensions that require extra dependencies are listed in the extras_require section under setup.py.

Install via manifest.yaml

All the plugins and backends have a manifest.yaml file in their source folder. Any extra dependencies are listed there

If you followed the extras or manifest.yaml way to discover the dependencies, then you can install them in two ways:

  1. pip installation:
[sudo] pip3 install 'platypush[extra1,extra2,extra3]'
  1. Sources installation:
cd $DIR_TO_PLATYPUSH
[sudo] pip3 install '.[extra1,extra2,extra3]'

Check the instructions reported in the documentation

If you follow this route then simply run the commands listed in the plugin/backend documentation to get the dependencies installed.

After installing the dependencies, create a configuration file under ~/.config/platypush/config.yaml (the application can load the configuration from another location through the -c option) containing the configuration of the backend and plugins that you want to use, and add any hooks and procedures for your use case.

You can then start the service by simply running:

platypush

It's advised to run it as a systemd service though - simply copy the provided .service file to ~/.config/systemd/user, check if the path of platypush matches the path where it's installed on your system, and start the service via systemctl:

systemctl --user start platypush

Virtual environment installation

Platypush provides a script named platyvenv that can parse a config.yaml and automatically create a virtual environment (under ~/.local/share/platypush/venv/<device_id>) with all the dependencies required by the configured integrations.

  1. Create the environment from a configuration file:

    platyvenv build -c /path/to/config.yaml
    
  2. Start the service from the virtual environment:

        # device_id matches either the hostname or the device_id in config.yaml
    platyvenv start device_id
    
  3. Stop the instance:

    platyvenv stop device_id
    
  4. Remove the instance:

    platyvenv rm device_id
    

Wiki instructions

Docker installation

You can also install Platypush in a container - the application provides a script named platydock that automatically creates a container instance from a config.yaml:

  1. Create the container from a configuration file:

    platydock build -c /path/to/config.yaml
    
  2. Start the container:

        # device_id matches either the hostname or the device_id in config.yaml
    platydock start device_id
    
  3. Stop the instance:

    platydock stop device_id
    
  4. Remove the instance:

    platydock rm device_id
    

Note that both the virtual environment and Docker container option offer the possibility to include extra YAML configuration files in the main config.yaml through the include directive (as long as they are in the same folder as the main config.yaml), as well as external Python scripts in a scripts directory in the same folder as the config.yaml.

Wiki instructions

Mobile app

An official Android app is provided on the F-Droid store. It allows to easily discover and manage multiple Platypush services on a network through the web interface, and it easily brings the power of Platypush to your fingertips.

Tests

To run the tests simply run pytest either from the project root folder or the tests/ folder. Or run the following command from the project root folder:

python -m tests

Funding

If you use and love Platypush, please consider buying me a coffee/beer.

I've been working on Platypush all by myself in my spare time for the past few years, and I've made sure that it remains open and free.

If you like this product, please consider supporting - I'm definitely not planning to get rich with this project, but I'd love to have at least the costs for the server covered by users.

Issues and requests opened by donors will also be given priority over others.