From 81e2b6766231e6d0853147c3c1218cbdda8d0732 Mon Sep 17 00:00:00 2001 From: Fabio Manganiello Date: Wed, 3 Jan 2018 15:12:23 +0100 Subject: [PATCH] Created configuration (markdown) --- configuration.md | 244 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 244 insertions(+) create mode 100644 configuration.md diff --git a/configuration.md b/configuration.md new file mode 100644 index 0000000..626ab73 --- /dev/null +++ b/configuration.md @@ -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 . +``` + +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 +``` \ No newline at end of file