From 97b6fab3764960b3353c3b91038f33136fc90567 Mon Sep 17 00:00:00 2001
From: Fabio Manganiello <blacklight86@gmail.com>
Date: Mon, 18 Dec 2017 01:53:29 +0100
Subject: [PATCH] Updated README

---
 README.md                    | 52 +++++++++++++++++++++++++++++++-----
 platypush/pusher/__init__.py |  1 +
 2 files changed, 47 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index a4b7b3599..f435fa806 100644
--- a/README.md
+++ b/README.md
@@ -105,7 +105,7 @@ Writing your own `platypush` plugin, that would execute your own custom logic wh
 
 4. If your module is `light/batsignal`, then its main class should be named `LightBatsignalPlugin`.
 
-5. The configuration for your module will be read from a section named `light.batsignal` from your `config.yaml`, the attributes are accessible in your class in `self.config`.
+5. The configuration for your module will be read from a section named `light.batsignal` from your `config.yaml`. Its values will passed over the plugin constructor arguments.
 
 The `__init__.py` will look like this:
 
@@ -117,23 +117,24 @@ from platypush.message.response import Response
 from .. import LightPlugin
 
 class LightBatsignalPlugin(LightPlugin):
-    def _init(self):
-        self.batsignal = batman.Batsignal(self.config['intensity'])
+    def __init__(self, intensity=100):
+        super().__init__()
+        self.batsignal = batman.Batsignal(intensity)
 
     def on(self, urgent=False):
         if urgent:
             self.batsignal.notify_robin()
 
         self.batsignal.on()
-        return Response('ok')
+        return Response(output='ok')
 
     def off(self):
         self.batsignal.off()
-        return Response('ok')
+        return Response(output='ok')
 
     def toggle(self):
         self.batsignal.toggle()
-        return Response('ok')
+        return Response(output='ok')
 
 ```
 
@@ -145,3 +146,42 @@ class LightBatsignalPlugin(LightPlugin):
 pusher --target your_pc --action light.batsignal.on --urgent 1
 ```
 
+Writing your backends
+---------------------
+
+You can also write your own backends, where a backend is nothing but a thread that listens for messages on a certain channel and pokes the main app whenever it receives one.
+
+1. Create your backend directory under `platypush/backend` (e.g. `voicemail`)
+
+2. In the case above, `platypush.backend.voicemail` will be your package name.
+
+3. Create an `__init__.py` under `platypush/backend/voicemail`.
+
+4. If your module is `voicemail`, then its main class should be named `VoicemailBackend`.
+
+5. The configuration for your module will be read from a section named `backend.voicemail` from your `config.yaml`. Its values will be passed over the backend constructor arguments.
+
+6. Implement the `run` method. Since a backend is a thread that polls for new messages on a channel, this will be the thread main method. `_send_msg` should call `self.on_msg` at the end to post a new message to the application.
+
+7. Implement the `_send_msg` method. This method will be called whenever the application needs to send a new message through `send_request` and `send_response`. You should never call `_send_msg` directly.
+
+The `__init__.py` will look like this:
+
+```python
+from .. import Backend
+
+class VoicemailBackend(Backend)
+    def __init__(self, phone)
+        super().__init__()
+        self.phone = phone
+        self.voicemail = Voicemail(...)
+
+    def _send_msg(self, msg):
+        self.voicemail.save_msg(msg)
+
+    def run(self):
+        while True:
+            msg = self.voicemail.poll()
+            self.on_msg(msg)
+```
+
diff --git a/platypush/pusher/__init__.py b/platypush/pusher/__init__.py
index 9e4f7ffce..767b86fd1 100755
--- a/platypush/pusher/__init__.py
+++ b/platypush/pusher/__init__.py
@@ -9,6 +9,7 @@ from platypush.message.request import Request
 def print_usage():
     print ('''Usage: {} [-h|--help] <-t|--target <target name>> <-a|--action <action name>> payload
     -h, --help:\t\tShow this help and exit
+    -c, --config:\tPath to the platypush config.yaml (default: ~/.config/platypush/config.yaml or /etc/platypush/config.yaml)
     -b, --backend:\tBackend to deliver the message [pushbullet|kafka] (default: whatever specified in your config with pusher=True)
     -t, --target:\tName of the target device/host
     -a, --action\tAction to run, it includes both the package name and the method (e.g. shell.exec or music.mpd.play)