Wiki stuff

master
Fabio Manganiello 4 years ago
parent 1955423d4e
commit 0cd1054524
  1. 2
      Home.md
  2. 210
      Plugins.md
  3. 145
      Quickstart.md

@ -26,6 +26,8 @@ The base components are:
* A _condition_, which can be fuzzly compared against an event. The matching logic will also return a _match score_ if the condition is met. The score is a function of the number of atomic matches (string tokens, scalars, key-values etc.) in the condition that are satisfied by a certain event. If multiple hooks are satisfied by a certain event, the algorithm will only run the ones with the highest score.
* One or more _actions_ to be executed in case of event match (e.g. "turn on the lights", "send a Messenger message to my s.o.", "turn on the heating", "play the radio" etc.)
Check [our documentation](https://platypush.readthedocs.io/en/latest/events.html) for a complete reference of the available events.
# Installation
```shell

@ -0,0 +1,210 @@
* [MPD/Mopidy](#mpd-mopidy-support)
* [Video and media](#video-and-media-support)
* [Philips Hue lights](#philips-hue-lights-support)
* [Belkin WeMo Switch](#belkin-wemo-switch)
* [Text-to-Speech](#text-to-speech-support)
* [Shell plugin](#shell-plugin)
* [HTTP requests plugin](#http-requests-plugin)
* [Database plugin](#database-plugin)
A couple of plugins are available out of the box with Platypush under `plugins/`. Some of them may require extra Python or system dependencies. This page will show you some of the available plugins and some possible use cases, although the only real limit to how to connect things together is just your own imagination. This is not intended to be a complete reference of all the available plugins with their supported methods and dependencies, please refer to our [ReadTheDocs](https://platypush.readthedocs.io/en/latest/plugins.html) page for a more complete reference.
# MPD/Mopidy support
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/music.mpd.html).
[MPD](https://musicpd.org/) is an application that allows to manage and play your music collection through a scalable client/server model. You can have your server running on a machine with a hard drive stuffed with mp3s, and access your collection from anywhere using a big family of compatible command line, graphical, web or mobile clients. [Mopidy](https://www.mopidy.com/) is an evolution of MPD that allows you to access music content from multiple sources through a wide set of plugins - e.g. Spotify, SoundCloud, Deezer, Pandora, TuneIn, Google Music.
Platypush can be a client for your MPD/Mopidy music server, allowing you to search for music, control your queue and the playback upon requests or events.
Configuration:
```yaml
music.mpd:
host: localhost
port: 6600
```
## Web interface
If you have enabled the HTTP backend, you can already point your browser to `http://hostname:8008` and you would see a new tab named `music.mpd` in your control panel. You can browse your music from here, modify the current playlist, search for music and control the playback state. If you're using mopidy and you have some plugins configured (Spotify, SoundCloud, TuneIn...), you'll be able to control music from your cloud accounts from here as well. The interface will look [like this](https://i.imgur.com/HbpDL5K.png).
Let's take a look at a couple more use cases.
## Start playback via HTTP request
Simple use case to get started, start playing the current track through a cURL command:
```shell
curl -XPOST -H 'Content-Type: application/json' \
-d '{"type":"request", "target":"hostname", "action":"music.mpd.play"}' \
http://hostname:8008/execute
```
## Search and play songs and albums using the integrated voice assistant
If you have configured already the voice assistant backend, you can configure an event hook to play a song or an album whenever you say _play [item] by [artist]_.
First configure an event hook for it that will invoke a new synchrounous procedure:
```yaml
event.hook.SearchSongVoiceCommand:
if:
type: platypush.message.event.assistant.SpeechRecognizedEvent
phrase: "play ${title} by ${artist}"
then:
-
action: procedure.search_and_play_song
```
Then define the `search_and_play_song` procedure:
```yaml
procedure.sync.search_and_play_song:
-
# Clear the content of the current playlist
action: music.mpd.clear
-
# Disable shuffle mode
action: music.mpd.random
args:
value: 0
-
# Perform an mpd search. Note how we re-used the "title" and "artist"
# context variables parsed from the voice assistant event
action: music.mpd.search
args:
filter:
- artist
- ${artist}
- any
- ${title}
-
# Play the first of the search results above. Note how we re-used the
# "output" context variable, that contains the output of the previous
# action (an array in the case of `music.mpd.search`), to get the file id
# of the first result and pass it to `music.mpd.play`
action: music.mpd.play
args:
resource: ${output[0]['file']}
```
## Video and media support
Platypush comes with support for video media, including YouTube, local media and torrents (requires [torrentcast](https://www.npmjs.com/package/torrentcast)). It's quite handy to turn a RaspberryPi into a full-blown media server or a Chromecast on steroids, voice controls included.
```yaml
video.omxplayer:
args:
- -o
- alsa # or hdmi
# ... any other default options for OMXPlayer
video.torrentcast:
server: localhost
port: 9090
```
## Philips Hue lights support
Control your [Philips Hue](https://www2.meethue.com/en-us) lights with custom requests and events triggered by your devices.
```yaml
light.hue:
bridge: bridge_name_or_ip
# If no lights or groups to actions are specified in
# the action or in the default configuration, all the
# lights will be targeted.
lights:
- Hall
- Living Room Left
- Living Room Right
- Garage
groups:
- Bedroom
- Kitchen
```
## Belkin WeMo Switch
The [WeMo Switch](http://www.belkin.com/us/p/P-F7C027/) is smart Wi-Fi controlled switch that can automate the control of any electric appliance - fridges, lights, coffee machines...
The Platypush plugin requires `ouimeaux` and will work with no configuration needed.
## Text-to-Speech support
If `mplayer` is installed, you can trigger a machine to say custom phrases in any language through the `tts` plugin. Quite cool if you want to let your RaspberryPi to automatically read you out loud the news or when you get a notification on your phone.
```yaml
tts:
lang: en-gb # Default language
```
## Shell plugin
You can also run custom shell commands on the target machine through the `shell` plugin, that requires no configuration. Example of remote execution through the `pusher` script:
```shell
pusher --target hostname --action shell.exec --cmd "uname -a"
```
## HTTP requests plugin
You can programmatically send HTTP requests in your event hooks and procedures through the `http.request` plugin.
Example:
```yaml
event.hook.TellMeTheWeather:
if:
type: platypush.message.event.assistant.SpeechRecognizedEvent
phrase: tell me the weather
then:
-
action: http.request.get
args:
url: https://your-weather-provider.com/api/weather
params:
- latlng: 0.0,0.0
headers:
- X-Auth-Token: YOUR_TOKEN
```
## Database plugin
You can use Platypush to programmatically insert, update, delete or select database records in your requests, procedures or event hooks. [SQLAlchemy](https://www.sqlalchemy.org/) is used as a backend, therefore Platypush support any engine schema natively supported by SQLAlchemy (SQLite, PostgreSQL, MySQL, Oracle...).
Configuration:
```yaml
db:
engine: sqlite:////home/user/temperature.db # (Optional) default engine; can still be overridden in your db calls
```
```yaml
procedure.sync.log_temperature:
-
action: http.request.get
args:
url: http://your-local-server/api/sensors/temperature # Example JSON output: {"temperature":21.0}
-
action: db.insert
# engine: mysql://.... # Optionally, you can override the default engine to point to another db
table: apartment_stats_temp
records:
-
temperature: ${temperature}
```
Or, if you want to select from a table (returns a list of dictionaries):
```shell
curl -XPOST -d 'msg={"type":"request","target":"hostname","action":"db.select", "args": {"query":"select * from temperature", "engine":"sqlite:////home/user/temperature.db"}}' http://hostname:8008
```
```json
{"id": null, "type": "response", "target": null, "origin": null, "response": {"output": [{"id": 1, "temperature": "21.0","created_at":"<timestamp>"}], "errors": []}}
```

@ -1,5 +1,8 @@
* [Quick start](#quick-start)
* [Procedures](#procedures)
* [For loops](#for-loops)
* [If conditions](#if-conditions)
* [Backends](#backends)
* [HTTP service configuration](#http-service-configuration)
* [PushBullet](#pushbullet-configuration)
@ -180,7 +183,7 @@ Note how the example above uses another plugin - `shell.exec` to run a shell com
Also, please note that the actions executed in an event hook will be executed in parallel. If you want to execute action synchronously, consider wrapping them into a synchronous _procedure_.
Congratulation, you've set up your first rule! Check out the [plugins documentation](https://platypush.readthedocs.io/en/latest/plugins.html) and the [backends documentation](https://platypush.readthedocs.io/en/latest/backends.html) for the list of supported plugins and backends (_documentation for events coming soon_).
Congratulation, you've set up your first rule! Check out the [plugins documentation](https://platypush.readthedocs.io/en/latest/plugins.html), the [backends documentation](https://platypush.readthedocs.io/en/latest/backends.html) and the [events documentation](https://platypush.readthedocs.io/en/latest/events.html) for the list of supported plugins, backends and events.
# Procedures
@ -286,6 +289,11 @@ procedure.sync.LogHourlyForecast:
phrase: The weather is good outside
```
You've now got all the basic ingredients to configure your own plugins and write you own rules. You can proceed looking at some examples with the available:
* [Plugins](plugins)
* [Backends](backends)
# Backends
Backend configurations start with `backend.` in the `config.yaml`.
@ -355,141 +363,6 @@ backend.button.flic:
By the way, the Flic app only supports a maximum of three events per button - short press, long press and double press. With the Platypush plugin you can trigger countless actions by configuring multiple combinations of short and long presses - provided that you can remember them.
# Plugins
A couple of plugins are available out of the box with platypush under `plugins/`. Some of them may require extras Python or system dependencies. Some of the available plugins include:
## MPD/Mopidy support
[MPD](https://musicpd.org/) is an application that allows to manage and play your music collection through a scalable client/server model. You can have your server running on a machine with a hard drive stuffed with mp3s, and access your collection from anywhere using a big family of compatible command line, graphical, web or mobile clients. [Mopidy](https://www.mopidy.com/) is an evolution of MPD that allows you to access music content from multiple sources through a wide set of plugins - e.g. Spotify, SoundCloud, Deezer, Pandora, TuneIn, Google Music.
Platypush can be a client for your MPD/Mopidy music server, allowing you to search for music, control your queue and the playback upon requests or events.
Configuration:
```yaml
music.mpd:
host: localhost
port: 6600
```
## Video and media support
Platypush comes with support for video media, including YouTube, local media and torrents (requires [torrentcast](https://www.npmjs.com/package/torrentcast)). It's quite handy to turn a RaspberryPi into a full-blown media server or a Chromecast on steroids, voice controls included.
```yaml
video.omxplayer:
args:
- -o
- alsa # or hdmi
# ... any other default options for OMXPlayer
video.torrentcast:
server: localhost
port: 9090
```
## Philips Hue lights support
Control your [Philips Hue](https://www2.meethue.com/en-us) lights with custom requests and events triggered by your devices.
```yaml
light.hue:
bridge: bridge_name_or_ip
# If no lights or groups to actions are specified in
# the action or in the default configuration, all the
# lights will be targeted.
lights:
- Hall
- Living Room Left
- Living Room Right
- Garage
groups:
- Bedroom
- Kitchen
```
## Belkin WeMo Switch
The [WeMo Switch](http://www.belkin.com/us/p/P-F7C027/) is smart Wi-Fi controlled switch that can automate the control of any electric appliance - fridges, lights, coffee machines...
The Platypush plugin requires `ouimeaux` and will work with no configuration needed.
## Text-to-Speech support
If `mplayer` is installed, you can trigger a machine to say custom phrases in any language through the `tts` plugin. Quite cool if you want to let your RaspberryPi to automatically read you out loud the news or when you get a notification on your phone.
```yaml
tts:
lang: en-gb # Default language
```
## Shell plugin
You can also run custom shell commands on the target machine through the `shell` plugin, that requires no configuration. Example of remote execution through the `pusher` script:
```shell
pusher --target hostname --action shell.exec --cmd "uname -a"
```
## HTTP requests plugin
You can programmatically send HTTP requests in your event hooks and procedures through the `http.request` plugin.
Example:
```yaml
event.hook.TellMeTheWeather:
if:
type: platypush.message.event.assistant.SpeechRecognizedEvent
phrase: tell me the weather
then:
-
action: http.request.get
args:
url: https://your-weather-provider.com/api/weather
params:
- latlng: 0.0,0.0
headers:
- X-Auth-Token: YOUR_TOKEN
```
## Database plugin
You can use Platypush to programmatically insert, update, delete or select database records in your requests, procedures or event hooks. [SQLAlchemy](https://www.sqlalchemy.org/) is used as a backend, therefore Platypush support any engine schema natively supported by SQLAlchemy (SQLite, PostgreSQL, MySQL, Oracle...).
Configuration:
```yaml
db:
engine: sqlite:////home/user/temperature.db # (Optional) default engine; can still be overridden in your db calls
```
```yaml
procedure.sync.log_temperature:
-
action: http.request.get
args:
url: http://your-local-server/api/sensors/temperature # Example JSON output: {"temperature":21.0}
-
action: db.insert
# engine: mysql://.... # Optionally, you can override the default engine to point to another db
table: apartment_stats_temp
records:
-
temperature: ${temperature}
```
Or, if you want to select from a table (returns a list of dictionaries):
```shell
curl -XPOST -d 'msg={"type":"request","target":"hostname","action":"db.select", "args": {"query":"select * from temperature", "engine":"sqlite:////home/user/temperature.db"}}' http://hostname:8008
```
```json
{"id": null, "type": "response", "target": null, "origin": null, "response": {"output": [{"id": 1, "temperature": "21.0","created_at":"<timestamp>"}], "errors": []}}
```
# Mobile notification mirroring
If you enable the PushBullet backend and [notification mirroring](https://docs.pushbullet.com/#mirrored-notifications) on your Android or iOS device, the PushBullet backend will be able to post events to Platypush if you receive notifications on your mobile, and you can react on those. You can for instance configure Platypush to log specific Whatsapp messages on a local db, read out the headlines of your favourite news app when you receive a push, connect custom Tasker events through [AutoNotification](https://play.google.com/store/apps/details?id=com.joaomgcd.autonotification&hl=en), mirror the notifications on a display connected to a RaspberryPi, and so on.

Loading…
Cancel
Save