Merge pull request #158 from erics465/master

Documentation for pull request #155

docs/references/hbmqtt_pub.rst

@@ -14,6 +14,7 @@ Usage
              [-q | --qos QOS] [-d] [-k KEEP_ALIVE] [--clean-session]
              [--ca-file CAFILE] [--ca-path CAPATH] [--ca-data CADATA]
              [ --will-topic WILL_TOPIC [--will-message WILL_MESSAGE] [--will-qos WILL_QOS] [--will-retain] ]
+             [--extra-headers HEADER]
 
 Note that for simplicity, ``hbmqtt_pub`` uses mostly the same argument syntax as `mosquitto_pub`_.
 
@@ -44,6 +45,7 @@ Options
 --will-message      Specify a message that will be stored by the broker and sent out if this client disconnects unexpectedly. This must be used in conjunction with ``--will-topic``.
 --will-qos          The QoS to use for the Will. Defaults to 0. This must be used in conjunction with ``--will-topic``.
 --will-retain       If given, if the client disconnects unexpectedly the message sent out will be treated as a retained message. This must be used in conjunction with ``--will-topic``.
+--extra-headers     Specify a JSON object string with key-value pairs representing additional headers that are transmitted on the initial connection, but only when using a websocket connection
 
 
 .. _MQTT URL scheme: https://github.com/mqtt/mqtt.github.io/wiki/URI-Scheme
@@ -93,6 +95,11 @@ Send the contents of a file in two ways:
 
     hbmqtt_pub --url mqtt://localhost -t my/topic -s < ./data
 
+Publish temperature information to localhost with QoS 1 over mqtt encapsulated in a websocket connection and additional headers:
+::
+
+    hbmqtt_pub --url wss://localhost -t sensors/temperature -m 32 -q 1 --extra-headers '{"Authorization": "Bearer <token>"}'
+
 
 .. _mosquitto_pub : http://mosquitto.org/man/mosquitto_pub-1.html
 

docs/references/hbmqtt_sub.rst

@@ -13,6 +13,7 @@ Usage
   hbmqtt_sub --url BROKER_URL -t TOPIC... [-n COUNT] [-c CONFIG_FILE] [-i CLIENT_ID] [-q | --qos QOS] [-d]
              [-k KEEP_ALIVE] [--clean-session] [--ca-file CAFILE] [--ca-path CAPATH] [--ca-data CADATA]
              [ --will-topic WILL_TOPIC [--will-message WILL_MESSAGE] [--will-qos WILL_QOS] [--will-retain] ]
+             [--extra-headers HEADER]
 
 Note that for simplicity, ``hbmqtt_sub`` uses mostly the same argument syntax as `mosquitto_sub`_.
 
@@ -37,6 +38,7 @@ Options
 --will-message      Specify a message that will be stored by the broker and sent out if this client disconnects unexpectedly. This must be used in conjunction with ``--will-topic``.
 --will-qos          The QoS to use for the Will. Defaults to 0. This must be used in conjunction with ``--will-topic``.
 --will-retain       If given, if the client disconnects unexpectedly the message sent out will be treated as a retained message. This must be used in conjunction with ``--will-topic``.
+--extra-headers     Specify a JSON object string with key-value pairs representing additional headers that are transmitted on the initial connection, but only when using a websocket connection
 
 
 .. _MQTT URL scheme: https://github.com/mqtt/mqtt.github.io/wiki/URI-Scheme
@@ -77,3 +79,7 @@ Subscribe to 10 messages with QoS 2 from /#:
 
 .. _mosquitto_sub : http://mosquitto.org/man/mosquitto_sub-1.html
 
+Subscribe with QoS 0 to all messages published under $SYS/: over mqtt encapsulated in a websocket connection and additional headers:
+::
+
+    hbmqtt_sub --url wss://localhost -t '$SYS/#' -q 0 --extra-headers '{"Authorization": "Bearer <token>"}'

hbmqtt/client.py

@@ -134,6 +134,7 @@ class MQTTClient:
             :param cafile: server certificate authority file (optional, used for secured connection)
             :param capath: server certificate authority path (optional, used for secured connection)
             :param cadata: server certificate authority data (optional, used for secured connection)
+            :param extra_headers: a dictionary with additional http headers that should be sent on the initial connection (optional, used only with websocket connections)
             :return: `CONNACK <http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718033>`_ return code
             :raise: :class:`hbmqtt.client.ConnectException` if connection fails
         """

scripts/pub_script.py

@@ -7,7 +7,7 @@ hbmqtt_pub - MQTT 3.1.1 publisher
 Usage:
     hbmqtt_pub --version
     hbmqtt_pub (-h | --help)
-    hbmqtt_pub --url BROKER_URL -t TOPIC (-f FILE | -l | -m MESSAGE | -n | -s) [-c CONFIG_FILE] [-i CLIENT_ID] [-q | --qos QOS] [-d] [-k KEEP_ALIVE] [--clean-session] [--ca-file CAFILE] [--ca-path CAPATH] [--ca-data CADATA] [ --will-topic WILL_TOPIC [--will-message WILL_MESSAGE] [--will-qos WILL_QOS] [--will-retain] ] [-r]
+    hbmqtt_pub --url BROKER_URL -t TOPIC (-f FILE | -l | -m MESSAGE | -n | -s) [-c CONFIG_FILE] [-i CLIENT_ID] [-q | --qos QOS] [-d] [-k KEEP_ALIVE] [--clean-session] [--ca-file CAFILE] [--ca-path CAPATH] [--ca-data CADATA] [ --will-topic WILL_TOPIC [--will-message WILL_MESSAGE] [--will-qos WILL_QOS] [--will-retain] ] [--extra-headers HEADER] [-r]
 
 Options:
     -h --help           Show this screen.
@@ -30,6 +30,7 @@ Options:
     --will-message WILL_MESSAGE
     --will-qos WILL_QOS
     --will-retain
+    --extra-headers EXTRA_HEADERS      JSON object with key-value pairs of additional headers for websocket connections
     -d                  Enable debug messages
 """
 
@@ -37,6 +38,7 @@ import sys
 import logging
 import asyncio
 import os
+import json
 from hbmqtt.client import MQTTClient, ConnectException
 from hbmqtt.version import get_version
 from docopt import docopt
@@ -60,6 +62,11 @@ def _get_qos(arguments):
     except:
         return None
 
+def _get_extra_headers(arguments):
+    try:
+        return json.loads(arguments['--extra-headers'])
+    except:
+        return {}
 
 def _get_message(arguments):
     if arguments['-n']:
@@ -97,7 +104,8 @@ def do_pub(client, arguments):
                                   cleansession=arguments['--clean-session'],
                                   cafile=arguments['--ca-file'],
                                   capath=arguments['--ca-path'],
-                                  cadata=arguments['--ca-data'])
+                                  cadata=arguments['--ca-data'],
+                                  extra_headers=_get_extra_headers(arguments))
         qos = _get_qos(arguments)
         topic = arguments['-t']
         retain = arguments['-r']

scripts/sub_script.py

@@ -7,7 +7,7 @@ hbmqtt_sub - MQTT 3.1.1 publisher
 Usage:
     hbmqtt_sub --version
     hbmqtt_sub (-h | --help)
-    hbmqtt_sub --url BROKER_URL -t TOPIC... [-n COUNT] [-c CONFIG_FILE] [-i CLIENT_ID] [-q | --qos QOS] [-d] [-k KEEP_ALIVE] [--clean-session] [--ca-file CAFILE] [--ca-path CAPATH] [--ca-data CADATA] [ --will-topic WILL_TOPIC [--will-message WILL_MESSAGE] [--will-qos WILL_QOS] [--will-retain] ]
+    hbmqtt_sub --url BROKER_URL -t TOPIC... [-n COUNT] [-c CONFIG_FILE] [-i CLIENT_ID] [-q | --qos QOS] [-d] [-k KEEP_ALIVE] [--clean-session] [--ca-file CAFILE] [--ca-path CAPATH] [--ca-data CADATA] [ --will-topic WILL_TOPIC [--will-message WILL_MESSAGE] [--will-qos WILL_QOS] [--will-retain] ] [--extra-headers HEADER]
 
 Options:
     -h --help           Show this screen.
@@ -27,6 +27,7 @@ Options:
     --will-message WILL_MESSAGE
     --will-qos WILL_QOS
     --will-retain
+    --extra-headers EXTRA_HEADERS      JSON object with key-value pairs of additional headers for websocket connections
     -d                  Enable debug messages
 """
 
@@ -34,6 +35,7 @@ import sys
 import logging
 import asyncio
 import os
+import json
 from hbmqtt.client import MQTTClient, ConnectException
 from hbmqtt.errors import MQTTException
 from hbmqtt.version import get_version
@@ -58,6 +60,12 @@ def _get_qos(arguments):
     except:
         return QOS_0
 
+def _get_extra_headers(arguments):
+    try:
+        return json.loads(arguments['--extra-headers'])
+    except:
+        return {}
+
 
 @asyncio.coroutine
 def do_sub(client, arguments):
@@ -67,7 +75,8 @@ def do_sub(client, arguments):
                                   cleansession=arguments['--clean-session'],
                                   cafile=arguments['--ca-file'],
                                   capath=arguments['--ca-path'],
-                                  cadata=arguments['--ca-data'])
+                                  cadata=arguments['--ca-data'],
+                                  extra_headers=_get_extra_headers(arguments))
         qos = _get_qos(arguments)
         filters = []
         for topic in arguments['-t']: