kopia lustrzana https://github.com/Yakifo/amqtt
convert rst files to md
Andrew Mirsky
rodzic
335e0e20d1
commit
9e13cb9da4
110
README.md
110
README.md
|
|
@ -1,105 +1,55 @@
|
||||||
|license| |ci| |coverage| |rtfm| |gitter| |python_versions| |python_wheel| |PyPI|
|
[](https://amqtt.readthedocs.io/en/latest/)
|
||||||
|
[](https://github.com/Yakifo/amqtt/actions/workflows/python-package.yml)
|
||||||
|
[](https://coveralls.io/github/Yakifo/amqtt?branch=master)
|
||||||
|
[](https://amqtt.readthedocs.io/en/latest/)
|
||||||
|
[](https://gitter.im/amqtt/community)
|
||||||
|
|
||||||
|
|
||||||
|
[](https://pypi.org/project/amqtt/)
|
||||||
|
|
||||||
.. |license| image:: https://img.shields.io/github/license/Yakifo/amqtt?style=flat-square
|
# WORK IN PROGRESS
|
||||||
:target: https://amqtt.readthedocs.io/en/latest/
|
[!!! MAINTAINERS WANTED !!!](https://github.com/Yakifo/amqtt/issues/163)
|
||||||
:alt: MIT licensed
|
|
||||||
|
|
||||||
.. |ci| image:: https://img.shields.io/github/workflow/status/Yakifo/amqtt/Python%20package?style=flat-square
|
# aMQTT
|
||||||
:target: https://github.com/Yakifo/amqtt/actions/workflows/python-package.yml
|
|
||||||
|
|
||||||
.. |coverage| image:: https://img.shields.io/coveralls/github/Yakifo/amqtt?style=flat-square
|
`aMQTT` is an open source [MQTT](http://www.mqtt.org) client and broker implementation.
|
||||||
:target: https://coveralls.io/github/Yakifo/amqtt?branch=master
|
|
||||||
|
|
||||||
.. |rtfm| image:: https://img.shields.io/readthedocs/amqtt?style=flat-square
|
Built on top of [asyncio](https://docs.python.org/3/library/asyncio.html), Python's standard asynchronous I/O framework, aMQTT provides a straightforward API based on coroutines, making it easy to write highly concurrent applications.
|
||||||
:target: https://amqtt.readthedocs.io/en/latest/
|
|
||||||
:alt: Documentation Status
|
|
||||||
|
|
||||||
.. |gitter| image:: https://img.shields.io/gitter/room/Yakifo/amqtt?style=flat-square
|
It was forked from [HBMQTT](https://github.com/beerfactory/hbmqtt) after it was deprecated by the original author.
|
||||||
:target: https://gitter.im/amqtt/community
|
|
||||||
:alt: 'Join the chat at https://gitter.im/amqtt/community'
|
|
||||||
|
|
||||||
.. |python_versions| image:: https://img.shields.io/pypi/pyversions/amqtt?style=flat-square
|
## Features
|
||||||
:alt: Python Version
|
|
||||||
|
|
||||||
.. |python_wheel| image:: https://img.shields.io/pypi/wheel/amqtt?style=flat-square
|
aMQTT implements the full set of [MQTT 3.1.1](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) protocol specifications and provides the following features:
|
||||||
:alt: supports python wheel
|
|
||||||
|
|
||||||
.. |PyPI| image:: https://img.shields.io/pypi/v/amqtt?style=flat-square
|
|
||||||
:target: https://pypi.org/project/amqtt/
|
|
||||||
:alt: PyPI
|
|
||||||
|
|
||||||
|
|
||||||
WORK IN PROGRESS.
|
|
||||||
=======
|
|
||||||
`!!! MAINTAINERS WANTED !!! <https://github.com/Yakifo/amqtt/issues/163>`_
|
|
||||||
|
|
||||||
|
|
||||||
aMQTT
|
|
||||||
======
|
|
||||||
|
|
||||||
``aMQTT`` is an open source `MQTT`_ client and broker implementation.
|
|
||||||
|
|
||||||
Built on top of `asyncio`_, Python's standard asynchronous I/O framework, aMQTT provides a straightforward API
|
|
||||||
based on coroutines, making it easy to write highly concurrent applications.
|
|
||||||
|
|
||||||
It was forked from `HBMQTT`_ after it was deprecated by the original author.
|
|
||||||
|
|
||||||
|
|
||||||
.. _asyncio: https://docs.python.org/3/library/asyncio.html
|
|
||||||
.. _HBMQTT: https://github.com/beerfactory/hbmqtt
|
|
||||||
|
|
||||||
Features
|
|
||||||
--------
|
|
||||||
|
|
||||||
aMQTT implements the full set of `MQTT 3.1.1`_ protocol specifications and provides the following features:
|
|
||||||
|
|
||||||
- Support QoS 0, QoS 1 and QoS 2 messages flow
|
- Support QoS 0, QoS 1 and QoS 2 messages flow
|
||||||
- Client auto-reconnection on network lost
|
- Client auto-reconnection on network lost
|
||||||
- Authentication through password file (more methods can be added through a plugin system)
|
- Authentication through password file (more methods can be added through a plugin system)
|
||||||
- Basic ``$SYS`` topics
|
- Basic `$SYS` topics
|
||||||
- TCP and websocket support
|
- TCP and websocket support
|
||||||
- SSL support over TCP and websocket
|
- SSL support over TCP and websocket
|
||||||
- Plugin system
|
- Plugin system
|
||||||
|
|
||||||
|
## Project Status and Roadmap
|
||||||
Project Status and Roadmap
|
|
||||||
---------------------------
|
|
||||||
|
|
||||||
The current focus is to build setup the project infrastructure for the new fork.
|
The current focus is to build setup the project infrastructure for the new fork.
|
||||||
From there the goal is to fix outstanding known issues and clean up the code.
|
From there the goal is to fix outstanding known issues and clean up the code.
|
||||||
|
|
||||||
+----------+---------------------------+----------------------------+--------------+
|
| Version | hbmqtt compatibility | Supported Python Versions | PyPi Release |
|
||||||
| Version | hbmqtt compatibility | Supported Python Versions | PyPi Release |
|
|---------|---------------------|-------------------------|--------------|
|
||||||
+----------+---------------------------+----------------------------+--------------+
|
| 0.10.x | YES - Drop-in Replacement | 3.7* | 0.10.1 |
|
||||||
| 0.10.x | YES - Drop-in Replacement | 3.7* | 0.10.1 |
|
| 0.11.x | NO - Module renamed and small API differences | 3.7 - 3.10 | No release yet |
|
||||||
+----------+---------------------------+----------------------------+--------------+
|
|
||||||
| 0.11.x | NO - Module renamed | 3.7 - 3.10 | No release |
|
|
||||||
| | and small API differences | | yet |
|
|
||||||
+----------+---------------------------+----------------------------+--------------+
|
|
||||||
|
|
||||||
|
\* Due to a change in Python 3.8 where the semantics of asyncio.CancelledError was changed to be a subclass of BaseException instead of Exception, old versions of hbmqtt and aMQTT will break, see https://github.com/Yakifo/amqtt/issues/133. Therefore only 3.7 is mentioned as supported version for 0.10.x.
|
||||||
|
|
||||||
* Due to a change in Python 3.8 where the semantics of asyncio.CancelledError was changed
|
## Getting started
|
||||||
to be a subclass of BaseException instead of Exception, old versions of hbmqtt and aMQTT
|
|
||||||
will break, see https://github.com/Yakifo/amqtt/issues/133.
|
|
||||||
Therefore only 3.7 is mentioned as supported version for 0.10.x.
|
|
||||||
|
|
||||||
|
`amqtt` is available on [PyPI](https://pypi.python.org/pypi/amqtt) and can be installed simply using `pip`:
|
||||||
|
|
||||||
Getting started
|
```bash
|
||||||
---------------
|
$ pip install amqtt
|
||||||
|
```
|
||||||
|
|
||||||
`amqtt` is available on `Pypi <https://pypi.python.org/pypi/amqtt>`_ and can installed simply using ``pip`` :
|
Documentation is available on [Read the Docs](http://amqtt.readthedocs.org/).
|
||||||
::
|
|
||||||
|
|
||||||
$ pip install amqtt
|
Bug reports, patches and suggestions welcome! Just [open an issue](https://github.com/Yakifo/amqtt/issues/new) or join the [gitter community](https://gitter.im/amqtt/community).
|
||||||
|
|
||||||
Documentation is available on `Read the Docs`_.
|
|
||||||
|
|
||||||
Bug reports, patches and suggestions welcome! Just `open an issue`_ or join the `gitter channel`_.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
.. _MQTT: http://www.mqtt.org
|
|
||||||
.. _MQTT 3.1.1: http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html
|
|
||||||
.. _Read the Docs: http://amqtt.readthedocs.org/
|
|
||||||
.. _open an issue: https://github.com/Yakifo/amqtt/issues/new
|
|
||||||
.. _gitter channel: https://gitter.im/amqtt/community
|
|
||||||
|
|
|
||||||
|
|
@ -1,68 +1,17 @@
|
||||||
aMQTT
|
# Welcome to MkDocs
|
||||||
======
|
|
||||||
|
|
||||||
``aMQTT`` is an open source `MQTT`_ client and broker implementation.
|
For full documentation visit [mkdocs.org](https://www.mkdocs.org).
|
||||||
|
|
||||||
Built on top of :mod:`asyncio`, Python's standard asynchronous I/O framework, aMQTT provides a straightforward API
|
## Commands
|
||||||
based on coroutines, making it easy to write highly concurrent applications.
|
|
||||||
|
|
||||||
Features
|
* `mkdocs new [dir-name]` - Create a new project.
|
||||||
--------
|
* `mkdocs serve` - Start the live-reloading docs server.
|
||||||
|
* `mkdocs build` - Build the documentation site.
|
||||||
|
* `mkdocs -h` - Print help message and exit.
|
||||||
|
|
||||||
aMQTT implements the full set of `MQTT 3.1.1`_ protocol specifications and provides the following features:
|
## Project layout
|
||||||
|
|
||||||
- Support QoS 0, QoS 1 and QoS 2 messages flow
|
|
||||||
- Client auto-reconnection on network lost
|
|
||||||
- Authentication through password file (more methods can be added through a plugin system)
|
|
||||||
- Basic ``$SYS`` topics
|
|
||||||
- TCP and websocket support
|
|
||||||
- SSL support over TCP and websocket
|
|
||||||
- Plugin system
|
|
||||||
|
|
||||||
|
|
||||||
Requirements
|
|
||||||
------------
|
|
||||||
|
|
||||||
aMQTT is built on Python's `asyncio`.
|
|
||||||
It requires Python 3.6 or newer.
|
|
||||||
|
|
||||||
Installation
|
|
||||||
------------
|
|
||||||
|
|
||||||
It is not recommended to install third-party library in Python system packages directory. The preferred way for
|
|
||||||
installing aMQTT is to create a virtual environment and then install all the dependencies you need. Refer to
|
|
||||||
`PEP 405`_ to learn more.
|
|
||||||
|
|
||||||
Once you have a environment setup and ready, aMQTT can be installed with the following command ::
|
|
||||||
|
|
||||||
(venv) $ pip install amqtt
|
|
||||||
|
|
||||||
``pip`` will download and install aMQTT and all its dependencies.
|
|
||||||
|
|
||||||
|
|
||||||
User guide
|
|
||||||
----------
|
|
||||||
|
|
||||||
If you need aMQTT for running a MQTT client or deploying a MQTT broker, the :doc:`quickstart` describes how to use console scripts provided by aMQTT.
|
|
||||||
|
|
||||||
If you want to develop an application which needs to connect to a MQTT broker, the :doc:`references/mqttclient` documentation explains how to use aMQTT API for connecting, publishing and subscribing with a MQTT broker.
|
|
||||||
|
|
||||||
If you want to run you own MQTT broker, th :doc:`references/broker` reference documentation explains how to embed a MQTT broker inside a Python application.
|
|
||||||
|
|
||||||
News and updates are listed in the :doc:`changelog`.
|
|
||||||
|
|
||||||
|
|
||||||
.. _MQTT: http://www.mqtt.org
|
|
||||||
.. _MQTT 3.1.1: http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html
|
|
||||||
.. _PEP 405: https://www.python.org/dev/peps/pep-0405/
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 2
|
|
||||||
:hidden:
|
|
||||||
|
|
||||||
quickstart
|
|
||||||
changelog
|
|
||||||
transition
|
|
||||||
references/index
|
|
||||||
license
|
|
||||||
|
|
||||||
|
mkdocs.yml # The configuration file.
|
||||||
|
docs/
|
||||||
|
index.md # The documentation homepage.
|
||||||
|
... # Other markdown pages, images and other files.
|
||||||
|
|
|
||||||
|
|
@ -1,94 +1,88 @@
|
||||||
Quickstart
|
# Quickstart
|
||||||
==========
|
|
||||||
|
|
||||||
``aMQTT`` is an open source `MQTT` client and broker implementation; these can be
|
`aMQTT` is an open source `MQTT` client and broker implementation; these can be integrated into other projects using the appropriate APIs. To get started, three command-line scripts are also installed along with the package:
|
||||||
integrated into other projects using the appropriate APIs. To get started, three
|
|
||||||
command-line scripts are also installed along with the package:
|
|
||||||
|
|
||||||
* ``amqtt`` - the MQTT broker
|
* `amqtt` - the MQTT broker
|
||||||
* ``amqtt_pub`` - an MQTT client to publish messages
|
* `amqtt_pub` - an MQTT client to publish messages
|
||||||
* ``amqtt_sub`` - an MQTT client to listen for messages
|
* `amqtt_sub` - an MQTT client to listen for messages
|
||||||
|
|
||||||
|
To install the `aMQTT` package:
|
||||||
|
|
||||||
To install the ``aMQTT`` package ::
|
```bash
|
||||||
|
(venv) $ pip install amqtt
|
||||||
|
```
|
||||||
|
|
||||||
(venv) $ pip install amqtt
|
## Running a broker
|
||||||
|
|
||||||
Running a broker
|
`amqtt` is a command-line tool for the MQTT 3.1.1 compliant broker:
|
||||||
----------------
|
|
||||||
|
|
||||||
``amqtt`` is a command-line tool for the MQTT 3.1.1 compliant broker:
|
```bash
|
||||||
::
|
$ amqtt
|
||||||
|
[2015-11-06 22:45:16,470] :: INFO - Listener 'default' bind to 0.0.0.0:1883 (max_connections=-1)
|
||||||
|
```
|
||||||
|
|
||||||
$ amqtt
|
See [amqtt reference documentation](references/amqtt.md) for details about available options and settings.
|
||||||
[2015-11-06 22:45:16,470] :: INFO - Listener 'default' bind to 0.0.0.0:1883 (max_connections=-1)
|
|
||||||
|
|
||||||
See :doc:`references/amqtt` reference documentation for details about available options and settings.
|
## Publishing messages
|
||||||
|
|
||||||
|
`amqtt_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 using a TCP connection to `test.mosquitto.org`:
|
||||||
|
|
||||||
Publishing messages
|
```bash
|
||||||
-------------------
|
$ amqtt_pub --url mqtt://test.mosquitto.org -t test -m some_data
|
||||||
|
[2015-11-06 22:21:55,108] :: INFO - amqtt_pub/5135-myhostname.local Connecting to broker
|
||||||
``amqtt_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.
|
[2015-11-06 22:21:55,333] :: INFO - amqtt_pub/5135-myhostname.local Publishing to 'test'
|
||||||
|
[2015-11-06 22:21:55,336] :: INFO - amqtt_pub/5135-myhostname.local Disconnected from broker
|
||||||
Publishing ```some_data`` to as ``/test`` topic using a TCP connection to ``test.mosquitto.org``:
|
```
|
||||||
::
|
|
||||||
|
|
||||||
$ amqtt_pub --url mqtt://test.mosquitto.org -t test -m some_data
|
|
||||||
[2015-11-06 22:21:55,108] :: INFO - amqtt_pub/5135-myhostname.local Connecting to broker
|
|
||||||
[2015-11-06 22:21:55,333] :: INFO - amqtt_pub/5135-myhostname.local Publishing to 'test'
|
|
||||||
[2015-11-06 22:21:55,336] :: INFO - amqtt_pub/5135-myhostname.local Disconnected from broker
|
|
||||||
|
|
||||||
Websocket connections are also supported:
|
Websocket connections are also supported:
|
||||||
::
|
|
||||||
|
|
||||||
$ amqtt_pub --url ws://test.mosquitto.org:8080 -t test -m some_data
|
```bash
|
||||||
[2015-11-06 22:22:42,542] :: INFO - amqtt_pub/5157-myhostname.local Connecting to broker
|
$ amqtt_pub --url ws://test.mosquitto.org:8080 -t test -m some_data
|
||||||
[2015-11-06 22:22:42,924] :: INFO - amqtt_pub/5157-myhostname.local Publishing to 'test'
|
[2015-11-06 22:22:42,542] :: INFO - amqtt_pub/5157-myhostname.local Connecting to broker
|
||||||
[2015-11-06 22:22:52,926] :: INFO - amqtt_pub/5157-myhostname.local Disconnected from broker
|
[2015-11-06 22:22:42,924] :: INFO - amqtt_pub/5157-myhostname.local Publishing to 'test'
|
||||||
|
[2015-11-06 22:22:52,926] :: INFO - amqtt_pub/5157-myhostname.local Disconnected from broker
|
||||||
|
```
|
||||||
|
|
||||||
Additionally, TCP connections can be secured via TLS and websockets via SSL.
|
Additionally, TCP connections can be secured via TLS and websockets via SSL.
|
||||||
|
|
||||||
``amqtt_pub`` can read from file or stdin and use data read as message payload:
|
`amqtt_pub` can read from file or stdin and use data read as message payload:
|
||||||
::
|
|
||||||
|
|
||||||
$ some_command | amqtt_pub --url mqtt://localhost -t test -l
|
```bash
|
||||||
|
$ some_command | amqtt_pub --url mqtt://localhost -t test -l
|
||||||
|
```
|
||||||
|
|
||||||
See :doc:`references/amqtt_pub` reference documentation for details about available options and settings.
|
See [amqtt_pub reference documentation](references/amqtt_pub.md) for details about available options and settings.
|
||||||
|
|
||||||
Subscribing a topic
|
## Subscribing a topic
|
||||||
-------------------
|
|
||||||
|
|
||||||
``amqtt_sub`` is a command-line tool which can be used to subscribe to a specific topics or a topic patterns.
|
`amqtt_sub` is a command-line tool which can be used to subscribe to a specific topics or a topic patterns.
|
||||||
|
|
||||||
Subscribe to the ``my/test`` topic and the ``test/#`` topic pattern:
|
Subscribe to the `my/test` topic and the `test/#` topic pattern:
|
||||||
::
|
|
||||||
|
|
||||||
$ amqtt_sub --url mqtt://localhost -t my/test -t test/#
|
```bash
|
||||||
|
$ amqtt_sub --url mqtt://localhost -t my/test -t test/#
|
||||||
|
```
|
||||||
|
|
||||||
This will run and print messages to standard output; it can be stopped by ^C.
|
This will run and print messages to standard output; it can be stopped by ^C.
|
||||||
|
|
||||||
See :doc:`references/amqtt_sub` reference documentation for details about available options and settings.
|
See [amqtt_sub reference documentation](references/amqtt_sub.md) for details about available options and settings.
|
||||||
|
|
||||||
|
## URL Scheme
|
||||||
|
|
||||||
URL Scheme
|
aMQTT command line tools use the `--url` to establish a network connection with the broker. It follows Python's [urlparse](https://docs.python.org/3/library/urllib.parse.html) structure but also adds the [mqtt scheme](https://github.com/mqtt/mqtt.org/wiki/URI-Scheme).
|
||||||
----------
|
|
||||||
|
|
||||||
aMQTT command line tools use the ``--url`` to establish a network connection with the broker. It follows
|
```
|
||||||
python's `urlparse <https://docs.python.org/3/library/urllib.parse.html>`_ structure but also adds
|
[mqtt|ws][s]://[username][:password]@host.domain[:port]
|
||||||
the `mqtt scheme <https://github.com/mqtt/mqtt.org/wiki/URI-Scheme>`_.
|
```
|
||||||
::
|
|
||||||
|
|
||||||
[mqtt|ws][s]://[username][:password]@host.domain[:port]
|
|
||||||
|
|
||||||
Here are some examples:
|
Here are some examples:
|
||||||
::
|
|
||||||
|
|
||||||
mqtt://localhost
|
|
||||||
mqtt://localhost:1884
|
|
||||||
mqtt://user:password@localhost
|
|
||||||
ws://test.mosquitto.org
|
|
||||||
wss://user:password@localhost
|
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
mqtt://localhost
|
||||||
|
mqtt://localhost:1884
|
||||||
|
mqtt://user:password@localhost
|
||||||
|
ws://test.mosquitto.org
|
||||||
|
wss://user:password@localhost
|
||||||
|
```
|
||||||
|
|
|
||||||
|
|
@ -1,196 +1,173 @@
|
||||||
amqtt
|
# broker
|
||||||
======
|
|
||||||
|
|
||||||
``amqtt`` is a command-line script for running a MQTT 3.1.1 broker.
|
`amqtt` is a command-line script for running a MQTT 3.1.1 broker.
|
||||||
|
|
||||||
Usage
|
## Usage
|
||||||
-----
|
|
||||||
|
|
||||||
``amqtt`` usage :
|
`amqtt` usage:
|
||||||
::
|
|
||||||
|
|
||||||
amqtt --version
|
```
|
||||||
amqtt (-h | --help)
|
amqtt --version
|
||||||
amqtt [-c <config_file> ] [-d]
|
amqtt (-h | --help)
|
||||||
|
amqtt [-c <config_file> ] [-d]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Options
|
||||||
|
|
||||||
Options
|
- `--version` - amqtt version information
|
||||||
-------
|
- `-h, --help` - Display `amqtt_sub` usage help
|
||||||
|
- `-c` - Set the YAML configuration file to read and pass to the client runtime.
|
||||||
|
|
||||||
--version amqtt version information
|
## Configuration
|
||||||
-h, --help Display ``amqtt_sub`` usage help
|
|
||||||
-c Set the YAML configuration file to read and pass to the client runtime.
|
|
||||||
|
|
||||||
|
Without the `-c` argument, the broker will run with the following, default configuration:
|
||||||
|
|
||||||
Configuration
|
```yaml
|
||||||
-------------
|
listeners:
|
||||||
|
default:
|
||||||
|
type: tcp
|
||||||
|
bind: 0.0.0.0:1883
|
||||||
|
sys_interval: 20
|
||||||
|
auth:
|
||||||
|
allow-anonymous: true
|
||||||
|
plugins:
|
||||||
|
- auth_file
|
||||||
|
- auth_anonymous
|
||||||
|
```
|
||||||
|
|
||||||
Without the ``-c`` argument, the broker will run with the following, default configuration:
|
Using the `-c` argument allows for configuration with a YAML structured file. The following sections contain the available configuration elements:
|
||||||
|
|
||||||
.. code-block:: yaml
|
## Field Descriptions
|
||||||
|
|
||||||
listeners:
|
### listeners (mapping)
|
||||||
default:
|
|
||||||
type: tcp
|
|
||||||
bind: 0.0.0.0:1883
|
|
||||||
sys_interval: 20
|
|
||||||
auth:
|
|
||||||
allow-anonymous: true
|
|
||||||
plugins:
|
|
||||||
- auth_file
|
|
||||||
- auth_anonymous
|
|
||||||
|
|
||||||
Using the ``-c`` argument allows for configuration with a `YAML`_ structured file. The following sections It contains the following which may contains the following configuration elements :
|
|
||||||
|
|
||||||
|
|
||||||
Field Descriptions
|
|
||||||
------------------
|
|
||||||
|
|
||||||
**listeners** (mapping)
|
|
||||||
|
|
||||||
Defines network listeners for the MQTT server.
|
Defines network listeners for the MQTT server.
|
||||||
|
|
||||||
- **<interface name>** (mapping, `default` for parameters to be used across all specified interfaces or user-specified name for the specific interface)
|
#### <interface name> (mapping)
|
||||||
The listener configuration.
|
`default` for parameters to be used across all specified interfaces or user-specified name for the specific interface.
|
||||||
|
The listener configuration.
|
||||||
|
|
||||||
- **bind** (*string*, required)
|
- **bind** (*string*, required)
|
||||||
|
Address and port to bind to, in the form `host:port` (e.g., `0.0.0.0:1883`).
|
||||||
|
|
||||||
Address and port to bind to, in the form `host:port` (e.g., `0.0.0.0:1883`).
|
- **type** (*string*, optional)
|
||||||
|
Protocol type. Typically `"tcp"` or `"ws"`.
|
||||||
|
|
||||||
- **type** (*string*, optional)
|
- **max-connections** (*integer*, optional)
|
||||||
|
Maximum number of clients that can connect to this interface
|
||||||
|
|
||||||
Protocol type. Typically `"tcp"` or `"ws"`.
|
- **ssl** (*string*, default: `off`)
|
||||||
|
Enable (on) or disable (off) SSL. One of `cafile`, `capath`, `cadata` or `certfile`/`keyfile`.
|
||||||
|
|
||||||
- **max-connections** (*integer*, optional)
|
- **cafile** (*string*, optional)
|
||||||
|
Path to a file of concatenated CA certificates in PEM format. See [Certificates](https://docs.python.org/3/library/ssl.html#ssl-certificates) for more info.
|
||||||
|
|
||||||
Maximum number of clients that can connect to this interface
|
- **capath** (*string*, optional)
|
||||||
|
Path to a directory containing several CA certificates in PEM format, following an [OpenSSL specific layout](https://docs.openssl.org/master/man3/SSL_CTX_load_verify_locations/).
|
||||||
|
|
||||||
- **ssl** (*string*, default: ``off``)
|
- **cadata** (*string*, optional)
|
||||||
|
Either an ASCII string of one or more PEM-encoded certificates or a bytes-like object of DER-encoded certificates
|
||||||
|
|
||||||
Enable (on) or disable (off) SSL. One of ``cafile``, ``capath``, ``cadata`` or ``certfile``/``keyfile``.
|
- **certfile** (*string*, optional)
|
||||||
|
Path to a single file in PEM format containing the certificate as well as any number of CA certificates needed to establish the certificate's authenticity
|
||||||
|
|
||||||
- **cafile** (*string*, optional)
|
- **keyfile** (*string*, optional)
|
||||||
|
A file containing the private key. Otherwise the private key will be taken from certfile as well
|
||||||
|
|
||||||
path to a file of concatenated CA certificates in PEM format. see
|
### timeout-disconnect-delay (*integer*, optional)
|
||||||
`Certificates <https://docs.python.org/3/library/ssl.html#ssl-certificates>`_ for more info.
|
|
||||||
|
|
||||||
- **capath** (*string*, optional)
|
Client disconnect timeout without a keep-alive
|
||||||
|
|
||||||
path to a directory containing several CA certificates in PEM format, following
|
### plugins (*list of strings*)
|
||||||
an `OpenSSL specific layout <https://docs.openssl.org/master/man3/SSL_CTX_load_verify_locations/>`_.
|
|
||||||
|
|
||||||
- **cadata** (*string*, optional)
|
|
||||||
|
|
||||||
either an ASCII string of one or more PEM-encoded certificates or a bytes-like object of DER-encoded certificates
|
|
||||||
|
|
||||||
- **certfile** (*string*, optional)
|
|
||||||
|
|
||||||
path to a single file in PEM format containing the certificate as well as any number of
|
|
||||||
CA certificates needed to establish the certificate’s authenticity
|
|
||||||
|
|
||||||
- **keyfile** (*string*, optional)
|
|
||||||
|
|
||||||
a file containing the private key. Otherwise the private key will be taken from certfile as well
|
|
||||||
|
|
||||||
**timeout-disconnect-delay** (*integer*, optional)
|
|
||||||
|
|
||||||
client disconnect timeout without a keep-alive
|
|
||||||
|
|
||||||
**plugins** (*list of strings*)
|
|
||||||
A list of plugin names to load. Common values include:
|
A list of plugin names to load. Common values include:
|
||||||
|
|
||||||
- ``auth_file`` – Enables file-based authentication
|
- `auth_file` – Enables file-based authentication
|
||||||
- ``auth_anonymous`` – Enables anonymous access
|
- `auth_anonymous` – Enables anonymous access
|
||||||
- ``event_logger_plugin``
|
- `event_logger_plugin`
|
||||||
- ``packet_logger_plugin``
|
- `packet_logger_plugin`
|
||||||
- ``topic_taboo``
|
- `topic_taboo`
|
||||||
- ``topic_acl``
|
- `topic_acl`
|
||||||
- ``broker_sys``
|
- `broker_sys`
|
||||||
|
|
||||||
**auth** (mapping)
|
### auth (mapping)
|
||||||
|
|
||||||
Authentication and authorization settings.
|
Authentication and authorization settings.
|
||||||
|
|
||||||
- **allow-anonymous** (*boolean*)
|
- **allow-anonymous** (*boolean*)
|
||||||
|
|
||||||
Whether to allow anonymous clients to connect (`true` or `false`).
|
Whether to allow anonymous clients to connect (`true` or `false`).
|
||||||
|
|
||||||
- **password-file** (*string*, required for `auth_file` plugin)
|
- **password-file** (*string*, required for `auth_file` plugin)
|
||||||
|
Lines of `username:password` combination where the password is sha-512 encoded using `mkpasswd -m sha-512` or:
|
||||||
|
|
||||||
lines of ``username:password`` combination where the the password is sha-512 encoded
|
```python
|
||||||
using ``mkpasswd -m sha-512`` or
|
import sys
|
||||||
|
from getpass import getpass
|
||||||
|
from passlib.hash import sha512_crypt
|
||||||
|
|
||||||
.. code-block:: python
|
passwd = input() if not sys.stdin.isatty() else getpass()
|
||||||
|
print(sha512_crypt.hash(passwd))
|
||||||
|
```
|
||||||
|
|
||||||
import sys
|
### sys-interval (*integer*, optional for `broker_sys` plugin, defaults to TBD)
|
||||||
from getpass import getpass
|
|
||||||
from passlib.hash import sha512_crypt
|
|
||||||
|
|
||||||
passwd = input() if not sys.stdin.isatty() else getpass()
|
|
||||||
print(sha512_crypt.hash(passwd))
|
|
||||||
|
|
||||||
**sys-interval** (*integer*, optional for ``broker_sys`` plugin, defaults to TBD)
|
|
||||||
|
|
||||||
Interval in seconds to publish system statistics to `$SYS` topics.
|
Interval in seconds to publish system statistics to `$SYS` topics.
|
||||||
|
|
||||||
|
## Configuration example
|
||||||
|
|
||||||
Configuration example
|
```yaml
|
||||||
---------------------
|
listeners:
|
||||||
|
default:
|
||||||
|
max-connections: 500
|
||||||
|
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-tls-1:
|
||||||
|
bind: 127.0.0.1:8883
|
||||||
|
ssl: on
|
||||||
|
cafile: /some/cafile
|
||||||
|
my-ws-1:
|
||||||
|
bind: 0.0.0.0:9001
|
||||||
|
type: ws
|
||||||
|
my-wss-1:
|
||||||
|
bind: 0.0.0.0:9003
|
||||||
|
type: ws
|
||||||
|
ssl: on
|
||||||
|
certfile: /some/certfile
|
||||||
|
keyfile: /some/key
|
||||||
|
plugins:
|
||||||
|
- auth_file
|
||||||
|
- broker_sys
|
||||||
|
|
||||||
.. code-block:: yaml
|
timeout-disconnect-delay: 2
|
||||||
|
auth:
|
||||||
|
password-file: /some/passwd_file
|
||||||
|
```
|
||||||
|
|
||||||
listeners:
|
The `listeners` section defines 5 bindings:
|
||||||
default:
|
|
||||||
max-connections: 500
|
|
||||||
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-tls-1:
|
|
||||||
bind: 127.0.0.1:8883
|
|
||||||
ssl: on
|
|
||||||
cafile: /some/cafile
|
|
||||||
my-ws-1:
|
|
||||||
bind: 0.0.0.0:9001
|
|
||||||
type: ws
|
|
||||||
my-wss-1:
|
|
||||||
bind: 0.0.0.0:9003
|
|
||||||
type: ws
|
|
||||||
ssl: on
|
|
||||||
certfile: /some/certfile
|
|
||||||
keyfile: /some/key
|
|
||||||
plugins:
|
|
||||||
- auth_file
|
|
||||||
- broker_sys
|
|
||||||
|
|
||||||
timeout-disconnect-delay: 2
|
* `my-tcp-1`: an unsecured TCP listener on port 1883 allowing `500` clients connections simultaneously
|
||||||
auth:
|
* `my-tcp-2`: an unsecured TCP listener on port 1884 allowing `1000` client connections
|
||||||
password-file: /some/passwd_file
|
* `my-tcp-ssl-1`: a secured TCP listener on port 8883 allowing `500` clients connections simultaneously
|
||||||
|
* `my-ws-1`: an unsecured websocket listener on port 9001 allowing `500` clients connections simultaneously
|
||||||
|
* `my-wss-1`: a secured websocket listener on port 9003 allowing `500`
|
||||||
The ``listeners`` section define 3 bindings :
|
|
||||||
|
|
||||||
* ``my-tcp-1`` : an unsecured TCP listener on port 1883 allowing ``500`` clients connections simultaneously
|
|
||||||
* ``my-tcp-2`` : an unsecured TCP listener on port 1884 allowing ``1000`` client connections
|
|
||||||
* ``my-tcp-ssl-1`` : a secured TCP listener on port 8883 allowing ``500`` clients connections simultaneously
|
|
||||||
* ``my-ws-1`` : an unsecured websocket listener on port 9001 allowing ``500`` clients connections simultaneously
|
|
||||||
* ``my-wss-1`` : a secured websocket listener on port 9003 allowing ``500``
|
|
||||||
|
|
||||||
The plugins section enables:
|
The plugins section enables:
|
||||||
|
|
||||||
* ``auth_file`` plugin, requiring `password-file` to be defined in the ``auth`` section
|
* `auth_file` plugin, requiring `password-file` to be defined in the `auth` section
|
||||||
* ``broker_sys`` plugin, requiring `sys_interval` to be defined
|
* `broker_sys` plugin, requiring `sys_interval` to be defined
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
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
|
||||||
|
```
|
||||||
|
|
||||||
username:password
|
where `password` should be the encrypted password. Use the `mkpasswd -m sha-512` command to build encoded passphrase. Password file example:
|
||||||
|
|
||||||
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.
|
||||||
# Test user with 'test' password encrypted with sha-512
|
```
|
||||||
test:$6$l4zQEHEcowc1Pnv4$HHrh8xnsZoLItQ8BmpFHM4r6q5UqK3DnXp2GaTm5zp5buQ7NheY3Xt9f6godVKbEtA.hOC7IEDwnok3pbAOip.
|
|
||||||
|
|
|
||||||
|
|
@ -1,104 +1,88 @@
|
||||||
amqtt_pub
|
# amqtt_pub
|
||||||
==========
|
|
||||||
|
|
||||||
``amqtt_pub`` is a MQTT client that publishes simple messages on a topic from the command line.
|
`amqtt_pub` is a MQTT client that publishes simple messages on a topic from the command line.
|
||||||
|
|
||||||
Usage
|
## Usage
|
||||||
-----
|
|
||||||
|
|
||||||
``amqtt_pub`` usage : ::
|
`amqtt_pub` usage:
|
||||||
|
|
||||||
amqtt_pub --version
|
```
|
||||||
amqtt_pub (-h | --help)
|
amqtt_pub --version
|
||||||
amqtt_pub --url BROKER_URL -t TOPIC (-f FILE | -l | -m MESSAGE | -n | -s) [-c CONFIG_FILE] [-i CLIENT_ID] [-d]
|
amqtt_pub (-h | --help)
|
||||||
[-q | --qos QOS] [-d] [-k KEEP_ALIVE] [--clean-session]
|
amqtt_pub --url BROKER_URL -t TOPIC (-f FILE | -l | -m MESSAGE | -n | -s) [-c CONFIG_FILE] [-i CLIENT_ID] [-d]
|
||||||
[--ca-file CAFILE] [--ca-path CAPATH] [--ca-data CADATA]
|
[-q | --qos QOS] [-d] [-k KEEP_ALIVE] [--clean-session]
|
||||||
[ --will-topic WILL_TOPIC [--will-message WILL_MESSAGE] [--will-qos WILL_QOS] [--will-retain] ]
|
[--ca-file CAFILE] [--ca-path CAPATH] [--ca-data CADATA]
|
||||||
[--extra-headers HEADER]
|
[ --will-topic WILL_TOPIC [--will-message WILL_MESSAGE] [--will-qos WILL_QOS] [--will-retain] ]
|
||||||
|
[--extra-headers HEADER]
|
||||||
|
```
|
||||||
|
|
||||||
Note that for simplicity, ``amqtt_pub`` uses mostly the same argument syntax as `mosquitto_pub`_.
|
Note that for simplicity, `amqtt_pub` uses mostly the same argument syntax as [mosquitto_pub](http://mosquitto.org/man/mosquitto_pub-1.html).
|
||||||
|
|
||||||
.. _mosquitto_pub: http://mosquitto.org/man/mosquitto_pub-1.html
|
## Options
|
||||||
|
|
||||||
Options
|
- `--version` - amqtt version information
|
||||||
-------
|
- `-h, --help` - Display `amqtt_pub` usage help
|
||||||
|
- `-c` - Set the YAML configuration file to read and pass to the client runtime.
|
||||||
|
- `-d` - Enable debugging information.
|
||||||
|
- `--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 `amqtt_pub` will publish a message for each line read.
|
||||||
|
- `-i` - The id to use for this client. If not given, defaults to `amqtt_pub/` appended with the process id and the hostname of the client.
|
||||||
|
- `-l` - Send messages read from stdin. `amqtt_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](https://github.com/mqtt/mqtt.github.io/wiki/URI-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`.
|
||||||
|
- `--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
|
||||||
|
|
||||||
--version amqtt version information
|
## Configuration
|
||||||
-h, --help Display ``amqtt_pub`` usage help
|
|
||||||
-c Set the YAML configuration file to read and pass to the client runtime.
|
|
||||||
-d Enable debugging information.
|
|
||||||
--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 ``amqtt_pub`` will publish a message for each line read.
|
|
||||||
-i The id to use for this client. If not given, defaults to ``amqtt_pub/`` appended with the process id and the hostname of the client.
|
|
||||||
-l Send messages read from stdin. ``amqtt_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``.
|
|
||||||
--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
|
|
||||||
|
|
||||||
|
If `-c` argument is given, `amqtt_pub` will read specific MQTT settings for the given configuration file. This file must be a valid [YAML](http://yaml.org/) file which may contain the following configuration elements:
|
||||||
|
|
||||||
.. _MQTT URL scheme: https://github.com/mqtt/mqtt.github.io/wiki/URI-Scheme
|
* `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 connection with the broker is interrupted. Defaults to `false`.
|
||||||
|
* `reconnect_retries`: Maximum reconnection retries. Defaults to `2`. Negative value will cause client to reconnect infinitely.
|
||||||
|
* `reconnect_max_interval`: Maximum interval between 2 connection retry. Defaults to `10`.
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
Configuration
|
Examples below are adapted from [mosquitto_pub](http://mosquitto.org/man/mosquitto_pub-1.html) documentation.
|
||||||
-------------
|
|
||||||
|
|
||||||
If ``-c`` argument is given, ``amqtt_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``. Negative value will cause client to reconnect infinietly.
|
|
||||||
* ``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:
|
Publish temperature information to localhost with QoS 1:
|
||||||
::
|
```bash
|
||||||
|
amqtt_pub --url mqtt://localhost -t sensors/temperature -m 32 -q 1
|
||||||
amqtt_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:
|
Publish timestamp and temperature information to a remote host on a non-standard port and QoS 0:
|
||||||
::
|
```bash
|
||||||
|
amqtt_pub --url mqtt://192.168.1.1:1885 -t sensors/temperature -m "1266193804 32"
|
||||||
amqtt_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:
|
Publish light switch status. Message is set to retained because there may be a long period of time between light switch events:
|
||||||
::
|
```bash
|
||||||
|
amqtt_pub --url mqtt://localhost -r -t switches/kitchen_lights/status -m "on"
|
||||||
amqtt_pub --url mqtt://localhost -r -t switches/kitchen_lights/status -m "on"
|
```
|
||||||
|
|
||||||
Send the contents of a file in two ways:
|
Send the contents of a file in two ways:
|
||||||
::
|
```bash
|
||||||
|
amqtt_pub --url mqtt://localhost -t my/topic -f ./data
|
||||||
|
|
||||||
amqtt_pub --url mqtt://localhost -t my/topic -f ./data
|
amqtt_pub --url mqtt://localhost -t my/topic -s < ./data
|
||||||
|
```
|
||||||
amqtt_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:
|
Publish temperature information to localhost with QoS 1 over mqtt encapsulated in a websocket connection and additional headers:
|
||||||
::
|
```bash
|
||||||
|
amqtt_pub --url wss://localhost -t sensors/temperature -m 32 -q 1 --extra-headers '{"Authorization": "Bearer <token>"}'
|
||||||
amqtt_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
|
|
||||||
|
|
|
||||||
|
|
@ -1,85 +1,71 @@
|
||||||
amqtt_sub
|
# amqtt_sub
|
||||||
==========
|
|
||||||
|
|
||||||
``amqtt_sub`` is a command line MQTT client that subscribes to some topics and output data received from messages published.
|
`amqtt_sub` is a command line MQTT client that subscribes to some topics and output data received from messages published.
|
||||||
|
|
||||||
Usage
|
## Usage
|
||||||
-----
|
|
||||||
|
|
||||||
``amqtt_sub`` usage : ::
|
`amqtt_sub` usage:
|
||||||
|
|
||||||
amqtt_sub --version
|
```
|
||||||
amqtt_sub (-h | --help)
|
amqtt_sub --version
|
||||||
amqtt_sub --url BROKER_URL -t TOPIC... [-n COUNT] [-c CONFIG_FILE] [-i CLIENT_ID] [-q | --qos QOS] [-d]
|
amqtt_sub (-h | --help)
|
||||||
[-k KEEP_ALIVE] [--clean-session] [--ca-file CAFILE] [--ca-path CAPATH] [--ca-data CADATA]
|
amqtt_sub --url BROKER_URL -t TOPIC... [-n COUNT] [-c CONFIG_FILE] [-i CLIENT_ID] [-q | --qos QOS] [-d]
|
||||||
[ --will-topic WILL_TOPIC [--will-message WILL_MESSAGE] [--will-qos WILL_QOS] [--will-retain] ]
|
[-k KEEP_ALIVE] [--clean-session] [--ca-file CAFILE] [--ca-path CAPATH] [--ca-data CADATA]
|
||||||
[--extra-headers HEADER]
|
[ --will-topic WILL_TOPIC [--will-message WILL_MESSAGE] [--will-qos WILL_QOS] [--will-retain] ]
|
||||||
|
[--extra-headers HEADER]
|
||||||
|
```
|
||||||
|
|
||||||
Note that for simplicity, ``amqtt_sub`` uses mostly the same argument syntax as `mosquitto_sub`_.
|
Note that for simplicity, `amqtt_sub` uses mostly the same argument syntax as [mosquitto_sub](http://mosquitto.org/man/mosquitto_sub-1.html).
|
||||||
|
|
||||||
Options
|
## Options
|
||||||
-------
|
|
||||||
|
|
||||||
--version amqtt version information
|
- `--version` - amqtt version information
|
||||||
-h, --help Display ``amqtt_sub`` usage help
|
- `-h, --help` - Display `amqtt_sub` usage help
|
||||||
-c Set the YAML configuration file to read and pass to the client runtime.
|
- `-c` - Set the YAML configuration file to read and pass to the client runtime.
|
||||||
-d Enable debugging information.
|
- `-d` - Enable debugging information.
|
||||||
--ca-file Define the path to a file containing PEM encoded CA certificates that are trusted. Used to enable SSL communication.
|
- `--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-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.
|
- `--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.
|
- `--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 ``amqtt_sub/`` appended with the process id and the hostname of the client.
|
- `-i` - The id to use for this client. If not given, defaults to `amqtt_sub/` appended with the process id and the hostname of the client.
|
||||||
-k Set the CONNECT keep alive timeout.
|
- `-k` - Set the CONNECT keep alive timeout.
|
||||||
-n Number of messages to read before ending. Read forever if not given.
|
- `-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.
|
- `-q, --qos` - Specify the quality of service to use for receiving messages. This QoS is sent in the subscribe request.
|
||||||
-t Topic filters to subscribe.
|
- `-t` - Topic filters to subscribe.
|
||||||
--url Broker connection URL, conforming to `MQTT URL scheme`_.
|
- `--url` - Broker connection URL, conforming to [MQTT URL scheme](https://github.com/mqtt/mqtt.github.io/wiki/URI-Scheme).
|
||||||
--will-topic The topic on which to send a Will, in the event that the client disconnects unexpectedly.
|
- `--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-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-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``.
|
- `--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
|
- `--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
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
.. _MQTT URL scheme: https://github.com/mqtt/mqtt.github.io/wiki/URI-Scheme
|
If `-c` argument is given, `amqtt_sub` will read specific MQTT settings for the given configuration file. This file must be a valid [YAML](http://yaml.org/) file which may contain 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 connection with the broker is interrupted. Defaults to `false`.
|
||||||
|
* `reconnect_retries`: Maximum reconnection retries. Defaults to `2`. Negative value will cause client to reconnect infinitely.
|
||||||
|
* `reconnect_max_interval`: Maximum interval between 2 connection retry. Defaults to `10`.
|
||||||
|
|
||||||
Configuration
|
## Examples
|
||||||
-------------
|
|
||||||
|
|
||||||
If ``-c`` argument is given, ``amqtt_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``. Negative value will cause client to reconnect infinietly.
|
|
||||||
* ``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.
|
|
||||||
|
|
||||||
|
Examples below are adapted from [mosquitto_sub](http://mosquitto.org/man/mosquitto_sub-1.html) documentation.
|
||||||
|
|
||||||
Subscribe with QoS 0 to all messages published under $SYS/:
|
Subscribe with QoS 0 to all messages published under $SYS/:
|
||||||
::
|
```bash
|
||||||
|
amqtt_sub --url mqtt://localhost -t '$SYS/#' -q 0
|
||||||
amqtt_sub --url mqtt://localhost -t '$SYS/#' -q 0
|
```
|
||||||
|
|
||||||
|
|
||||||
Subscribe to 10 messages with QoS 2 from /#:
|
Subscribe to 10 messages with QoS 2 from /#:
|
||||||
::
|
```bash
|
||||||
|
amqtt_sub --url mqtt://localhost -t # -q 2 -n 10
|
||||||
|
```
|
||||||
|
|
||||||
amqtt_sub --url mqtt://localhost -t # -q 2 -n 10
|
Subscribe with QoS 0 to all messages published under $SYS/ over mqtt encapsulated in a websocket connection and additional headers:
|
||||||
|
```bash
|
||||||
.. _mosquitto_sub : http://mosquitto.org/man/mosquitto_sub-1.html
|
amqtt_sub --url wss://localhost -t '$SYS/#' -q 0 --extra-headers '{"Authorization": "Bearer <token>"}'
|
||||||
|
```
|
||||||
Subscribe with QoS 0 to all messages published under $SYS/: over mqtt encapsulated in a websocket connection and additional headers:
|
|
||||||
::
|
|
||||||
|
|
||||||
amqtt_sub --url wss://localhost -t '$SYS/#' -q 0 --extra-headers '{"Authorization": "Bearer <token>"}'
|
|
||||||
|
|
|
||||||
|
|
@ -1,113 +1,104 @@
|
||||||
Broker API reference
|
# Broker API reference
|
||||||
====================
|
|
||||||
|
|
||||||
The :class:`~amqtt.broker.Broker` class provides a complete MQTT 3.1.1 broker implementation. This class allows Python developers to embed a MQTT broker in their own applications.
|
The `amqtt.broker.Broker` class provides a complete MQTT 3.1.1 broker implementation. This class allows Python developers to embed a MQTT broker in their own applications.
|
||||||
|
|
||||||
Usage example
|
## Usage example
|
||||||
-------------
|
|
||||||
|
|
||||||
The following example shows how to start a broker using the default configuration:
|
The following example shows how to start a broker using the default configuration:
|
||||||
|
|
||||||
.. code-block:: python
|
```python
|
||||||
|
import logging
|
||||||
import logging
|
import asyncio
|
||||||
import asyncio
|
import os
|
||||||
import os
|
from amqtt.broker import Broker
|
||||||
from amqtt.broker import Broker
|
|
||||||
|
|
||||||
|
|
||||||
async def broker_coro():
|
async def broker_coro():
|
||||||
broker = Broker()
|
broker = Broker()
|
||||||
await broker.start()
|
await broker.start()
|
||||||
|
|
||||||
|
|
||||||
if __name__ == '__main__':
|
if __name__ == '__main__':
|
||||||
formatter = "[%(asctime)s] :: %(levelname)s :: %(name)s :: %(message)s"
|
formatter = "[%(asctime)s] :: %(levelname)s :: %(name)s :: %(message)s"
|
||||||
logging.basicConfig(level=logging.INFO, format=formatter)
|
logging.basicConfig(level=logging.INFO, format=formatter)
|
||||||
asyncio.get_event_loop().run_until_complete(broker_coro())
|
asyncio.get_event_loop().run_until_complete(broker_coro())
|
||||||
asyncio.get_event_loop().run_forever()
|
asyncio.get_event_loop().run_forever()
|
||||||
|
```
|
||||||
|
|
||||||
When executed, this script gets the default event loop and asks it to run the ``broker_coro`` until it completes.
|
When executed, this script gets the default event loop and asks it to run the `broker_coro` until it completes.
|
||||||
``broker_coro`` creates :class:`~amqtt.broker.Broker` instance and then :meth:`~amqtt.broker.Broker.start` the broker for serving.
|
`broker_coro` creates `amqtt.broker.Broker` instance and then starts the broker for serving using the `start()` method.
|
||||||
Once completed, the loop is ran forever, making this script never stop ...
|
Once completed, the loop is ran forever, making this script never stop...
|
||||||
|
|
||||||
Reference
|
## Reference
|
||||||
---------
|
|
||||||
|
|
||||||
Broker API
|
### Broker API
|
||||||
..........
|
|
||||||
|
|
||||||
.. automodule:: amqtt.broker
|
The `amqtt.broker` module provides the following key methods in the `Broker` class:
|
||||||
|
|
||||||
.. autoclass:: Broker
|
- `start()`: Starts the broker and begins serving
|
||||||
|
- `shutdown()`: Gracefully shuts down the broker
|
||||||
|
|
||||||
.. automethod:: start
|
### Broker configuration
|
||||||
.. automethod:: shutdown
|
|
||||||
|
|
||||||
Broker configuration
|
The `Broker` class's `__init__` method accepts a `config` parameter which allows setup of behavior and default settings. This argument must be a Python dict object. For convenience, it is presented below as a YAML file[^1]:
|
||||||
....................
|
|
||||||
|
|
||||||
The :class:`~amqtt.broker.Broker` ``__init__`` method accepts a ``config`` parameter which allow to setup some behaviour and defaults settings. This argument must be a Python dict object. For convenience, it is presented below as a YAML file [1]_.
|
```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:1884
|
||||||
|
max-connections: 1000
|
||||||
|
my-tcp-ssl-1:
|
||||||
|
bind: 127.0.0.1:8885
|
||||||
|
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'] #List of plugins to activate for authentication among all registered plugins
|
||||||
|
allow-anonymous: true / false
|
||||||
|
password-file: /some/passwd_file
|
||||||
|
topic-check:
|
||||||
|
enabled: true / false # Set to False if topic filtering is not needed
|
||||||
|
plugins: ['topic_acl'] #List of plugins to activate for topic filtering among all registered plugins
|
||||||
|
acl:
|
||||||
|
# username: [list of allowed topics]
|
||||||
|
username1: ['repositories/+/master', 'calendar/#', 'data/memes'] # List of topics on which client1 can publish and subscribe
|
||||||
|
username2: ...
|
||||||
|
anonymous: [] # List of topics on which an anonymous client can publish and subscribe
|
||||||
|
```
|
||||||
|
|
||||||
.. code-block:: python
|
The `listeners` section allows defining network listeners which must be started by the `Broker`. Several listeners can be setup. `default` subsection defines common attributes for all listeners. Each listener can have the following settings:
|
||||||
|
|
||||||
listeners:
|
* `bind`: IP address and port binding.
|
||||||
default:
|
* `max-connections`: Set maximum number of active connection for the listener. `0` means no limit.
|
||||||
max-connections: 50000
|
* `type`: transport protocol type; can be `tcp` for classic TCP listener or `ws` for MQTT over websocket.
|
||||||
type: tcp
|
* `ssl`: enables (`on`) or disable secured connection over the transport protocol.
|
||||||
my-tcp-1:
|
* `cafile`, `cadata`, `certfile` and `keyfile`: mandatory parameters for SSL secured connections.
|
||||||
bind: 127.0.0.1:1883
|
|
||||||
my-tcp-2:
|
|
||||||
bind: 1.2.3.4:1884
|
|
||||||
max-connections: 1000
|
|
||||||
my-tcp-ssl-1:
|
|
||||||
bind: 127.0.0.1:8885
|
|
||||||
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'] #List of plugins to activate for authentication among all registered plugins
|
|
||||||
allow-anonymous: true / false
|
|
||||||
password-file: /some/passwd_file
|
|
||||||
topic-check:
|
|
||||||
enabled: true / false # Set to False if topic filtering is not needed
|
|
||||||
plugins: ['topic_acl'] #List of plugins to activate for topic filtering among all registered plugins
|
|
||||||
acl:
|
|
||||||
# username: [list of allowed topics]
|
|
||||||
username1: ['repositories/+/master', 'calendar/#', 'data/memes'] # List of topics on which client1 can publish and subscribe
|
|
||||||
username2: ...
|
|
||||||
anonymous: [] # List of topics on which an anonymous client can publish and subscribe
|
|
||||||
|
|
||||||
|
The `auth` section setup authentication behaviour:
|
||||||
|
|
||||||
The ``listeners`` section allows to define network listeners which must be started by the :class:`~amqtt.broker.Broker`. Several listeners can be setup. ``default`` subsection defines common attributes for all listeners. Each listener can have the following settings:
|
* `plugins`: defines the list of activated plugins. Note the plugins must be defined in the `amqtt.broker.plugins` [entry point](https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins).
|
||||||
|
* `allow-anonymous`: used by the internal `amqtt.plugins.authentication.AnonymousAuthPlugin` plugin. This parameter enables (`on`) or disable anonymous connection, i.e. connection without username.
|
||||||
|
* `password-file`: used by the internal `amqtt.plugins.authentication.FileAuthPlugin` plugin. This parameter gives to path of the password file to load for authenticating users.
|
||||||
|
|
||||||
* ``bind``: IP address and port binding.
|
The `topic-check` section setup access control policies for publishing and subscribing to topics:
|
||||||
* ``max-connections``: Set maximum number of active connection for the listener. ``0`` means no limit.
|
|
||||||
* ``type``: transport protocol type; can be ``tcp`` for classic TCP listener or ``ws`` for MQTT over websocket.
|
|
||||||
* ``ssl`` enables (``on``) or disable secured connection over the transport protocol.
|
|
||||||
* ``cafile``, ``cadata``, ``certfile`` and ``keyfile`` : mandatory parameters for SSL secured connections.
|
|
||||||
|
|
||||||
The ``auth`` section setup authentication behaviour:
|
* `enabled`: set to true if you want to impose an access control policy. Otherwise, set it to false.
|
||||||
|
* `plugins`: defines the list of activated plugins. Note the plugins must be defined in the `amqtt.broker.plugins` [entry point](https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins).
|
||||||
* ``plugins``: defines the list of activated plugins. Note the plugins must be defined in the ``amqtt.broker.plugins`` `entry point <https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins>`_.
|
|
||||||
* ``allow-anonymous`` : used by the internal :class:`amqtt.plugins.authentication.AnonymousAuthPlugin` plugin. This parameter enables (``on``) or disable anonymous connection, ie. connection without username.
|
|
||||||
* ``password-file`` : used by the internal :class:`amqtt.plugins.authentication.FileAuthPlugin` plugin. This parameter gives to path of the password file to load for authenticating users.
|
|
||||||
|
|
||||||
The ``topic-check`` section setup access control policies for publishing and subscribing to topics:
|
|
||||||
|
|
||||||
* ``enabled``: set to true if you want to impose an access control policy. Otherwise, set it to false.
|
|
||||||
* ``plugins``: defines the list of activated plugins. Note the plugins must be defined in the ``amqtt.broker.plugins`` `entry point <https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins>`_.
|
|
||||||
* additional parameters: depending on the plugin used for access control, additional parameters should be added.
|
* additional parameters: depending on the plugin used for access control, additional parameters should be added.
|
||||||
* In case of ``topic_acl`` plugin, the Access Control List (ACL) must be defined in the parameter ``acl``.
|
* In case of `topic_acl` plugin, the Access Control List (ACL) must be defined in the parameter `acl`.
|
||||||
* For each username, a list with the allowed topics must be defined.
|
* For each username, a list with the allowed topics must be defined.
|
||||||
* If the client logs in anonymously, the ``anonymous`` entry within the ACL is used in order to grant/deny subscriptions.
|
* If the client logs in anonymously, the `anonymous` entry within the ACL is used in order to grant/deny subscriptions.
|
||||||
|
|
||||||
|
[^1]: See [PyYAML](http://pyyaml.org/wiki/PyYAMLDocumentation) for loading YAML files as Python dict.
|
||||||
.. [1] See `PyYAML <http://pyyaml.org/wiki/PyYAMLDocumentation>`_ for loading YAML files as Python dict.
|
|
||||||
|
|
|
||||||
|
|
@ -1,21 +1,21 @@
|
||||||
Common API
|
# Common API
|
||||||
==========
|
|
||||||
|
|
||||||
This document describes ``aMQTT`` common API both used by :doc:`mqttclient` and :doc:`broker`.
|
This document describes `aMQTT` common API both used by [MQTT Client](mqttclient.md) and [Broker](broker.md).
|
||||||
|
|
||||||
Reference
|
## Reference
|
||||||
---------
|
|
||||||
|
|
||||||
ApplicationMessage
|
### ApplicationMessage
|
||||||
..................
|
|
||||||
|
|
||||||
.. automodule:: amqtt.session
|
The `amqtt.session` module provides the following message classes:
|
||||||
|
|
||||||
.. autoclass:: ApplicationMessage
|
#### ApplicationMessage
|
||||||
:members:
|
|
||||||
|
|
||||||
.. autoclass:: IncomingApplicationMessage
|
Base class for MQTT application messages.
|
||||||
:show-inheritance:
|
|
||||||
|
|
||||||
.. autoclass:: OutgoingApplicationMessage
|
#### IncomingApplicationMessage
|
||||||
:show-inheritance:
|
|
||||||
|
Inherits from ApplicationMessage. Represents messages received from MQTT clients.
|
||||||
|
|
||||||
|
#### OutgoingApplicationMessage
|
||||||
|
|
||||||
|
Inherits from ApplicationMessage. Represents messages to be sent to MQTT clients.
|
||||||
|
|
|
||||||
|
|
@ -1,30 +1,15 @@
|
||||||
References
|
# References
|
||||||
==========
|
|
||||||
|
|
||||||
Reference documentation for aMQTT console scripts and programming API.
|
Reference documentation for aMQTT console scripts and programming API.
|
||||||
|
|
||||||
Console scripts
|
## Console scripts
|
||||||
---------------
|
|
||||||
|
|
||||||
* :doc:`amqtt_pub` : MQTT client for publishing messages to a broker
|
* [amqtt_pub](amqtt_pub.md): MQTT client for publishing messages to a broker
|
||||||
* :doc:`amqtt_sub` : MQTT client for subscribing to a topics and retrieved published messages
|
* [amqtt_sub](amqtt_sub.md): MQTT client for subscribing to topics and retrieved published messages
|
||||||
* :doc:`amqtt` : Autonomous MQTT broker
|
* [amqtt](amqtt.md): Autonomous MQTT broker
|
||||||
|
|
||||||
Programming API
|
## Programming API
|
||||||
---------------
|
|
||||||
|
|
||||||
* :doc:`mqttclient` : MQTT client API reference
|
* [mqttclient](mqttclient.md): MQTT client API reference
|
||||||
* :doc:`broker` : MQTT broker API reference
|
* [broker](broker.md): MQTT broker API reference
|
||||||
* :doc:`common` : Common API
|
* [common](common.md): Common API
|
||||||
|
|
||||||
TBD
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:hidden:
|
|
||||||
|
|
||||||
amqtt_pub
|
|
||||||
amqtt_sub
|
|
||||||
amqtt
|
|
||||||
mqttclient
|
|
||||||
broker
|
|
||||||
common
|
|
||||||
|
|
|
||||||
|
|
@ -1,190 +1,180 @@
|
||||||
MQTTClient API
|
# MQTTClient API
|
||||||
==============
|
|
||||||
|
|
||||||
The :class:`~amqtt.client.MQTTClient` class implements the client part of MQTT protocol. It can be used to publish and/or subscribe MQTT message on a broker accessible on the network through TCP or websocket protocol, both secured or unsecured.
|
The `amqtt.client.MQTTClient` class implements the client part of MQTT protocol. It can be used to publish and/or subscribe MQTT message on a broker accessible on the network through TCP or websocket protocol, both secured or unsecured.
|
||||||
|
|
||||||
|
## Usage examples
|
||||||
|
|
||||||
Usage examples
|
### Subscriber
|
||||||
--------------
|
|
||||||
|
|
||||||
Subscriber
|
The example below shows how to write a simple MQTT client which subscribes a topic and prints every messages received from the broker:
|
||||||
..........
|
|
||||||
|
|
||||||
The example below shows how to write a simple MQTT client which subscribes a topic and prints every messages received from the broker :
|
```python
|
||||||
|
import logging
|
||||||
|
import asyncio
|
||||||
|
|
||||||
.. code-block:: python
|
from amqtt.client import MQTTClient, ClientException
|
||||||
|
from amqtt.mqtt.constants import QOS_1, QOS_2
|
||||||
|
|
||||||
import logging
|
logger = logging.getLogger(__name__)
|
||||||
import asyncio
|
|
||||||
|
|
||||||
from amqtt.client import MQTTClient, ClientException
|
async def uptime_coro():
|
||||||
from amqtt.mqtt.constants import QOS_1, QOS_2
|
C = MQTTClient()
|
||||||
|
await C.connect('mqtt://test.mosquitto.org/')
|
||||||
|
# Subscribe to '$SYS/broker/uptime' with QOS=1
|
||||||
|
# Subscribe to '$SYS/broker/load/#' with QOS=2
|
||||||
|
await C.subscribe([
|
||||||
|
('$SYS/broker/uptime', QOS_1),
|
||||||
|
('$SYS/broker/load/#', QOS_2),
|
||||||
|
])
|
||||||
|
try:
|
||||||
|
for i in range(1, 100):
|
||||||
|
message = await C.deliver_message()
|
||||||
|
packet = message.publish_packet
|
||||||
|
print("%d: %s => %s" % (i, packet.variable_header.topic_name, str(packet.payload.data)))
|
||||||
|
await C.unsubscribe(['$SYS/broker/uptime', '$SYS/broker/load/#'])
|
||||||
|
await C.disconnect()
|
||||||
|
except ClientException as ce:
|
||||||
|
logger.error("Client exception: %s" % ce)
|
||||||
|
|
||||||
logger = logging.getLogger(__name__)
|
if __name__ == '__main__':
|
||||||
|
formatter = "[%(asctime)s] %(name)s {%(filename)s:%(lineno)d} %(levelname)s - %(message)s"
|
||||||
|
logging.basicConfig(level=logging.DEBUG, format=formatter)
|
||||||
|
asyncio.get_event_loop().run_until_complete(uptime_coro())
|
||||||
|
```
|
||||||
|
|
||||||
async def uptime_coro():
|
When executed, this script gets the default event loop and asks it to run the `uptime_coro` until it completes.
|
||||||
C = MQTTClient()
|
`uptime_coro` starts by initializing a `MQTTClient` instance.
|
||||||
await C.connect('mqtt://test.mosquitto.org/')
|
The coroutine then calls `connect()` to connect to the broker, here `test.mosquitto.org`.
|
||||||
# Subscribe to '$SYS/broker/uptime' with QOS=1
|
|
||||||
# Subscribe to '$SYS/broker/load/#' with QOS=2
|
|
||||||
await C.subscribe([
|
|
||||||
('$SYS/broker/uptime', QOS_1),
|
|
||||||
('$SYS/broker/load/#', QOS_2),
|
|
||||||
])
|
|
||||||
try:
|
|
||||||
for i in range(1, 100):
|
|
||||||
message = await C.deliver_message()
|
|
||||||
packet = message.publish_packet
|
|
||||||
print("%d: %s => %s" % (i, packet.variable_header.topic_name, str(packet.payload.data)))
|
|
||||||
await C.unsubscribe(['$SYS/broker/uptime', '$SYS/broker/load/#'])
|
|
||||||
await C.disconnect()
|
|
||||||
except ClientException as ce:
|
|
||||||
logger.error("Client exception: %s" % ce)
|
|
||||||
|
|
||||||
if __name__ == '__main__':
|
|
||||||
formatter = "[%(asctime)s] %(name)s {%(filename)s:%(lineno)d} %(levelname)s - %(message)s"
|
|
||||||
logging.basicConfig(level=logging.DEBUG, format=formatter)
|
|
||||||
asyncio.get_event_loop().run_until_complete(uptime_coro())
|
|
||||||
|
|
||||||
When executed, this script gets the default event loop and asks it to run the ``uptime_coro`` until it completes.
|
|
||||||
``uptime_coro`` starts by initializing a :class:`~amqtt.client.MQTTClient` instance.
|
|
||||||
The coroutine then call :meth:`~amqtt.client.MQTTClient.connect` to connect to the broker, here ``test.mosquitto.org``.
|
|
||||||
Once connected, the coroutine subscribes to some topics, and then wait for 100 messages. Each message received is simply written to output.
|
Once connected, the coroutine subscribes to some topics, and then wait for 100 messages. Each message received is simply written to output.
|
||||||
Finally, the coroutine unsubscribes from topics and disconnects from the broker.
|
Finally, the coroutine unsubscribes from topics and disconnects from the broker.
|
||||||
|
|
||||||
Publisher
|
### Publisher
|
||||||
.........
|
|
||||||
|
|
||||||
The example below uses the :class:`~amqtt.client.MQTTClient` class to implement a publisher.
|
The example below uses the `MQTTClient` class to implement a publisher.
|
||||||
This test publish 3 messages asynchronously to the broker on a test topic.
|
This test publish 3 messages asynchronously to the broker on a test topic.
|
||||||
For the purposes of the test, each message is published with a different Quality Of Service.
|
For the purposes of the test, each message is published with a different Quality Of Service.
|
||||||
This example also shows to method for publishing message asynchronously.
|
This example also shows two methods for publishing messages asynchronously.
|
||||||
|
|
||||||
.. code-block:: python
|
```python
|
||||||
|
import logging
|
||||||
|
import asyncio
|
||||||
|
|
||||||
import logging
|
from amqtt.client import MQTTClient
|
||||||
import asyncio
|
from amqtt.mqtt.constants import QOS_0, QOS_1, QOS_2
|
||||||
|
|
||||||
from amqtt.client import MQTTClient
|
logger = logging.getLogger(__name__)
|
||||||
from amqtt.mqtt.constants import QOS_0, QOS_1, QOS_2
|
|
||||||
|
|
||||||
logger = logging.getLogger(__name__)
|
async def test_coro():
|
||||||
|
C = MQTTClient()
|
||||||
|
await C.connect('mqtt://test.mosquitto.org/')
|
||||||
|
tasks = [
|
||||||
|
asyncio.ensure_future(C.publish('a/b', b'TEST MESSAGE WITH QOS_0')),
|
||||||
|
asyncio.ensure_future(C.publish('a/b', b'TEST MESSAGE WITH QOS_1', qos=QOS_1)),
|
||||||
|
asyncio.ensure_future(C.publish('a/b', b'TEST MESSAGE WITH QOS_2', qos=QOS_2)),
|
||||||
|
]
|
||||||
|
await asyncio.wait(tasks)
|
||||||
|
logger.info("messages published")
|
||||||
|
await C.disconnect()
|
||||||
|
|
||||||
async def test_coro():
|
|
||||||
|
async def test_coro2():
|
||||||
|
try:
|
||||||
C = MQTTClient()
|
C = MQTTClient()
|
||||||
await C.connect('mqtt://test.mosquitto.org/')
|
ret = await C.connect('mqtt://test.mosquitto.org:1883/')
|
||||||
tasks = [
|
message = await C.publish('a/b', b'TEST MESSAGE WITH QOS_0', qos=QOS_0)
|
||||||
asyncio.ensure_future(C.publish('a/b', b'TEST MESSAGE WITH QOS_0')),
|
message = await C.publish('a/b', b'TEST MESSAGE WITH QOS_1', qos=QOS_1)
|
||||||
asyncio.ensure_future(C.publish('a/b', b'TEST MESSAGE WITH QOS_1', qos=QOS_1)),
|
message = await C.publish('a/b', b'TEST MESSAGE WITH QOS_2', qos=QOS_2)
|
||||||
asyncio.ensure_future(C.publish('a/b', b'TEST MESSAGE WITH QOS_2', qos=QOS_2)),
|
#print(message)
|
||||||
]
|
|
||||||
await asyncio.wait(tasks)
|
|
||||||
logger.info("messages published")
|
logger.info("messages published")
|
||||||
await C.disconnect()
|
await C.disconnect()
|
||||||
|
except ConnectException as ce:
|
||||||
|
logger.error("Connection failed: %s" % ce)
|
||||||
|
asyncio.get_event_loop().stop()
|
||||||
|
|
||||||
|
|
||||||
async def test_coro2():
|
if __name__ == '__main__':
|
||||||
try:
|
formatter = "[%(asctime)s] %(name)s {%(filename)s:%(lineno)d} %(levelname)s - %(message)s"
|
||||||
C = MQTTClient()
|
logging.basicConfig(level=logging.DEBUG, format=formatter)
|
||||||
ret = await C.connect('mqtt://test.mosquitto.org:1883/')
|
asyncio.get_event_loop().run_until_complete(test_coro())
|
||||||
message = await C.publish('a/b', b'TEST MESSAGE WITH QOS_0', qos=QOS_0)
|
asyncio.get_event_loop().run_until_complete(test_coro2())
|
||||||
message = await C.publish('a/b', b'TEST MESSAGE WITH QOS_1', qos=QOS_1)
|
```
|
||||||
message = await C.publish('a/b', b'TEST MESSAGE WITH QOS_2', qos=QOS_2)
|
|
||||||
#print(message)
|
|
||||||
logger.info("messages published")
|
|
||||||
await C.disconnect()
|
|
||||||
except ConnectException as ce:
|
|
||||||
logger.error("Connection failed: %s" % ce)
|
|
||||||
asyncio.get_event_loop().stop()
|
|
||||||
|
|
||||||
|
As usual, the script runs the publish code through the async loop. `test_coro()` and `test_coro2()` are ran in sequence.
|
||||||
|
Both do the same job. `test_coro()` publishes 3 messages in sequence. `test_coro2()` publishes the same message asynchronously.
|
||||||
|
The difference appears when looking at the sequence of MQTT messages sent.
|
||||||
|
|
||||||
if __name__ == '__main__':
|
`test_coro()` achieves:
|
||||||
formatter = "[%(asctime)s] %(name)s {%(filename)s:%(lineno)d} %(levelname)s - %(message)s"
|
```
|
||||||
logging.basicConfig(level=logging.DEBUG, format=formatter)
|
amqtt/YDYY;NNRpYQSy3?o -out-> PublishPacket(ts=2015-11-11 21:54:48.843901, fixed=MQTTFixedHeader(length=28, flags=0x0), variable=PublishVariableHeader(topic=a/b, packet_id=None), payload=PublishPayload(data="b'TEST MESSAGE WITH QOS_0'"))
|
||||||
asyncio.get_event_loop().run_until_complete(test_coro())
|
amqtt/YDYY;NNRpYQSy3?o -out-> PublishPacket(ts=2015-11-11 21:54:48.844152, fixed=MQTTFixedHeader(length=30, flags=0x2), variable=PublishVariableHeader(topic=a/b, packet_id=1), payload=PublishPayload(data="b'TEST MESSAGE WITH QOS_1'"))
|
||||||
asyncio.get_event_loop().run_until_complete(test_coro2())
|
amqtt/YDYY;NNRpYQSy3?o <-in-- PubackPacket(ts=2015-11-11 21:54:48.979665, fixed=MQTTFixedHeader(length=2, flags=0x0), variable=PacketIdVariableHeader(packet_id=1), payload=None)
|
||||||
|
amqtt/YDYY;NNRpYQSy3?o -out-> PublishPacket(ts=2015-11-11 21:54:48.980886, fixed=MQTTFixedHeader(length=30, flags=0x4), variable=PublishVariableHeader(topic=a/b, packet_id=2), payload=PublishPayload(data="b'TEST MESSAGE WITH QOS_2'"))
|
||||||
|
amqtt/YDYY;NNRpYQSy3?o <-in-- PubrecPacket(ts=2015-11-11 21:54:49.029691, fixed=MQTTFixedHeader(length=2, flags=0x0), variable=PacketIdVariableHeader(packet_id=2), payload=None)
|
||||||
|
amqtt/YDYY;NNRpYQSy3?o -out-> PubrelPacket(ts=2015-11-11 21:54:49.030823, fixed=MQTTFixedHeader(length=2, flags=0x2), variable=PacketIdVariableHeader(packet_id=2), payload=None)
|
||||||
|
amqtt/YDYY;NNRpYQSy3?o <-in-- PubcompPacket(ts=2015-11-11 21:54:49.092514, fixed=MQTTFixedHeader(length=2, flags=0x0), variable=PacketIdVariableHeader(packet_id=2), payload=None)
|
||||||
|
```
|
||||||
|
|
||||||
As usual, the script runs the publish code through the async loop. ``test_coro()`` and ``test_coro()`` are ran in sequence.
|
while `test_coro2()` runs:
|
||||||
Both do the same job. ``test_coro()`` publish 3 messages in sequence. ``test_coro2()`` publishes the same message asynchronously.
|
```
|
||||||
The difference appears the looking at the sequence of MQTT messages sent.
|
amqtt/LYRf52W[56SOjW04 -out-> PublishPacket(ts=2015-11-11 21:54:48.466123, fixed=MQTTFixedHeader(length=28, flags=0x0), variable=PublishVariableHeader(topic=a/b, packet_id=None), payload=PublishPayload(data="b'TEST MESSAGE WITH QOS_0'"))
|
||||||
|
amqtt/LYRf52W[56SOjW04 -out-> PublishPacket(ts=2015-11-11 21:54:48.466432, fixed=MQTTFixedHeader(length=30, flags=0x2), variable=PublishVariableHeader(topic=a/b, packet_id=1), payload=PublishPayload(data="b'TEST MESSAGE WITH QOS_1'"))
|
||||||
|
amqtt/LYRf52W[56SOjW04 -out-> PublishPacket(ts=2015-11-11 21:54:48.466695, fixed=MQTTFixedHeader(length=30, flags=0x4), variable=PublishVariableHeader(topic=a/b, packet_id=2), payload=PublishPayload(data="b'TEST MESSAGE WITH QOS_2'"))
|
||||||
|
amqtt/LYRf52W[56SOjW04 <-in-- PubackPacket(ts=2015-11-11 21:54:48.613062, fixed=MQTTFixedHeader(length=2, flags=0x0), variable=PacketIdVariableHeader(packet_id=1), payload=None)
|
||||||
|
amqtt/LYRf52W[56SOjW04 <-in-- PubrecPacket(ts=2015-11-11 21:54:48.661073, fixed=MQTTFixedHeader(length=2, flags=0x0), variable=PacketIdVariableHeader(packet_id=2), payload=None)
|
||||||
|
amqtt/LYRf52W[56SOjW04 -out-> PubrelPacket(ts=2015-11-11 21:54:48.661925, fixed=MQTTFixedHeader(length=2, flags=0x2), variable=PacketIdVariableHeader(packet_id=2), payload=None)
|
||||||
|
amqtt/LYRf52W[56SOjW04 <-in-- PubcompPacket(ts=2015-11-11 21:54:48.713107, fixed=MQTTFixedHeader(length=2, flags=0x0), variable=PacketIdVariableHeader(packet_id=2), payload=None)
|
||||||
|
```
|
||||||
|
|
||||||
``test_coro()`` achieves:
|
Both coroutines have the same results except that `test_coro2()` manages messages flow in parallel which may be more efficient.
|
||||||
::
|
|
||||||
|
|
||||||
amqtt/YDYY;NNRpYQSy3?o -out-> PublishPacket(ts=2015-11-11 21:54:48.843901, fixed=MQTTFixedHeader(length=28, flags=0x0), variable=PublishVariableHeader(topic=a/b, packet_id=None), payload=PublishPayload(data="b'TEST MESSAGE WITH QOS_0'"))
|
## Reference
|
||||||
amqtt/YDYY;NNRpYQSy3?o -out-> PublishPacket(ts=2015-11-11 21:54:48.844152, fixed=MQTTFixedHeader(length=30, flags=0x2), variable=PublishVariableHeader(topic=a/b, packet_id=1), payload=PublishPayload(data="b'TEST MESSAGE WITH QOS_1'"))
|
|
||||||
amqtt/YDYY;NNRpYQSy3?o <-in-- PubackPacket(ts=2015-11-11 21:54:48.979665, fixed=MQTTFixedHeader(length=2, flags=0x0), variable=PacketIdVariableHeader(packet_id=1), payload=None)
|
|
||||||
amqtt/YDYY;NNRpYQSy3?o -out-> PublishPacket(ts=2015-11-11 21:54:48.980886, fixed=MQTTFixedHeader(length=30, flags=0x4), variable=PublishVariableHeader(topic=a/b, packet_id=2), payload=PublishPayload(data="b'TEST MESSAGE WITH QOS_2'"))
|
|
||||||
amqtt/YDYY;NNRpYQSy3?o <-in-- PubrecPacket(ts=2015-11-11 21:54:49.029691, fixed=MQTTFixedHeader(length=2, flags=0x0), variable=PacketIdVariableHeader(packet_id=2), payload=None)
|
|
||||||
amqtt/YDYY;NNRpYQSy3?o -out-> PubrelPacket(ts=2015-11-11 21:54:49.030823, fixed=MQTTFixedHeader(length=2, flags=0x2), variable=PacketIdVariableHeader(packet_id=2), payload=None)
|
|
||||||
amqtt/YDYY;NNRpYQSy3?o <-in-- PubcompPacket(ts=2015-11-11 21:54:49.092514, fixed=MQTTFixedHeader(length=2, flags=0x0), variable=PacketIdVariableHeader(packet_id=2), payload=None)fixed=MQTTFixedHeader(length=2, flags=0x0), variable=PacketIdVariableHeader(packet_id=2), payload=None)
|
|
||||||
|
|
||||||
while ``test_coro2()`` runs:
|
### MQTTClient API
|
||||||
::
|
|
||||||
|
|
||||||
amqtt/LYRf52W[56SOjW04 -out-> PublishPacket(ts=2015-11-11 21:54:48.466123, fixed=MQTTFixedHeader(length=28, flags=0x0), variable=PublishVariableHeader(topic=a/b, packet_id=None), payload=PublishPayload(data="b'TEST MESSAGE WITH QOS_0'"))
|
The `amqtt.client` module provides the following methods in the `MQTTClient` class:
|
||||||
amqtt/LYRf52W[56SOjW04 -out-> PublishPacket(ts=2015-11-11 21:54:48.466432, fixed=MQTTFixedHeader(length=30, flags=0x2), variable=PublishVariableHeader(topic=a/b, packet_id=1), payload=PublishPayload(data="b'TEST MESSAGE WITH QOS_1'"))
|
|
||||||
amqtt/LYRf52W[56SOjW04 -out-> PublishPacket(ts=2015-11-11 21:54:48.466695, fixed=MQTTFixedHeader(length=30, flags=0x4), variable=PublishVariableHeader(topic=a/b, packet_id=2), payload=PublishPayload(data="b'TEST MESSAGE WITH QOS_2'"))
|
|
||||||
amqtt/LYRf52W[56SOjW04 <-in-- PubackPacket(ts=2015-11-11 21:54:48.613062, fixed=MQTTFixedHeader(length=2, flags=0x0), variable=PacketIdVariableHeader(packet_id=1), payload=None)
|
|
||||||
amqtt/LYRf52W[56SOjW04 <-in-- PubrecPacket(ts=2015-11-11 21:54:48.661073, fixed=MQTTFixedHeader(length=2, flags=0x0), variable=PacketIdVariableHeader(packet_id=2), payload=None)
|
|
||||||
amqtt/LYRf52W[56SOjW04 -out-> PubrelPacket(ts=2015-11-11 21:54:48.661925, fixed=MQTTFixedHeader(length=2, flags=0x2), variable=PacketIdVariableHeader(packet_id=2), payload=None)
|
|
||||||
amqtt/LYRf52W[56SOjW04 <-in-- PubcompPacket(ts=2015-11-11 21:54:48.713107, fixed=MQTTFixedHeader(length=2, flags=0x0), variable=PacketIdVariableHeader(packet_id=2), payload=None)
|
|
||||||
|
|
||||||
Both coroutines have the same results except that ``test_coro2()`` manages messages flow in parallel which may be more efficient.
|
- `connect()`: Connect to a remote broker
|
||||||
|
- `disconnect()`: Disconnect from the broker
|
||||||
|
- `reconnect()`: Reconnect to the broker
|
||||||
|
- `ping()`: Send a PING request to the broker
|
||||||
|
- `publish()`: Publish a message to the broker
|
||||||
|
- `subscribe()`: Subscribe to one or more topics
|
||||||
|
- `unsubscribe()`: Unsubscribe from one or more topics
|
||||||
|
- `deliver_message()`: Receive the next message from the broker
|
||||||
|
|
||||||
Reference
|
### MQTTClient configuration
|
||||||
---------
|
|
||||||
|
|
||||||
MQTTClient API
|
The `MQTTClient` `__init__` method accepts a `config` parameter which allows setup of behavior and default settings. This argument must be a Python dict object which may contain the following entries:
|
||||||
..............
|
|
||||||
|
|
||||||
.. automodule:: amqtt.client
|
* `keep_alive`: keep alive (in seconds) to send when connecting to the broker (defaults to `10` seconds). `MQTTClient` will *auto-ping* the broker if no message is sent within the keep-alive interval. This avoids disconnection from the broker.
|
||||||
|
* `ping_delay`: *auto-ping* delay before keep-alive times out (defaults to `1` seconds).
|
||||||
|
* `default_qos`: Default QoS (`0`) used by `publish()` if `qos` argument is not given.
|
||||||
|
* `default_retain`: Default retain (`False`) used by `publish()` if `qos` argument is not given.
|
||||||
|
* `auto_reconnect`: enable or disable auto-reconnect feature (defaults to `True`).
|
||||||
|
* `reconnect_max_interval`: maximum interval (in seconds) to wait before two connection retries (defaults to `10`).
|
||||||
|
* `reconnect_retries`: maximum number of connect retries (defaults to `2`). Negative value will cause client to reconnect infinitely.
|
||||||
|
|
||||||
.. autoclass:: MQTTClient
|
Default QoS and default retain can also be overridden by adding a `topics` with may contain QoS and retain values for specific topics. See the following example:
|
||||||
|
|
||||||
.. automethod:: connect
|
```python
|
||||||
.. automethod:: disconnect
|
config = {
|
||||||
.. automethod:: reconnect
|
'keep_alive': 10,
|
||||||
.. automethod:: ping
|
'ping_delay': 1,
|
||||||
.. automethod:: publish
|
'default_qos': 0,
|
||||||
.. automethod:: subscribe
|
'default_retain': False,
|
||||||
.. automethod:: unsubscribe
|
'auto_reconnect': True,
|
||||||
.. automethod:: deliver_message
|
'reconnect_max_interval': 5,
|
||||||
|
'reconnect_retries': 10,
|
||||||
MQTTClient configuration
|
'topics': {
|
||||||
........................
|
'test': { 'qos': 1 },
|
||||||
|
'some_topic': { 'qos': 2, 'retain': True }
|
||||||
The :class:`~amqtt.client.MQTTClient` ``__init__`` method accepts a ``config`` parameter which allow to setup some behaviour and defaults settings. This argument must be a Python dict object which may contain the following entries:
|
|
||||||
|
|
||||||
* ``keep_alive``: keep alive (in seconds) to send when connecting to the broker (defaults to ``10`` seconds). :class:`~amqtt.client.MQTTClient` will *auto-ping* the broker if not message is sent within the keep-alive interval. This avoids disconnection from the broker.
|
|
||||||
* ``ping_delay``: *auto-ping* delay before keep-alive times out (defaults to ``1`` seconds).
|
|
||||||
* ``default_qos``: Default QoS (``0``) used by :meth:`~amqtt.client.MQTTClient.publish` if ``qos`` argument is not given.
|
|
||||||
* ``default_retain``: Default retain (``False``) used by :meth:`~amqtt.client.MQTTClient.publish` if ``qos`` argument is not given.,
|
|
||||||
* ``auto_reconnect``: enable or disable auto-reconnect feature (defaults to ``True``).
|
|
||||||
* ``reconnect_max_interval``: maximum interval (in seconds) to wait before two connection retries (defaults to ``10``).
|
|
||||||
* ``reconnect_retries``: maximum number of connect retries (defaults to ``2``). Negative value will cause client to reconnect infinietly.
|
|
||||||
|
|
||||||
Default QoS and default retain can also be overridden by adding a ``topics`` with may contain QoS and retain values for specific topics. See the following example:
|
|
||||||
|
|
||||||
.. code-block:: python
|
|
||||||
|
|
||||||
config = {
|
|
||||||
'keep_alive': 10,
|
|
||||||
'ping_delay': 1,
|
|
||||||
'default_qos': 0,
|
|
||||||
'default_retain': False,
|
|
||||||
'auto_reconnect': True,
|
|
||||||
'reconnect_max_interval': 5,
|
|
||||||
'reconnect_retries': 10,
|
|
||||||
'topics': {
|
|
||||||
'test': { 'qos': 1 },
|
|
||||||
'some_topic': { 'qos': 2, 'retain': True }
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
With this setting any message published will set with QOS_0 and retain flag unset except for :
|
With this setting any message published will be set with QOS_0 and retain flag unset except for:
|
||||||
|
|
||||||
* messages sent to ``test`` topic : they will be sent with QOS_1
|
* messages sent to `test` topic: they will be sent with QOS_1
|
||||||
* messages sent to ``some_topic`` topic : they will be sent with QOS_2 and retain flag set
|
* messages sent to `some_topic` topic: they will be sent with QOS_2 and retain flag set
|
||||||
|
|
||||||
In any case, the ``qos`` and ``retain`` argument values passed to method :meth:`~amqtt.client.MQTTClient.publish` will override these settings.
|
In any case, the `qos` and `retain` argument values passed to method `publish()` will override these settings.
|
||||||
|
|
|
||||||
|
|
@ -19,6 +19,11 @@ nav:
|
||||||
- Quickstart: quickstart.md
|
- Quickstart: quickstart.md
|
||||||
- Usage:
|
- Usage:
|
||||||
- Broker: references/amqtt.md
|
- Broker: references/amqtt.md
|
||||||
|
- Publisher: references/amqtt_pub.md
|
||||||
|
- Subscriber: references/amqtt_sub.md
|
||||||
|
- API:
|
||||||
|
- Broker: references/broker.md
|
||||||
|
- Client: references/client.md
|
||||||
# - Changelog: changelog.md
|
# - Changelog: changelog.md
|
||||||
# - Credits: credits.md
|
# - Credits: credits.md
|
||||||
# - License: license.md
|
# - License: license.md
|
||||||
|
|
|
||||||
Ładowanie…
Reference in New Issue