From b3b2a7a8057bda8604a7d9d689bdce69737b0a25 Mon Sep 17 00:00:00 2001 From: Fabio Manganiello Date: Wed, 9 Mar 2022 23:37:31 +0100 Subject: [PATCH] Generating the README TOC via pre-commit script [closes #209] --- .pre-commit-config.yaml | 15 ++ README.md | 472 +++++++++++++++++++++++++--------------- 2 files changed, 311 insertions(+), 176 deletions(-) create mode 100644 .pre-commit-config.yaml diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 00000000..69dd2085 --- /dev/null +++ b/.pre-commit-config.yaml @@ -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 diff --git a/README.md b/README.md index b02856cc..f1312d93 100644 --- a/README.md +++ b/README.md @@ -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: 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_]] + + +- [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) + + - 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*) -and it provides a comprehensive and customizable user interface that collects everything you need to visualize and -control under one roof. +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](https://ifttt.com), [Tasker](https://tasker.joaoapps.com/), -[Microsoft Flow](https://flow.microsoft.com), [PushBullet](https://pushbullet.com) and -[Home Assistant](https://www.home-assistant.io/) to provide an environment where the user can easily connect things -together. +It takes some concepts from [IFTTT](https://ifttt.com), +[Tasker](https://tasker.joaoapps.com/), [Microsoft +Flow](https://flow.microsoft.com), [PushBullet](https://pushbullet.com) and +[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 -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. +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: @@ -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) - 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), - [microphones](https://docs.platypush.tech/en/latest/platypush/plugins/sound.html) and - [machine learning models](https://docs.platypush.tech/en/latest/platypush/plugins/tensorflow.html) to create smart + [microphones](https://docs.platypush.tech/en/latest/platypush/plugins/sound.html) + and [machine learning + models](https://docs.platypush.tech/en/latest/platypush/plugins/tensorflow.html) + to create smart 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) 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) - [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) -- 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) - [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)) ## Architecture -The architecture of Platypush consists of a few simple pieces, orchestrated by a configuration file stored by default -under [`~/.config/platypush/config.yaml`](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/conf/config.yaml): +The architecture of Platypush consists of a few simple pieces, orchestrated by +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 -[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. +[Full list](https://docs.platypush.tech/en/latest/plugins.html) -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: +Plugins are integrations that do things - like [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 to write a configuration for a plugin +by reading its documentation: ```yaml light.hue: @@ -102,9 +156,11 @@ light.hue: ### 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: +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: ```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 -[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.). +[Full list](https://docs.platypush.tech/en/latest/backends.html) -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: +They are background services that either listen for messages on channels (like +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 -# Get a token + # Get a token curl -XPOST -H 'Content-Type: application/json' -d ' { "username": "$YOUR_USER", "password": "$YOUR_PASSWORD" }' 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", "action": "tts.say", @@ -156,33 +229,38 @@ curl -XPOST -H 'Content-Type: application/json' -H "Authorization: Bearer $YOUR_ }' 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 -[Bluetooth device is connected](https://docs.platypush.tech/en/latest/platypush/events/bluetooth.html#platypush.message.event.bluetooth.BluetoothDeviceConnectedEvent), -or a -[Flic button is pressed](https://docs.platypush.tech/en/latest/platypush/events/button.flic.html#platypush.message.event.button.flic.FlicButtonEvent), -or some -[speech is detected on the voice assistant service](https://docs.platypush.tech/en/latest/platypush/events/assistant.html#platypush.message.event.assistant.SpeechRecognizedEvent), -or an -[RSS feed has new items](https://docs.platypush.tech/en/latest/platypush/events/http.rss.html#platypush.message.event.http.rss.NewFeedEvent), -or a -[new email is received](https://docs.platypush.tech/en/latest/platypush/events/mail.html#platypush.message.event.mail.MailReceivedEvent), -or a -[new track is played](https://docs.platypush.tech/en/latest/platypush/events/music.html#platypush.message.event.music.NewPlayingTrackEvent), -or an -[NFC tag is detected](https://docs.platypush.tech/en/latest/platypush/events/nfc.html#platypush.message.event.nfc.NFCTagDetectedEvent), -or -[new sensor data is 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). +[Full list](https://docs.platypush.tech/en/latest/events.html) + +When a certain event occurs (e.g. a JSON request is received, or a [Bluetooth +device is +connected](https://docs.platypush.tech/en/latest/platypush/events/bluetooth.html#platypush.message.event.bluetooth.BluetoothDeviceConnectedEvent), +or a [Flic button is +pressed](https://docs.platypush.tech/en/latest/platypush/events/button.flic.html#platypush.message.event.button.flic.FlicButtonEvent), +or some [speech is detected on the voice assistant +service](https://docs.platypush.tech/en/latest/platypush/events/assistant.html#platypush.message.event.assistant.SpeechRecognizedEvent), +or an [RSS feed has new +items](https://docs.platypush.tech/en/latest/platypush/events/http.rss.html#platypush.message.event.http.rss.NewFeedEvent), +or a [new email is +received](https://docs.platypush.tech/en/latest/platypush/events/mail.html#platypush.message.event.mail.MailReceivedEvent), +or a [new track is +played](https://docs.platypush.tech/en/latest/platypush/events/music.html#platypush.message.event.music.NewPlayingTrackEvent), +or an [NFC tag is +detected](https://docs.platypush.tech/en/latest/platypush/events/nfc.html#platypush.message.event.nfc.NFCTagDetectedEvent), +or [new sensor data is +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 -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 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: - Sections of the [`config.yaml`](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/conf/config.yaml). Example: @@ -206,9 +284,10 @@ event.hook.SearchSongVoiceCommand: 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): - + ```python from platypush.event.hook import hook from platypush.utils import run @@ -227,13 +306,17 @@ def on_music_play_command(event, title=None, artist=None, **context): ### Procedures -Procedures are pieces of custom logic that can be executed as atomic actions using `procedure.` 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. +Procedures are pieces of custom logic that can be executed as atomic actions +using `procedure.` as an action name. -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: +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: ```yaml procedure.at_home: @@ -256,7 +339,7 @@ procedure.at_home: Python example: ```python -# Content of ~/.config/platypush/scripts/home.py + # Content of ~/.config/platypush/scripts/home.py from platypush.procedure import procedure from platypush.utils import run @@ -270,11 +353,12 @@ def at_home(**context): 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: +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: ```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", "action": "procedure.at_home" @@ -283,15 +367,18 @@ curl -XPOST -H 'Content-Type: application/json' -H "Authorization: Bearer $YOUR_ ### 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. +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 +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 ` `. -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 cron.check_bt_device: @@ -310,7 +397,7 @@ cron.check_bt_device: Python example: ```python -# Content of ~/.config/platypush/scripts/bt_cron.py + # Content of ~/.config/platypush/scripts/bt_cron.py from platypush.cron import cron from platypush.utils import run @@ -325,15 +412,18 @@ def check_bt_device(**context): ### The web interface -If [`backend.http`](https://docs.platypush.tech/en/latest/platypush/backend/http.html) 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. +If +[`backend.http`](https://docs.platypush.tech/en/latest/platypush/backend/http.html) +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](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/conf/dashboard.xml) that can -be used to show information from multiple sources on a large screen. +The web service also provides means for the user to create [custom +dashboards](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/conf/dashboard.xml) +that can be used to show information from multiple sources on a large screen. ## 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: ```yaml -# Example for Debian-based distributions + # Example for Debian-based distributions [sudo] apt-get install redis-server -# Enable and start the service + # Enable and start the service [sudo] systemctl enable redis [sudo] systemctl start redis ``` To install the core platform: -* The `pip` way: +- The `pip` way: ```shell [sudo] pip3 install platypush ``` -* The sources way: +- The sources way: ```shell git clone https://git.platypush.tech/platypush/platypush.git cd platypush +[sudo] pip install . + # Or [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 -extension: +### Installing the dependencies for your extensions -#### 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: @@ -385,15 +490,18 @@ If you follow this route then you can install the extra dependencies in one of t cd $DIR_TO_PLATYPUSH [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 -installed. +#### Check the instructions reported in the documentation -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. +If you follow this route then simply run the commands listed in the +[plugin/backend documentation](https://docs.platypush.tech) 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: @@ -402,89 +510,100 @@ platypush ``` 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 -`~/.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`: +[`.service` +file](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/systemd/platypush.service) +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 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 -environment (under `~/.local/share/platypush/venv/`) with all the dependencies required by the configured -integrations. +Platypush provides a script named `platyvenv` that can parse a `config.yaml` +and automatically create a virtual environment (under +`~/.local/share/platypush/venv/`) with all the dependencies required +by the configured integrations. 1. Create the environment from a configuration file: -```shell -platyvenv build -c /path/to/config.yaml -``` + ```shell + platyvenv build -c /path/to/config.yaml + ``` 2. Start the service from the virtual environment: -```shell -# device_id matches either the hostname or the device_id in config.yaml -platyvenv start device_id -``` + ```shell + # device_id matches either the hostname or the device_id in config.yaml + platyvenv start device_id + ``` 3. Stop the instance: -```shell -platyvenv stop device_id -``` + ```shell + platyvenv stop device_id + ``` 4. Remove the instance: -```shell -platyvenv rm device_id -``` + ```shell + 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 -creates a container instance from a `config.yaml`: +### 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: -```shell -platydock build -c /path/to/config.yaml -``` + ```shell + platydock build -c /path/to/config.yaml + ``` 2. Start the container: -```shell -# device_id matches either the hostname or the device_id in config.yaml -platydock start device_id -``` + ```shell + # device_id matches either the hostname or the device_id in config.yaml + platydock start device_id + ``` 3. Stop the instance: -```shell -platydock stop device_id -``` + ```shell + platydock stop device_id + ``` 4. Remove the instance: -```shell -platydock rm device_id -``` + ```shell + 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`. +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](https://git.platypush.tech/platypush/platypush/-/wikis/Run-platypush-in-a-container) ## Mobile app -An [official Android app](https://f-droid.org/en/packages/tech.platypush.platypush/) 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. +An [official Android +app](https://f-droid.org/en/packages/tech.platypush.platypush/) 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: +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: ```shell 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). -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. +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. +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.