From 2a4dad1c948bc35454fde6792f9cc3a14e3fb8fa Mon Sep 17 00:00:00 2001 From: Roger Light Date: Fri, 25 Apr 2014 11:49:57 +0100 Subject: [PATCH] Add a simple example. Change-Id: Iaadf10ab339c31da7351b792fb3b3e642c6f4bd5 --- README.rst | 48 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 46 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index cf5599d..2787e6f 100644 --- 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 `_ 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 `_ 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 `_ 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 `_ 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 `_ 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 ****** -- 2.39.5