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

s/platypush.readthedocs.io/docs.platypush.tech/g

Fabio Manganiello 2021-02-02 01:28:26 +01:00
parent 070d113f42
commit cc8b49d53a
4 changed files with 76 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
Backends.md

@ -26,7 +26,7 @@ Platypush backends are components that can listen for event on any source that g
# HTTP server
[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/http.html)
[Backend reference](https://docs.platypush.tech/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:
@ -142,7 +142,7 @@ Note that you can design the layout of the dashboard by specifying how many colu
# RSS feeds backend
[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/http.poll.html)
[Backend reference](https://docs.platypush.tech/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.
@ -201,7 +201,7 @@ You can also configure the backend to generate a digest of the new items it scan
# Assistant backend
[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/assistant.google.html)
[Backend reference](https://docs.platypush.tech/en/latest/platypush/backend/assistant.google.html)
The assistant backend allows you to interact with a built-in voice assistant. Only the Google Assistant is currently supported (sorry Amazon).
@ -373,7 +373,7 @@ If you use the web panel or the dashboard you'll also notice that the assistant
# Redis backend
[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/redis.html)
[Backend reference](https://docs.platypush.tech/en/latest/platypush/backend/redis.html)
[Redis](https://redis.io/) is an in-memory data structure store. It can be used as an in-memory store, as a cache or as a message broker. Obviously, latter case is quite interesting when it comes to Platypush :)
@ -395,7 +395,7 @@ Messages received over the configured queue (requests, responses or events) will
# MQTT backend
[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/mqtt.html)
[Backend reference](https://docs.platypush.tech/en/latest/platypush/backend/mqtt.html)
[MQTT](http://mqtt.org/) is a message-queue based protocol to exchange messages across devices. MQTT implementations like Paho MQTT, Mosquitto and Adafruit IO are quite popular for communication across IoT devices. You can interact with an MQTT service through this plugin to build any arbitrary complex message-based logic across your Platypush devices. The asynchronous nature of MQTT makes it a better candidate over the HTTP plugin to deliver messages to other devices if you don't mind much about the response.
@ -416,7 +416,7 @@ You can now start sending messages to your backend through the [MQTT plugin](plu
# Websocket backend
[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/websocket.html)
[Backend reference](https://docs.platypush.tech/en/latest/platypush/backend/websocket.html)
You can send messages to Platypush over a websocket connection. Example configuration:
@ -450,7 +450,7 @@ wscat -w 0 -c 'ws://turing:8765' -x '{"type":"request", "target":"hostname", "ac
# TCP backend
[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/tcp.html)
[Backend reference](https://docs.platypush.tech/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:
@ -469,7 +469,7 @@ echo -n '{"type":"request", "target":"hostname", "action":"plugin.action"}' | nc
# Pushbullet backend
[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/pushbullet.html)
[Backend reference](https://docs.platypush.tech/en/latest/platypush/backend/pushbullet.html)
[Pushbullet](https://www.pushbullet.com/) is a quite cool piece of software to keep your devices in sync, exchange messages, synchronize clipboards and sms across devices, access remote files, and so on. You can install it as an Android or iPhone app, as a browser extension, or use it from your browser directly. It can be quite powerful if paired with Platypush - and it has the first backend I have developed as well. You can use the plugin in pair with the backend to do things like:
@ -646,7 +646,7 @@ You can also send raw Platypush messages (requests, responses and events) over P
Such feature is quite useful for example to execute plugin actions or deliver events to your Platypush devices through your Android device, using [Tasker](https://play.google.com/store/apps/details?id=net.dinglisch.android.taskerm) with the [Pushbullet plugin](https://play.google.com/store/apps/details?id=com.gerus.push.tasker). For instance, you can create a rule that sends a specific text to your Platypush device or a JSON request with a properly formatted request whenever your phone enters your home area, for example to turn on the lights or the heating.
You can also communicate the other way around: you can programmatically send pushes to Pushbullet from Platypush using the [plugin](https://platypush.readthedocs.io/en/latest/platypush/plugins/pushbullet.html) and you can build rules in Tasker on your mobile device to execute specific actions depending on the received message - for example start ringing if you say "find my phone" to the assistant, play a song by URI on the Spotify app, open Google Maps with the directions from your home to a specific place, and so on.
You can also communicate the other way around: you can programmatically send pushes to Pushbullet from Platypush using the [plugin](https://docs.platypush.tech/en/latest/platypush/plugins/pushbullet.html) and you can build rules in Tasker on your mobile device to execute specific actions depending on the received message - for example start ringing if you say "find my phone" to the assistant, play a song by URI on the Spotify app, open Google Maps with the directions from your home to a specific place, and so on.
You can also connect [IFTTT](https://ifttt.com) to Platypush actions by leveraging Pushbullet. For example, you can create an applet triggered on sunset (date/time channel) to turn on the lights by sending a push like this to your Platypush device:
@ -656,7 +656,7 @@ You can also connect [IFTTT](https://ifttt.com) to Platypush actions by leveragi
# Kafka backend
[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/kafka.html)
[Backend reference](https://docs.platypush.tech/en/latest/platypush/backend/kafka.html)
[Apache Kafka](https://kafka.apache.org/) is a distributed streaming platform that allows you to build flexible message-based interfaces across your devices.
@ -665,7 +665,7 @@ You can connect Platypush to a Kafka broker server through this backend and conf
Messages received over the topic will:
* Be processed as Platypush messages (requests, responses or messages) if they are valid JSON-formatted messages
* Trigger a [`KafkaMessageEvent`](https://platypush.readthedocs.io/en/latest/platypush/event/kafka) that you can build event hooks on otherwise
* Trigger a [`KafkaMessageEvent`](https://docs.platypush.tech/en/latest/platypush/event/kafka) that you can build event hooks on otherwise
The configuration is quite straightforward:
@ -677,7 +677,7 @@ backend.kafka:
# MPD/Mopidy backend
[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/music.mpd.html)
[Backend reference](https://docs.platypush.tech/en/latest/platypush/backend/music.mpd.html)
You can use this backend to get events from your MPD/Mopidy music server, for instance when a new track is being played, when the playback is paused/resumed or when the current playlist changes.
@ -712,7 +712,7 @@ event.hook.ScrobbleNewTrack:
# MIDI backend
[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/midi.html)
[Backend reference](https://docs.platypush.tech/en/latest/platypush/backend/midi.html)
You can listen for events on a MIDI port. You can use to do things like connecting a MIDI keyboard or drumkit. You can set up cool things like controlling your house with your MIDI piano - with 88 keys you've got plenty of configuration choices :)
@ -751,7 +751,7 @@ procedure.sync.OnMidiEvent:
# Flic buttons backend
[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/button.flic.html)
[Backend reference](https://docs.platypush.tech/en/latest/platypush/backend/button.flic.html)
[Flic buttons](https://flic.io/) are clever smart buttons controlled over bluetooth. You can get the app and configure it to run anything on a button press - running Tasker actions, playing some media, make a phone call etc. - or you can get the Flic backend configured on Platypush to use the buttons to control actions on your computer or Raspberry instead of your phone.
@ -799,11 +799,11 @@ event.hook.FlicButtonStartConversation:
## Raspberry Pi camera backend
[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/camera.pi.html)
[Backend reference](https://docs.platypush.tech/en/latest/platypush/backend/camera.pi.html)
Control your [RaspberryPi camera](https://www.raspberrypi.org/products/camera-module-v2/), take pictures or record either to file or to a network stream through this backend.
You can programmatically control this backend (start and stop recording or take pictures) through the [Pi Camera plugin](https://platypush.readthedocs.io/en/latest/platypush/plugins/camera.pi.html).
You can programmatically control this backend (start and stop recording or take pictures) through the [Pi Camera plugin](https://docs.platypush.tech/en/latest/platypush/plugins/camera.pi.html).
Sample configuration:
@ -814,7 +814,7 @@ backend.camera.pi:
# you can start recording with a call to the `camera.pi.start_recording` action
```
See the [online reference](https://platypush.readthedocs.io/en/latest/platypush/backend/camera.pi.html#platypush.backend.camera.pi.CameraPiBackend.__init__) for all the supported camera options.
See the [online reference](https://docs.platypush.tech/en/latest/platypush/backend/camera.pi.html#platypush.backend.camera.pi.CameraPiBackend.__init__) for all the supported camera options.
Once restarted Platypush you can connect to your Pi camera through a remote client using for instance vlc or mplayer:
@ -836,7 +836,7 @@ curl -XPOST -H 'Content-Type: application/json' \
# Sensor backends
Platypush comes with a wide selection of backends to interact with sensors of various types. And you can easily create your own backend to interact with a new class of sensors by extending the [base sensor backend](https://platypush.readthedocs.io/en/latest/platypush/backend/sensor.html) and implement the `get_measurement` method to get the values. Any sensor backend gets a configuration interface that allows you to specify the poll interval and the thresholds:
Platypush comes with a wide selection of backends to interact with sensors of various types. And you can easily create your own backend to interact with a new class of sensors by extending the [base sensor backend](https://docs.platypush.tech/en/latest/platypush/backend/sensor.html) and implement the `get_measurement` method to get the values. Any sensor backend gets a configuration interface that allows you to specify the poll interval and the thresholds:
```yaml
backend.sensor.sensor_name:
@ -853,15 +853,15 @@ backend.sensor.sensor_name:
A sensor backend will trigger three types of events:
* [`SensorDataChangeEvent`](https://platypush.readthedocs.io/en/latest/platypush/events/sensor.html#platypush.message.event.sensor.SensorDataChangeEvent.__init__) when the value read from a sensor changes
* [`SensorDataAboveThresholdEvent`](https://platypush.readthedocs.io/en/latest/platypush/events/sensor.html#platypush.message.event.sensor.SensorDataAboveThresholdEvent.__init__) when a sensor value goes above a configured threshold
* [`SensorDataBelowThresholdEvent`](https://platypush.readthedocs.io/en/latest/platypush/events/sensor.html#platypush.message.event.sensor.SensorDataBelowThresholdEvent.__init__) when a sensor value goes below a configured threshold
* [`SensorDataChangeEvent`](https://docs.platypush.tech/en/latest/platypush/events/sensor.html#platypush.message.event.sensor.SensorDataChangeEvent.__init__) when the value read from a sensor changes
* [`SensorDataAboveThresholdEvent`](https://docs.platypush.tech/en/latest/platypush/events/sensor.html#platypush.message.event.sensor.SensorDataAboveThresholdEvent.__init__) when a sensor value goes above a configured threshold
* [`SensorDataBelowThresholdEvent`](https://docs.platypush.tech/en/latest/platypush/events/sensor.html#platypush.message.event.sensor.SensorDataBelowThresholdEvent.__init__) when a sensor value goes below a configured threshold
## Infrared sensors
### ZeroBorg backend
[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/sensor.ir.zeroborg.html)
[Backend reference](https://docs.platypush.tech/en/latest/platypush/backend/sensor.ir.zeroborg.html)
The [ZeroBorg](https://www.piborg.org/motor-control-1135/zeroborg) is a nice piece of circuitry that pairs quite well with any Raspberry and allows you to easily control motors. It also comes with a built-in infrared sensor. If this backend is enabled, it will listen for infrared events (e.g. from one of your remotes) that you can map to run any custom action.
@ -892,7 +892,7 @@ event.hook.OnRemoteBlueLightPress:
## MCP3008
[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/sensor.mcp3008.html)
[Backend reference](https://docs.platypush.tech/en/latest/platypush/backend/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.
@ -941,7 +941,7 @@ event.hook.OnSensorAboveThreshold:
## Arduino and serial backend
[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/sensor.serial.html)
[Backend reference](https://docs.platypush.tech/en/latest/platypush/backend/sensor.serial.html)
It's possible to poll for sensor events on a serial interface as well, e.g. through an Arduino or compatible device. The only advice is to program your microcontroller so that it returns sensors data as a JSON string over the serial interface, e.g.
@ -968,7 +968,7 @@ You can now configure your event hooks on `SensorDataChangeEvent`, `SensorDataAb
# inotify backend
[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/inotify.html)
[Backend reference](https://docs.platypush.tech/en/latest/platypush/backend/inotify.html)
[inotify](https://en.wikipedia.org/wiki/Inotify) is a Linux kernel subsystem that allows you to monitor events on your filesystem (file opened, changed, created etc.).
@ -1005,7 +1005,7 @@ event.hook.OnFileChanged:
# Smart cards backend
[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/scard.html)
[Backend reference](https://docs.platypush.tech/en/latest/platypush/backend/scard.html)
You can use the smart card backend to read smart card (NFC) events through a USB or compatible NFC card reader.
@ -1058,5 +1058,5 @@ For now, you can for instance put your own custom Platypush commands on a smart
# Weather forecast backend
[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/weather.forecast.html)
[Backend reference](https://docs.platypush.tech/en/latest/platypush/backend/weather.forecast.html)

8
Home.md

@ -19,9 +19,9 @@ The base components are:
* The __Bus__: An internal queue where all the other components exchange messages.
* __Backends__: Components that poll other data sources (a local queue, a remote websocket, a Kafka instance, or even a vocal assistant, a programmable button or a sensor) and post either requests or events on the bus when something happens on the data source. Some of them can have a full-duplex integration with the bus, i.e. post requests and events on the bus as they come and deliver responses from the bus back to the sender (examples: PushBullet, Apache Kafka, HTTP services, sockets), while some are pure data sources that will only post events on the bus (examples: sensors, buttons, vocal assistants). Check [our documentation](https://platypush.readthedocs.io/en/latest/backends.html) for a complete reference of the available backends.
* __Backends__: Components that poll other data sources (a local queue, a remote websocket, a Kafka instance, or even a vocal assistant, a programmable button or a sensor) and post either requests or events on the bus when something happens on the data source. Some of them can have a full-duplex integration with the bus, i.e. post requests and events on the bus as they come and deliver responses from the bus back to the sender (examples: PushBullet, Apache Kafka, HTTP services, sockets), while some are pure data sources that will only post events on the bus (examples: sensors, buttons, vocal assistants). Check [our documentation](https://docs.platypush.tech/en/latest/backends.html) for a complete reference of the available backends.
* __Plugins__: Configurable components which expose _actions_ that can be triggered by requests or events. Examples: smart lights, music controls, YouTube or torrentcast features, text-to-speech, generic shell commands, etc.). They would usually deliver output and errors as responses on the bus. Check [our documentation](https://platypush.readthedocs.io/en/latest/plugins.html) for a complete reference of the available plugins.
* __Plugins__: Configurable components which expose _actions_ that can be triggered by requests or events. Examples: smart lights, music controls, YouTube or torrentcast features, text-to-speech, generic shell commands, etc.). They would usually deliver output and errors as responses on the bus. Check [our documentation](https://docs.platypush.tech/en/latest/plugins.html) for a complete reference of the available plugins.
* __Procedures__: Pre-configured lists of actions that can be triggered by requests or events.
@ -29,7 +29,7 @@ The base components are:
* A _condition_, which can be fuzzly compared against an event. The matching logic will also return a _match score_ if the condition is met. The score is a function of the number of atomic matches (string tokens, scalars, key-values etc.) in the condition that are satisfied by a certain event. If multiple hooks are satisfied by a certain event, the algorithm will only run the ones with the highest score.
* One or more _actions_ to be executed in case of event match (e.g. "turn on the lights", "send a Messenger message to my s.o.", "turn on the heating", "play the radio" etc.)
Check [our documentation](https://platypush.readthedocs.io/en/latest/events.html) for a complete reference of the available events.
Check [our documentation](https://docs.platypush.tech/en/latest/events.html) for a complete reference of the available events.
# Installation
@ -62,7 +62,7 @@ There are two advised ways to install extra dependencies for the plugins you wan
#### `pip` extras
You can easily install the optional dependencies for the extra plugins you want to use by using the [PEP-508 extras syntax](https://www.python.org/dev/peps/pep-0508/#extras). For example, if you want to run the [HTTP server](https://platypush.readthedocs.io/en/latest/platypush/backend/http.html) then you can install it through:
You can easily install the optional dependencies for the extra plugins you want to use by using the [PEP-508 extras syntax](https://www.python.org/dev/peps/pep-0508/#extras). For example, if you want to run the [HTTP server](https://docs.platypush.tech/en/latest/platypush/backend/http.html) then you can install it through:
```shell
pip install "platypush[http]"

82
Plugins.md

@ -32,11 +32,11 @@
* [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.
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://docs.platypush.tech/en/latest/plugins.html) page for a more complete reference.
# MPD/Mopidy support
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/music.mpd.html).
[Plugin reference](https://docs.platypush.tech/en/latest/platypush/plugins/music.mpd.html).
[MPD](https://musicpd.org/) is an application that allows to manage and play your music collection through a scalable client/server model. You can have your server running on a machine with a hard drive stuffed with mp3s, and access your collection from anywhere using a big family of compatible command line, graphical, web or mobile clients. [Mopidy](https://www.mopidy.com/) is an evolution of MPD that allows you to access music content from multiple sources through a wide set of plugins - e.g. Spotify, SoundCloud, Deezer, Pandora, TuneIn, Google Music.
@ -118,7 +118,7 @@ procedure.sync.search_and_play_song:
# Redis plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/redis.html)
[Plugin reference](https://docs.platypush.tech/en/latest/platypush/plugins/redis.html)
[Redis](https://redis.io/) is an in-memory data structure store. It can be used as an in-memory store, as a cache or as a message broker. Obviously, latter case is quite interesting when it comes to Platypush :)
@ -134,7 +134,7 @@ curl -XPOST -H 'Content-Type: application/json' \
# Video and media support
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/video.omxplayer.html)
[Plugin reference](https://docs.platypush.tech/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.
@ -246,7 +246,7 @@ If you enabled the plugin you'll also have a nice [video search and control tab]
# Philips Hue lights support
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/light.hue.html)
[Plugin reference](https://docs.platypush.tech/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.
@ -302,7 +302,7 @@ By enabling any of these plugins (even creating an empty config entry just with
## Belkin WeMo Switch
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/switch.wemo.html)
[Plugin reference](https://docs.platypush.tech/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...
@ -316,7 +316,7 @@ curl -XPOST -H 'Content-Type: application/json' \
## TP-Link smart plugs
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/switch.tplink.html)
[Plugin reference](https://docs.platypush.tech/en/latest/platypush/plugins/switch.tplink.html)
This plugin allows you to interact with TP-Link smart plugs like the [HS100](https://www.tp-link.com/us/products/details/cat-5516_HS100.html).
@ -330,7 +330,7 @@ curl -XPOST -H 'Content-Type: application/json' \
## Switchbot
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/switch.switchbot.html)
[Plugin reference](https://docs.platypush.tech/en/latest/platypush/plugins/switch.switchbot.html)
[Switchbot](https://www.switch-bot.com/) is a quite interesting smart home device as it aims to make non-smart devices "smart". It consists in a box with a small bluetooth-controlled mechanical arm that can apply enough pressure to press any button - you can use it to control through Platypush the buttons on your coffee machine, your dishwasher or your old tv for instance.
@ -363,7 +363,7 @@ curl -XPOST -H 'Content-Type: application/json' \
# Shell plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/shell.html)
[Plugin reference](https://docs.platypush.tech/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:
@ -373,7 +373,7 @@ 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)
[Plugin reference](https://docs.platypush.tech/en/latest/platypush/plugins/http.request.html)
You can programmatically send HTTP requests in your event hooks and procedures through the `http.request` plugin.
@ -397,7 +397,7 @@ event.hook.TellMeTheWeather:
# Database plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/db.html)
[Plugin reference](https://docs.platypush.tech/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...).
@ -423,7 +423,7 @@ procedure.sync.log_temperature:
temperature: ${temperature}
```
[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.
[update](https://docs.platypush.tech/en/latest/platypush/plugins/db.html#platypush.plugins.db.DbPlugin.update) and [delete](https://docs.platypush.tech/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):
@ -445,7 +445,7 @@ curl -XPOST -H 'Content-type: application/json' \
# Variables
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/variable.google.html)
[Plugin reference](https://docs.platypush.tech/en/latest/platypush/plugins/variable.google.html)
`variable` is a special plugin that allows to set, get and unset variables that you can reuse for instance within a procedure execution, to store states that will be used by some other pieces of logic, or share data with other programs.
@ -482,7 +482,7 @@ curl -XPOST -H 'Content-type: application/json' \
# Google Assistant plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/assistant.google.html)
[Plugin reference](https://docs.platypush.tech/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:
@ -499,7 +499,7 @@ event.hook.FlicButtonStartConversation:
# Calendar plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/calendar.html)
[Plugin reference](https://docs.platypush.tech/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.
@ -515,7 +515,7 @@ calendar:
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.
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://docs.platypush.tech/en/latest/platypush/plugins/google.html) on how to generate OAuth2 tokens for your Google account that these plugins can use.
# Sensor plugins
@ -523,7 +523,7 @@ 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)
[Plugin reference](https://docs.platypush.tech/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.
@ -597,7 +597,7 @@ If you want to poll your sensors periodically and get a Platypush event whenever
## Distance
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/gpio.sensor.distance.html)
[Plugin reference](https://docs.platypush.tech/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.
@ -633,7 +633,7 @@ Output (in millimiters):
# Serial
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/serial.html)
[Plugin reference](https://docs.platypush.tech/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.).
@ -677,7 +677,7 @@ Once you enable the `serial` or `mcp3008` plugin and backend you'll be able to m
# ZeroBorg
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/gpio.zeroborg.html)
[Plugin reference](https://docs.platypush.tech/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.
@ -738,7 +738,7 @@ curl -XPOST -H 'Content-Type: application/json' \
# MIDI plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/midi.html)
[Plugin reference](https://docs.platypush.tech/en/latest/platypush/plugins/midi.html)
Some of the musicians who ended up on this page probably know the [MIDI protocol](http://www.indiana.edu/~emusic/361/midi.htm). Platypush allows you to register a custom MIDI device that can send messages to the OS MIDI sequencer. It's like tricking your machine to think that Platypush is a MIDI keyboard or drum machine. You can for instance create some instrument tracks in LMMS or FruityLoops, link them to your Platypush MIDI source, and play notes through any kind of events that Platypush can process - you can use a Leap Motion to play notes by just waving your hand, use a proximity sensor, play notes with switches and buttons, and so on, the only limit being your creativity.
@ -750,13 +750,13 @@ curl -XPOST -H 'Content-Type: application/json' \
http://hostname:8008/execute
```
You can also send raw MIDI messages through the [`send_message`](https://platypush.readthedocs.io/en/latest/platypush/plugins/midi.html#platypush.plugins.midi.MidiPlugin.send_message) action.
You can also send raw MIDI messages through the [`send_message`](https://docs.platypush.tech/en/latest/platypush/plugins/midi.html#platypush.plugins.midi.MidiPlugin.send_message) action.
You can also listen for MIDI events and run actions based on them by using the MIDI backend.
# MQTT plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/mqtt.html)
[Plugin reference](https://docs.platypush.tech/en/latest/platypush/plugins/mqtt.html)
[MQTT](http://mqtt.org/) is a message-queue based protocol to exchange messages across devices. MQTT implementations like Paho MQTT, Mosquitto and Adafruit IO are quite popular for communication across IoT devices. You can interact with an MQTT service through this plugin to build any arbitrary complex message-based logic across your Platypush devices. The asynchronous nature of MQTT makes it a better candidate over the HTTP plugin to deliver messages to other devices if you don't mind much about the response. An HTTP call to the Flask server to turn on the lights, for example, requires the sender to wrap the request into an HTTP message, the receiver to react immediately on that while the sender is synchrounously waiting for an answer, execute the light control action (which might take a while), and then wrap the response into an HTTP message back to the sender. Compare it instead with a message-queue based implementation, where you send the message to a queue where the receiver is listening and as soon as the receiver is available it will pick it up - no need for the sender to hang for the response. Also, the message queue doesn't require the receiver to be directly accessible (through IP/hostname and port) to the sender, as it happens in an HTTP interaction. The sender can send a message to the queue, hosted by an MQTT server, and as long as the receiver (or any receiver) is listening on the same queue, the message will be picked up.
@ -774,7 +774,7 @@ You can (or should) of course also use the [MQTT backend](Backends#mqtt-backend)
# Pushbullet plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/pushbullet.html)
[Plugin reference](https://docs.platypush.tech/en/latest/platypush/plugins/pushbullet.html)
[Pushbullet](https://www.pushbullet.com/) is a quite cool piece of software to keep your devices in sync, exchange messages, synchronize clipboards and sms across devices, access remote files, and so on. You can install it as an Android or iPhone app, as a browser extension, or use it from your browser directly. It can be quite powerful if paired with Platypush - and it has the first backend I have developed as well. You can use the plugin in pair with the backend to do things like:
@ -797,7 +797,7 @@ curl -XPOST -H 'Content-Type: application/json' \
# Kafka plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/kafka.html)
[Plugin reference](https://docs.platypush.tech/en/latest/platypush/plugins/kafka.html)
Use this plugin if you want to synchronize messages to your devices over a Kafka message instance. Some use cases:
@ -826,7 +826,7 @@ curl -XPOST -H 'Content-Type: application/json' \
# IFTTT plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/ifttt.html)
[Plugin reference](https://docs.platypush.tech/en/latest/platypush/plugins/ifttt.html)
[IFTTT](https://ifttt.com) is a very versatile cloud service to automate tasks and trigger actions on particular events. IFTTT comes with some channels that may not be available on Platypush (e.g. trigger events on your Android or iOS device, send Telegram messages, create Trello tasks etc.), or you've been an IFTTT user already and you might want to integrate Platypush with your existing IFTTT configuration.
@ -859,7 +859,7 @@ curl -XPOST -H 'Content-Type: application/json' \
# Adafruit IO plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/adafruit.io.html)
[Plugin reference](https://docs.platypush.tech/en/latest/platypush/plugins/adafruit.io.html)
[Adafruit IO](https://io.adafruit.com) is a message-based cloud storage for numerical values. You can use it to store reads from your sensors, see the values on the Adafruit dashboard wherever you are, trigger IFTTT rules if a value goes below or above a threshold and so on.
@ -891,7 +891,7 @@ procedure.sync.OnSensorData:
# Autoremote plugin
[Plugin reference](https://platypush.readthedocs.io/en/latest/platypush/plugins/autoremote.html)
[Plugin reference](https://docs.platypush.tech/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 :)
@ -911,19 +911,19 @@ autoremote:
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.
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://docs.platypush.tech/en/latest/platypush/plugins/autoremote.html#platypush.plugins.autoremote.AutoremotePlugin.send_message) and [send_notification](https://docs.platypush.tech/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)
[Plugin reference](https://docs.platypush.tech/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.
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://docs.platypush.tech/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)
[Plugin reference](https://docs.platypush.tech/en/latest/platypush/plugins/torrent.html)
You can use Platypush to search, download and manage torrents. Example configuration:
@ -935,18 +935,18 @@ torrent:
- 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.
Refer to the [plugin reference](https://docs.platypush.tech/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.
Note also that the `download` method will generate few [types of events](https://docs.platypush.tech/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.
* [TorrentDownloadStartEvent](https://docs.platypush.tech/en/latest/platypush/events/torrent.html#platypush.message.event.torrent.TorrentDownloadStartEvent) when a torrent starts downloading.
* [TorrentSeedingStartEvent](https://docs.platypush.tech/en/latest/platypush/events/torrent.html#platypush.message.event.torrent.TorrentSeedingStartEvent) when a torrent starts seeding.
* [TorrentStateChangeEvent](https://docs.platypush.tech/en/latest/platypush/events/torrent.html#platypush.message.event.torrent.TorrentStateChangeEvent) when a torrent status changes.
* [TorrentDownloadProgressEvent](https://docs.platypush.tech/en/latest/platypush/events/torrent.html#platypush.message.event.torrent.TorrentDownloadProgressEvent) when the download progress state of a torrent changes.
* [TorrentDownloadStopEvent](https://docs.platypush.tech/en/latest/platypush/events/torrent.html#platypush.message.event.torrent.TorrentDownloadStopEvent) when the download of a torrent stops.
* [TorrentDownloadCompletedEvent](https://docs.platypush.tech/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)
[Plugin reference](https://docs.platypush.tech/en/latest/platypush/plugins/weather.forecast.html)

8
Quickstart.md

@ -25,11 +25,11 @@
# Quick start
In this first example, let's suppose that you want to control your smart lights (we'll use the [Philips Hue](https://www2.meethue.com/en-us) plugin in this example, but you can easily use any other plugin) whenever you say "turn on the lights" to your embedded smart assistant (Platypush comes with [support for Google Assistant](https://platypush.readthedocs.io/en/latest/platypush/backend/assistant.google.html) through the [Google SDK](https://developers.google.com/assistant/sdk/), all you need is a microphone plugged into your device).
In this first example, let's suppose that you want to control your smart lights (we'll use the [Philips Hue](https://www2.meethue.com/en-us) plugin in this example, but you can easily use any other plugin) whenever you say "turn on the lights" to your embedded smart assistant (Platypush comes with [support for Google Assistant](https://docs.platypush.tech/en/latest/platypush/backend/assistant.google.html) through the [Google SDK](https://developers.google.com/assistant/sdk/), all you need is a microphone plugged into your device).
1. Start by creating an empty configuration file. It will be `/etc/platypush/config.yaml` if you want to share the configuration with all the user on the machine, or `~/.config/platypush/config.yaml` if you want a user-specific configuration.
2. Download the `phue` Python package (``pip install phue``), required by the [Hue plugin](https://platypush.readthedocs.io/en/latest/platypush/plugins/light.hue.html)
2. Download the `phue` Python package (``pip install phue``), required by the [Hue plugin](https://docs.platypush.tech/en/latest/platypush/plugins/light.hue.html)
3. Add the Hue configuration to your file:
@ -113,7 +113,7 @@ The web interface will also require basic HTTP authentication through this token
Note that if you configured a token you'll be promped with a basic HTTP authentication. The password will be your token, any username works for now.
9. Check out [the plugin docs](https://platypush.readthedocs.io/en/latest/platypush/plugins/light.hue.html) to know more about the configuration variables or the supported methods for this plugin. The configuration values for any plugin are simply the parameters passed to its constructor. Same for the methods - just pass them on `args`:
9. Check out [the plugin docs](https://docs.platypush.tech/en/latest/platypush/plugins/light.hue.html) to know more about the configuration variables or the supported methods for this plugin. The configuration values for any plugin are simply the parameters passed to its constructor. Same for the methods - just pass them on `args`:
```shell
curl -XPOST -H 'Content-Type: application/json' \
@ -183,7 +183,7 @@ Note how the example above uses another plugin - `shell.exec` to run a shell com
Also, please note that the actions executed in an event hook will be executed in parallel. If you want to execute action synchronously, consider wrapping them into a synchronous _procedure_.
Congratulation, you've set up your first rule! Check out the [plugins documentation](https://platypush.readthedocs.io/en/latest/plugins.html), the [backends documentation](https://platypush.readthedocs.io/en/latest/backends.html) and the [events documentation](https://platypush.readthedocs.io/en/latest/events.html) for the list of supported plugins, backends and events.
Congratulation, you've set up your first rule! Check out the [plugins documentation](https://docs.platypush.tech/en/latest/plugins.html), the [backends documentation](https://docs.platypush.tech/en/latest/backends.html) and the [events documentation](https://docs.platypush.tech/en/latest/events.html) for the list of supported plugins, backends and events.
# Procedures