Backends expanded
Fabio Manganiello
parent
88e2cc2009
commit
5608cc3145
210
Backends.md
210
Backends.md
|
|
@ -45,6 +45,13 @@ backend.http:
|
|||
|
||||
Websockets are used both in the web panel and dashboard interfaces to deliver real-time messages to the plugins and widgets.
|
||||
|
||||
**NOTE**: If you configured a security `token` on your Platypush instance (warmly recommended), then all the HTTP calls need to bear that token either:
|
||||
|
||||
- On the `X-Token` header
|
||||
- On the query string (`?token=...`)
|
||||
- At the top level of the JSON request (`{"type":"request", ..., "token":"..."}`)
|
||||
- Through interactive basic HTTP authentication in case of browser-based interaction
|
||||
|
||||
## cURL commands
|
||||
|
||||
Once you've got your web server running, you can easily send action requests to the Platypush plugins through cURL, Postman etc.
|
||||
|
|
@ -186,14 +193,217 @@ You can also configure the backend to generate a digest of the new items it scan
|
|||
|
||||
[Backend reference](https://platypush.readthedocs.io/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).
|
||||
|
||||
All you need to get a full-blown assistant with support for custom commands is any kind of computer with a microphone.
|
||||
|
||||
Follow the instructions on the [Google Assistant SDK](https://developers.google.com/assistant/sdk/guides/library/python/embed/install-sample#generate_credentials) website to get started by enabling the Assistant API, get a credentials file and install the required dependencies.
|
||||
|
||||
Then enable the Assistant backend through a configuration like this:
|
||||
|
||||
```yaml
|
||||
backend.assistant.google:
|
||||
device_model_id: Platypush # A unique device ID - default: Platypush
|
||||
credentials_file: ~/.config/google-oauthlib-tool/credentials.json # Path to the JSON credentials file
|
||||
```
|
||||
|
||||
Restart Platypush and test it out by saying _Ok Google_ or _Hey Google_. Have fun.
|
||||
|
||||
You can also enable the [Assistant plugin](Plugins#google-assistant-plugin) to programmatically start or stop the conversation without saying the hotword.
|
||||
|
||||
## Assistant events
|
||||
|
||||
You can build event hooks on assistant events - on conversation start, end, timeout, on speech recognized, on response processed etc.
|
||||
|
||||
For example, to play some custom sound when the conversation starts or ends:
|
||||
|
||||
```yaml
|
||||
event.hook.AssistantConversationStarted:
|
||||
if:
|
||||
type: platypush.message.event.assistant.ConversationStartEvent
|
||||
then:
|
||||
action: shell.exec
|
||||
args:
|
||||
cmd: 'aplay /usr/share/sounds/conversation_start.wav'
|
||||
|
||||
event.hook.AssistantConversationEnded:
|
||||
if:
|
||||
type: platypush.message.event.assistant.ConversationEndEvent
|
||||
then:
|
||||
action: shell.exec
|
||||
args:
|
||||
cmd: 'aplay /usr/share/sounds/conversation_end.wav'
|
||||
```
|
||||
|
||||
Or play the radio by just saying it using the Mopidy plugin + the TuneIn backend for Mopidy:
|
||||
|
||||
```yaml
|
||||
event.hook.PlayRadioAssistantCommand:
|
||||
if:
|
||||
type: platypush.message.event.assistant.SpeechRecognizedEvent
|
||||
phrase: "play (the)? radio"
|
||||
then:
|
||||
action: music.mpd.play
|
||||
args:
|
||||
resource: tunein:station:radio_id
|
||||
```
|
||||
|
||||
Note the use of `(the)?` in the phrase filter. The phrase filter supports basic regular expressions, so the filter above would trigger the hook whether the assistant recognizes "play the radio" or "play radio" - and even if the phrase is recognized within the context of a larger sentence.
|
||||
|
||||
You can also extract named tokens out of the recognized phrase. Take a look at this example that enables you to search for a song or an album by saying the artist and the title and play the first matched result:
|
||||
|
||||
```yaml
|
||||
event.hook.SearchSongVoiceCommand:
|
||||
if:
|
||||
type: platypush.message.event.assistant.SpeechRecognizedEvent
|
||||
# Use the ${} notation to denote a portion of the recognized phrase to be extracted
|
||||
# until the next recognized token or the end of the string.
|
||||
phrase: "play ${title} by ${artist}"
|
||||
then:
|
||||
-
|
||||
action: procedure.search_and_play_song
|
||||
|
||||
procedure.sync.search_and_play_song:
|
||||
-
|
||||
# Clear the content of the current playlist
|
||||
action: music.mpd.clear
|
||||
-
|
||||
# Disable shuffle mode
|
||||
action: music.mpd.random
|
||||
args:
|
||||
value: 0
|
||||
-
|
||||
# Perform an mpd search. Note how we re-used the "title" and "artist"
|
||||
# context variables parsed from the voice assistant event
|
||||
action: music.mpd.search
|
||||
args:
|
||||
filter:
|
||||
- artist
|
||||
- ${artist}
|
||||
- any
|
||||
- ${title}
|
||||
-
|
||||
# Play the first of the search results above. Note how we re-used the
|
||||
# "output" context variable, that contains the output of the previous
|
||||
# action (an array in the case of `music.mpd.search`), to get the file id
|
||||
# of the first result and pass it to `music.mpd.play`
|
||||
action: music.mpd.play
|
||||
args:
|
||||
resource: ${output[0]['file']}
|
||||
```
|
||||
|
||||
Or search and play YouTube videos:
|
||||
|
||||
```yaml
|
||||
event.hook.PlayYoutubeVideo:
|
||||
if:
|
||||
type: platypush.message.event.assistant.SpeechRecognizedEvent
|
||||
phrase: "play ${query} on youtube"
|
||||
then:
|
||||
action: video.omxplayer.search
|
||||
args:
|
||||
query: ${query}
|
||||
autoplay: True
|
||||
queue_results: True
|
||||
types:
|
||||
- youtube
|
||||
```
|
||||
|
||||
Or a torrent (will first have to download it and then stream it):
|
||||
|
||||
```yaml
|
||||
event.hook.PlayTorrent:
|
||||
if:
|
||||
type: platypush.message.event.assistant.SpeechRecognizedEvent
|
||||
phrase: "play (the)? torrent ${query}"
|
||||
then:
|
||||
action: video.omxplayer.search
|
||||
args:
|
||||
query: ${query}
|
||||
autoplay: True
|
||||
queue_results: True
|
||||
types:
|
||||
- torrent
|
||||
```
|
||||
|
||||
Or (of course) turn on the lights:
|
||||
|
||||
```yaml
|
||||
event.hook.LightsOnAssistantCommand:
|
||||
if:
|
||||
type: platypush.message.event.assistant.SpeechRecognizedEvent
|
||||
phrase: "turn on (the)? lights?"
|
||||
then:
|
||||
action: light.hue.on
|
||||
```
|
||||
|
||||
Or start a light animation:
|
||||
|
||||
```yaml
|
||||
event.hook.LightsAnimationOnAssistantCommand:
|
||||
if:
|
||||
type: platypush.message.event.assistant.SpeechRecognizedEvent
|
||||
phrase: "start (the)? animation"
|
||||
then:
|
||||
action: procedure.LightsAnimationOnAssistantCommand
|
||||
|
||||
procedure.sync.LightsAnimationOnAssistantCommand:
|
||||
-
|
||||
action: light.hue.stop_animation
|
||||
-
|
||||
action: light.hue.animate
|
||||
args:
|
||||
animation: color_transition
|
||||
sat_range: [230,255]
|
||||
bri_range: [127,255]
|
||||
hue_range: [0,65535]
|
||||
```
|
||||
|
||||
If you use the web panel or the dashboard you'll also notice that the assistant events (conversation start and end, speech recognized and processed response) will also be shown as pop-up notifications.
|
||||
|
||||
# Redis backend
|
||||
|
||||
[Backend reference](https://platypush.readthedocs.io/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 :)
|
||||
|
||||
Redis is also used heavily by some of our plugins and backends to communicate and synchronize properly, especially if the components live in different processes (for example, the web server) and need to exchange messages with the main process. Redis is a perfect candidate for the purpose. It has a low latency, and the server is lightweight enough to run even on a Raspberry Pi Zero without issues. It's therefore **strongly recommended** to enable both the Redis [plugin](Plugins#redis-plugin) and backend (and install a local Redis server) to take full advantage of Platypush features.
|
||||
|
||||
For instance, the web server backend leverages Redis to dispatch and receive inter-process messages over the websocket interface - used to deliver push notifications to the web clients.
|
||||
|
||||
After installing and starting a local Redis server, configure your backend:
|
||||
|
||||
```yaml
|
||||
backend.redis:
|
||||
queue: platypush_bus_mq # Default queue where messages will be delivered
|
||||
redis_args:
|
||||
host: localhost # Default
|
||||
port: 6379 # Default
|
||||
```
|
||||
|
||||
Messages received over the configured queue (requests, responses or events) will be routed to the application bus. A typical use case is when you want to set up another script or application that runs its own logic and you want it to interact with some Platypush plugin - all you have to do is to push an action request in JSON format on the configured Redis queue.
|
||||
|
||||
# MQTT backend
|
||||
|
||||
[Backend reference](https://platypush.readthedocs.io/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.
|
||||
|
||||
The MQTT backend will listen on a specific message queue (or _topic_ in MQTT terminology) and, just like the Redis plugin, it will post any recognized Platypush JSON message (request, response or event) to the main application.
|
||||
|
||||
Example configuration:
|
||||
|
||||
```yaml
|
||||
backend.mqtt:
|
||||
host: mqtt_server # IP or hostname that hosts the MQTT server
|
||||
port: 1883 # MQTT port
|
||||
topic: platypush_bus_mq # Queue to listen on. Note that the hostname will be appended,
|
||||
# so that each each device can listen on its own queue. Therefore
|
||||
# the actual topic name will be "platypush_bus_mq/hostname"
|
||||
```
|
||||
|
||||
You can now start sending messages to your backend through the [MQTT plugin](plugins#mqtt-plugin) or another app, also running on another machine.
|
||||
|
||||
# Pushbullet backend
|
||||
|
||||
[Backend reference](https://platypush.readthedocs.io/en/latest/platypush/backend/pushbullet.html)
|
||||
|
|
|
|||
|
|
@ -62,7 +62,7 @@ curl -XPOST -H 'Content-Type: application/json' \
|
|||
|
||||
## 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]_.
|
||||
If you have configured already the [voice assistant backend](Backends#assistant-backend), you can configure an event hook to play a song or an album whenever you say _play [item] by [artist]_.
|
||||
|
||||
First configure an event hook for it that will invoke a new synchrounous procedure:
|
||||
|
||||
|
|
@ -114,7 +114,7 @@ procedure.sync.search_and_play_song:
|
|||
|
||||
[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 :)
|
||||
|
||||
Redis is also used heavily by some of our plugins and backends to communicate and synchronize properly, especially if the components live in different processes (for example, the web server) and need to exchange messages with the main process. Redis is a perfect candidate for the purpose. It has a low latency, and the server is lightweight enough to run even on a Raspberry Pi Zero without issues. It's therefore **strongly recommended** to enable both the Redis plugin and backend (and install a Redis server) to take full advantage of Platypush features.
|
||||
Redis is also used heavily by some of our plugins and backends to communicate and synchronize properly, especially if the components live in different processes (for example, the web server) and need to exchange messages with the main process. Redis is a perfect candidate for the purpose. It has a low latency, and the server is lightweight enough to run even on a Raspberry Pi Zero without issues. It's therefore **strongly recommended** to enable both the Redis plugin and [backend](Backends#redis-backend) (and install a local Redis server) to take full advantage of Platypush features.
|
||||
|
||||
The Redis plugin has a quite simple API to deliver messages:
|
||||
|
||||
|
|
@ -760,7 +760,7 @@ curl -XPOST -H 'Content-Type: application/json' \
|
|||
http://hostname:8008/execute
|
||||
```
|
||||
|
||||
You can (or should) of course also use the MQTT backend. By doing so you can send messages across that Platypush devices containing action requests, events or responses. You can create routing rules for messages, or propagate the events you receive on a device over another one - for example I've configured a rule for all of my devices with connected sensors to route their `SensorDataChangeEvent` events over MQTT to a hub device, where I can monitor from a single web panel the values of all my sensors around the house. Another good use case for MQTT is to send messages from your Android devices to your Platypush devices. The same developer of Taker has recently developed [Join](https://joaoapps.com/join/), that allows you among the other things to programmatically send messages over MQTT. You can then create tasks that send messages to Platypush when you get a call, receive an sms, connect to some WiFi network or enter some area. You can also create Join action to send custom commands to your Platypush devices from a tap on your phone.
|
||||
You can (or should) of course also use the [MQTT backend](Backends#mqtt-backend). By doing so you can send messages across that Platypush devices containing action requests, events or responses. You can create routing rules for messages, or propagate the events you receive on a device over another one - for example I've configured a rule for all of my devices with connected sensors to route their `SensorDataChangeEvent` events over MQTT to a hub device, where I can monitor from a single web panel the values of all my sensors around the house. Another good use case for MQTT is to send messages from your Android devices to your Platypush devices. The same developer of Taker has recently developed [Join](https://joaoapps.com/join/), that allows you among the other things to programmatically send messages over MQTT. You can then create tasks that send messages to Platypush when you get a call, receive an sms, connect to some WiFi network or enter some area. You can also create Join action to send custom commands to your Platypush devices from a tap on your phone.
|
||||
|
||||
# Pushbullet plugin
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue