platypush/platypush
platypush
/
platypush
2
2
Fork 4
Code Issues 48 Pull Requests Packages Projects 4 Releases Wiki Activity

Finalized plugins

Fabio Manganiello 2018-07-21 02:13:04 +02:00
parent 88ee07ba9b
commit 5f5a4c39b9
1 changed files with 201 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

227
Plugins.md

@ -2,13 +2,18 @@
* [Web interface](#web-interface)
* [Start playback via HTTP request](#start-playback-via-http-request)
* [Search and play songs and albums using the integrated voice assistant](#search-and-play-songs-and-albums-using-the-integrated-voice-assistant)
* [Redis plugin](#redis-plugin)
* [Video and media](#video-and-media-support)
* [Philips Hue lights](#philips-hue-lights-support)
* [Belkin WeMo Switch](#belkin-wemo-switch)
* [Switch plugins](#switch-plugins)
* [Belkin WeMo Switch](#belkin-wemo-switch)
* [TP-Link smart plugs](#tp-link-smart-plugs)
* [Switchbot](#switchbot)
* [Text-to-Speech](#text-to-speech-support)
* [Shell plugin](#shell-plugin)
* [HTTP requests plugin](#http-requests-plugin)
* [Database plugin](#database-plugin)
* [Variables](#variables)
* [Google Assistant plugin](#google-assistant-plugin)
* [Calendar plugin](#calendar-plugin)
* [Sensor plugins](#sensor-plugins)
@ -16,7 +21,10 @@
* [Distance](#distance)
* [Serial](#serial)
* [Build a robot with the ZeroBorg plugin](#zeroborg)
* [MIDI plugin](#midi-plugin)
* [MQTT plugin](#mqtt-plugin)
* [Pushbullet plugin](#pushbullet-plugin)
* [Weather plugin](#weather-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.
@ -36,7 +44,7 @@ music.mpd:
port: 6600
```
## Web interface
# 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).
@ -52,7 +60,7 @@ curl -XPOST -H 'Content-Type: application/json' \
http://hostname:8008/execute
```
### Search and play songs and albums using the integrated voice assistant
## 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]_.
@ -100,7 +108,23 @@ procedure.sync.search_and_play_song:
resource: ${output[0]['file']}
```
## Video and media support
# Redis plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/redis.html)
[Redis](https://redis.io/) is an in-memory data structure store. It can be used as an in-memory store, as a cache or as a message broker. Obviously, latter case is quite interesting when it comes to Platypush :)
Redis is also used heavily by some of our plugins and backends to communicate and synchronize properly, especially if the components live in different processes (for example, the web server) and need to exchange messages with the main process. Redis is a perfect candidate for the purpose. It has a low latency, and the server is lightweight enough to run even on a Raspberry Pi Zero without issues. It's therefore **strongly recommended** to enable both the Redis plugin and backend (and install a Redis server) to take full advantage of Platypush features.
The Redis plugin has a quite simple API to deliver messages:
```shell
curl -XPOST -H 'Content-Type: application/json' \
-d '{"type":"request", "target":"hostname", "action":"redis.send_message", "args": {"queue":"my_queue_name", "msg":"My message"}}' \
http://hostname:8008/execute
```
# Video and media support
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/video.omxplayer.html)
@ -134,7 +158,7 @@ video.omxplayer:
Some cURL examples:
### Play local media
## Play local media
```shell
curl -XPOST -H 'Content-Type: application/json' \
@ -142,7 +166,7 @@ curl -XPOST -H 'Content-Type: application/json' \
http://hostname:8008/execute
```
### Play media by URL
## Play media by URL
```shell
curl -XPOST -H 'Content-Type: application/json' \
@ -150,7 +174,7 @@ curl -XPOST -H 'Content-Type: application/json' \
http://hostname:8008/execute
```
### Play a YouTube video
## Play a YouTube video
**Note**: it requires [youtube-dl](https://rg3.github.io/youtube-dl/) installed on your system.
@ -160,7 +184,7 @@ curl -XPOST -H 'Content-Type: application/json' \
http://hostname:8008/execute
```
### Play a torrent content by Magnet link
## Play a torrent content by Magnet link
**Note**: it requires [python-libtorrent](https://pypi.org/project/python-libtorrent/).
@ -172,7 +196,7 @@ curl -XPOST -H 'Content-Type: application/json' \
http://hostname:8008/execute
```
### Search and play videos from any source
## Search and play videos from any source
The OMXPlayer plugin comes with a powerful search feature that allows you to search and play videos from any available source (currently supported: local files, YouTube and torrent sources).
@ -212,7 +236,7 @@ You can also pass `"queue_results":true` if you want to add the search results t
If you enabled the plugin you'll also have a nice [video search and control tab](https://i.imgur.com/820732a.png) added to your web panel.
## Philips Hue lights support
# Philips Hue lights support
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/light.hue.html)
@ -239,7 +263,7 @@ If you enabled the plugin, you'll also have a [lights control tab](https://i.img
Some cURL examples:
### Turn on the kitchen lights
## Turn on the kitchen lights
```shell
curl -XPOST -H 'Content-Type: application/json' \
@ -247,7 +271,7 @@ curl -XPOST -H 'Content-Type: application/json' \
http://hostname:8008/execute
```
### Set the sunset scene on the living room lights
## Set the sunset scene on the living room lights
```shell
curl -XPOST -H 'Content-Type: application/json' \
@ -255,7 +279,7 @@ curl -XPOST -H 'Content-Type: application/json' \
http://hostname:8008/execute
```
### Blink your living room lights for five seconds
## Blink your living room lights for five seconds
```shell
curl -XPOST -H 'Content-Type: application/json' \
@ -263,15 +287,56 @@ curl -XPOST -H 'Content-Type: application/json' \
http://hostname:8008/execute
```
# Switch plugins
You can use Platypush to control a variety of smart plugs and switches in your smart home setup.
By enabling any of these plugins (even creating an empty config entry just with `disabled: False` if no confi is required), you'll also get the associated switch tab in the web panel where you can control your devices through a web interface.
## Belkin WeMo Switch
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/switch.wemo.html)
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.
Example:
## Text-to-Speech support
```shell
curl -XPOST -H 'Content-Type: application/json' \
-d '{"type":"request", "target":"hostname", "action":"switch.wemo.on", "args": {"device":"192.168.1.2"}}' \
http://hostname:8008/execute
```
## TP-Link smart plugs
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/switch.tplink.html)
This plugin allows you to interact with TP-Link smart plugs like the [HS100](https://www.tp-link.com/us/products/details/cat-5516_HS100.html).
Example:
```shell
curl -XPOST -H 'Content-Type: application/json' \
-d '{"type":"request", "target":"hostname", "action":"switch.tplink.on", "args": {"device":"192.168.1.3"}}' \
http://hostname:8008/execute
```
## Switchbot
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/switch.switchbot.html)
[Switchbot](https://www.switch-bot.com/) is a quite interesting smart home device as it aims to make non-smart devices "smart". It consists in a box with a small bluetooth-controlled mechanical arm that can apply enough pressure to press any button - you can use it to control through Platypush the buttons on your coffee machine, your dishwasher or your old tv for instance.
Note that, unlike the other plugins, Switchbot requires root privileges as it needs to send a raw bluetooth low-energy message using GATT to communicate with the Switchbot. It means that if you're running Platypush as an unprivileged user (and you should!!), you'll need for now to make a `sudo` rule for it. I plan to make it better/safer though.
Example:
```shell
curl -XPOST -H 'Content-Type: application/json' \
-d '{"type":"request", "target":"hostname", "action":"switch.switchbot.press", "args": {"device":"00:11:22:33:44:55"}}' \
http://hostname:8008/execute
```
# 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.
@ -280,7 +345,15 @@ tts:
lang: en-gb # Default language
```
## Shell plugin
Example:
```shell
curl -XPOST -H 'Content-Type: application/json' \
-d '{"type":"request", "target":"hostname", "action":"tts.say", "args": {"phrase":"Connecting people"}}' \
http://hostname:8008/execute
```
# Shell plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/shell.html)
@ -290,7 +363,7 @@ You can also run custom shell commands on the target machine through the `shell`
pusher --target hostname --action shell.exec --cmd "uname -a"
```
## HTTP requests plugin
# HTTP requests plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/http.request.html)
@ -314,7 +387,7 @@ event.hook.TellMeTheWeather:
- X-Auth-Token: YOUR_TOKEN
```
## Database plugin
# Database plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/db.html)
@ -362,7 +435,44 @@ curl -XPOST -H 'Content-type: application/json' \
}
```
## Google Assistant plugin
# Variables
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/variable.google.html)
`variable` is a special plugin that allows to set, get and unset variables that you can reuse for instance within a procedure execution, to store states that will be used by some other pieces of logic, or share data with other programs.
**NOTE**: this plugin relies on the [database plugin](#database-plugin) to be configured. It will indeed store the variables on a local database to persist them across restart and easily share them with other processes.
Example that sets a variable named `AT_HOME`:
```shell
curl -XPOST -H 'Content-type: application/json' \
-d 'msg={"type":"request","target":"hostname","action":"variable.set", "args": {"AT_HOME":1}' \
http://hostname:8008
```
You can now build some custom logic in a synchronous procedure based on that value:
```yaml
procedure.sync.turn_lights_on_sunset:
-
action: variable.get
args:
name: AT_HOME
- if ${AT_HOME}:
- action: light.hue.on
```
And then unset it if you don't need it anymore (will delete the row):
```shell
curl -XPOST -H 'Content-type: application/json' \
-d 'msg={"type":"request","target":"hostname","action":"variable.unset", "args": {"name":"AT_HOME"}' \
http://hostname:8008
```
# Google Assistant plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/assistant.google.html)
@ -379,7 +489,7 @@ event.hook.FlicButtonStartConversation:
action: assistant.google.start_conversation
```
## Calendar plugin
# Calendar plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/calendar.html)
@ -399,11 +509,11 @@ calendar:
Note the use of the Google Calendar plugin type. The Google Calendar plugin belongs to the family of Google plugins, which currently includes Calendar, GMail and Maps (to be expanded). Check the instruction on the [Google plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/google.html) on how to generate OAuth2 tokens for your Google account that these plugins can use.
## Sensor plugins
# Sensor plugins
You can query sensors connect through multiple interfaces through Platypush.
### MCP3008
## MCP3008
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/gpio.sensor.mcp3008.html)
@ -475,7 +585,7 @@ Output:
}
```
### Distance
## Distance
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/gpio.sensor.distance.html)
@ -511,7 +621,7 @@ Output (in millimiters):
}
```
## Serial
# Serial
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/serial.html)
@ -553,7 +663,9 @@ Output:
}
```
## ZeroBorg
Once you enable the `serial` or `mcp3008` plugin and backend you'll be able to monitor the state of your sensors or analog sources through a new tab on the [web panel](https://i.imgur.com/yQYGuhW.png).
# ZeroBorg
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/gpio.zeroborg.html)
@ -614,3 +726,66 @@ curl -XPOST -H 'Content-Type: application/json' \
http://hostname:8008/execute
```
# MIDI plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/midi.html)
Some of the musicians who ended up on this page probably know the [MIDI protocol](http://www.indiana.edu/~emusic/361/midi.htm). Platypush allows you to register a custom MIDI device that can send messages to the OS MIDI sequencer. It's like tricking your machine to think that Platypush is a MIDI keyboard or drum machine. You can for instance create some instrument tracks in LMMS or FruityLoops, link them to your Platypush MIDI source, and play notes through any kind of events that Platypush can process - you can use a Leap Motion to play notes by just waving your hand, use a proximity sensor, play notes with switches and buttons, and so on, the only limit being your creativity.
An example that sends the C4 (middle C, MIDI note 0x60 or 96 in decimal) at medium velocity (64) for 1 second:
```shell
curl -XPOST -H 'Content-Type: application/json' \
-d '{"type":"request", "target":"hostname", "action":"midi.play_note", "args": {"note":96, "velocity":64, "duration":1}}' \
http://hostname:8008/execute
```
You can also send raw MIDI messages through the [`send_message`](https://platypush.readthedocs.io/en/latest/platypush/plugins/midi.html#platypush.plugins.midi.MidiPlugin.send_message) action.
You can also listen for MIDI events and run actions based on them by using the MIDI backend.
# MQTT plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/mqtt.html)
[MQTT](http://mqtt.org/) is a message-queue based protocol to exchange messages across devices. MQTT implementations like Paho MQTT, Mosquitto and Adafruit IO are quite popular for communication across IoT devices. You can interact with an MQTT service through this plugin to build any arbitrary complex message-based logic across your Platypush devices. The asynchronous nature of MQTT makes it a better candidate over the HTTP plugin to deliver messages to other devices if you don't mind much about the response. An HTTP call to the Flask server to turn on the lights, for example, requires the sender to wrap the request into an HTTP message, the receiver to react immediately on that while the sender is synchrounously waiting for an answer, execute the light control action (which might take a while), and then wrap the response into an HTTP message back to the sender. Compare it instead with a message-queue based implementation, where you send the message to a queue where the receiver is listening and as soon as the receiver is available it will pick it up - no need for the sender to hang for the response. Also, the message queue doesn't require the receiver to be directly accessible (through IP/hostname and port) to the sender, as it happens in an HTTP interaction. The sender can send a message to the queue, hosted by an MQTT server, and as long as the receiver (or any receiver) is listening on the same queue, the message will be picked up.
Sending a message over an MQTT backend requires an MQTT `host` server and `port` (default: 1883), the `message` to be sent (anything that implements `__str__`), and the `topic` to send the message to - see it like a channel where one or multiple devices might be listening.
Example:
```shell
curl -XPOST -H 'Content-Type: application/json' \
-d '{"type":"request", "target":"hostname", "action":"mqtt.send_message", "args": {"topic":"my_topic", "server":"my_mqtt_server", "port":1883, "message":"It worked"}}' \
http://hostname:8008/execute
```
You can (or should) of course also use the MQTT backend. By doing so you can send messages across that Platypush devices containing action requests, events or responses. You can create routing rules for messages, or propagate the events you receive on a device over another one - for example I've configured a rule for all of my devices with connected sensors to route their `SensorDataChangeEvent` events over MQTT to a hub device, where I can monitor from a single web panel the values of all my sensors around the house. Another good use case for MQTT is to send messages from your Android devices to your Platypush devices. The same developer of Taker has recently developed [Join](https://joaoapps.com/join/), that allows you among the other things to programmatically send messages over MQTT. You can then create tasks that send messages to Platypush when you get a call, receive an sms, connect to some WiFi network or enter some area. You can also create Join action to send custom commands to your Platypush devices from a tap on your phone.
# Pushbullet plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/pushbullet.html)
[Pushbullet](https://www.pushbullet.com/) is a quite cool piece of software to keep your devices in sync, exchange messages, synchronize clipboards and sms across devices, access remote files, and so on. You can install it as an Android or iPhone app, as a browser extension, or use it from your browser directly. It can be quite powerful if paired with Platypush - and it has the first backend I have developed as well. You can use the plugin in pair with the backend to do things like:
* Send URLs, text and Platypush messages to your Android devices
* Trigger Platypush actions through your Android device, wherever you are
* Synchronize the clipboards
* Synchronize your phone notifications to your Raspberry Pi
* Send and receive pictures
* ...and so on
Note that you need to enable the Pushbullet backend in order to use this plugin.
Example command to send a file to all of your connected Pushbullet devices:
```shell
curl -XPOST -H 'Content-Type: application/json' \
-d '{"type":"request", "target":"hostname", "action":"pushbullet.send_file", "args": {"filename":"/home/user/myphoto.jpg"}}' \
http://hostname:8008/execute
```
# Weather plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/weather.html)