Home

• Quickstart

• Installation

• Plugins installation

• APIs

• Variables

• Entities

• Configuration

• A full configuration example

• The Web interface

Platypush is a general-purpose and extensible platform for automation across multiple services and devices with hundreds of supported integrations.

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 borrows concepts from IFTTT, Tasker and Home Assistant to provide an environment where the user can easily connect things together. It focuses on an automation-as-code and API-first approach, offering power users great flexibility in customizing their routines.

It’s built with compatibility and flexibility in mind, and it can easily run on any device that can run a Python interpreter - from a Raspberry Pi, to an old smartphone, to a beefy server.

Core concepts

The foundations of Platypush rest on a few simple building blocks that offer great versatility to build arbitrarily complex automation routines:

• 🧩 Plugins. Plugins are the bread-and-butter of the platform. Each plugin exposes an API to interact with an integration - there are plugins for media players and devices, calendars, sensors, voice assistants, smart devices, cloud services, and so on.

  • ⏻ Actions. These are the methods of a plugin transparently exposed to the user over a simple JSON RPC API, and they are always expressed in the format <plugin_name>.<action_name>. For instance, light.hue.on can be used to turn on Philips Hue-compatible lights, media.vlc.play to play some media on a VLC player, etc.

  • ⚙️ Backends. These are special integrations whose main purpose is to deliver messages to the main application. The principal one is the http backend, which exposes the HTTP and WebSocket APIs, serves the main UI and is used by several integrations to provide additional services. A nodered backend is also available to expose a Platypush action component to a Node-RED instance, as well as an internal redis backend and an (insecure) tcp backend to receive raw messages.

• 📧 Events. Plugins emit events whenever some particular conditions happen for example, a new media track is played, a voice assistant conversation has started, and so on.

  • 🪝 Hooks. Users can define custom callbacks on events in the form of hooks. Hooks can contain lists of actions to execute when a certain event matches the hook condition, or any kind of custom logic - for example, send a notification on my phone when the presence sensor in my garage goes on, or use a TTS plugin to process the digest of the latest RSS feeds if I tell the voice assistant “play the news”. Event hooks can be expressed either in YAML format or as Python runtime scripts.

• 📜 Procedures. Procedures are custom snippets of logic that can be invoked using the Platypush API. For example, you can define an at_home procedure that will be executed when you arrive home, which turns on the lights, plays the music, sets the thermostat temperature etc., and then call it using the Platypush API from any device. Like event hooks, procedures can be defined both in YAML format (good if you just want to execute lists of actions without much added logic), or as Python scripts.

  • 🕗 Cronjobs. Cronjobs are special procedures that can be executed either at regular intervals (the UNIX cron syntax is supported), or at a specific time (one-shot). Just like procedures, they can be defined either in YAML or as Python scripts.

• 💡 Entities. Some plugins expose generic entities - such a lights, sensors, media players, switches, voice assistants etc. These entities can be controlled through the same generic APIs, emit the same types of events, can be controlled from the same Web view or dashboard, and their state is persisted across runs.