kopia lustrzana https://github.com/Yakifo/amqtt
Quick start and command-line tools documentation
Nico
rodzic
0e2d0c4a8a
commit
56e0b92fcf
|
|
@ -5,5 +5,5 @@ Changelog
|
||||||
...
|
...
|
||||||
|
|
||||||
* Added compatibility with Python 3.5.
|
* 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`.
|
||||||
|
|
@ -37,6 +37,7 @@ extensions = [
|
||||||
'sphinx.ext.todo',
|
'sphinx.ext.todo',
|
||||||
'sphinx.ext.coverage',
|
'sphinx.ext.coverage',
|
||||||
'sphinx.ext.ifconfig',
|
'sphinx.ext.ifconfig',
|
||||||
|
'sphinx.ext.viewcode',
|
||||||
]
|
]
|
||||||
|
|
||||||
# Add any paths that contain templates here, relative to this directory.
|
# Add any paths that contain templates here, relative to this directory.
|
||||||
|
|
|
||||||
|
|
@ -66,5 +66,6 @@ News and updates are listed in the :doc:`changelog`.
|
||||||
|
|
||||||
quickstart
|
quickstart
|
||||||
changelog
|
changelog
|
||||||
|
references/index
|
||||||
license
|
license
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
Quickstart
|
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.
|
* publishing a message on some topic on an external MQTT broker.
|
||||||
* subscribing some topics and getting published messages.
|
* 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
|
(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 : ::
|
Here are some examples of URL:
|
||||||
|
::
|
||||||
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``.
|
|
||||||
|
|
||||||
|
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
|
.. _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
|
||||||
|
----------------
|
||||||
|
|
||||||
|
``hbmqtt`` is a command-line tool for running a MQTT broker:
|
||||||
Publish temperature information to localhost with QoS 1:
|
|
||||||
::
|
::
|
||||||
|
|
||||||
hbmqtt_pub --url mqtt://localhost -t sensors/temperature -m 32 -q 1
|
$ hbmqtt
|
||||||
|
[2015-11-06 22:45:16,470] :: INFO - Listener 'default' bind to 0.0.0.0:1883 (max_connecionts=-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
|
|
||||||
|
|
||||||
|
See :doc:`references/hbmqtt` reference documentation for details about available options and settings.
|
||||||
|
|
|
||||||
|
|
@ -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.
|
||||||
|
|
@ -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
|
||||||
|
|
||||||
|
|
@ -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
|
||||||
|
|
||||||
|
|
@ -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
|
||||||
|
|
||||||
|
|
||||||
Ładowanie…
Reference in New Issue