[mousetrap/gnome3-wip: 137/240] Update README.

[Heidi Ellis <heidiellis src gnome org>]

commit 33ab2f816e4e332bee2c05d9560956081077809f
Author: Stoney Jackson <dr stoney gmail com>
Date:   Mon Jun 23 20:30:10 2014 -0400

    Update README.

 README |   93 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 files changed, 83 insertions(+), 10 deletions(-)
---
diff --git a/README b/README
index c3cb01b..e2a9062 100644
--- a/README
+++ b/README
@@ -2,25 +2,98 @@
 
 License: GPL v2.0 (see COPYING)
 
+
 ## Required
 
-TODO: List required software
+* Python
+* PyYAML
+* OpenCV
+
 
 ## Download
 
-    git clone https://git.gnome.org/browse/mousetrap
-    cd mousetrap
+    $ git clone https://git.gnome.org/browse/mousetrap
 
-## Build
 
-    ./autoconf.sh
-    make
+## Run
 
-## Install
+    $ cd mousetrap
+    $ source bin/mt-setup
+    $ mt-run
 
-    sudo make install
 
-## Run
+## Use
+
+By default, MouseTrap tracks your face, allowing you to controll the
+mouse pointer using a joystick metaphore. When you look left,
+the pointer moves left; look right, it moves right; look up, it moves up;
+look down, it moves down; look straight ahead, it stops moving. To click,
+close your left eye for about 1.5 seconds.
+
+
+## Configure
+
+    $ cp $MOUSETRAP/src/mousetrap/config_default.yaml ~/.mousetrap.yaml
+    $ vim ~/.mousetrap.yaml
+
+
+## Writing a Plugin
+
+### 1. Implement plugin class.
+
+```
+# Import the interface for plugins.
+import mousetrap.plugins.interface as interface
+
+
+# Create a logger for logging.
+import logging
+LOGGER = logging.getLogger(__name__)
+
+
+# Define a class that inherits from mousetrap.plugins.interface.Plugin
+class MyPlugin(interface.Plugin):
+
+    # Define a constructor that takes an instance of mousetrap.config.Config
+    # as the first parameter (after self).
+    def __init__(self, config):
+        self._config = config
+
+        # Access class configuration by using self as a key.
+        # Here we retreive 'x' from our class configuration.
+        self._x = config[self]['x']
+
+    # Define a run method that takes an instance of mousetrap.main.App as the
+    # first parameter (after self). Run is called on each pass of the main
+    # loop.
+    def run(self, app):
+
+        # App contians data shared between the system and plugins.
+        # See mousetrap.main.App for attributes that are defined by mousetrap.
+        # For example, we can access the pointer:
+        app.pointer.set_position((0, 0))
+
+        # We can access attrbitues that are populated by other plugins.
+        image = app.image
+
+        # We can make attributes available to other plugins by adding them
+        # to app.
+        app.greeting = 'Just saying %s!' % (self._x)
+```
+
+### 2. Edit configuration file to tell MouseTrap about your plugin.
+
+```
+#!~/.mousetrap.yaml
+
+assembly:
+- mousetrap.plugins.camera.CameraPlugin     # sets app.image
+- mousetrap.plugins.display.DisplayPlugin   # displays app.image in a window
+- python.path.to.MyPlugin                   # runs after CameraPlugin
 
-    mousetrap
+classes:
+  python.path.to.MyPlugin:
+    x: hi
+```
 
+For more examples, see the plugins in `mousetrap.plugin`.