From 88ee07ba9b89b8be9af689a480296f3edd46f84a Mon Sep 17 00:00:00 2001 From: Fabio Manganiello Date: Tue, 17 Jul 2018 01:51:03 +0200 Subject: [PATCH] Added more plugins to the wiki --- Plugins.md | 428 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 417 insertions(+), 11 deletions(-) diff --git a/Plugins.md b/Plugins.md index 1dc0d53..ef07d4f 100644 --- a/Plugins.md +++ b/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":""}], "errors": []}} +{ + "type": "response", + "response": { + "output": [{"id": 1, "temperature": "21.0","created_at":""}], + "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: