Created configuration (markdown)
Fabio Manganiello
parent
ea3b8417c6
commit
81e2b67662
|
|
@ -0,0 +1,244 @@
|
|||
# Configuration
|
||||
|
||||
* [Backends](#backends)
|
||||
* [PushBullet](#pushbullet-configuration)
|
||||
* [Apache Kafka](#apache-kafka-configuration)
|
||||
* [Local backend](#local-backend-configuration)
|
||||
* [Google Assistant](#google-assistant-configuration)
|
||||
* [Flic buttons](#flic-buttons-configuration)
|
||||
* [Plugins](#plugins)
|
||||
* [MPD/Mopidy](#mpd-mopidy-support)
|
||||
* [Video and media](#video-and-media-support)
|
||||
* [Philips Hue lights](#philips-hue-lights-support)
|
||||
* [Belkin WeMo Switch](#belkin-wemo-switch)
|
||||
* [Text-to-Speech](#text-to-speech-support)
|
||||
* [Shell plugin](#shell-plugin)
|
||||
* [Procedures](#procedures)
|
||||
* [Event Hooks](#event-hooks)
|
||||
|
||||
Copy `/etc/platypush/config.example.yaml` to `/etc/platypush/config.yaml` (system-wise settings) or `~/.config/platypush/config.yaml` (user-wise settings).
|
||||
|
||||
Some configuration snippets:
|
||||
|
||||
### device_id
|
||||
|
||||
Each target device is identified by a unique device_id in the messages sent over your account. The device_id is the hostname by default, unless a different value is set in config.yaml at the root level.
|
||||
|
||||
### Backends
|
||||
|
||||
Platypush comes by default with a [PushBullet](https://www.pushbullet.com/) backend, an [Apache Kafka](https://kafka.apache.org/) backend, and a (quite unstable) local backend based on fifos. Backend configurations start with `backend.` in the `config.yaml`.
|
||||
|
||||
#### PushBullet configuration
|
||||
|
||||
You will need:
|
||||
|
||||
* Your PushBullet access token (create one [here](https://www.pushbullet.com/#settings/account));
|
||||
* The name of the (virtual) PushBullet device used to listen for events (create one [here](https://www.pushbullet.com/#devices)).
|
||||
|
||||
```yaml
|
||||
backend.pushbullet:
|
||||
token: PUSHBULLET_TOKEN
|
||||
device: platypush
|
||||
```
|
||||
|
||||
#### Apache Kafka configuration
|
||||
|
||||
This would be a sample snippet for an Apache Kafka configuration:
|
||||
|
||||
```yaml
|
||||
backend.kafka:
|
||||
pusher: True # Default pusher backend
|
||||
server: server:9092 # Kafka server and port
|
||||
topic: platypush # Topic prefix. Note: platypush will create a topic for each device named <topic>.<device_id>
|
||||
```
|
||||
|
||||
Note: specifying `pusher: True` on a backend configuration means that that backend will be the default one used to deliver requests or events to other nodes through the `pusher` script, if no `--backend` option is passed.
|
||||
|
||||
#### Local backend configuration
|
||||
|
||||
```yaml
|
||||
backend.local:
|
||||
request_fifo: /tmp/platypush-requests.fifo
|
||||
response_fifo: /tmp/platypush-responses.fifo
|
||||
```
|
||||
|
||||
#### Google Assistant configuration
|
||||
|
||||
Follow the steps on the [Google Assistant SDK](https://github.com/googlesamples/assistant-sdk-python/tree/master/google-assistant-sdk) page and get the assistant sample running on your machine.
|
||||
|
||||
Afterwards, you can enable custom speech-triggered actions on Platypush by just enabling the assistant backend:
|
||||
|
||||
```yaml
|
||||
backend.assistant.google:
|
||||
disabled: False
|
||||
```
|
||||
|
||||
#### Flic buttons configuration
|
||||
|
||||
[Flic buttons](https://flic.io/) are a quite cool and useful accessory. You can pair them with your phone over Bluetooth and they can trigger anything on your device - play music on Spotify, start a timer, trigger a Tasker task, snooze alarms, trigger fake phone calls...
|
||||
|
||||
A [beta SDK](https://github.com/50ButtonsEach/fliclib-linux-hci) is available as well that allows you to pair the buttons to any bluetooth device, not necessarily running the Flic app.
|
||||
|
||||
Install the SDK and run the `flicd` server on your machine. You can then enable the Flic plugin:
|
||||
|
||||
```yaml
|
||||
backend.button.flic:
|
||||
server: localhost
|
||||
|
||||
```
|
||||
|
||||
By the way, the Flic app only supports a maximum of three events per button - short press, long press and double press. With the Platypush plugin you can trigger countless actions by configuring multiple combinations of short and long presses - provided that you can remember them.
|
||||
|
||||
### Plugins
|
||||
|
||||
A couple of plugins are available out of the box with platypush under `plugins/`. Some of them may require extras Python or system dependencies. Some of the available plugins include:
|
||||
|
||||
#### MPD/Mopidy support
|
||||
|
||||
[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.
|
||||
|
||||
Platypush can be a client for your MPD/Mopidy music server, allowing you to search for music, control your queue and the playback upon requests or events.
|
||||
|
||||
Configuration:
|
||||
|
||||
```yaml
|
||||
music.mpd:
|
||||
host: localhost
|
||||
port: 6600
|
||||
```
|
||||
|
||||
#### Video and media support
|
||||
|
||||
Platypush comes with support for video media, including YouTube, local media and torrents (requires [torrentcast](https://www.npmjs.com/package/torrentcast)). It's quite handy to turn a RaspberryPi into a full-blown media server or a Chromecast on steroids, voice controls included.
|
||||
|
||||
```yaml
|
||||
video.omxplayer:
|
||||
args:
|
||||
- -o
|
||||
- alsa # or hdmi
|
||||
# ... any other default options for OMXPlayer
|
||||
|
||||
video.torrentcast:
|
||||
server: localhost
|
||||
port: 9090
|
||||
```
|
||||
|
||||
#### Philips Hue lights support
|
||||
|
||||
Control your [Philips Hue](https://www2.meethue.com/en-us) lights with custom requests and events triggered by your devices.
|
||||
|
||||
```yaml
|
||||
light.hue:
|
||||
bridge: bridge_name_or_ip
|
||||
# If no lights or groups to actions are specified in
|
||||
# the action or in the default configuration, all the
|
||||
# lights will be targeted.
|
||||
|
||||
lights:
|
||||
- Hall
|
||||
- Living Room Left
|
||||
- Living Room Right
|
||||
- Garage
|
||||
groups:
|
||||
- Bedroom
|
||||
- Kitchen
|
||||
```
|
||||
|
||||
#### Belkin WeMo Switch
|
||||
|
||||
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...
|
||||
|
||||
The Platypush plugin requires `ouimeaux` and will work with no configuration needed.
|
||||
|
||||
#### Text-to-Speech support
|
||||
|
||||
If `mplayer` is installed, you can trigger a machine to say custom phrases in any language through the `tts` plugin. Quite cool if you want to let your RaspberryPi to automatically read you out loud the news or when you get a notification on your phone.
|
||||
|
||||
```yaml
|
||||
tts:
|
||||
lang: en-gb # Default language
|
||||
```
|
||||
|
||||
#### Shell plugin
|
||||
|
||||
You can also run custom shell commands on the target machine through the `shell` plugin, that requires (for now) no configuration.
|
||||
|
||||
### Procedures
|
||||
|
||||
Procedures are sequences of actions that will be executed in parallel or in series (*TODO*) by Platypush. Useful to refactor sequences of repeated actions in your requests or event hooks. Their configuration names start with `procedure.`.
|
||||
|
||||
```yaml
|
||||
procedure.at_home:
|
||||
-
|
||||
action: tts.say
|
||||
args:
|
||||
phrase: Welcome home, YOUR_NAME
|
||||
-
|
||||
action: light.hue.on
|
||||
-
|
||||
action: switch.wemo.on
|
||||
args:
|
||||
device: Heater
|
||||
-
|
||||
action: music.mpd.play
|
||||
args:
|
||||
resource: spotify:user:you:playlist:your_favourite_playlist
|
||||
-
|
||||
action: shell.exec
|
||||
args:
|
||||
cmd: './bin/sensors_report.sh'
|
||||
```
|
||||
|
||||
### Event Hooks
|
||||
|
||||
Event hooks are one of the most powerful features of Platypush. They are the equivalent of a profile in Tasker, or a recipe in IFTTT. They link events received on the main bus to actions that can be triggered on the local or on a remote node. Events will usually be ignored unless you configured a hook for handling them. Their configuration names start with `event.hook.`.
|
||||
|
||||
Some examples:
|
||||
|
||||
```yaml
|
||||
event.hook.AssistantConversationStarted:
|
||||
if:
|
||||
type: platypush.message.event.assistant.ConversationStartEvent
|
||||
then:
|
||||
-
|
||||
action: shell.exec
|
||||
args:
|
||||
cmd: 'aplay /usr/share/sounds/start.wav'
|
||||
|
||||
|
||||
event.hook.LightsSceneAssistantCommand:
|
||||
if:
|
||||
type: platypush.message.event.assistant.SpeechRecognizedEvent
|
||||
# Note: regex support (still quite experimental though) and support for
|
||||
# parsing context variables out of the trigger event, that can be used
|
||||
# in the executed actions. Context variables names start with $
|
||||
# (escape it with \ if you want to use the literal symbol instead).
|
||||
# The context variables already include the variables of the source event,
|
||||
# meaning that you can use $phrase as well in your action for this example.
|
||||
phrase: "set (the)? scene on $name"
|
||||
then:
|
||||
-
|
||||
action: light.hue.scene
|
||||
args:
|
||||
# If you said "set the scene on sunset", $name=sunset
|
||||
name: $name
|
||||
|
||||
|
||||
event.hook.NextSongFlicButton:
|
||||
if:
|
||||
type: platypush.message.event.button.flic.FlicButtonEvent
|
||||
btn_addr: 00:11:22:33:44:55
|
||||
sequence:
|
||||
# Lists are supported too
|
||||
- ShortPressEvent
|
||||
- LongPressEvent
|
||||
then:
|
||||
-
|
||||
action: music.mpd.next
|
||||
# You can also specify multiple actions
|
||||
-
|
||||
action: media.ctrl.forward
|
||||
# Or procedures
|
||||
-
|
||||
action: procedure.your_proc
|
||||
```
|
||||
Loading…
Reference in New Issue