From 88e2cc2009d012dd28a866ac1a4baef914e1ff8b Mon Sep 17 00:00:00 2001 From: Fabio Manganiello Date: Sun, 22 Jul 2018 02:10:00 +0200 Subject: [PATCH] Added backends page --- Backends.md | 254 ++++++++++++++++++++++++++++++++++++++++++++++++++ Home.md | 4 +- Quickstart.md | 6 ++ 3 files changed, 263 insertions(+), 1 deletion(-) create mode 100644 Backends.md diff --git a/Backends.md b/Backends.md new file mode 100644 index 0000000..9f5a4ba --- /dev/null +++ b/Backends.md @@ -0,0 +1,254 @@ +* [HTTP server](#http-server) +* [RSS feeds backend](#rss-feeds-backend) +* [Assistant backend](#assistant-backend) +* [Redis backend](#redis-backend) +* [MQTT backend](#mqtt-backend) +* [Pushbullet backend](#pushbullet-backend) +* [Kafka backend](#kafka-backend) +* [MPD/Mopidy backend](#mpd-mopidy-backend) +* [MIDI backend](#midi-backend) +* [Flic buttons backend](#flic-buttons-backend) +* [Camera backend](#camera-backend) + * [Raspberry Pi camera backend](#raspberry-picamera-backend) +* [Sensor backends](#sensor-backends) + * [Infrared sensor](#infrared-sensor) + * [ZeroBorg backend](#zeroborg-backend) + * [Leap Motion](#leap-motion) + * [MCP3008](#mcp3008) + * [Arduino and serial backend](#arduino-and-serial-backend) +* [inotify backend](#inotify-backend) +* [Smart cards backend](#smart-cards-backend) +* [Weather forecast backend](#weather-forecast-backend) + + +Platypush backends are components that can listen for event on any source that generates events or messages. Platypush can support through backends things like message queues, HTTP requests, voice assistant interactions, music player events, MIDI events, button events, measurements from sensors, events from smart cards and more. You can see a backend as a component that runs in its own thread or process and posts messages, action requests or events to the main bus when something happens. + +# HTTP server + +[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/http.html) + +The HTTP server is a powerful feature of Platypush and one of the main ways to interact with the application and its components. If configured, the HTTP backend will run a Flask server (default port: 8008) that you can use to interact with Platypush in several ways: + +1. To send action requests as JSON messages through the web API +2. To control the configured plugins (lights, switches, music, sensors etc.) through the web panel +3. As a dashboard to show on a monitor or a tv with your favourite widgets (calendar, music player, weather, sensors state, news etc.) + +## Configuration + +Configuring the HTTP backend is quite easy. Add these lines to your `~/.config/platypush/config.yaml` to get the web server running: + +```yaml +backend.http: + port: 8008 # Default HTTP port + websocket_port: 8009 # Default port for the websockets +``` + +Websockets are used both in the web panel and dashboard interfaces to deliver real-time messages to the plugins and widgets. + +## cURL commands + +Once you've got your web server running, you can easily send action requests to the Platypush plugins through cURL, Postman etc. + +Example 1: play music through the [MPD plugin](plugins#mpd-mopidy-support): + +```shell +curl -XPOST -H 'Content-Type: application/json' \ + -d '{"type":"request", "target":"hostname", "action":"music.mpd.play"}' \ + http://hostname:8008/execute +``` + +Example 2: turn on your lights through the [Philips Hue plugin](plugins#philips-hue-lights-support): + +```shell +curl -XPOST -H 'Content-Type: application/json' \ + -d '{"type":"request", "target":"hostname", "action":"lights.hue.on", "args": {"groups": ["Living Room"]}}' \ + http://hostname:8008/execute +``` + +Example 3: run a configured procedure: + +```shell +curl -XPOST -H 'Content-Type: application/json' \ + -d '{"type":"request", "target":"hostname", "action":"procedure.at_home"}' \ + http://hostname:8008/execute +``` + +## Web panel + +The HTTP backend provides you with a web panel that you can use to control your configured plugins. Just point your browser to http://hostname:8008 after enabling the HTTP backend to test it out. + +You should see an interface that looks [like this](https://i.imgur.com/HbpDL5K.png). The tabs will are linked to the plugins you have configured in your main config file, for those that provide a web panel tab. If a plugin doesn't require any configuration, you can still entry an explicit configuration line to enable it to notify the web panel to include it in the interface: + +```yaml +tts: + # I'm fine with the default configuration but I want to make sure + # that the tab is enabled in the web panel + disabled: False +``` + +You can use the web panel to control your lights, music, video, sensors, motors, switches, and whatever is provided by the plugins. + +## Dashboard + +You can use Platypush to power a fullscreen dashboard with your calendar, music state, photos, weather forecast, news, sensors state etc. to show on a computer, tv or laptop screen. + +Change your `backend.http` configuration to also include the widgets that you want to include on the dashboard. + +```yaml +backend.http: + port: 8008 + websocket_port: 8009 + dashboard: # Your dashboard configuration + background_image: https://some/background.png # Background image + widgets: # Widgets configuration + calendar: # Calendar widget. It requires the calendar plugin to be configured + columns: 6 # 6 columns on the first row + music: # Music playback state. It requires the music.mpd plugin to be configured + columns: 3 # 3 columns on the first row + date-time-weather: # Date, weather and sensors plugin + columns: 3 # 3 columns on the first row + image-carousel: # Photo carousel + columns: 6 # 6 columns on the second row + images_path: /static/resources/Dropbox/Photos/carousel # Path to scan for pictures, relative to + # the backend/http path + refresh_seconds: 15 # Time between two pictures + rss-news: # News from your RSS feeds + # Requires backend.http.poll to be enabled with some + # RSS sources, and configured to write items to sqlite db + columns: 6 # 6 columns on the second row + limit: 25 # Maximum number of items to show in a carousel news iteration + db: "sqlite:////home/blacklight/.local/share/platypush/feeds/rss.db" # Database where the HTTP poll backend + # stores the RSS items +``` + +Note that you can design the layout of the dashboard by specifying how many columns a widget should take. Each row contains 12 columns. In the example above, for example, we placed the calendar widget to occupy half of the first row while the music and weather widgets take one quarter each, and the second row is split between the image carousel and the news carousel. + +# RSS feeds backend + +[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/http.poll.html) + +Platypush comes with an `http.poll` backend that allows you to poll web resources (JSON endpoints, RSS feeds etc.) for new items. + +Support for new items poll on JSON endpoints is still experimental, as I haven't yet figured out a general-purpose elegant way to do it. But you can use the backend for polling RSS feeds as well. The backend will poll the selected RSS sources for new items and store them on a local database. You can then build few things on top of that: + +- Show the news on your dashboard news carousel widget +- Ask the assistant to read you the latest news +- Get a notification whenever some magazine publishes a new article +- Build a weekly PDF digest of a certain source +- ...and so on + +Sample configuration: + +```yaml +backend.http.poll: + requests: + - + type: platypush.backend.http.request.rss.RssUpdates + url: http://www.theguardian.com/rss/world + title: The Guardian - World News + poll_seconds: 120 # Seconds between two requests + max_entries: 10 # Maximum number of entries to parse on each scan + - + type: platypush.backend.http.request.rss.RssUpdates + url: http://www.physorg.com/rss-feed + title: Phys.org + poll_seconds: 120 + max_entries: 10 + - + type: platypush.backend.http.request.rss.RssUpdates + url: http://feeds.feedburner.com/Techcrunch + title: Tech Crunch + poll_seconds: 120 + max_entries: 10 + - + type: platypush.backend.http.request.rss.RssUpdates + url: http://www.nytimes.com/services/xml/rss/nyt/HomePage.xml + title: The New York Times + poll_seconds: 120 + max_entries: 10 +``` + +You can also configure the backend to generate a digest of the new items it scans from each source - they will be saved under `~/.local/share/platypush/feeds/cache` - and to extract the text out of the articles using the [Mercury Reader API](https://mercury.postlight.com/web-parser/). After getting a Mercury API token, you can configure an RSS source to generate a feed containing the content of the new seen items like this: + + +```yaml + - + type: platypush.backend.http.request.rss.RssUpdates + url: http://feeds.feedburner.com/Techcrunch + title: Tech Crunch + mercury_api_key: YOUR_KEY + digest_format: pdf # or html + poll_seconds: 120 + max_entries: 10 +``` + +# Assistant backend + +[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/assistant.google.html) + +# Redis backend + +[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/redis.html) + +# MQTT backend + +[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/mqtt.html) + +# Pushbullet backend + +[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/pushbullet.html) + +# Kafka backend + +[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/kafka.html) + +# MPD/Mopidy backend + +[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/music.mpd.html) + +# MIDI backend + +[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/midi.html) + +# Flic buttons backend + +[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/button.flic.html) + +# Camera backend + +## Raspberry Pi camera backend + +[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/camera.pi.html) + +# Sensor backends + +## Infrared sensor + +### ZeroBorg backend + +[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/sensor.ir.zeroborg.html) + +## Leap Motion + +[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/sensor.leap.html) + +## MCP3008 + +[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/sensor.mcp3008.html) + +## Arduino and serial backend + +[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/sensor.serial.html) + +# inotify backend + +[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/inotify.html) + +# Smart cards backend + +[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/scard.html) + +# Weather forecast backend + +[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/weather.forecast.html) + diff --git a/Home.md b/Home.md index 448fa4d..487d3ea 100644 --- a/Home.md +++ b/Home.md @@ -3,7 +3,9 @@ Platypush * [Architecture](#architecture) * [Installation](#installation) -* [Configuration](configuration) +* [Quickstart](quickstart) +* [Plugins](plugins) +* [Backends](backends) * [Shell interface](shell-interface) * [Writing your plugins](writing-your-own-plugins) * [Writing your backends](writing-your-own-backends) diff --git a/Quickstart.md b/Quickstart.md index d413a8f..345a445 100644 --- a/Quickstart.md +++ b/Quickstart.md @@ -403,3 +403,9 @@ include: - include/backends.yaml - include/assistant_common.yaml ``` + +Now you can take a more in-depth to look to the available: + +- [Plugins](plugins) +- [Backends](backends) +