From 3089fe36e0988e25cc73d70205e586b79f409ecb Mon Sep 17 00:00:00 2001 From: Fabio Manganiello Date: Sun, 28 Oct 2018 23:47:47 +0100 Subject: [PATCH] Updated wiki --- Backends.md | 55 ++++++++++++++++++++++++++++++++++ Plugins.md | 60 +++++++++++++++++++++++++++++++++++++ Writing-your-own-plugins.md | 56 +++++++++++++++++++++++++++------- 3 files changed, 161 insertions(+), 10 deletions(-) diff --git a/Backends.md b/Backends.md index 85c7c3b..bb7ef03 100644 --- a/Backends.md +++ b/Backends.md @@ -3,6 +3,8 @@ * [Assistant backend](#assistant-backend) * [Redis backend](#redis-backend) * [MQTT backend](#mqtt-backend) +* [Websocket backend](#websocket-backend) +* [TCP backend](#tcp-backend) * [Pushbullet backend](#pushbullet-backend) * [Kafka backend](#kafka-backend) * [MPD/Mopidy backend](#mpd-mopidy-backend) @@ -403,6 +405,59 @@ backend.mqtt: You can now start sending messages to your backend through the [MQTT plugin](plugins#mqtt-plugin) or another app, also running on another machine. +# Websocket backend + +[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/websocket.html) + +You can send messages to Platypush over a websocket connection. Example configuration: + +```yaml +backend.websocket: + port: 8765 # Websocket port (default: 8765) + bind_address: 0.0.0.0 # Bind address (default: 0.0.0.0, accept any connection) + ssl_cert: ~/.ssl/certs/localhost.pem # Path to the PEM certificate file if you want to enable SSL (default: None) + client_timeout: 60 # Close an inactive websocket client connection after these many seconds. + # A zero-value will keep the connection alive until closure or client timeout + # (default: 60 seconds) +``` + +After enabling you can easily send messages to Platypush through your JavaScript code, for example: + +```javascript +var socket = new WebSocket('ws://hostname:8765'); +socket.onmessage = (msg) => { + console.log(msg); +}; + +var msg = {"type":"request", "target":"hostname", "action":"plugin.action"}; +socket.send(JSON.stringify(msg)); +``` + +Or through command-line tools like [wscat](https://www.npmjs.com/package/wscat): + +```shell +wscat -w 0 -c 'ws://turing:8765' -x '{"type":"request", "target":"hostname", "action":"light.batsignal.on"}' +``` + +# TCP backend + +[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/tcp.html) + +Platypush comes with a simple TCP socket-backend that will simply read JSON messages from a specified port, forward them to the bus and process the responses back on the client socket. Example configuration: + +```yaml +backend.tcp: + port: 5555 # Listen port + bind_address: 0.0.0.0 # Bind address (default: 0.0.0.0, accept any connection) + listen_queue: 5 # Size of the TCP connections pool (default: 5) +``` + +After enabling and restarting Platypush you can easily test this backend with tools like telnet or netcat: + +```shell +echo -n '{"type":"request", "target":"hostname", "action":"plugin.action"}' | nc hostname 5555 +``` + # Pushbullet backend [Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/pushbullet.html) diff --git a/Plugins.md b/Plugins.md index 445090a..154202a 100644 --- a/Plugins.md +++ b/Plugins.md @@ -27,6 +27,9 @@ * [Kafka plugin](#kafka-plugin) * [IFTTT plugin](#ifttt-plugin) * [Adafruit IO plugin](#adafruit-io-plugin) +* [Autoremote plugin](#autoremote-plugin) +* [Kodi plugin](#kodi-plugin) +* [Torrent plugin](#torrent-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. @@ -886,6 +889,63 @@ procedure.sync.OnSensorData: value: ${data.get('temperature')} ``` +# Autoremote plugin + +[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/autoremote.html) + +[Tasker](https://tasker.joaoapps.com/) is a really powerful app for Android that allows you to automate everything on your system, create tasks and triggers to control app, settings, notifications and so on. Some of its features are quite similar to those offered by Platypush, but it runs on Android while Platypush will likely run on your favourite Linux-based computer or mini-computer :) + +It'd be amazing to make those two worlds communicate, for instance by sending notifications to your phone about the media that plays on your Raspberry or triggering an alert on your phone if you're not at home and your Raspberry camera detected some motion. + +It's relatively easy to send messages from Tasker to Platypush. Pick your favourite Tasker plugin (Pushbullet, MQTT or Node-Red over [Join](https://play.google.com/store/apps/details?id=com.joaomgcd.join), any web request plugin...) and you can start creating Tasker routines that send messages to Platypush over the configured channel. + +In order to send messages from Platypush to Tasker instead you can leverage [AutoRemote](https://joaoapps.com/autoremote/), a Tasker plugin that allows you to send custom messages and notifications to an Android device through a multitude of ways (Chrome extension, web API, Tasker integration etc.). + +All you need is to install the app on your Android device and follow the steps to register your device. You'll get a unique URL for your device. If you open it you'll notice a `key=` section in the URL. That's the key you'll need in order to configure the AutoRemote plugin on Platypush: + +```yaml +autoremote: + devices: + OnePlus6: AUTOREMOTE_KEY_1 + PixelC: AUTOREMOTE_KEY_2 + Nexus5: AUTOREMOTE_KEY_3 +``` + +Note that you can install and configure AutoRemote on multiple Android devices and configure the Platypush plugin with their keys and a unique name in order to send messages to them. You can now use the [send_message](https://platypush.readthedocs.io/en/latest/platypush/plugins/autoremote.html#platypush.plugins.autoremote.AutoremotePlugin.send_message) and [send_notification](https://platypush.readthedocs.io/en/latest/platypush/plugins/autoremote.html#platypush.plugins.autoremote.AutoremotePlugin.send_notification) to respectively send messages and notifications to your device and build Tasker routines on them. + +# Kodi plugin + +[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/media.kodi.html) + +[Kodi](https://kodi.tv) is a popular media player and media center. It's compatible with plenty of devices and OSes (including Android, Linux, MacOS, Windows and several embedded players) and there are tons of add-ons available, for anything that goes from media library managemnt to subtitles to radio and tv channels to YouTube. + +Kodi also comes with a powerful API, and Platypush can leverage it by allowing you to control your player. You can for instance build a DIY remote control system for your media center by using any IR remote and any IR sensor to navigate the Kodi interface or control the playback status. Or create rules to automatically add to your library and start playing a torrent file when it's done downloading. The [plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/media.kodi.html) is quite rich and the available methods should mirror almost at 100% what is provided by the Kodi API. + +# Torrent plugin + +[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/torrent.html) + +You can use Platypush to search, download and manage torrents. Example configuration: + +```yaml +torrent: + download_dir: ~//Downloads # Torrents download directory + torrent_ports: # Pair of ports used by the torrent tracker (default: 6881 and 6891) + - 6881 + - 6891 +``` + +Refer to the [plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/torrent.html) for documentation on the available methods and their interface. + +Note also that the `download` method will generate few [types of events](https://platypush.readthedocs.io/en/latest/platypush/events/torrent.html) and you can build triggers on those, for instance an event hook that automatically starts your favourite player when a movie has done downloading or a notification for the progress of your downloads synced to your mobile device. + +* [TorrentDownloadStartEvent](https://platypush.readthedocs.io/en/latest/platypush/events/torrent.html#platypush.message.event.torrent.TorrentDownloadStartEvent) when a torrent starts downloading. +* [TorrentSeedingStartEvent](https://platypush.readthedocs.io/en/latest/platypush/events/torrent.html#platypush.message.event.torrent.TorrentSeedingStartEvent) when a torrent starts seeding. +* [TorrentStateChangeEvent](https://platypush.readthedocs.io/en/latest/platypush/events/torrent.html#platypush.message.event.torrent.TorrentStateChangeEvent) when a torrent status changes. +* [TorrentDownloadProgressEvent](https://platypush.readthedocs.io/en/latest/platypush/events/torrent.html#platypush.message.event.torrent.TorrentDownloadProgressEvent) when the download progress state of a torrent changes. +* [TorrentDownloadStopEvent](https://platypush.readthedocs.io/en/latest/platypush/events/torrent.html#platypush.message.event.torrent.TorrentDownloadStopEvent) when the download of a torrent stops. +* [TorrentDownloadCompletedEvent](https://platypush.readthedocs.io/en/latest/platypush/events/torrent.html#platypush.message.event.torrent.TorrentDownloadCompletedEvent) when a torrent download is complete. + # Weather plugin [Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/weather.forecast.html) diff --git a/Writing-your-own-plugins.md b/Writing-your-own-plugins.md index a3ac4c5..92c092a 100644 --- a/Writing-your-own-plugins.md +++ b/Writing-your-own-plugins.md @@ -15,36 +15,72 @@ The `__init__.py` will look like this: ```python import batman -from platypush.message.response import Response - -from .. import LightPlugin +# Decorator used to identify class methods to be exposed as plugin actions +from platypush.plugins import action +from platypush.plugins.light import LightPlugin class LightBatsignalPlugin(LightPlugin): def __init__(self, intensity=100): super().__init__() self.batsignal = batman.Batsignal(intensity) + @action + def status(self): + return {'status': self.batsignal.status()} + + @action def on(self, urgent=False): if urgent: self.batsignal.notify_robin() self.batsignal.on() - return Response(output='ok') + return self.status() + @action def off(self): self.batsignal.off() - return Response(output='ok') + return self.status() + @action def toggle(self): - self.batsignal.toggle() - return Response(output='ok') + if self.batsignal.status().on: + self.batsignal.off() + else: + self.batsignal.on() + + return self.status() ``` 6. Rebuild and reinstall `platypush` if required and relaunch it. -7. Test your new plugin by sending some bullets to it: +7. Test your new plugin by sending some requests to it: + +* Via cURL: ```shell -pusher --target your_pc --action light.batsignal.on --urgent 1 -``` \ No newline at end of file +curl -XPOST -H 'Content-Type: application/json' \ + -d '{"type":"request", "target":"hostname", "action":"light.batsignal.on"}' \ + http://hostname:8008/execute +``` + +* Via TCP backend: + +```shell +echo -n '{"type":"request", "target":"hostname", "action":"light.batsignal.on"}' | nc hostname 3333 +``` + +* Via Redis backend: + +```shell +echo "RPUSH platypush_bus_mq '{\"type\":\"request\",\"target\":\"turing\",\"action\":\"light.batsignal.on\"}'" | redis-cli +``` + +* Via websocket backend: + +```shell +wscat -w 0 -c 'ws://turing:8765' -x '{"type":"request", "target":"hostname", "action":"light.batsignal.on"}' +``` + +Or you can even experiment and connect [Node-Red](https://nodered.org) components and flows to trigger your custom action. +