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

Added more plugins to the wiki

Fabio Manganiello 2018-07-17 01:51:03 +02:00
parent 0cd1054524
commit 88ee07ba9b
1 changed files with 417 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

428
Plugins.md

@ -1,4 +1,7 @@
* [MPD/Mopidy](#mpd-mopidy-support)
* [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)
* [Video and media](#video-and-media-support)
* [Philips Hue lights](#philips-hue-lights-support)
* [Belkin WeMo Switch](#belkin-wemo-switch)
@ -6,6 +9,13 @@
* [Shell plugin](#shell-plugin)
* [HTTP requests plugin](#http-requests-plugin)
* [Database plugin](#database-plugin)
* [Google Assistant plugin](#google-assistant-plugin)
* [Calendar plugin](#calendar-plugin)
* [Sensor plugins](#sensor-plugins)
* [MCP3008](#mcp3008)
* [Distance](#distance)
* [Serial](#serial)
* [Build a robot with the ZeroBorg plugin](#zeroborg)
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.
@ -42,7 +52,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]_.
@ -92,22 +102,120 @@ procedure.sync.search_and_play_song:
## 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.
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/video.omxplayer.html)
Platypush comes with support for video media, including YouTube, local media and torrents. 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:
media_dirs:
# Local media content will be search in these directories
- /mnt/exthd/media/movies
- /mnt/exthd/media/series
# Torrents and other remote content will be downloaded to this directory
download_dir: /mnt/exthd/downloads
# Torrent bind ports override (default ports: 6881, 6891)
torrent_ports:
- 7881
- 7891
args:
# You can specify any extra option passed to the OMXPlayer (https://elinux.org/Omxplayer) executable here
- -o
- alsa # or hdmi
# ... any other default options for OMXPlayer
video.torrentcast:
server: localhost
port: 9090
- --subtitles
- /home/user/subs
- -orientation
- 90
# ...
```
Some cURL examples:
### Play local media
```shell
curl -XPOST -H 'Content-Type: application/json' \
-d '{"type":"request", "target":"hostname", "action":"video.omxplayer.play", "args": {"resource":"file:///path/video.mp4"}}' \
http://hostname:8008/execute
```
### Play media by URL
```shell
curl -XPOST -H 'Content-Type: application/json' \
-d '{"type":"request", "target":"hostname", "action":"video.omxplayer.play", "args": {"resource":"http://distribution.bbb3d.renderfarming.net/video/mp4/bbb_sunflower_1080p_60fps_stereo_abl.mp4"}}' \
http://hostname:8008/execute
```
### Play a YouTube video
**Note**: it requires [youtube-dl](https://rg3.github.io/youtube-dl/) installed on your system.
```shell
curl -XPOST -H 'Content-Type: application/json' \
-d '{"type":"request", "target":"hostname", "action":"video.omxplayer.play", "args": {"resource":"https://www.youtube.com/watch?v=XCAQ0MZTJmg"}}' \
http://hostname:8008/execute
```
### Play a torrent content by Magnet link
**Note**: it requires [python-libtorrent](https://pypi.org/project/python-libtorrent/).
This will first download the torrent content to `download_dir` and then play it (streaming while downloading isn't currently supported, the few tests I've run seem to stress the Raspberry Pi too much).
```shell
curl -XPOST -H 'Content-Type: application/json' \
-d '{"type":"request", "target":"hostname", "action":"video.omxplayer.play", "args": {"resource":"magnet:?magnet_uri"}}' \
http://hostname:8008/execute
```
### 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).
An example:
```shell
curl -XPOST -H 'Content-Type: application/json' \
-d '{"type":"request", "target":"hostname", "action":"video.omxplayer.search", "args":{"query":"A Space Odyssey"}}' \
http://hostname:8008/execute
```
Output:
```json
{
"type":"response",
"response": {
"output": [
{
"url": "file:///mnt/hd/media/movies/A Space Odyssey/2001 - A Space Odyssey.avi",
"title": "2001 - A Space Odyssey.avi"
},
{
"url": "magnet:?xt=urn:...",
"title": "2001: A Space Odyssey"
},
{
"url": "https://www.youtube.com/watch?v=oR_e9y-bka0",
"title": "2001: A SPACE ODYSSEY - Trailer"
}
]
}
}
```
You can also pass `"queue_results":true` if you want to add the search results to the current play queue, or `"autoplay":true` if you want to automatically play the first search result.
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
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/light.hue.html)
Control your [Philips Hue](https://www2.meethue.com/en-us) lights with custom requests and events triggered by your devices.
```yaml
@ -115,7 +223,7 @@ 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.
# available lights will be targeted by the commands
lights:
- Hall
@ -127,8 +235,38 @@ light.hue:
- Kitchen
```
If you enabled the plugin, you'll also have a [lights control tab](https://i.imgur.com/HwsNsms.png) on your web panel.
Some cURL examples:
### Turn on the kitchen lights
```shell
curl -XPOST -H 'Content-Type: application/json' \
-d '{"type":"request", "target":"hostname", "action":"light.hue.on", "args": {"groups":"Kitchen"}}' \
http://hostname:8008/execute
```
### Set the sunset scene on the living room lights
```shell
curl -XPOST -H 'Content-Type: application/json' \
-d '{"type":"request", "target":"hostname", "action":"light.hue.scene", "args": {"name":"Sunset", "groups":"Living Room"}}' \
http://hostname:8008/execute
```
### Blink your living room lights for five seconds
```shell
curl -XPOST -H 'Content-Type: application/json' \
-d '{"type":"request", "target":"hostname", "action":"light.hue.animate", "args": {"animation":"blink", "groups":"Living Room", "transition_seconds":0.5, "duration": 5}}' \
http://hostname:8008/execute
```
## 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.
@ -144,6 +282,8 @@ tts:
## Shell plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/shell.html)
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
@ -152,6 +292,8 @@ pusher --target hostname --action shell.exec --cmd "uname -a"
## HTTP requests plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/http.request.html)
You can programmatically send HTTP requests in your event hooks and procedures through the `http.request` plugin.
Example:
@ -174,6 +316,8 @@ event.hook.TellMeTheWeather:
## Database plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/db.html)
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:
@ -198,13 +342,275 @@ procedure.sync.log_temperature:
temperature: ${temperature}
```
Or, if you want to select from a table (returns a list of dictionaries):
[update](https://platypush.readthedocs.io/en/latest/platypush/plugins/db.html#platypush.plugins.db.DbPlugin.update) and [delete](https://platypush.readthedocs.io/en/latest/platypush/plugins/db.html#platypush.plugins.db.DbPlugin.delete) methods are also available.
If you want to programmatically select from a table via HTTP call (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
curl -XPOST -H 'Content-type: application/json' \
-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": []}}
{
"type": "response",
"response": {
"output": [{"id": 1, "temperature": "21.0","created_at":"<timestamp>"}],
"errors": []
}
}
```
## Google Assistant plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/assistant.google.html)
If you have the Google Assistant backend configured, then you can use the assistant plugin to programmatically start or stop an interaction with the assistant. For instance, you can start a conversation without saying the "Ok, Google" hotword by pressing a Flic button, if you have the Flic backend configured:
```yaml
event.hook.FlicButtonStartConversation:
if:
type: platypush.message.event.button.flic.FlicButtonEvent
btn_addr: <button MAC address>
sequence:
- ShortPressEvent
then:
action: assistant.google.start_conversation
```
## Calendar plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/calendar.html)
You can use the calendar plugin to get your upcoming events or (*TODO*) change or create events on multiple data sources - Google Calendar, Facebook events calendar, remote ICal resource etc.
Example configuration:
```yaml
calendar:
calendars:
-
type: platypush.plugins.google.calendar.GoogleCalendarPlugin
-
type: platypush.plugins.calendar.ical.IcalCalendarPlugin
url: https://www.facebook.com/ical/u.php?uid=USER_ID&key=FB_KEY
```
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
You can query sensors connect through multiple interfaces through Platypush.
### MCP3008
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/gpio.sensor.mcp3008.html)
The [MCP3008](https://learn.adafruit.com/raspberry-pi-analog-to-digital-converters/mcp3008) is a very useful ADC converter that you can use to read data from multiple analog sources and transmit them to a digital device that doesn't support direct GPIO analog input (like the Raspberry Pi). You can use it instead of an Arduino or serial device if you want lower latency, or a more compact or cheaper solution.
An example configuration:
```yaml
gpio.sensor.mcp3008:
# In this configuration the MCP3008 is connected in software SPI mode,
# a better option if you don't have many GPIO pins available although
# it introduces a bit of latency compared to the hardware SPI mode.
# Here we specify the GPIO pin numbers where you connect your MCP3008
# interface. Specify spi_port and spi_device instead if you want to run
# in hardware SPI mode.
CLK: 15
MISO: 22
MOSI: 17
CS: 25
# Reference tension, usually 3.3V or 5V on a Raspberry
Vdd: 3.3
# Here you can link names and analog conversion functions to the
# analog sources connected to your MCP3008 pins.
channels:
# Channels are identified by MCP3008 pin number
0:
name: temperature
# The conversion function is a snippet of Python code that you can specify to
# convert the output voltage of your analog sensor (normalized between 0 and 255)
# into a human readable value (e.g. meters, Celsius degrees, km/h, % etc.).
# In this example we used a simple LM35DZ (http://www.ti.com/lit/ds/symlink/lm35.pdf)
# temperature sensors and specified a function to convert the analog value into
# a Celsius degrees value.
# Note that the analog value is denoted as `x` in the function definition.
conv_function: 'round(x*100.0, 2)' # T = Vout / (10 [mV/C])
1:
name: light
# Here we used a simple ALS-PT9
# (http://www.everlight.com/file/ProductFile/201407061531031645.pdf) light sensor,
# that comes with an internal 10 kΩ resistor. The detected luminosity (in lumen)
# is proportional to the current (in μA) on the resistor, the conversion function
# simply uses Ohm's law (I = V/R) to get the lumens from the analog voltage value.
conv_function: 'round(x*1000.0, 6)'
```
cURL example:
```shell
curl -XPOST -H 'Content-Type: application/json' \
-d '{"type":"request","target":"hostname","action":"gpio.sensor.mcp3008.get_measurement"}' \
http://hostname:8008/execute
```
Output:
```json
{
"type": "response",
"response": {
"output": {
"temperature": 22.42,
"light": 50.5
},
"errors": []
}
}
```
### Distance
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/gpio.sensor.distance.html)
I've tested this plugin quite successfully with the [HC-SR04](https://cdn.sparkfun.com/datasheets/Sensors/Proximity/HCSR04.pdf) ultrasound distance sensor, an inexpensive and accurate options for anyone playing with robotics.
The sensor works like an ultrasound radar - it sends a pulse controlled by the `trigger_pin`, and detects the returning signal through the `echo_pin`. Known the average speed of sound in air, it's relatively easy to get the distance of the nearest obstacle. All you have to do is connect the trigger and echo pins to the GPIO interface of your device. Note: take into account that the HC-SR04 works at 5V. If you're interfacing it with a device that works with a lower voltage (the GPIO logic of a Raspberry usually runs at 3.3V) you may want to use a voltage converter or set up your [cheap voltage divider](https://learn.sparkfun.com/tutorials/voltage-dividers) with two resistors to prevent damage to your GPIO interface.
Example configuration:
```yaml
gpio.sensor.distance:
trigger_pin: 13
echo_pin: 14
```
cURL example:
```shell
curl -XPOST -H 'Content-Type: application/json' \
-d '{"type":"request","target":"hostname","action":"gpio.sensor.distance.get_measurement"}' \
http://hostname:8008/execute
```
Output (in millimiters):
```json
{
"type": "response",
"response": {
"output": 313.17,
"errors": []
}
}
```
## Serial
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/serial.html)
Use the serial plugin if you want to read analog data through serial interface (typical use cases: Arduino or compatible devices, serial ports etc.).
It's advised if the serial device returns data in JSON format (if you use Arduino you can use the [ArduinoJson](https://github.com/bblanchon/ArduinoJson) library to write JSON to the serial interface).
Example configuration:
```yaml
serial:
device: /dev/ACM0
baud_rate: 9600
```
If you're using udev to dynamically assign your device names, you might consider configuring [udev rules](https://wiki.archlinux.org/index.php/udev#About_udev_rules) to prevent the "dance" of the device names when they are disconnected and reconnected (and renamed to ACM0, ACM1, ACM2 etc.).
cURL example:
```shell
curl -XPOST -H 'Content-Type: application/json' \
-d '{"type":"request", "target":"hostname", "action":"serial.get_measurement"}' \
http://hostname:8008/execute
```
Output:
```json
{
"type": "response",
"response": {
"output": {
"smoke": 0,
"temperature": 23.90402,
"humidity": 39.08141
},
"errors": []
}
}
```
## ZeroBorg
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/gpio.zeroborg.html)
The [ZeroBorg](https://www.piborg.org/motor-control-1135/zeroborg) is a nice piece of circuitry that pairs quite well with Raspberry Pi and compatible devices. It comes with four outputs that you can use to control motors and servos by applying a current. It also comes with an infrared sensor that you can use to detect inputs from an IR remote, Platypush provides a backend to read events from this sensor as well.
The ZeroBorg plugin also allows you to interact with sensors data to control your motors.
Here's an example configuration I use for my 4WD robot controlled by a Raspberry Pi Zero paired with a ZeroBorg device. [MagPi](https://raspberrypi.org/magpi-issues/MagPi51.pdf) provides detailed instructions on how to build such a robot. Note that the calibration values came after numerous tests to get the robot to move straight. Your values may vary depending on your set up, the load of the connected components, the weight and how it is distributed.
```yaml
gpio.zeroborg:
directions:
up:
motor_1_power: 0.4821428571428572
motor_2_power: 0.4821428571428572
motor_3_power: -0.6707142857142858
motor_4_power: -0.6707142857142858
down:
motor_1_power: -0.4821428571428572
motor_2_power: -0.4821428571428572
motor_3_power: 0.825
motor_4_power: 0.825
left:
motor_1_power: -0.1392857142857143
motor_2_power: -0.1392857142857143
motor_3_power: -1.0553571428571429
motor_4_power: -1.0553571428571429
right:
motor_1_power: 1.0017857142857143
motor_2_power: 1.0017857142857143
motor_3_power: 0.6214285714285713
motor_4_power: 0.6214285714285713
auto:
sensors:
-
plugin: "gpio.sensor.distance",
threshold: 400.0,
timeout: 2.0,
above_threshold_direction: "up",
below_threshold_direction: "left"
```
Note that the special direction `auto` can contain a configuration that allows your device to move autonomously based on the inputs it gets from some sensors. In this case, I set the sensors configuration (a list) to periodically poll a GPIO-based ultrasound distance sensor plugin. `timeout` says after how long a poll attempt should fail. The plugin package is specified through `plugin` (`gpio.sensor.distance`) in this case, note that the plugin must be configured as well in order to work). The `threshold` value says around which value your logic should trigger. In this case, threshold=400 (40 cm). When the distance value is above that threshold (`above_threshold_direction`), then go "up" (no obstacles ahead). Otherwise (`below_threshold_direction`), turn "left" (avoid the obstacle). Feel free to build a more robust autopilot by adding more sensors :)
Once you enable the plugin, you can also drive the robot through the [control tab](https://i.imgur.com/2n3amcs.png) that will be available in the control panel. It also supports directional keys and spacebar long-press to toggle the automatic pilot (click inside of the tab first to focus it).
cURL example to drive your robot up and stop after 5 seconds:
```shell
curl -XPOST -H 'Content-Type: application/json' \
-d '{"type":"request", "target":"hostname", "action":"gpio.zeroborg.drive", "args": {"direction":"up"}}' \
http://hostname:8008/execute
sleep 5
curl -XPOST -H 'Content-Type: application/json' \
-d '{"type":"request", "target":"hostname", "action":"gpio.zeroborg.stop"}' \
http://hostname:8008/execute
```