Included quick start
Fabio Manganiello
parent
1f91df553c
commit
5dc6411264
171
Configuration.md
171
Configuration.md
|
|
@ -1,3 +1,4 @@
|
|||
* [Quick start](#quick-start)
|
||||
* [Backends](#backends)
|
||||
* [HTTP service configuration](#http-service-configuration)
|
||||
* [PushBullet](#pushbullet-configuration)
|
||||
|
|
@ -19,63 +20,175 @@
|
|||
* [Mobile notification mirroring](#mobile-notification-mirroring)
|
||||
* [Include directive](#include-directive)
|
||||
|
||||
Copy `/etc/platypush/config.example.yaml` to `/etc/platypush/config.yaml` (system-wise settings) or `~/.config/platypush/config.yaml` (user-wise settings).
|
||||
## Quick start
|
||||
|
||||
Some configuration snippets:
|
||||
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).
|
||||
|
||||
## device_id
|
||||
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.
|
||||
|
||||
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.
|
||||
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)
|
||||
|
||||
3. Add the Hue configuration to your file:
|
||||
|
||||
```yaml
|
||||
device_id: some_custom_name
|
||||
light.hue:
|
||||
bridge: 192.168.1.100 # IP address or host name of your bridge
|
||||
groups:
|
||||
- Living Room # Default groups to control if not specified in the request
|
||||
```
|
||||
|
||||
# Backends
|
||||
|
||||
Platypush comes by default with an HTTP service as a backend, 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`.
|
||||
|
||||
## HTTP service configuration
|
||||
|
||||
You can configure Platypush to receive requests and send responses leveraging the internal HTTP service based on [Flask](http://flask.pocoo.org/).
|
||||
|
||||
Sample configuration:
|
||||
4. Also, enable the web server backend, we'll use it to test our plugin through `curl`:
|
||||
|
||||
```yaml
|
||||
backend.http:
|
||||
port: 8008
|
||||
token: YOUR_TOKEN # Any randomly generated token or passphrase used to authenticate your requests
|
||||
```
|
||||
|
||||
Start your Platypush server:
|
||||
Note that `flask` is a required dependency to run the web server (``pip install flask``). `websockets` (``pip install websockets``) and ``redis`` (``pip install redis``) are optional dependency but I'd recommend to install them as well. Redis in particular is used by many components to communicate with each other, especially when they don't run in the same process, while websockets allows you to get live events on the web client.
|
||||
|
||||
5. Now start Platypush:
|
||||
|
||||
```yaml
|
||||
$ platypush
|
||||
```
|
||||
|
||||
Note: if you have authentication issues with the Hue bridge, press the physical connect button on the bridge and restart the application.
|
||||
|
||||
6. Try to send commands to your lights:
|
||||
|
||||
```shell
|
||||
python -m platypush
|
||||
curl -XPOST -H 'Content-Type: application/json' \
|
||||
-d '{"type":"request", "target":"your_device_id", "action":"light.hue.on"}' \
|
||||
http://localhost:8008/execute
|
||||
```
|
||||
|
||||
Send requests:
|
||||
Replace `your_device_id` with your hostname (it's the default Platypush device ID) - just type `hostname` in your command line to get it. You can also override the device ID via configuration:
|
||||
|
||||
```shell
|
||||
curl -XPOST \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-Token: YOUR_TOKEN" \
|
||||
-d '{"type":"request","target":"your_hostname","action":"shell.exec", "args": {"cmd":"echo ping"}}' \
|
||||
http://localhost:8008/execute
|
||||
```yaml
|
||||
device_id: my_new_device_id
|
||||
```
|
||||
|
||||
Your lights should have turned on - congratulations!
|
||||
|
||||
Note that each request has:
|
||||
|
||||
- The `type=request` field set
|
||||
- The target device_id
|
||||
- The action name. It will be the plugin package name followed by the name of the method in its main class, in this case `light.hue.on`
|
||||
- An optional key-valued list of method arguments named `args`
|
||||
|
||||
A Platypush response will always have a structure like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": null,
|
||||
"id": "response_id",
|
||||
"type": "response",
|
||||
"target": null,
|
||||
"origin": null,
|
||||
"target": "target",
|
||||
"origin": "origin",
|
||||
"response": {
|
||||
"output": "ping\n",
|
||||
"errors": []
|
||||
"output": "The response output",
|
||||
"errors": ["The response errors"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
7. You can optionally set up via configuration a token to authenticate your calls to the server:
|
||||
|
||||
```yaml
|
||||
token: your_authentication_token
|
||||
```
|
||||
|
||||
If configured, the calls to the service will require this bearer token to be provided either:
|
||||
|
||||
- As a query string parameter (`?token=your_authentication_token`)
|
||||
- As an HTTP header (`X-Token: your_authentication_token`)
|
||||
- At the root of your JSON request (attribute name: `token`)
|
||||
|
||||
The web interface will also require basic HTTP authentication through this token.
|
||||
|
||||
8. You can also point your browser to _http://localhost:8008/_, and you should now see the web interface where you can control your lights - change colors, state, and animate them. You'll only see one tab for now as you've only configured one plugin, but once you configure more plugins your web interface may look as something [like this](https://i.imgur.com/KLGovbA.png).
|
||||
|
||||
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`:
|
||||
|
||||
```shell
|
||||
curl -XPOST -H 'Content-Type: application/json' \
|
||||
-d '{"type":"request", "target":"your_device_id", "action":"light.hue.on", "args": {"groups":["Bedroom"]}}' \
|
||||
http://localhost:8008/execute
|
||||
```
|
||||
|
||||
10. Connect the action to your smart assistant now. Follow the steps on the [Google website](https://developers.google.com/assistant/sdk/guides/library/python/) to get the assistant SDK installed and the credential file ready. Then configure your assistant backend:
|
||||
|
||||
```yaml
|
||||
backend.assistant.google:
|
||||
device_model_id: your_model_id # From your Google project configuration
|
||||
credentials_file: /path/to/your/credentials.json
|
||||
```
|
||||
|
||||
11. Connect a microphone, restart the application and try to say "Ok Google" and try some basic interaction with the assistant. If everything went well, you should now be able to use the Google Assistant on your device.
|
||||
|
||||
12. Configure an event hook to run the "lights on" action whenever you say "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
|
||||
```
|
||||
|
||||
Event hooks:
|
||||
|
||||
- Start with the `event.hook.` string followed by a unique name
|
||||
- Have an `if` and `then` clause. In the `if` clause you specify the `type` of the event that will trigger the hook (event inheritance works) and, optionally, the arguments in the event that must match to fire the action. In this case, `platypush.message.event.assistant.SpeechRecognizedEvent` has a `phrase` argument that contains the phrase recognized by the assistant. If the confition matches, then the list of requests in the `then` clause will be triggered (you don't need to specify `type`, as they will always be requests, nor `target`, as it will be the local host).
|
||||
|
||||
If you wanted to pass extra arguments to the action:
|
||||
|
||||
```yaml
|
||||
event.hook.LightsOnAssistantCommand:
|
||||
if:
|
||||
type: platypush.message.event.assistant.SpeechRecognizedEvent
|
||||
phrase: "turn on the lights"
|
||||
then:
|
||||
action: light.hue.on
|
||||
args:
|
||||
groups:
|
||||
- Bedroom
|
||||
- Bathroom
|
||||
```
|
||||
|
||||
You can also run multiple actions in the same hook:
|
||||
|
||||
```yaml
|
||||
event.hook.LightsOnAssistantCommand:
|
||||
if:
|
||||
type: platypush.message.event.assistant.SpeechRecognizedEvent
|
||||
phrase: "turn on the lights"
|
||||
then:
|
||||
-
|
||||
action: light.hue.on
|
||||
-
|
||||
action: shell.exec
|
||||
args:
|
||||
echo "Lights turned on" >> /your/log/file
|
||||
```
|
||||
|
||||
Note how the example above uses another plugin - `shell.exec` to run a shell command. Since this plugin doesn't require any configuration, you don't have to explicitly configure it in order to use it.
|
||||
|
||||
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** (we'll tackle them soon).
|
||||
|
||||
Congratulation, you've set up your first rule! Check out the [plugins documentation](https://platypush.readthedocs.io/en/latest/plugins.html) and the [backends documentation](https://platypush.readthedocs.io/en/latest/backends.html) for the list of supported plugins and backends (_documentation for events coming soon_).
|
||||
|
||||
# Backends
|
||||
|
||||
Backend configurations start with `backend.` in the `config.yaml`.
|
||||
|
||||
## HTTP service configuration
|
||||
|
||||
Already covered in [quick start](#quick-start).
|
||||
|
||||
## PushBullet configuration
|
||||
|
||||
You will need:
|
||||
|
|
|
|||
22
Home.md
22
Home.md
|
|
@ -1,15 +1,6 @@
|
|||
Platypush
|
||||
=========
|
||||
|
||||
[](https://travis-ci.org/BlackLight/platypush)
|
||||
|
||||
|
||||
Execute any command or custom complex logic on your devices, wherever they are, using PushBullet, Apache Kafka, or any backend.
|
||||
|
||||
Platypush aims to be a general-purpose middleware infrastructure to process any request and run any logic triggered by custom events on a generic network of hosts.
|
||||
|
||||
Its development is mainly driven by the necessity of a lightweight infrastructure for running generic triggers and actions in a virtual network, generalizing a bit the idea of an Android app like Tasker or a web service like IFTTT or Microsoft Flow, and turning it into something that anybody can run on their own devices. It's actively being tested on RaspberryPi devices and it has interesting applications when it comes to home automation and IoT, but it should be generic enough to solve most of the automation and information delivery issues in a distributed network.
|
||||
|
||||
* [Architecture](#architecture)
|
||||
* [Installation](#installation)
|
||||
* [Configuration](configuration)
|
||||
|
|
@ -25,9 +16,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).
|
||||
* __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.
|
||||
|
||||
* __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.
|
||||
* __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.
|
||||
|
||||
* __Procedures__: Pre-configured lists of actions that can be triggered by requests or events.
|
||||
|
||||
|
|
@ -49,6 +40,11 @@ cd platypush
|
|||
python setup.py install
|
||||
```
|
||||
|
||||
Check `all_requirements.txt` for any extra dependencies you may want to install depending on your configuration. You can also install all the dependencies (may take some time on slow machines) by running `pip install -r all_requirements.txt`.
|
||||
Check `requirements.txt` for any extra dependencies you may want to install depending on your configuration. You can also install all the dependencies (may take some time on slow machines) by running `pip install -r requirements.txt`.
|
||||
|
||||
After configuring the server, start it by simply running `platypush`, `python -m platypush`, or make your own service.
|
||||
|
||||
**NOTE**: Platypush is only compatible with Python 3 and higher.
|
||||
|
||||
After installing the application, you're ready to [start configuring it](configuration) according to your needs.
|
||||
|
||||
After configuring the server, start it by simply running `platypush`.
|
||||
Loading…
Reference in New Issue