Add a simple example.

Change-Id: Iaadf10ab339c31da7351b792fb3b3e642c6f4bd5

diff --git a/README.rst b/README.rst
index cf5599d107c880ead78fb100b7d2e4c79e759848..2787e6f93897e0781550a3dea0559d9fa50cf981 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -1,9 +1,11 @@
 Eclipse Paho MQTT Python Client
 ===============================
 
-This repository contains the source code for the `Eclipse Paho <http://eclipse.org/paho/>`_ MQTT Python client library, which implements versions 3.1 and 3.1.1 of the MQTT protocol.
+This document describes the source code for the `Eclipse Paho <http://eclipse.org/paho/>`_ MQTT Python client library, which implements versions 3.1 and 3.1.1 of the MQTT protocol.
 
-This code builds libraries which enable applications to connect to an `MQTT <http://mqtt.org/>`_ broker to publish messages, and to subscribe to topics and receive published messages.
+This code provides a client class which enable applications to connect to an `MQTT <http://mqtt.org/>`_ broker to publish messages, and to subscribe to topics and receive published messages. It also provides some helper functions to make publishing one off messages to an MQTT server very straightforward.
+
+It supports Python 2.7 or 3.x, with limited support for Python 2.6.
 
 The MQTT protocol is a machine-to-machine (M2M)/"Internet of Things" connectivity protocol. Designed as an extremely lightweight publish/subscribe messaging transport, it is useful for connections with remote locations where a small code footprint is required and/or network bandwidth is at a premium.
 
@@ -13,6 +15,7 @@ Paho is an `Eclipse Foundation <https://www.eclipse.org/org/foundation/>`_ proje
 Contents
 --------
 
+* Source_
 * Installation_
 * `Usage and API`_
     * `Client`_
@@ -55,6 +58,14 @@ To obtain the full code, including examples and tests, you can clone the git rep
 
     git clone git://git.eclipse.org/gitroot/paho/org.eclipse.paho.mqtt.python.git
 
+
+Once you have the code, it can be installed from your repository as well:
+
+::
+
+    cd org.eclipse.paho.mqtt.python
+    python setup.py install
+
 Usage and API
 -------------
 
@@ -62,6 +73,39 @@ Detailed API documentation is available through **pydoc**. Samples are available
 
 The package provides two modules, a full client and a helper for simple publishing.
 
+Getting Started
+***************
+
+Here is a very simple example that subscribes to the broker $SYS topic tree and prints out the resulting messages:
+
+::
+
+    import paho.mqtt.client as mqtt
+    
+    # The callback for when the client receives a CONNACK response from the server.
+    def on_connect(client, userdata, rc):
+        print("Connected with result code "+str(rc))
+
+        # Subscribing in on_connect() means that if we lose the connection and
+        # reconnect then subscriptions will be renewed.
+        client.subscribe("$SYS/#")
+
+    # The callback for when a PUBLISH message is received from the server.
+    def on_message(client, userdata, msg):
+        print(msg.topic+" "+str(msg.payload))
+
+    client = mqtt.Client()
+    client.on_connect = on_connect
+    client.on_message = on_message
+
+    client.connect("iot.eclipse.org", 1883, 60)
+
+    # Blocking call that processes network traffic, dispatches callbacks and
+    # handles reconnecting.
+    # Other loop*() functions are available that give a threaded interface and a
+    # manual interface.
+    client.loop_forever()
+
 Client
 ******