Update docs and change use_websockets -> transport.

Change-Id: I13f00efebe431738701678d96a6e70d481a56c80

ChangeLog.txt

@@ -16,6 +16,7 @@ v1.2 - 2016-xx-xx
   #42.
 - Modify callbacks definition/structure to allow classical inheritence. Closes
   #53, #54.
+- Add websockets support.
 
 
 v1.1 - 2015-01-30

README.rst

@@ -130,7 +130,7 @@ Client()
 
 ::
 
-    Client(client_id="", clean_session=True, userdata=None, protocol=MQTTv311)
+    Client(client_id="", clean_session=True, userdata=None, protocol=MQTTv311, transport="tcp")
 
 The ``Client()`` constructor takes the following arguments:
 
@@ -157,7 +157,12 @@ userdata
 protocol
     the version of the MQTT protocol to use for this client. Can be either
     ``MQTTv31`` or ``MQTTv311``
-    
+
+transport
+    set to "websockets" to send MQTT over WebSockets. Leave at the default of
+    "tcp" to use raw TCP.
+
+
 Example
 .......
 
@@ -953,7 +958,7 @@ Publish a single message to a broker, then disconnect cleanly.
 
     single(topic, payload=None, qos=0, retain=False, hostname="localhost",
         port=1883, client_id="", keepalive=60, will=None, auth=None, tls=None,
-        protocol=mqtt.MQTTv311)
+        protocol=mqtt.MQTTv311, transport="tcp")
            
 
 Function arguments
@@ -1017,7 +1022,10 @@ tls
 
 protocol
     choose the version of the MQTT protocol to use. Use either ``MQTTv31`` or ``MQTTv311``.
-    
+
+transport
+    set to "websockets" to send MQTT over WebSockets. Leave at the default of
+    "tcp" to use raw TCP.
 Example
 '''''''
 
@@ -1035,7 +1043,7 @@ Publish multiple messages to a broker, then disconnect cleanly.
 ::
 
     multiple(msgs, hostname="localhost", port=1883, client_id="", keepalive=60,
-        will=None, auth=None, tls=None, protocol=mqtt.MQTTv311)
+        will=None, auth=None, tls=None, protocol=mqtt.MQTTv311, transport="tcp")
 
 Function arguments
 ''''''''''''''''''
@@ -1055,7 +1063,7 @@ msgs
     
     ("<topic>", "<payload>", qos, retain)
 
-See ``single()`` for the description of ``hostname``, ``port``, ``client_id``, ``keepalive``, ``will``, ``auth``, ``tls``, ``protocol``.
+See ``single()`` for the description of ``hostname``, ``port``, ``client_id``, ``keepalive``, ``will``, ``auth``, ``tls``, ``protocol``, ``transport``.
 
 Example
 '''''''

examples/sub-ws.py

+#!/usr/bin/python3
+
+# Copyright (c) 2010-2013 Roger Light <roger@atchoo.org>
+#
+# All rights reserved. This program and the accompanying materials
+# are made available under the terms of the Eclipse Distribution License v1.0
+# which accompanies this distribution. 
+#
+# The Eclipse Distribution License is available at 
+#   http://www.eclipse.org/org/documents/edl-v10.php.
+#
+# Contributors:
+#    Roger Light - initial implementation
+# Copyright (c) 2010,2011 Roger Light <roger@atchoo.org>
+# All rights reserved.
+
+# This shows a simple example of an MQTT subscriber.
+
+import sys
+
+try:
+    import paho.mqtt.client as mqtt
+except ImportError:
+    # This part is only required to run the example from within the examples
+    # directory when the module itself is not installed.
+    #
+    # If you have the module installed, just use "import paho.mqtt.client"
+    import os
+    import inspect
+    cmd_subfolder = os.path.realpath(os.path.abspath(os.path.join(os.path.split(inspect.getfile( inspect.currentframe() ))[0],"../src")))
+    if cmd_subfolder not in sys.path:
+        sys.path.insert(0, cmd_subfolder)
+    import paho.mqtt.client as mqtt
+
+def on_connect(mqttc, obj, flags, rc):
+    print("rc: "+str(rc))
+
+def on_message(mqttc, obj, msg):
+    print(msg.topic+" "+str(msg.qos)+" "+str(msg.payload))
+
+def on_publish(mqttc, obj, mid):
+    print("mid: "+str(mid))
+
+def on_subscribe(mqttc, obj, mid, granted_qos):
+    print("Subscribed: "+str(mid)+" "+str(granted_qos))
+
+def on_log(mqttc, obj, level, string):
+    print(string)
+
+# If you want to use a specific client id, use
+# mqttc = mqtt.Client("client-id")
+# but note that the client id must be unique on the broker. Leaving the client
+# id parameter empty will generate a random id for you.
+mqttc = mqtt.Client(transport="websockets")
+mqttc.on_message = on_message
+mqttc.on_connect = on_connect
+mqttc.on_publish = on_publish
+mqttc.on_subscribe = on_subscribe
+# Uncomment to enable debug messages
+mqttc.on_log = on_log
+mqttc.connect("test.mosquitto.org", 8080, 60)
+mqttc.subscribe("$SYS/broker/version", 0)
+
+
+mqttc.loop_forever()
+

src/paho/mqtt/client.py

@@ -451,7 +451,7 @@ class Client(object):
       MQTT_LOG_ERR, and MQTT_LOG_DEBUG. The message itself is in buf.
 
     """
-    def __init__(self, client_id="", clean_session=True, userdata=None, protocol=MQTTv31, use_websocket=False):
+    def __init__(self, client_id="", clean_session=True, userdata=None, protocol=MQTTv31, transport="tcp"):
         """client_id is the unique client id string used when connecting to the
         broker. If client_id is zero length or None, then one will be randomly
         generated. In this case, clean_session must be True. If this is not the
@@ -477,13 +477,13 @@ class Client(object):
         version, the client will automatically attempt to reconnect using v3.1
         instead.
 
-        use_websocket determines the protocol type, if True, the client will connect
-        to the broker using a websocket connection.
+        Set transport to "websockets" to use WebSockets as the transport
+        mechanism. Set to "tcp" to use raw TCP, which is the default.
         """
         if not clean_session and (client_id == "" or client_id is None):
             raise ValueError('A client id must be provided if clean session is False.')
 
-        self._use_websocket = use_websocket
+        self._transport = transport
         self._protocol = protocol
         self._userdata = userdata
         self._sock = None
@@ -822,7 +822,7 @@ class Client(object):
                 else:
                     ssl.match_hostname(self._ssl.getpeercert(), self._host)
 
-        if self._use_websocket:
+        if self._transport == "websockets":
             if self._tls_ca_certs is not None:
                 self._ssl = WebsocketWrapper(self._ssl, self._host, self._port, True)
             else:
@@ -2672,7 +2672,8 @@ class WebsocketWrapper:
                  b"Host: " + str(self._host).encode('utf-8') + b":" + str(self._port).encode('utf-8') + b"\r\n" +\
                  b"Origin: http://" + str(self._host).encode('utf-8') + b":" + str(self._port).encode('utf-8') + b"\r\n" +\
                  b"Sec-WebSocket-Key: " + sec_websocket_key + b"\r\n" +\
-                 b"Sec-WebSocket-Version: 13\r\n\r\n"
+                 b"Sec-WebSocket-Version: 13\r\n" +\
+                 b"Sec-WebSocket-Protocol: mqtt\r\n\r\n"
 
         if self._ssl:
             self._socket.write(header)

src/paho/mqtt/publish.py

@@ -62,7 +62,7 @@ def _on_publish(c, userdata, mid):
 
 
 def multiple(msgs, hostname="localhost", port=1883, client_id="", keepalive=60,
-             will=None, auth=None, tls=None, protocol=mqtt.MQTTv31):
+             will=None, auth=None, tls=None, protocol=mqtt.MQTTv31, transport="tcp"):
     """Publish multiple messages to a broker, then disconnect cleanly.
 
     This function creates an MQTT client, connects to a broker and publishes a
@@ -110,13 +110,15 @@ def multiple(msgs, hostname="localhost", port=1883, client_id="", keepalive=60,
           default to None if not provided, which results in the client using
           the default behaviour - see the paho.mqtt.client documentation.
           Defaults to None, which indicates that TLS should not be used.
+    transport : set to "tcp" to use the default setting of transport which is
+          raw TCP. Set to "websockets" to use WebSockets as the transport.
     """
 
     if type(msgs) is not list:
         raise ValueError('msgs must be a list')
 
     client = mqtt.Client(client_id=client_id,
-                         userdata=msgs, protocol=protocol)
+                         userdata=msgs, protocol=protocol, transport=transport)
     client.on_publish = _on_publish
     client.on_connect = _on_connect
 
@@ -172,7 +174,7 @@ def multiple(msgs, hostname="localhost", port=1883, client_id="", keepalive=60,
 
 def single(topic, payload=None, qos=0, retain=False, hostname="localhost",
            port=1883, client_id="", keepalive=60, will=None, auth=None,
-           tls=None, protocol=mqtt.MQTTv31):
+           tls=None, protocol=mqtt.MQTTv31, transport="tcp"):
     """Publish a single message to a broker, then disconnect cleanly.
 
     This function creates an MQTT client, connects to a broker and publishes a
@@ -210,8 +212,10 @@ def single(topic, payload=None, qos=0, retain=False, hostname="localhost",
           default to None if not provided, which results in the client using
           the default behaviour - see the paho.mqtt.client documentation.
           Defaults to None, which indicates that TLS should not be used.
+    transport : set to "tcp" to use the default setting of transport which is
+          raw TCP. Set to "websockets" to use WebSockets as the transport.
     """
 
     msg = {'topic':topic, 'payload':payload, 'qos':qos, 'retain':retain}
-    multiple([msg], hostname, port, client_id, keepalive, will, auth, tls, protocol)
+    multiple([msg], hostname, port, client_id, keepalive, will, auth, tls, protocol, transport)
 

src/paho/mqtt/subscribe.py

@@ -61,7 +61,7 @@ def _on_message_simple(c, userdata, message):
 
 def callback(callback, topics, qos=0, userdata=None, hostname="localhost",
         port=1883, client_id="", keepalive=60, will=None, auth=None, tls=None,
-        protocol=mqtt.MQTTv31):
+        protocol=mqtt.MQTTv31, transport="tcp"):
     """Subscribe to a list of topics and process them in a callback function.
 
     This function creates an MQTT client, connects to a broker and subscribes
@@ -109,6 +109,8 @@ def callback(callback, topics, qos=0, userdata=None, hostname="localhost",
           default to None if not provided, which results in the client using
           the default behaviour - see the paho.mqtt.client documentation.
           Defaults to None, which indicates that TLS should not be used.
+    transport : set to "tcp" to use the default setting of transport which is
+          raw TCP. Set to "websockets" to use WebSockets as the transport.
     """
 
     if qos < 0 or qos > 2:
@@ -121,7 +123,7 @@ def callback(callback, topics, qos=0, userdata=None, hostname="localhost",
             'userdata':userdata}
 
     client = mqtt.Client(client_id=client_id,
-                         userdata=callback_userdata, protocol=protocol)
+                         userdata=callback_userdata, protocol=protocol, transport=transport)
     client.on_message = _on_message_callback
     client.on_connect = _on_connect
 
@@ -177,7 +179,7 @@ def callback(callback, topics, qos=0, userdata=None, hostname="localhost",
 
 def simple(topics, qos=0, msg_count=1, retained=True, hostname="localhost", port=1883,
         client_id="", keepalive=60, will=None, auth=None, tls=None,
-        protocol=mqtt.MQTTv31):
+        protocol=mqtt.MQTTv31, transport="tcp"):
     """Subscribe to a list of topics and return msg_count messages.
 
     This function creates an MQTT client, connects to a broker and subscribes
@@ -230,6 +232,8 @@ def simple(topics, qos=0, msg_count=1, retained=True, hostname="localhost", port
           default to None if not provided, which results in the client using
           the default behaviour - see the paho.mqtt.client documentation.
           Defaults to None, which indicates that TLS should not be used.
+    transport : set to "tcp" to use the default setting of transport which is
+          raw TCP. Set to "websockets" to use WebSockets as the transport.
     """
 
     if msg_count < 1:
@@ -245,7 +249,7 @@ def simple(topics, qos=0, msg_count=1, retained=True, hostname="localhost", port
     userdata = {'retained':retained, 'msg_count':msg_count, 'messages':messages}
 
     callback(_on_message_simple, topics, qos, userdata, hostname, port,
-            client_id, keepalive, will, auth, tls, protocol)
+            client_id, keepalive, will, auth, tls, protocol, transport)
 
     return userdata['messages']