diff --git a/.gitignore b/.gitignore index 2cf97a71e..c08d6c1f1 100644 --- a/.gitignore +++ b/.gitignore @@ -2,7 +2,6 @@ *.swp *.pyc __pycache__ -config.yaml build/ dist/ *.egg-info/ diff --git a/examples/conf/config.yaml b/examples/conf/config.yaml new file mode 100644 index 000000000..72d831d7f --- /dev/null +++ b/examples/conf/config.yaml @@ -0,0 +1,415 @@ +################################################################################# +# Sample platypush configuration file. +# Edit it and copy it to /etc/platypush/config.yaml for system installation or to +# ~/.config/platypush/config.yaml for user installation (recommended). +################################################################################# + +# -- +# include directive example +# -- +# +# You can split your configuration over multiple files +# and use the include directive to import them in your configuration. +# Relative paths are also supported, and computed using the config.yaml +# installation directory as base folder. Symlinks are also supported. +# +# Using multiple files is encouraged in the case of large configurations +# that can easily end up in a messy config.yaml file, as they help you +# keep your configuration more organized. +include: + - include/logging.yaml + - include/media.yaml + - include/sensors.yaml + +# The device_id is used by many components of platypush and it should uniquely +# identify a device in your network. If nothing is specified then the hostname +# will be used. +device_id: myname + +## -- +## Plugin configuration examples +## -- +# +# Plugins configuration is very straightforward. Each plugin is mapped to +# a plugin class. The methods of the class with @action annotation will +# be exported as runnable actions, while the __init__ parameters are +# configuration attributes that you can initialize in your config.yaml. +# Plugin classes are documented at https://platypush.readthedocs.io/en/latest/plugins.html +# +# In this example we'll configure the light.hue plugin, see +# https://platypush.readthedocs.io/en/latest/platypush/plugins/light.hue.html +# for reference. You can easily install the required dependencies for the plugin through +# pip install 'platypush[hue]' +light.hue: + # IP address or hostname of the Hue bridge + bridge: 192.168.1.10 + # Groups that will be handled by default if nothing is specified on the request + groups: + - Living Room + +# Example configuration of music.mpd plugin, see +# https://platypush.readthedocs.io/en/latest/platypush/plugins/music.mpd.html +# You can easily install the dependencies through pip install 'platypush[mpd]' +music.mpd: + host: localhost + port: 6600 + +# Example configuration of media.chromecast plugin, see +# https://platypush.readthedocs.io/en/latest/platypush/plugins/media.chromecast.html +# You can easily install the dependencies through pip install 'platypush[chromecast]' +media.chromecast: + chromecast: Living Room TV + +# Plugins with empty configuration can also be explicitly enabled by specifying +# enabled=True or disabled=False (it's a good practice if you want the +# corresponding web panel to be enabled, if available) +camera: + enabled: True + +# Support for last.fm scrobbling. Install dependencies with 'pip install "platypush[lastfm]" +lastfm: + api_key: your_api_key + api_secret: your_api_secret + username: your_username + password: your_password + +# Support for calendars - in this case Google and Facebook calendars +# Installing the dependencies: pip install 'platypush[ical,google]' +calendar: + calendars: + - + type: platypush.plugins.google.calendar.GoogleCalendarPlugin + - + type: platypush.plugins.calendar.ical.CalendarIcalPlugin + url: https://www.facebook.com/events/ical/upcoming/?uid=your_user_id&key=your_key + +## -- +## Backends configuration examples +## -- +# +# Backends are basically threads that run in the background and listen for something +# to happen and either trigger events or provide additional services on top of platypush. +# Just like plugins, backends are classes whose configuration matches one-to-one the +# supported parameters on the __init__ methods. You can check the documentation for the +# available backends here: https://platypush.readthedocs.io/en/latest/backends.html. +# Moreover, most of the backends will generate events that you can react to through custom +# event hooks. Check here for the events documentation: +# https://platypush.readthedocs.io/en/latest/events.html +# +# You may usually want to enable the HTTP backend, as it provides many useful features on +# top of platypush. Among those: +# +# - Expose the /execute endpoint, that allows you to send requests to platypush through a +# JSON-RPC interface. +# - Web panel, one of the key additiona features of platypush. Many plugins will expose web +# panel tabs for e.g. accessing and controlling lights, music, media and sensors. +# - Dashboard: platypush can be configured to show a custom dashboard on your screens with +# e.g. music platypush and weather info, news, upcoming calendar events and photo carousel. +# - Streaming support - the HTTP backend makes it possible to stream local media to other +# devices - e.g. Chromecasts and external browsers. +# +# To install the HTTP backend dependencies simply run 'pip install "platypush[http]"' +backend.http: + # Listening port + port: 8008 + + # Through resource_dirs you can specify external folders whose content can be accessed on + # the web server through a custom URL. In the case below we have a Dropbox folder containing + # our pictures and we mount it to the '/carousel' endpoint. + resource_dirs: + carousel: ~/Dropbox/Photos/carousel + + # Dashboard configuration. The dashboard is a collection of widgets and it's organized in + # multiple rows. Each rows can be split in 12 columns. Therefore 'columns: 12' will make + # a widget span over the whole row, while 'columns: 6' will make a widget take half the + # horizontal space of a column. + dashboard: + widgets: + - + widget: calendar + columns: 6 + - + widget: music + columns: 3 + - + widget: date-time-weather + columns: 3 + - + widget: image-carousel + columns: 6 + images_path: ~/Dropbox/Photos/carousel + refresh_seconds: 15 + - + widget: rss-news + # Requires backend.http.poll to be enabled with some + # RSS sources and write them to sqlite db + columns: 6 + limit: 25 + db: "sqlite:////home/user/.local/share/platypush/feeds/rss.db" + +# The HTTP poll backend is a versatile backend that can monitor for HTTP-based resources and +# trigger events whenever new entries are available. In the example below we show how to use +# the backend to listen for changes on a set of RSS feeds. New content will be stored by default +# on a SQLite database under ~/.local/share/platypush/feeds/rss.db. +# Install the required dependencies through 'pip install "platypush[rss,db]"' +backend.http.poll: + requests: + - + # HTTP poll type (RSS) + type: platypush.backend.http.request.rss.RssUpdates + # Remote URL + url: http://www.theguardian.com/rss/world + # Custom title + title: The Guardian - World News + # How often we should check for changes + poll_seconds: 600 + # Maximum number of new entries to be processed + max_entries: 10 + - + type: platypush.backend.http.request.rss.RssUpdates + url: http://www.physorg.com/rss-feed + title: Phys.org + poll_seconds: 600 + max_entries: 10 + - + type: platypush.backend.http.request.rss.RssUpdates + url: http://feeds.feedburner.com/Techcrunch + title: Tech Crunch + poll_seconds: 600 + 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: 300 + max_entries: 10 + +# MQTT backend. Installed required dependencies through 'pip install "platypush[mqtt]"' +backend.mqtt: + # Remote MQTT server IP or hostname + host: mqtt-server + # By default the backend will listen for messages on the platypush_bus_mq/device_id + # topic, but you can change the prefix using the topic attribute + topic: my_platypush_bus + +# Raw TCP socket backend. It can run commands sent as JSON over telnet or netcat +backend.tcp: + port: 3333 + +# Websocket backend. Install required dependencies through 'pip install "platypush[http]"' +backend.websocket: + port: 8765 + +## -- +## Assistant configuration examples +## -- +# +# Both Google Assistant and Alexa voice assistant interfaces are supported by platypush. +# You can easily make your custom voice assistant with a RaspberryPi and a USB microphone, +# or on your laptop. Note however that the Alexa integration is still experimental +# (mostly because of glitches and bugs on the avs package provided by Amazon), while the +# Google Assistant support should be more robust. The recommended way of triggering a +# hotword ('OK Google', 'Alexa' or any custom hotword you like) is through the snowboy +# backend (install it through 'pip install "platypush[hotword]"'). You can download custom +# voice model files (.umdl) from https://snowboy.kitt.ai. +backend.assistant.snowboy: + # Microphone audio gain + audio_gain: 1.1 + + models: + # "Computer" hotword model + computer: + # UMDL file path + voice_model_file: ~/.local/share/snowboy/models/computer.umdl + # Plugin to use (Google Assistant) + assistant_plugin: assistant.google.pushtotalk + # Language assistant (Italian) + assistant_language: it-IT + # Sound to play when the hotword is detected + detect_sound: ~/.local/share/sounds/hotword.wav + # Model sensitivity + sensitivity: 0.4 + # "OK Google" hotword model + ok_google: + voice_model_file: ~/.local/share/snowboy/models/OK Google.pmdl + assistant_plugin: assistant.google.pushtotalk + assistant_language: en-US + detect_sound: ~/.local/share/sounds/sci-fi/PremiumBeat_0013_cursor_selection_16.wav + sensitivity: 0.4 + # "Alexa" voice model + alexa: + voice_model_file: ~/.local/share/snowboy/models/Alexa.pmdl + assistant_plugin: assistant.echo + assistant_language: en-US + detect_sound: ~/.local/share/sounds/sci-fi/PremiumBeat_0013_cursor_selection_16.wav + sensitivity: 0.5 + +# Install Alexa dependencies with 'pip install "platypush[alexa]"' +assistant.echo: + audio_player: mplayer + +# Install Google Assistant dependencies with 'pip install "platypush[google-assistant]"' +assistant.google.pushtotalk: + language: en-US + +## -- +## Procedure examples +## -- +# +# Procedures are lists of actions that can be executed synchronously (default) or in parallel +# (procedure.async. prefix). Basic flow control operators (if/else/for) are also available. +# You can also access Python variables and evaluate Python expressions by using the ${} expressions. +# The 'context' special variable is a name->value dictionary containing the items returned from +# previous actions - for example if an action returned '{"status": "ok", "temperature":21.5}' then +# the following actions can access those variables through ${status} and ${temperature} respectively, +# and you can also add things like '- if ${temperature > 20.0}' or '- for ${temp in temperature_values}'. +# Alternatively, you can access those variable also through ${context.get('status')} or ${context.get('temperature')}. +# Other special variables that you can use in your procedures: +# +# - output: Will contain the parsed output of the previous action +# - errors: Will contain the errors of the previous action +# - event: If the procedure is executed within an event hook, it contains the event that triggered the hook +# +# An example procedure that can be called when you arrive home. You can run this procedure by sending a JSON +# message like this on whichever backend you like (HTTP, websocket, TCP, Redis, MQTT, Node-RED, Pushbullet...) +# {"type":"request", "action":"procedure.at_home"} +# You can for instance install Tasker+AutoLocation on your mobile and send this message whenever you enter +# your home area. +procedure.at_home: + # Set the db variable HOME to 1 + - action: variable.set + args: + HOME: 1 + + # Check the luminosity level from a connected LTR559 sensor + - action: gpio.sensor.ltr559.get_data + + # If it's below a certain threshold turn on the lights + - if ${int(light or 0) < 110}: + - action: light.hue.on + + # Say a welcome home message. Install dependencies through 'pip install "platypush[google-tts]"' + - action: tts.google.say + args: + text: Welcome home + + # Start the music + - action: music.mpd.play + +# Procedure that will be execute when you're outside of home +procedure.outside_home: + # Unset the db variable HOME + - action: variable.unset + args: + name: HOME + + # Stop the music + - action: music.mpd.stop + + # Turn off the lights + - action: light.hue.off + + # Start the camera streaming. Install the Pi Camera dependencies through + # 'pip install "platypush[picamera]"' + - action: camera.pi.start_streaming + args: + listen_port: 2222 + +# Procedures can also take optional arguments. The example below show a +# generic procedure to send a request to another platypush host over MQTT +# given target, action and args +procedure.send_request(target, action, args): + - action: mqtt.send_message + args: + topic: my_platypush_bus/${target} + host: mqtt-server + port: 1883 + msg: + type: request + target: ${target} + action: ${action} + args: "${context.get('args', {}}" + +## -- +## Event hook examples +## -- +# +# Event hooks are procedures that are run when a certain condition is met. +# Check the documentation of the backends to see which events they can trigger. +# An event hook consists of two parts: an 'if' field that specifies on which +# event the hook will be triggered (type and attributes content), and a 'then' +# field that uses the same syntax as procedures to specify a list of actions to +# execute when the event is matched. +# +# The example below plays the music on mpd/mopidy when your voice assistant +# triggers a speech recognized event with "play the music" content. +event.hook.PlayMusicAssistantCommand: + if: + type: platypush.message.event.assistant.SpeechRecognizedEvent + # Note that basic regexes are supported, so the hook will be triggered + # both if you say "play the music" and "play music" + phrase: "play (the)? music" + then: + - action: music.mpd.play + +# This will turn on the lights when you say "turn on the lights" +event.hook.TurnOnLightsCommand: + if: + type: platypush.message.event.assistant.SpeechRecognizedEvent + phrase: "turn on (the)? lights?" + then: + - action: light.hue.on + +# This will play a song by a specified artist +event.hook.SearchSongVoiceCommand: + if: + type: platypush.message.event.assistant.SpeechRecognizedEvent + # Note that you can use the ${} operator in event matching to + # extract part of the matched string into context variables that + # can be accessed in your event hook. + phrase: "play ${title} by ${artist}" + then: + - action: music.mpd.clear + - action: music.mpd.search + args: + filter: + - artist + - ${artist} + - any + - ${title} + + # Play the first search result + - action: music.mpd.play + args: + resource: ${output[0]['file']} + +# This event will scrobble newly listened tracks on mpd/mopidy to last.fm +event.hook.ScrobbleNewTrack: + if: + type: platypush.message.event.music.NewPlayingTrackEvent + then: + - action: lastfm.scrobble + args: + artist: ${track['artist']} + title: ${track['title']} + + - action: lastfm.update_now_playing + args: + artist: ${track['artist']} + title: ${track['title']} + +## -- +## Cron examples +## -- +# +# Cronjobs allow you to execute procedures at periodic intervals. +# Standard UNIX cron syntax is supported, plus an optional 6th indicator +# at the end of the expression to run jobs with second granularity. +# The example below executes a script at intervals of 1 minute. +cron.TestCron: + cron_expression: '* * * * *' + actions: + - action: shell.exec + args: + cmd: ~/bin/myscript.sh +