revil-O/platypush
1
0
Fork 0
forked from platypush/platypush
Code Pull requests Activity

Generating the README TOC via pre-commit script [closes #209]

Browse source
This commit is contained in:
Fabio Manganiello 2022-03-09 23:37:31 +01:00
parent 747e7f3e5d
commit b3b2a7a805
Signed by untrusted user: blacklight
GPG key ID: D90FBA7F76362774
2 changed files with 311 additions and 176 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
.pre-commit-config.yaml Normal file
View file

@ -0,0 +1,15 @@
# See https://pre-commit.com for more information
# See https://pre-commit.com/hooks.html for more hooks
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v3.2.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-yaml
- id: check-added-large-files
- repo: https://github.com/Lucas-C/pre-commit-hooks-nodejs
rev: v1.1.1
hooks:
- id: markdown-toc

472
README.md
View file

@ -10,37 +10,71 @@ Platypush
[![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/BlackLight/platypush.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/BlackLight/platypush/context:python) [![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/BlackLight/platypush.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/BlackLight/platypush/context:python)
[![Language grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/BlackLight/platypush.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/BlackLight/platypush/context:javascript) [![Language grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/BlackLight/platypush.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/BlackLight/platypush/context:javascript)
[[_TOC_]] <!-- toc -->
- [Architecture](#architecture)
* [Plugins](#plugins)
* [Actions](#actions)
* [Backends](#backends)
* [Events](#events)
* [Hooks](#hooks)
* [Procedures](#procedures)
* [Cronjobs](#cronjobs)
* [The web interface](#the-web-interface)
- [Installation](#installation)
* [System installation](#system-installation)
* [Installing the dependencies for your extensions](#installing-the-dependencies-for-your-extensions)
+ [Install via `extras` name](#install-via-extras-name)
+ [Install via `manifest.yaml`](#install-via-manifestyaml)
+ [Check the instructions reported in the documentation](#check-the-instructions-reported-in-the-documentation)
* [Virtual environment installation](#virtual-environment-installation)
* [Docker installation](#docker-installation)
- [Mobile app](#mobile-app)
- [Tests](#tests)
- [Funding](#funding)
<!-- tocstop -->
- Recommended read: [**Getting started with Platypush**](https://blog.platypush.tech/article/Ultimate-self-hosted-automation-with-Platypush). - Recommended read: [**Getting started with Platypush**](https://blog.platypush.tech/article/Ultimate-self-hosted-automation-with-Platypush).
- The [blog](https://blog.platypush.tech) is in general a good place to get more insights on what you can build with it and inspiration about possible usages. - The [blog](https://blog.platypush.tech) is in general a good place to get
more insights on what you can build with it and inspiration about possible
usages.
- The [wiki](https://git.platypush.tech/platypush/platypush/-/wikis/home) also contains many resources on getting started. - The [wiki](https://git.platypush.tech/platypush/platypush/-/wikis/home) also
contains many resources on getting started.
- Extensive documentation for all the available integrations and messages [is available](https://docs.platypush.tech/). - Extensive documentation for all the available integrations and messages [is
available](https://docs.platypush.tech/).
- If you have issues/feature requests/enhancement ideas please [create an issue](https://git.platypush.tech/platypush/platypush/-/issues). - If you have issues/feature requests/enhancement ideas please [create an
issue](https://git.platypush.tech/platypush/platypush/-/issues).
- A [Reddit channel](https://www.reddit.com/r/platypush) is also available for more general questions. - A [Reddit channel](https://www.reddit.com/r/platypush) is also available for
more general questions.
--- ---
Platypush is a general-purpose extensible platform for automation and integration across multiple services and devices. 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*) It enables users to create their own self-hosted pieces of automation based on
and it provides a comprehensive and customizable user interface that collects everything you need to visualize and events (*if this happens then do that*)
control under one roof. 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](https://ifttt.com), [Tasker](https://tasker.joaoapps.com/), It takes some concepts from [IFTTT](https://ifttt.com),
[Microsoft Flow](https://flow.microsoft.com), [PushBullet](https://pushbullet.com) and [Tasker](https://tasker.joaoapps.com/), [Microsoft
[Home Assistant](https://www.home-assistant.io/) to provide an environment where the user can easily connect things Flow](https://flow.microsoft.com), [PushBullet](https://pushbullet.com) and
together. [Home Assistant](https://www.home-assistant.io/) 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 Its ideal home is a single-board computer like a RaspberryPi that you can
and cloud automation in your own living room or garage, but it can easily run on any device that can run a Python configure to orchestrate any home automation and cloud automation in your own
interpreter, and the bar for the hardware requirements is very low as well - I use it to run pieces of automation on living room or garage, but it can easily run on any device that can run a
devices as powerful as a RaspberryPi Zero or an old Nokia N900 with Linux. 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: You can use Platypush to do things like:
@ -49,8 +83,10 @@ You can use Platypush to do things like:
- [Create custom and privacy-secure voice assistants that run custom hooks on your phrases](https://blog.platypush.tech/article/Build-custom-voice-assistants) - [Create custom and privacy-secure voice assistants that run custom hooks on your phrases](https://blog.platypush.tech/article/Build-custom-voice-assistants)
- Build integrations between [sensors](https://docs.platypush.tech/en/latest/platypush/backend/sensor.html), - Build integrations between [sensors](https://docs.platypush.tech/en/latest/platypush/backend/sensor.html),
[cameras](https://docs.platypush.tech/en/latest/platypush/plugins/camera.pi.html), [cameras](https://docs.platypush.tech/en/latest/platypush/plugins/camera.pi.html),
[microphones](https://docs.platypush.tech/en/latest/platypush/plugins/sound.html) and [microphones](https://docs.platypush.tech/en/latest/platypush/plugins/sound.html)
[machine learning models](https://docs.platypush.tech/en/latest/platypush/plugins/tensorflow.html) to create smart and [machine learning
models](https://docs.platypush.tech/en/latest/platypush/plugins/tensorflow.html)
to create smart
pieces of automation for e.g. pieces of automation for e.g.
[people detection](https://blog.platypush.tech/article/Detect-people-with-a-RaspberryPi-a-thermal-camera-Platypush-and-a-pinch-of-machine-learning) [people detection](https://blog.platypush.tech/article/Detect-people-with-a-RaspberryPi-a-thermal-camera-Platypush-and-a-pinch-of-machine-learning)
or [sound detection](https://blog.platypush.tech/article/Create-your-smart-baby-monitor-with-Platypush-and-Tensorflow) or [sound detection](https://blog.platypush.tech/article/Create-your-smart-baby-monitor-with-Platypush-and-Tensorflow)
@ -62,35 +98,53 @@ You can use Platypush to do things like:
- [Control your smart switches](https://docs.platypush.tech/en/latest/platypush/plugins/switch.html) - [Control your smart switches](https://docs.platypush.tech/en/latest/platypush/plugins/switch.html)
- [Implement automated custom text-to-speech routines](https://docs.platypush.tech/en/latest/platypush/plugins/tts.html) - [Implement automated custom text-to-speech routines](https://docs.platypush.tech/en/latest/platypush/plugins/tts.html)
- [Build any kind of interactions and automation routines with your Android device using Tasker](https://blog.platypush.tech/article/How-to-build-your-personal-infrastructure-for-data-collection-and-visualization) - [Build any kind of interactions and automation routines with your Android device using Tasker](https://blog.platypush.tech/article/How-to-build-your-personal-infrastructure-for-data-collection-and-visualization)
- Play [local videos](https://docs.platypush.tech/en/latest/platypush/plugins/media.mpv.html), YouTube videos and torrent media from any device and service, to any device - Play [local
videos](https://docs.platypush.tech/en/latest/platypush/plugins/media.mpv.html),
YouTube videos and torrent media from any device and service, to any device
- [Get weather forecast events for your location and build automation routines on them](https://docs.platypush.tech/en/latest/platypush/plugins/weather.darksky.html) - [Get weather forecast events for your location and build automation routines on them](https://docs.platypush.tech/en/latest/platypush/plugins/weather.darksky.html)
- [Create a custom single hub for Zigbee and Z-Wave smart devices](https://blog.platypush.tech/article/Transform-a-RaspberryPi-into-a-universal-Zigbee-and-Z-Wave-bridge) - [Create a custom single hub for Zigbee and Z-Wave smart devices](https://blog.platypush.tech/article/Transform-a-RaspberryPi-into-a-universal-Zigbee-and-Z-Wave-bridge)
- Build your own web dashboard with calendar, weather, news and music controls (basically, anything that has a Platypush web widget) - Build your own web dashboard with calendar, weather, news and music controls
(basically, anything that has a Platypush web widget)
- ...and much more (basically, anything that comes with a [Platypush plugin](https://docs.platypush.tech/en/latest/plugins.html)) - ...and much more (basically, anything that comes with a [Platypush plugin](https://docs.platypush.tech/en/latest/plugins.html))
## Architecture ## Architecture
The architecture of Platypush consists of a few simple pieces, orchestrated by a configuration file stored by default The architecture of Platypush consists of a few simple pieces, orchestrated by
under [`~/.config/platypush/config.yaml`](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/conf/config.yaml): a configuration file stored by default under
[`~/.config/platypush/config.yaml`](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/conf/config.yaml):
### [Plugins](https://docs.platypush.tech/en/latest/plugins.html) ### Plugins
They are integrations that do things - like [Full list](https://docs.platypush.tech/en/latest/plugins.html)
[modify files](https://docs.platypush.tech/en/latest/platypush/plugins/file.html),
[train and evaluate machine learning models](https://docs.platypush.tech/en/latest/platypush/plugins/tensorflow.html),
[control cameras](https://docs.platypush.tech/en/latest/platypush/plugins/camera.pi.html),
[read sensors](https://docs.platypush.tech/en/latest/platypush/plugins/gpio.sensor.dht.html),
[parse a web page](https://docs.platypush.tech/en/latest/platypush/plugins/http.webpage.html),
[control lights](https://docs.platypush.tech/en/latest/platypush/plugins/light.hue.html),
[send emails](https://docs.platypush.tech/en/latest/platypush/plugins/mail.smtp.html),
[control Chromecasts](https://docs.platypush.tech/en/latest/platypush/plugins/media.chromecast.html),
[run voice queries](https://docs.platypush.tech/en/latest/platypush/plugins/assistant.google.html),
[handle torrent transfers](https://docs.platypush.tech/en/latest/platypush/plugins/torrent.html) or
control [Zigbee](https://docs.platypush.tech/en/latest/platypush/plugins/zigbee.mqtt.html) or
[Z-Wave](https://docs.platypush.tech/en/latest/platypush/plugins/zwave.html) devices.
The configuration of a plugin matches one-on-one that of its documented class constructor, so it's very straightforward Plugins are integrations that do things - like [modify
to write a configuration for a plugin by reading its documentation: files](https://docs.platypush.tech/en/latest/platypush/plugins/file.html),
[train and evaluate machine learning
models](https://docs.platypush.tech/en/latest/platypush/plugins/tensorflow.html),
[control
cameras](https://docs.platypush.tech/en/latest/platypush/plugins/camera.pi.html),
[read
sensors](https://docs.platypush.tech/en/latest/platypush/plugins/gpio.sensor.dht.html),
[parse a web
page](https://docs.platypush.tech/en/latest/platypush/plugins/http.webpage.html),
[control
lights](https://docs.platypush.tech/en/latest/platypush/plugins/light.hue.html),
[send
emails](https://docs.platypush.tech/en/latest/platypush/plugins/mail.smtp.html),
[control
Chromecasts](https://docs.platypush.tech/en/latest/platypush/plugins/media.chromecast.html),
[run voice
queries](https://docs.platypush.tech/en/latest/platypush/plugins/assistant.google.html),
[handle torrent
transfers](https://docs.platypush.tech/en/latest/platypush/plugins/torrent.html)
or control
[Zigbee](https://docs.platypush.tech/en/latest/platypush/plugins/zigbee.mqtt.html)
or [Z-Wave](https://docs.platypush.tech/en/latest/platypush/plugins/zwave.html)
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:
```yaml ```yaml
light.hue: light.hue:
@ -102,9 +156,11 @@ light.hue:
### Actions ### Actions
Plugins expose *actions*, that match one-on-one the plugin class methods denoted by `@action`, so it's very Plugins expose *actions*, that match one-on-one the plugin class methods
straightforward to invoke plugin actions by just reading the plugin documentation. They can be invoked directly from denoted by `@action`, so it's very straightforward to invoke plugin actions by
your own scripts or they can be sent to the platform through any supported channel as simple JSON messages: 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:
```json ```json
{ {
@ -116,37 +172,54 @@ your own scripts or they can be sent to the platform through any supported chann
} }
``` ```
### [Backends](https://docs.platypush.tech/en/latest/backends.html) ### Backends
They are background services that either listen for messages on channels (like an [Full list](https://docs.platypush.tech/en/latest/backends.html)
[HTTP backend](https://docs.platypush.tech/en/latest/platypush/backend/http.html), an
[MQTT instance](https://docs.platypush.tech/en/latest/platypush/backend/mqtt.html), a
[Kafka instance](https://docs.platypush.tech/en/latest/platypush/backend/kafka.html), a
[Websocket service](https://docs.platypush.tech/en/latest/platypush/backend/websocket.html),
[Pushbullet](https://docs.platypush.tech/en/latest/platypush/backend/pushbullet.html) etc.) or monitor a device or a
service for events (like a [sensor](https://docs.platypush.tech/en/latest/platypush/backend/sensor.html), a custom
[voice assistant](https://docs.platypush.tech/en/latest/platypush/backend/assistant.google.html), a bridge running on a
[Zigbee](https://docs.platypush.tech/en/latest/platypush/backend/zigbee.mqtt.html) or
[Z-Wave](https://docs.platypush.tech/en/latest/platypush/backend/zwave.html), an
[NFC card reader](https://docs.platypush.tech/en/latest/platypush/backend/nfc.html), a
[MIDI device](https://docs.platypush.tech/en/latest/platypush/backend/midi.html), a
[Telegram channel](https://docs.platypush.tech/en/latest/platypush/backend/chat.telegram.html), a
[Bluetooth scanner](https://docs.platypush.tech/en/latest/platypush/backend/bluetooth.scanner.ble.html) etc.).
If a backend supports the execution of requests (e.g. HTTP, MQTT, Kafka, Websocket and TCP) then you can send requests They are background services that either listen for messages on channels (like
to these services in JSON format. For example, in the case of the HTTP backend: an [HTTP
backend](https://docs.platypush.tech/en/latest/platypush/backend/http.html), an
[MQTT
instance](https://docs.platypush.tech/en/latest/platypush/backend/mqtt.html), a
[Kafka
instance](https://docs.platypush.tech/en/latest/platypush/backend/kafka.html),
a [Websocket
service](https://docs.platypush.tech/en/latest/platypush/backend/websocket.html),
[Pushbullet](https://docs.platypush.tech/en/latest/platypush/backend/pushbullet.html)
etc.) or monitor a device or a service for events (like a
[sensor](https://docs.platypush.tech/en/latest/platypush/backend/sensor.html),
a custom [voice
assistant](https://docs.platypush.tech/en/latest/platypush/backend/assistant.google.html),
a bridge running on a
[Zigbee](https://docs.platypush.tech/en/latest/platypush/backend/zigbee.mqtt.html)
or
[Z-Wave](https://docs.platypush.tech/en/latest/platypush/backend/zwave.html),
an [NFC card
reader](https://docs.platypush.tech/en/latest/platypush/backend/nfc.html), a
[MIDI
device](https://docs.platypush.tech/en/latest/platypush/backend/midi.html), a
[Telegram
channel](https://docs.platypush.tech/en/latest/platypush/backend/chat.telegram.html),
a [Bluetooth
scanner](https://docs.platypush.tech/en/latest/platypush/backend/bluetooth.scanner.ble.html)
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:
```shell ```shell
# Get a token # Get a token
curl -XPOST -H 'Content-Type: application/json' -d ' curl -XPOST -H 'Content-Type: application/json' -d '
{ {
"username": "$YOUR_USER", "username": "$YOUR_USER",
"password": "$YOUR_PASSWORD" "password": "$YOUR_PASSWORD"
}' http://host:8008/auth }' http://host:8008/auth
# Execute a request # Execute a request
curl -XPOST -H 'Content-Type: application/json' -H "Authorization: Bearer $YOUR_TOKEN" -d ' curl -XPOST -H 'Content-Type: application/json' \
-H "Authorization: Bearer $YOUR_TOKEN" -d '
{ {
"type": "request", "type": "request",
"action": "tts.say", "action": "tts.say",
@ -156,33 +229,38 @@ curl -XPOST -H 'Content-Type: application/json' -H "Authorization: Bearer $YOUR_
}' http://host:8008/execute }' http://host:8008/execute
``` ```
### [Events](https://docs.platypush.tech/en/latest/events.html) ### Events
When a certain event occurs (e.g. a JSON request is received, or a [Full list](https://docs.platypush.tech/en/latest/events.html)
[Bluetooth device is connected](https://docs.platypush.tech/en/latest/platypush/events/bluetooth.html#platypush.message.event.bluetooth.BluetoothDeviceConnectedEvent),
or a When a certain event occurs (e.g. a JSON request is received, or a [Bluetooth
[Flic button is pressed](https://docs.platypush.tech/en/latest/platypush/events/button.flic.html#platypush.message.event.button.flic.FlicButtonEvent), device is
or some connected](https://docs.platypush.tech/en/latest/platypush/events/bluetooth.html#platypush.message.event.bluetooth.BluetoothDeviceConnectedEvent),
[speech is detected on the voice assistant service](https://docs.platypush.tech/en/latest/platypush/events/assistant.html#platypush.message.event.assistant.SpeechRecognizedEvent), or a [Flic button is
or an pressed](https://docs.platypush.tech/en/latest/platypush/events/button.flic.html#platypush.message.event.button.flic.FlicButtonEvent),
[RSS feed has new items](https://docs.platypush.tech/en/latest/platypush/events/http.rss.html#platypush.message.event.http.rss.NewFeedEvent), or some [speech is detected on the voice assistant
or a service](https://docs.platypush.tech/en/latest/platypush/events/assistant.html#platypush.message.event.assistant.SpeechRecognizedEvent),
[new email is received](https://docs.platypush.tech/en/latest/platypush/events/mail.html#platypush.message.event.mail.MailReceivedEvent), or an [RSS feed has new
or a items](https://docs.platypush.tech/en/latest/platypush/events/http.rss.html#platypush.message.event.http.rss.NewFeedEvent),
[new track is played](https://docs.platypush.tech/en/latest/platypush/events/music.html#platypush.message.event.music.NewPlayingTrackEvent), or a [new email is
or an received](https://docs.platypush.tech/en/latest/platypush/events/mail.html#platypush.message.event.mail.MailReceivedEvent),
[NFC tag is detected](https://docs.platypush.tech/en/latest/platypush/events/nfc.html#platypush.message.event.nfc.NFCTagDetectedEvent), or a [new track is
or played](https://docs.platypush.tech/en/latest/platypush/events/music.html#platypush.message.event.music.NewPlayingTrackEvent),
[new sensor data is available](https://docs.platypush.tech/en/latest/platypush/events/sensor.html#platypush.message.event.sensor.SensorDataChangeEvent), or an [NFC tag is
or detected](https://docs.platypush.tech/en/latest/platypush/events/nfc.html#platypush.message.event.nfc.NFCTagDetectedEvent),
[a value of a Zigbee device changes](https://docs.platypush.tech/en/latest/platypush/events/zigbee.mqtt.html#platypush.message.event.zigbee.mqtt.ZigbeeMqttDevicePropertySetEvent), or [new sensor data is
etc.), the associated backend will trigger an [event](https://docs.platypush.tech/en/latest/events.html). available](https://docs.platypush.tech/en/latest/platypush/events/sensor.html#platypush.message.event.sensor.SensorDataChangeEvent),
or [a value of a Zigbee device
changes](https://docs.platypush.tech/en/latest/platypush/events/zigbee.mqtt.html#platypush.message.event.zigbee.mqtt.ZigbeeMqttDevicePropertySetEvent),
etc.), the associated backend will trigger an
[event](https://docs.platypush.tech/en/latest/events.html).
### Hooks ### Hooks
Event hooks are custom pieces of logic that will be run when a certain event is triggered. Hooks are the glue that Event hooks are custom pieces of logic that will be run when a certain event is
connects events to actions, exposing a paradigm similar to IFTTT (_if a certain event happens then run these actions_). triggered. Hooks are the glue that connects events to actions, exposing a
They can declared as: paradigm similar to IFTTT (_if a certain event happens then run these
actions_). They can declared as:
- Sections of the [`config.yaml`](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/conf/config.yaml). - Sections of the [`config.yaml`](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/conf/config.yaml).
Example: Example:
@ -206,9 +284,10 @@ event.hook.SearchSongVoiceCommand:
resource: ${output[0]['file']} resource: ${output[0]['file']}
``` ```
- Stand-alone Python scripts stored under `~/.config/platypush/scripts` and will be dynamically imported at start time. - Stand-alone Python scripts stored under `~/.config/platypush/scripts` and
will be dynamically imported at start time.
[Example](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/conf/hook.py): [Example](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/conf/hook.py):
```python ```python
from platypush.event.hook import hook from platypush.event.hook import hook
from platypush.utils import run from platypush.utils import run
@ -227,13 +306,17 @@ def on_music_play_command(event, title=None, artist=None, **context):
### Procedures ### Procedures
Procedures are pieces of custom logic that can be executed as atomic actions using `procedure.<name>` as an action name. Procedures are pieces of custom logic that can be executed as atomic actions
They can be defined either in the `config.yaml` or as Python scripts stored under `~/.config/platypush/scripts` - using `procedure.<name>` as an action name.
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 They can be defined either in the `config.yaml` or as Python scripts stored
that a certain thresholds, says a welcome home message using the TTS engine and starts playing the music: 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:
```yaml ```yaml
procedure.at_home: procedure.at_home:
@ -256,7 +339,7 @@ procedure.at_home:
Python example: Python example:
```python ```python
# Content of ~/.config/platypush/scripts/home.py # Content of ~/.config/platypush/scripts/home.py
from platypush.procedure import procedure from platypush.procedure import procedure
from platypush.utils import run from platypush.utils import run
@ -270,11 +353,12 @@ def at_home(**context):
run('music.mpd.play') 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 In either case, you can easily trigger the at-home procedure by sending an
example, over the HTTP backend: action request message to a backend - for example, over the HTTP backend:
```shell ```shell
curl -XPOST -H 'Content-Type: application/json' -H "Authorization: Bearer $YOUR_TOKEN" -d ' curl -XPOST -H 'Content-Type: application/json' \
-H "Authorization: Bearer $YOUR_TOKEN" -d '
{ {
"type": "request", "type": "request",
"action": "procedure.at_home" "action": "procedure.at_home"
@ -283,15 +367,18 @@ curl -XPOST -H 'Content-Type: application/json' -H "Authorization: Bearer $YOUR_
### Cronjobs ### Cronjobs
Cronjobs are pieces of logic that will be run at regular intervals, expressed in crontab-compatible syntax. Cronjobs are pieces of logic that will be run at regular intervals, expressed
They can be defined either in the `config.yaml` or as Python scripts stored under `~/.config/platypush/scripts` as in crontab-compatible syntax. They can be defined either in the `config.yaml`
functions labelled by the `@cron` decorator. 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 Note that seconds are also supported (unlike the standard crontab definition),
standard crontab format, they are at the end of the cron expression, so the expression is actually in the format 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>`. `<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: YAML example for a cronjob that is executed every 30 seconds and checks if a
Bluetooth device is nearby:
```yaml ```yaml
cron.check_bt_device: cron.check_bt_device:
@ -310,7 +397,7 @@ cron.check_bt_device:
Python example: Python example:
```python ```python
# Content of ~/.config/platypush/scripts/bt_cron.py # Content of ~/.config/platypush/scripts/bt_cron.py
from platypush.cron import cron from platypush.cron import cron
from platypush.utils import run from platypush.utils import run
@ -325,15 +412,18 @@ def check_bt_device(**context):
### The web interface ### The web interface
If [`backend.http`](https://docs.platypush.tech/en/latest/platypush/backend/http.html) is enabled then a web interface If
will be provided by default on `http://host:8008/`. Besides using the `/execute` endpoint for running requests, the [`backend.http`](https://docs.platypush.tech/en/latest/platypush/backend/http.html)
built-in web server also provides a full-featured interface that groups together the controls for most of the plugins - is enabled then a web interface will be provided by default on
e.g. sensors, switches, music controls and search, media library and torrent management, lights, Zigbee/Z-Wave devices `http://host:8008/`. Besides using the `/execute` endpoint for running
and so on. The UI is responsive and mobile-friendly. 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 The web service also provides means for the user to create [custom
[custom dashboards](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/conf/dashboard.xml) that can dashboards](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/conf/dashboard.xml)
be used to show information from multiple sources on a large screen. that can be used to show information from multiple sources on a large screen.
## Installation ## Installation
@ -342,36 +432,51 @@ be used to show information from multiple sources on a large screen.
Platypush uses Redis to deliver and store requests and temporary messages: Platypush uses Redis to deliver and store requests and temporary messages:
```yaml ```yaml
# Example for Debian-based distributions # Example for Debian-based distributions
[sudo] apt-get install redis-server [sudo] apt-get install redis-server
# Enable and start the service # Enable and start the service
[sudo] systemctl enable redis [sudo] systemctl enable redis
[sudo] systemctl start redis [sudo] systemctl start redis
``` ```
To install the core platform: To install the core platform:
* The `pip` way: - The `pip` way:
```shell ```shell
[sudo] pip3 install platypush [sudo] pip3 install platypush
``` ```
* The sources way: - The sources way:
```shell ```shell
git clone https://git.platypush.tech/platypush/platypush.git git clone https://git.platypush.tech/platypush/platypush.git
cd platypush cd platypush
[sudo] pip install .
# Or
[sudo] python3 setup.py install [sudo] python3 setup.py install
``` ```
Then install the extensions that you wish to use. There are a few ways to check the dependencies required by an ### Installing the dependencies for your extensions
extension:
#### Check their `extras` name in [`extras_require` under `setup.py`](https://git.platypush.tech/platypush/platypush/-/blob/master/setup.py#L72). 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:
If you follow this route then you can install the extra dependencies in one of the following ways: #### Install via `extras` name
All the extensions that require extra dependencies are listed in the
[`extras_require` section under
`setup.py`](https://git.platypush.tech/platypush/platypush/-/blob/master/setup.py#L72).
#### 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: 1. `pip` installation:
@ -385,15 +490,18 @@ If you follow this route then you can install the extra dependencies in one of t
cd $DIR_TO_PLATYPUSH cd $DIR_TO_PLATYPUSH
[sudo] pip3 install '.[extra1,extra2,extra3]' [sudo] pip3 install '.[extra1,extra2,extra3]'
``` ```
#### Check the dependencies/installation instructions reported under the plugin/backend documentation.
If you follow this route then simply run the commands listed in the plugin/backend documentation to get the dependencies #### Check the instructions reported in the documentation
installed.
After installing the dependencies, create a configuration file under `~/.config/platypush/config.yaml` (the application If you follow this route then simply run the commands listed in the
can load the configuration from another location through the `-c` option) containing the configuration of the backend [plugin/backend documentation](https://docs.platypush.tech) to get the
and plugins that you want to use, and add any hooks and procedures for your use case. 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: You can then start the service by simply running:
@ -402,89 +510,100 @@ platypush
``` ```
It's advised to run it as a systemd service though - simply copy the provided It's advised to run it as a systemd service though - simply copy the provided
[`.service` file](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/systemd/platypush.service) to [`.service`
`~/.config/systemd/user`, check if the path of `platypush` matches the path where it's installed on your system, and file](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/systemd/platypush.service)
start the service via `systemctl`: 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`:
```shell ```shell
systemctl --user start platypush systemctl --user start platypush
``` ```
### [Virtual environment installation](https://git.platypush.tech/platypush/platypush/-/wikis/Run-platypush-in-a-virtual-environment) ### Virtual environment installation
Platypush provides a script named `platyvenv` that can parse a `config.yaml` and automatically create a virtual Platypush provides a script named `platyvenv` that can parse a `config.yaml`
environment (under `~/.local/share/platypush/venv/<device_id>`) with all the dependencies required by the configured and automatically create a virtual environment (under
integrations. `~/.local/share/platypush/venv/<device_id>`) with all the dependencies required
by the configured integrations.
1. Create the environment from a configuration file: 1. Create the environment from a configuration file:
```shell ```shell
platyvenv build -c /path/to/config.yaml platyvenv build -c /path/to/config.yaml
``` ```
2. Start the service from the virtual environment: 2. Start the service from the virtual environment:
```shell ```shell
# device_id matches either the hostname or the device_id in config.yaml # device_id matches either the hostname or the device_id in config.yaml
platyvenv start device_id platyvenv start device_id
``` ```
3. Stop the instance: 3. Stop the instance:
```shell ```shell
platyvenv stop device_id platyvenv stop device_id
``` ```
4. Remove the instance: 4. Remove the instance:
```shell ```shell
platyvenv rm device_id platyvenv rm device_id
``` ```
### [Docker installation](https://git.platypush.tech/platypush/platypush/-/wikis/Run-platypush-in-a-container) [Wiki instructions](https://git.platypush.tech/platypush/platypush/-/wikis/Run-platypush-in-a-virtual-environment)
You can also install Platypush in a container - the application provides a script named `platydock` that automatically ### Docker installation
creates a container instance from a `config.yaml`:
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: 1. Create the container from a configuration file:
```shell ```shell
platydock build -c /path/to/config.yaml platydock build -c /path/to/config.yaml
``` ```
2. Start the container: 2. Start the container:
```shell ```shell
# device_id matches either the hostname or the device_id in config.yaml # device_id matches either the hostname or the device_id in config.yaml
platydock start device_id platydock start device_id
``` ```
3. Stop the instance: 3. Stop the instance:
```shell ```shell
platydock stop device_id platydock stop device_id
``` ```
4. Remove the instance: 4. Remove the instance:
```shell ```shell
platydock rm device_id platydock rm device_id
``` ```
Note that both the virtual environment and Docker container option offer the possibility to include extra YAML configuration Note that both the virtual environment and Docker container option offer the
files in the main `config.yaml` through the `include` directive (as long as they are in the same folder as the main possibility to include extra YAML configuration files in the main `config.yaml`
`config.yaml`), as well as external Python scripts in a `scripts` directory in the same folder as the `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](https://git.platypush.tech/platypush/platypush/-/wikis/Run-platypush-in-a-container)
## Mobile app ## Mobile app
An [official Android app](https://f-droid.org/en/packages/tech.platypush.platypush/) is provided on the F-Droid store. An [official Android
It allows to easily discover and manage multiple Platypush services on a network through the web interface, and it app](https://f-droid.org/en/packages/tech.platypush.platypush/) is provided on
easily brings the power of Platypush to your fingertips. 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 ## Tests
To run the tests simply run `pytest` either from the project root folder or the `tests/` folder. To run the tests simply run `pytest` either from the project root folder or the
Or run the following command from the project root folder: `tests/` folder. Or run the following command from the project root folder:
```shell ```shell
python -m tests python -m tests
@ -496,10 +615,11 @@ python -m tests
If you use and love Platypush, please consider [buying me a coffee/beer](https://paypal.me/fabiomanganiello). If you use and love Platypush, please consider [buying me a coffee/beer](https://paypal.me/fabiomanganiello).
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 I've been working on Platypush all by myself in my spare time for the past few
open and free. 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 If you like this product, please consider supporting - I'm definitely not
I'd love to have at least the costs for the server covered by users. 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. Issues and requests opened by donors will also be given priority over others.