Quick start and command-line tools documentation

pull/8/head
Nico 2015-11-06 22:47:12 +01:00
rodzic 0e2d0c4a8a
commit 56e0b92fcf
8 zmienionych plików z 372 dodań i 71 usunięć

Wyświetl plik

@ -5,5 +5,5 @@ Changelog
...
* Added compatibility with Python 3.5.
* Rewritten documentation.
* Rewritten documentation.
* Add command-line tools :doc:`references/hbmqtt`, :doc:`references/hbmqtt_pub` and :doc:`references/hbmqtt_sub`.

Wyświetl plik

@ -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.

Wyświetl plik

@ -66,5 +66,6 @@ News and updates are listed in the :doc:`changelog`.
quickstart
changelog
references/index
license

Wyświetl plik

@ -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.

Wyświetl plik

@ -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 <config_file> ] [-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.

Wyświetl plik

@ -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

Wyświetl plik

@ -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

Wyświetl plik

@ -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