mirror
/
amqtt
kopia lustrzana https://github.com/Yakifo/amqtt
1
0
Forkuj 0
Kod Zgłoszenia Packages Projekty Wydania Wiki Aktywność

convert rst files to md

pull/169/head
Andrew Mirsky 2025-05-21 09:53:46 -04:00
rodzic 335e0e20d1
commit 9e13cb9da4
Nie znaleziono w bazie danych klucza dla tego podpisu
ID klucza GPG: A98E67635CDF2C39
11 zmienionych plików z 580 dodań i 769 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

110
README.md
Wyświetl plik

@ -1,105 +1,55 @@
|license| |ci| |coverage| |rtfm| |gitter| |python_versions| |python_wheel| |PyPI|
[![MIT licensed](https://img.shields.io/github/license/Yakifo/amqtt?style=flat-square)](https://amqtt.readthedocs.io/en/latest/)
[![CI](https://img.shields.io/github/workflow/status/Yakifo/amqtt/Python%20package?style=flat-square)](https://github.com/Yakifo/amqtt/actions/workflows/python-package.yml)
[![Coverage](https://img.shields.io/coveralls/github/Yakifo/amqtt?style=flat-square)](https://coveralls.io/github/Yakifo/amqtt?branch=master)
[![Documentation Status](https://img.shields.io/readthedocs/amqtt?style=flat-square)](https://amqtt.readthedocs.io/en/latest/)
[![Join the chat](https://img.shields.io/gitter/room/Yakifo/amqtt?style=flat-square)](https://gitter.im/amqtt/community)
![Python Version](https://img.shields.io/pypi/pyversions/amqtt?style=flat-square)
![Python Wheel](https://img.shields.io/pypi/wheel/amqtt?style=flat-square)
[![PyPI](https://img.shields.io/pypi/v/amqtt?style=flat-square)](https://pypi.org/project/amqtt/)
.. |license| image:: https://img.shields.io/github/license/Yakifo/amqtt?style=flat-square
:target: https://amqtt.readthedocs.io/en/latest/
:alt: MIT licensed
# WORK IN PROGRESS
[!!! MAINTAINERS WANTED !!!](https://github.com/Yakifo/amqtt/issues/163)
.. |ci| image:: https://img.shields.io/github/workflow/status/Yakifo/amqtt/Python%20package?style=flat-square
:target: https://github.com/Yakifo/amqtt/actions/workflows/python-package.yml
# aMQTT
.. |coverage| image:: https://img.shields.io/coveralls/github/Yakifo/amqtt?style=flat-square
:target: https://coveralls.io/github/Yakifo/amqtt?branch=master
`aMQTT` is an open source [MQTT](http://www.mqtt.org) client and broker implementation.
.. |rtfm| image:: https://img.shields.io/readthedocs/amqtt?style=flat-square
:target: https://amqtt.readthedocs.io/en/latest/
:alt: Documentation Status
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.
.. |gitter| image:: https://img.shields.io/gitter/room/Yakifo/amqtt?style=flat-square
:target: https://gitter.im/amqtt/community
:alt: 'Join the chat at https://gitter.im/amqtt/community'
It was forked from [HBMQTT](https://github.com/beerfactory/hbmqtt) after it was deprecated by the original author.
.. |python_versions| image:: https://img.shields.io/pypi/pyversions/amqtt?style=flat-square
:alt: Python Version
## Features
.. |python_wheel| image:: https://img.shields.io/pypi/wheel/amqtt?style=flat-square
: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:
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:
- 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
- Basic `$SYS` topics
- TCP and websocket support
- SSL support over TCP and websocket
- Plugin system
Project Status and Roadmap
---------------------------
## Project Status and Roadmap
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.
+----------+---------------------------+----------------------------+--------------+
| Version | hbmqtt compatibility | Supported Python Versions | PyPi Release |
+----------+---------------------------+----------------------------+--------------+
| 0.10.x | YES - Drop-in Replacement | 3.7* | 0.10.1 |
+----------+---------------------------+----------------------------+--------------+
| 0.11.x | NO - Module renamed | 3.7 - 3.10 | No release |
| | and small API differences | | yet |
+----------+---------------------------+----------------------------+--------------+
| Version | hbmqtt compatibility | Supported Python Versions | PyPi Release |
|---------|---------------------|-------------------------|--------------|
| 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 |
\* 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
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.
## Getting started
`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
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
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).

75
docs/index.md
Wyświetl plik

@ -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
based on coroutines, making it easy to write highly concurrent applications.
## Commands
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:
- 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
## Project layout
mkdocs.yml # The configuration file.
docs/
index.md # The documentation homepage.
... # Other markdown pages, images and other files.

116
docs/quickstart.md
Wyświetl plik

@ -1,94 +1,88 @@
Quickstart
==========
# Quickstart
``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:
`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:
* ``amqtt`` - the MQTT broker
* ``amqtt_pub`` - an MQTT client to publish messages
* ``amqtt_sub`` - an MQTT client to listen for messages
* `amqtt` - the MQTT broker
* `amqtt_pub` - an MQTT client to publish 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
[2015-11-06 22:45:16,470] :: INFO - Listener 'default' bind to 0.0.0.0:1883 (max_connections=-1)
See [amqtt reference documentation](references/amqtt.md) for details about available options and settings.
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
-------------------
``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``:
::
$ 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
```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
[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:
::
$ amqtt_pub --url ws://test.mosquitto.org:8080 -t test -m some_data
[2015-11-06 22:22:42,542] :: INFO - amqtt_pub/5157-myhostname.local Connecting to 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
```bash
$ amqtt_pub --url ws://test.mosquitto.org:8080 -t test -m some_data
[2015-11-06 22:22:42,542] :: INFO - amqtt_pub/5157-myhostname.local Connecting to 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.
``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.
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
the `mqtt scheme <https://github.com/mqtt/mqtt.org/wiki/URI-Scheme>`_.
::
[mqtt|ws][s]://[username][:password]@host.domain[:port]
```
[mqtt|ws][s]://[username][:password]@host.domain[:port]
```
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
```

265
docs/references/amqtt.md
Wyświetl plik

@ -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 [-c <config_file> ] [-d]
```
amqtt --version
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
-h, --help Display ``amqtt_sub`` usage help
-c Set the YAML configuration file to read and pass to the client runtime.
## Configuration
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:
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)
### listeners (mapping)
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)
The listener configuration.
#### <interface name> (mapping)
`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
`Certificates <https://docs.python.org/3/library/ssl.html#ssl-certificates>`_ for more info.
### timeout-disconnect-delay (*integer*, optional)
- **capath** (*string*, optional)
Client disconnect timeout without a keep-alive
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/>`_.
- **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*)
### plugins (*list of strings*)
A list of plugin names to load. Common values include:
- ``auth_file`` – Enables file-based authentication
- ``auth_anonymous`` – Enables anonymous access
- ``event_logger_plugin``
- ``packet_logger_plugin``
- ``topic_taboo``
- ``topic_acl``
- ``broker_sys``
- `auth_file` – Enables file-based authentication
- `auth_anonymous` – Enables anonymous access
- `event_logger_plugin`
- `packet_logger_plugin`
- `topic_taboo`
- `topic_acl`
- `broker_sys`
**auth** (mapping)
### auth (mapping)
Authentication and authorization settings.
- **allow-anonymous** (*boolean*)
- **allow-anonymous** (*boolean*)
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
using ``mkpasswd -m sha-512`` or
```python
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
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)
### sys-interval (*integer*, optional for `broker_sys` plugin, defaults to TBD)
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:
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
The `listeners` section defines 5 bindings:
timeout-disconnect-delay: 2
auth:
password-file: /some/passwd_file
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``
* `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:
* ``auth_file`` plugin, requiring `password-file` to be defined in the ``auth`` section
* ``broker_sys`` plugin, requiring `sys_interval` to be defined
* `auth_file` plugin, requiring `password-file` to be defined in the `auth` section
* `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.
```

146
docs/references/amqtt_pub.md
Wyświetl plik

@ -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 --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] ]
[--extra-headers HEADER]
```
amqtt_pub --version
amqtt_pub (-h | --help)
amqtt_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] ]
[--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
-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
## Configuration
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
-------------
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.
Examples below are adapted from [mosquitto_pub](http://mosquitto.org/man/mosquitto_pub-1.html) documentation.
Publish temperature information to localhost with QoS 1:
::
amqtt_pub --url mqtt://localhost -t sensors/temperature -m 32 -q 1
```bash
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:
::
amqtt_pub --url mqtt://192.168.1.1:1885 -t sensors/temperature -m "1266193804 32"
```bash
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:
::
amqtt_pub --url mqtt://localhost -r -t switches/kitchen_lights/status -m "on"
```bash
amqtt_pub --url mqtt://localhost -r -t switches/kitchen_lights/status -m "on"
```
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:
::
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
```bash
amqtt_pub --url wss://localhost -t sensors/temperature -m 32 -q 1 --extra-headers '{"Authorization": "Bearer <token>"}'
```

122
docs/references/amqtt_sub.md
Wyświetl plik

@ -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 --url BROKER_URL -t TOPIC... [-n COUNT] [-c CONFIG_FILE] [-i CLIENT_ID] [-q | --qos QOS] [-d]
[-k KEEP_ALIVE] [--clean-session] [--ca-file CAFILE] [--ca-path CAPATH] [--ca-data CADATA]
[ --will-topic WILL_TOPIC [--will-message WILL_MESSAGE] [--will-qos WILL_QOS] [--will-retain] ]
[--extra-headers HEADER]
```
amqtt_sub --version
amqtt_sub (-h | --help)
amqtt_sub --url BROKER_URL -t TOPIC... [-n COUNT] [-c CONFIG_FILE] [-i CLIENT_ID] [-q | --qos QOS] [-d]
[-k KEEP_ALIVE] [--clean-session] [--ca-file CAFILE] [--ca-path CAPATH] [--ca-data CADATA]
[ --will-topic WILL_TOPIC [--will-message WILL_MESSAGE] [--will-qos WILL_QOS] [--will-retain] ]
[--extra-headers HEADER]
```
Note that for simplicity, ``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
-h, --help Display ``amqtt_sub`` 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.
-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.
-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 subscribe.
--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
- `--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.
- `-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.
- `-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.
- `-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 subscribe.
- `--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
## 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
-------------
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
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/:
::
amqtt_sub --url mqtt://localhost -t '$SYS/#' -q 0
```bash
amqtt_sub --url mqtt://localhost -t '$SYS/#' -q 0
```
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
.. _mosquitto_sub : http://mosquitto.org/man/mosquitto_sub-1.html
Subscribe with QoS 0 to all messages published under $SYS/: over mqtt encapsulated in a websocket connection and additional headers:
::
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:
```bash
amqtt_sub --url wss://localhost -t '$SYS/#' -q 0 --extra-headers '{"Authorization": "Bearer <token>"}'
```

165
docs/references/broker.md
Wyświetl plik

@ -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:
.. code-block:: python
import logging
import asyncio
import os
from amqtt.broker import Broker
```python
import logging
import asyncio
import os
from amqtt.broker import Broker
async def broker_coro():
broker = Broker()
await broker.start()
async def broker_coro():
broker = Broker()
await broker.start()
if __name__ == '__main__':
formatter = "[%(asctime)s] :: %(levelname)s :: %(name)s :: %(message)s"
logging.basicConfig(level=logging.INFO, format=formatter)
asyncio.get_event_loop().run_until_complete(broker_coro())
asyncio.get_event_loop().run_forever()
if __name__ == '__main__':
formatter = "[%(asctime)s] :: %(levelname)s :: %(name)s :: %(message)s"
logging.basicConfig(level=logging.INFO, format=formatter)
asyncio.get_event_loop().run_until_complete(broker_coro())
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.
``broker_coro`` creates :class:`~amqtt.broker.Broker` instance and then :meth:`~amqtt.broker.Broker.start` the broker for serving.
Once completed, the loop is ran forever, making this script never stop ...
When executed, this script gets the default event loop and asks it to run the `broker_coro` until it completes.
`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...
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
.. automethod:: shutdown
### Broker configuration
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:
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
* `bind`: IP address and port binding.
* `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:
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.
* ``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 `topic-check` section setup access control policies for publishing and subscribing to topics:
The ``auth`` section setup authentication behaviour:
* ``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>`_.
* `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.
* 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.
* 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.

28
docs/references/common.md
Wyświetl plik

@ -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
:members:
#### ApplicationMessage
.. autoclass:: IncomingApplicationMessage
:show-inheritance:
Base class for MQTT application messages.
.. autoclass:: OutgoingApplicationMessage
:show-inheritance:
#### IncomingApplicationMessage
Inherits from ApplicationMessage. Represents messages received from MQTT clients.
#### OutgoingApplicationMessage
Inherits from ApplicationMessage. Represents messages to be sent to MQTT clients.

33
docs/references/index.md
Wyświetl plik

@ -1,30 +1,15 @@
References
==========
# References
Reference documentation for aMQTT console scripts and programming API.
Console scripts
---------------
## Console scripts
* :doc:`amqtt_pub` : MQTT client for publishing messages to a broker
* :doc:`amqtt_sub` : MQTT client for subscribing to a topics and retrieved published messages
* :doc:`amqtt` : Autonomous MQTT broker
* [amqtt_pub](amqtt_pub.md): MQTT client for publishing messages to a broker
* [amqtt_sub](amqtt_sub.md): MQTT client for subscribing to topics and retrieved published messages
* [amqtt](amqtt.md): Autonomous MQTT broker
Programming API
---------------
## Programming API
* :doc:`mqttclient` : MQTT client API reference
* :doc:`broker` : MQTT broker API reference
* :doc:`common` : Common API
TBD
.. toctree::
:hidden:
amqtt_pub
amqtt_sub
amqtt
mqttclient
broker
common
* [mqttclient](mqttclient.md): MQTT client API reference
* [broker](broker.md): MQTT broker API reference
* [common](common.md): Common API

284
docs/references/mqttclient.md
Wyświetl plik

@ -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
import asyncio
logger = logging.getLogger(__name__)
from amqtt.client import MQTTClient, ClientException
from amqtt.mqtt.constants import QOS_1, QOS_2
async def uptime_coro():
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():
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)
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``.
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 `MQTTClient` instance.
The coroutine then calls `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.
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.
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
import asyncio
from amqtt.client import MQTTClient
from amqtt.mqtt.constants import QOS_0, QOS_1, QOS_2
from amqtt.client import MQTTClient
from amqtt.mqtt.constants import QOS_0, QOS_1, QOS_2
logger = logging.getLogger(__name__)
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()
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)
ret = await C.connect('mqtt://test.mosquitto.org:1883/')
message = await C.publish('a/b', b'TEST MESSAGE WITH QOS_0', qos=QOS_0)
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()
async def test_coro2():
try:
C = MQTTClient()
ret = await C.connect('mqtt://test.mosquitto.org:1883/')
message = await C.publish('a/b', b'TEST MESSAGE WITH QOS_0', qos=QOS_0)
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()
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(test_coro())
asyncio.get_event_loop().run_until_complete(test_coro2())
```
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__':
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(test_coro())
asyncio.get_event_loop().run_until_complete(test_coro2())
`test_coro()` achieves:
```
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'"))
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)
```
As usual, the script runs the publish code through the async loop. ``test_coro()`` and ``test_coro()`` are ran in sequence.
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.
while `test_coro2()` runs:
```
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'"))
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)
## Reference
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'"))
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)
The `amqtt.client` module provides the following methods in the `MQTTClient` class:
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
.. automethod:: disconnect
.. automethod:: reconnect
.. automethod:: ping
.. automethod:: publish
.. automethod:: subscribe
.. automethod:: unsubscribe
.. automethod:: deliver_message
MQTTClient configuration
........................
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 }
}
```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 ``some_topic`` topic : they will be sent with QOS_2 and retain flag set
* 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
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.

5
mkdocs.yml
Wyświetl plik

@ -19,6 +19,11 @@ nav:
- Quickstart: quickstart.md
- Usage:
- 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
# - Credits: credits.md
# - License: license.md