From 56e0b92fcffb48e0f0e07485d912fbbd044df044 Mon Sep 17 00:00:00 2001 From: Nico Date: Fri, 6 Nov 2015 22:47:12 +0100 Subject: [PATCH] Quick start and command-line tools documentation --- docs/changelog.rst | 4 +- docs/conf.py | 1 + docs/index.rst | 1 + docs/quickstart.rst | 129 +++++++++++++++------------------ docs/references/hbmqtt.rst | 106 +++++++++++++++++++++++++++ docs/references/hbmqtt_pub.rst | 98 +++++++++++++++++++++++++ docs/references/hbmqtt_sub.rst | 79 ++++++++++++++++++++ docs/references/index.rst | 25 +++++++ 8 files changed, 372 insertions(+), 71 deletions(-) create mode 100644 docs/references/hbmqtt.rst create mode 100644 docs/references/hbmqtt_pub.rst create mode 100644 docs/references/hbmqtt_sub.rst create mode 100644 docs/references/index.rst diff --git a/docs/changelog.rst b/docs/changelog.rst index ebbf3fc..1129bed 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -5,5 +5,5 @@ Changelog ... * Added compatibility with Python 3.5. - -* Rewritten documentation. \ No newline at end of file +* Rewritten documentation. +* Add command-line tools :doc:`references/hbmqtt`, :doc:`references/hbmqtt_pub` and :doc:`references/hbmqtt_sub`. \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 1656318..9d4a88f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -37,6 +37,7 @@ extensions = [ 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.ifconfig', + 'sphinx.ext.viewcode', ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/index.rst b/docs/index.rst index a98fb7e..0b6e31f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -66,5 +66,6 @@ News and updates are listed in the :doc:`changelog`. quickstart changelog + references/index license diff --git a/docs/quickstart.rst b/docs/quickstart.rst index b9ae503..e6183bd 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -1,7 +1,7 @@ Quickstart ========== -``HBMQTT`` provides console scripts for : +A quick way for getting started with ``HBMQTT`` is to use console scripts provided for : * publishing a message on some topic on an external MQTT broker. * subscribing some topics and getting published messages. @@ -11,85 +11,76 @@ These scripts are installed automatically when installing ``HBMQTT`` with the fo (venv) $ pip install hbmqtt -Read the foloowing sections to learn how to uses these scripts. +Publishing messages +------------------- -hbmqtt_pub +``hbmqtt_pub`` is a command-line tool which can be used for publishing some messages on a topic. It requires a few arguments like broker URL, topic name, QoS and data to send. Additional options allow more complex use case. + +Publishing ```some_data`` to as ``/test`` topic on is as simple as : +:: + + $ hbmqtt_pub --url mqtt://test.mosquitto.org -t /test -m some_data + [2015-11-06 22:21:55,108] :: INFO - hbmqtt_pub/5135-MacBook-Pro.local Connecting to broker + [2015-11-06 22:21:55,333] :: INFO - hbmqtt_pub/5135-MacBook-Pro.local Publishing to '/test' + [2015-11-06 22:21:55,336] :: INFO - hbmqtt_pub/5135-MacBook-Pro.local Disconnected from broker + +This will use insecure TCP connection to connect to test.mosquitto.org. ``hbmqtt_pub`` also allows websockets and secure connection: +:: + + $ hbmqtt_pub --url ws://test.mosquitto.org:8080 -t /test -m some_data + [2015-11-06 22:22:42,542] :: INFO - hbmqtt_pub/5157-MacBook-Pro.local Connecting to broker + [2015-11-06 22:22:42,924] :: INFO - hbmqtt_pub/5157-MacBook-Pro.local Publishing to '/test' + [2015-11-06 22:22:52,926] :: INFO - hbmqtt_pub/5157-MacBook-Pro.local Disconnected from broker + +``hbmqtt_pub`` can read from file or stdin and use data read as message payload: +:: + + $ some_command | hbmqtt_pub --url mqtt://localhost -t /test -l + +See :doc:`references/hbmqtt_pub` reference documentation for details about available options and settings. + +Subscribing a topic +------------------- + +``hbmqtt_sub`` is a command-line tool which can be used to subscribe for some pattern(s) on a broker and get date from messages published on topics matching these patterns by other MQTT clients. + +Subscribing a ``/test/#`` topic pattern is done with : +:: + + $ hbmqtt_sub --url mqtt://localhost -t /test/# + +This command will run forever and print on the standard output every messages received from the broker. The ``-n`` option allows to set a maximum number of messages to receive before stopping. + +See :doc:`references/hbmqtt_sub` reference documentation for details about available options and settings. + + +URL Scheme ---------- -``hbmqtt_pub`` is a MQTT client that publishes simple messages on a topic from the command line. +HBMQTT command line tools use the ``--url`` to establish a network connection with the broker. The ``--url`` parameter value must conform to the `MQTT URL scheme`_. The general accepted form is : +:: -Usage -..... + [mqtt|ws][s]://[username][:password]@host.domain[:port] -``hbmqtt_pub`` 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] ] - -Note that for simplicity, ``hbmqtt_pub`` uses mostly the same argument syntax as `mosquitto_pub`_. - -.. _mosquitto_pub: http://mosquitto.org/man/mosquitto_pub-1.html - -Options -....... - ---version HBMQTT version information --h, --help Display ``hbmqtt_pub`` usage help --c Set the YAML configuration file to read and pass to the client runtime. ---ca-file Define the path to a file containing PEM encoded CA certificates that are trusted. Used to enable SSL communication. ---ca-path Define the path to a directory containing PEM encoded CA certificates that are trusted. Used to enable SSL communication. ---ca-data Set the PEM encoded CA certificates that are trusted. Used to enable SSL communication. ---clean-session If given, set the CONNECT clean session flag to True. --f Send the contents of a file as the message. The file is read line by line, and ``hbmqtt_pub`` will publish a message for each line read. --i The id to use for this client. If not given, defaults to ``hbmqtt_pub/`` appended with the process id and the hostname of the client. --l Send messages read from stdin. ``hbmqtt_pub`` will publish a message for each line read. Blank lines won't be sent. --k Set the CONNECT keep alive timeout. --m Send a single message from the command line. --n Send a null (zero length) message. --q, --qos Specify the quality of service to use for the message, from 0, 1 and 2. Defaults to 0. --s Send a message read from stdin, sending the entire content as a single message. --t The MQTT topic on which to publish the message. ---url Broker connection URL, conforming to `MQTT URL scheme`_. ---will-topic The topic on which to send a Will, in the event that the client disconnects unexpectedly. ---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``. +Here are some examples of URL: +:: + mqtt://localhost + mqtt://localhost:1884 + mqtt://user@password:localhost + ws://test.mosquitto.org + wss://user@password:localhost .. _MQTT URL scheme: https://github.com/mqtt/mqtt.github.io/wiki/URI-Scheme -Examples -........ -Examples below are adapted from `mosquitto_pub`_ documentation. +Running a broker +---------------- - -Publish temperature information to localhost with QoS 1: +``hbmqtt`` is a command-line tool for running a MQTT broker: :: - hbmqtt_pub --url mqtt://localhost -t sensors/temperature -m 32 -q 1 - -Publish timestamp and temperature information to a remote host on a non-standard port and QoS 0: -:: - - hbmqttt_pub --url mqtt://192.168.1.1:1885 -t sensors/temperature -m "1266193804 32" - -Publish light switch status. Message is set to retained because there may be a long period of time between light switch events: -:: - - hbmqtt_pub --url mqtt://localhost -r -t switches/kitchen_lights/status -m "on" - -Send the contents of a file in two ways: -:: - - hbmqtt_pub --url mqtt://localhost -t my/topic -f ./data - - hbmqtt_pub --url mqtt://localhost -t my/topic -s < ./data - - -.. _mosquitto_pub : http://mosquitto.org/man/mosquitto_pub-1.html + $ hbmqtt + [2015-11-06 22:45:16,470] :: INFO - Listener 'default' bind to 0.0.0.0:1883 (max_connecionts=-1) +See :doc:`references/hbmqtt` reference documentation for details about available options and settings. diff --git a/docs/references/hbmqtt.rst b/docs/references/hbmqtt.rst new file mode 100644 index 0000000..0e518ab --- /dev/null +++ b/docs/references/hbmqtt.rst @@ -0,0 +1,106 @@ +hbmqtt +====== + +``hbmqtt`` is a command-line script for running a MQTT 3.1.1 broker. + +Usage +----- + +``hbmqtt`` usage : +:: + + hbmqtt --version + hbmqtt (-h | --help) + hbmqtt [-c ] [-d] + + +Options +------- + +--version HBMQTT version information +-h, --help Display ``hbmqtt_sub`` usage help +-c Set the YAML configuration file to read and pass to the client runtime. + + +Configuration +------------- + +If ``-c`` argument is given, ``hbmqtt`` will read specific MQTT settings for the given configuration file. This file must be a valid `YAML`_ file which may contains the following configuration elements : + +* ``listeners`` : network bindings configuration list +* ``timeout-disconnect-delay`` : client disconnect timeout after keep-alive timeout +* ``auth`` : authentication configuration + +Without the ``-c`` argument, the broker will run with the following default configuration: + +.. code-block:: yaml + + listeners: + default: + type: tcp + bind: 0.0.0.0:1883 + sys_interval: 20 + auth: + allow-anonymous: true + plugins: + - auth_file + - auth_anonymous + +Using this configuration, ``hbmqtt`` will start a broker : + +* listening on TCP port 1883 on all network interfaces. +* Publishing ``$SYS``_ update messages every ``20`` seconds. +* Allowing anonymous login, and password file bases authentication. + +.. _YAML: http://yaml.org/ + + +Configuration example +--------------------- + +.. code-block:: yaml + + listeners: + default: + max-connections: 50000 + type: tcp + my-tcp-1: + bind: 127.0.0.1:1883 + my-tcp-2: + bind: 1.2.3.4:1883 + max-connections: 1000 + my-tcp-ssl-1: + bind: 127.0.0.1:8883 + ssl: on + cafile: /some/cafile + capath: /some/folder + capath: certificate data + certfile: /some/certfile + keyfile: /some/key + my-ws-1: + bind: 0.0.0.0:8080 + type: ws + timeout-disconnect-delay: 2 + auth: + plugins: ['auth.anonymous'] + allow-anonymous: true + password-file: /some/passwd_file + +This configuration example shows use case of every parameter. + +The ``listeners`` section define 3 bindings : + +* ``my-tcp-1`` : a unsecured TCP listener on port 1883 allowing ``1000`` clients connections simultaneously +* ``my-tcp-ssl-1`` : a secured TCP listener on port 8883 allowing ``50000`` clients connections simultaneously +* ``my-ws-1`` : a unsecured websocket listener on port 8080 allowing ``50000`` clients connections simultaneously + +Authentication allows anonymous logins and password file based authentication. Password files are required to be text files containing user name and password in the form of : +:: + + username:password + +where ``password`` should be the encrypted password. Use the ``mkpasswd -m sha-512`` command to build encoded passphrase. Password file example: +:: + + # Test user with 'test' password encrypted with sha-512 + test:$6$l4zQEHEcowc1Pnv4$HHrh8xnsZoLItQ8BmpFHM4r6q5UqK3DnXp2GaTm5zp5buQ7NheY3Xt9f6godVKbEtA.hOC7IEDwnok3pbAOip. diff --git a/docs/references/hbmqtt_pub.rst b/docs/references/hbmqtt_pub.rst new file mode 100644 index 0000000..e377f29 --- /dev/null +++ b/docs/references/hbmqtt_pub.rst @@ -0,0 +1,98 @@ +hbmqtt_pub +========== + +``hbmqtt_pub`` is a MQTT client that publishes simple messages on a topic from the command line. + +Usage +----- + +``hbmqtt_pub`` 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] [-d] + [-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] ] + +Note that for simplicity, ``hbmqtt_pub`` uses mostly the same argument syntax as `mosquitto_pub`_. + +.. _mosquitto_pub: http://mosquitto.org/man/mosquitto_pub-1.html + +Options +------- + +--version HBMQTT version information +-h, --help Display ``hbmqtt_pub`` usage help +-c Set the YAML configuration file to read and pass to the client runtime. +-d Enable debugging informations. +--ca-file Define the path to a file containing PEM encoded CA certificates that are trusted. Used to enable SSL communication. +--ca-path Define the path to a directory containing PEM encoded CA certificates that are trusted. Used to enable SSL communication. +--ca-data Set the PEM encoded CA certificates that are trusted. Used to enable SSL communication. +--clean-session If given, set the CONNECT clean session flag to True. +-f Send the contents of a file as the message. The file is read line by line, and ``hbmqtt_pub`` will publish a message for each line read. +-i The id to use for this client. If not given, defaults to ``hbmqtt_pub/`` appended with the process id and the hostname of the client. +-l Send messages read from stdin. ``hbmqtt_pub`` will publish a message for each line read. Blank lines won't be sent. +-k Set the CONNECT keep alive timeout. +-m Send a single message from the command line. +-n Send a null (zero length) message. +-q, --qos Specify the quality of service to use for the message, from 0, 1 and 2. Defaults to 0. +-s Send a message read from stdin, sending the entire content as a single message. +-t The MQTT topic on which to publish the message. +--url Broker connection URL, conforming to `MQTT URL scheme`_. +--will-topic The topic on which to send a Will, in the event that the client disconnects unexpectedly. +--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``. + + +.. _MQTT URL scheme: https://github.com/mqtt/mqtt.github.io/wiki/URI-Scheme + + +Configuration +------------- + +If ``-c`` argument is given, ``hbmqtt_pub`` will read specific MQTT settings for the given configuration file. This file must be a valid `YAML`_ file which may contains the following configuration elements : + +* ``keep_alive`` : Keep-alive timeout sent to the broker. Defaults to ``10`` seconds. +* ``ping_delay`` : Auto-ping delay before keep-alive timeout. Defaults to 1. Setting to ``0`` will disable to 0 and may lead to broker disconnection. +* ``default_qos`` : Default QoS for messages published. Defaults to 0. +* ``default_retain`` : Default retain value to messages published. Defaults to ``false``. +* ``auto_reconnect`` : Enable or disable auto-reconnect if connectection with the broker is interrupted. Defaults to ``false``. +* ``reconnect_retries`` : Maximum reconnection retries. Defaults to ``2``. +* ``reconnect_max_interval`` : Maximum interval between 2 connection retry. Defaults to ``10``. + + +.. _YAML: http://yaml.org/ + +Examples +-------- + +Examples below are adapted from `mosquitto_pub`_ documentation. + + +Publish temperature information to localhost with QoS 1: +:: + + hbmqtt_pub --url mqtt://localhost -t sensors/temperature -m 32 -q 1 + +Publish timestamp and temperature information to a remote host on a non-standard port and QoS 0: +:: + + hbmqtt_pub --url mqtt://192.168.1.1:1885 -t sensors/temperature -m "1266193804 32" + +Publish light switch status. Message is set to retained because there may be a long period of time between light switch events: +:: + + hbmqtt_pub --url mqtt://localhost -r -t switches/kitchen_lights/status -m "on" + +Send the contents of a file in two ways: +:: + + hbmqtt_pub --url mqtt://localhost -t my/topic -f ./data + + hbmqtt_pub --url mqtt://localhost -t my/topic -s < ./data + + +.. _mosquitto_pub : http://mosquitto.org/man/mosquitto_pub-1.html + diff --git a/docs/references/hbmqtt_sub.rst b/docs/references/hbmqtt_sub.rst new file mode 100644 index 0000000..0ef8602 --- /dev/null +++ b/docs/references/hbmqtt_sub.rst @@ -0,0 +1,79 @@ +hbmqtt_sub +========== + +``hbmqtt_sub`` is a command line MQTT client that subscribes to some topics and output data received from messages published. + +Usage +----- + +``hbmqtt_sub`` 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] ] + +Note that for simplicity, ``hbmqtt_sub`` uses mostly the same argument syntax as `mosquitto_sub`_. + +Options +------- + +--version HBMQTT version information +-h, --help Display ``hbmqtt_sub`` usage help +-c Set the YAML configuration file to read and pass to the client runtime. +-d Enable debugging informations. +--ca-file Define the path to a file containing PEM encoded CA certificates that are trusted. Used to enable SSL communication. +--ca-path Define the path to a directory containing PEM encoded CA certificates that are trusted. Used to enable SSL communication. +--ca-data Set the PEM encoded CA certificates that are trusted. Used to enable SSL communication. +--clean-session If given, set the CONNECT clean session flag to True. +-i The id to use for this client. If not given, defaults to ``hbmqtt_sub/`` appended with the process id and the hostname of the client. +-k Set the CONNECT keep alive timeout. +-n Number of messages to read before ending. Read forever if not given. +-q, --qos Specify the quality of service to use for receiving messages. This QoS is sent in the subscribe request. +-t Topic filters to subcribe. +--url Broker connection URL, conforming to `MQTT URL scheme`_. +--will-topic The topic on which to send a Will, in the event that the client disconnects unexpectedly. +--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``. + + +.. _MQTT URL scheme: https://github.com/mqtt/mqtt.github.io/wiki/URI-Scheme + + +Configuration +------------- + +If ``-c`` argument is given, ``hbmqtt_sub`` will read specific MQTT settings for the given configuration file. This file must be a valid `YAML`_ file which may contains the following configuration elements : + +* ``keep_alive`` : Keep-alive timeout sent to the broker. Defaults to ``10`` seconds. +* ``ping_delay`` : Auto-ping delay before keep-alive timeout. Defaults to 1. Setting to ``0`` will disable to 0 and may lead to broker disconnection. +* ``default_qos`` : Default QoS for messages published. Defaults to 0. +* ``default_retain`` : Default retain value to messages published. Defaults to ``false``. +* ``auto_reconnect`` : Enable or disable auto-reconnect if connectection with the broker is interrupted. Defaults to ``false``. +* ``reconnect_retries`` : Maximum reconnection retries. Defaults to ``2``. +* ``reconnect_max_interval`` : Maximum interval between 2 connection retry. Defaults to ``10``. + + +.. _YAML: http://yaml.org/ + +Examples +-------- + +Examples below are adapted from `mosquitto_sub`_ documentation. + + +Subscribe with QoS 0 to all messages plublish under $SYS/: +:: + + hbmqtt_sub --url mqtt://localhost -t '$SYS/#' -q 0 + + +Subscribe to 10 messages with QoS 2 from /#: +:: + + hbmqtt_sub --url mqtt://localhost -t /# -q 2 -n 10 + +.. _mosquitto_sub : http://mosquitto.org/man/mosquitto_sub-1.html + diff --git a/docs/references/index.rst b/docs/references/index.rst new file mode 100644 index 0000000..f4731ef --- /dev/null +++ b/docs/references/index.rst @@ -0,0 +1,25 @@ +References +========== + +Reference documentation for HBMQTT console scripts and programming API. + +Console scripts +--------------- + +* :doc:`hbmqtt_pub` : MQTT client for publishing messages to a broker +* :doc:`hbmqtt_sub` : MQTT client for subscribing to a topics and retrieved published messages +* :doc:`hbmqtt` : Autonomous MQTT broker + +Programming API +--------------- + +TBD + +.. toctree:: + :hidden: + + hbmqtt_pub + hbmqtt_sub + hbmqtt + +