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

Added backends page

Fabio Manganiello 2018-07-22 02:10:00 +02:00
parent 5f5a4c39b9
commit 88e2cc2009
3 changed files with 263 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

254
Backends.md Normal file

@ -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)

4
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)

6
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)