Wiki stuff
Fabio Manganiello
parent
1955423d4e
commit
0cd1054524
2
Home.md
2
Home.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": []}}
|
||||
```
|
||||
|
||||
|
||||
145
Quickstart.md
145
Quickstart.md
|
|
@ -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…
Reference in New Issue