diff --git a/README.md b/README.md index 336713c..42d07cf 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ [![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) +[![CI](https://github.com/Yakifo/amqtt/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Yakifo/amqtt/actions/workflows/ci.yml) +[![CodeQL](https://github.com/Yakifo/amqtt/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/Yakifo/amqtt/actions/workflows/codeql-analysis.yml) [![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) @@ -9,41 +9,22 @@ ![docs/assets/amqtt.svg](docs/assets/amqtt.svg) -# aMQTT -`aMQTT` is an open source [MQTT](http://www.mqtt.org) client and broker implementation. - -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. - -It was forked from [HBMQTT](https://github.com/beerfactory/hbmqtt) after it was deprecated by the original author. +`aMQTT` is an open source [MQTT](http://www.mqtt.org) broker[^1], natively implemented with Python's [asyncio](https://docs.python.org/3/library/asyncio.html). ## 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: - +- 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 +- Communication over TCP and/or websocket, including support for SSL/TLS - 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 - -## 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 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. +- Functionality expansion; plugins included: + - Authentication through password file + - Basic `$SYS` topics ## Getting started -`amqtt` is available on [PyPI](https://pypi.python.org/pypi/amqtt) and can be installed simply using `pip`: +`amqtt` is available on [PyPI](https://pypi.python.org/pypi/amqtt) ```bash $ pip install amqtt @@ -54,5 +35,16 @@ Documentation is available on [Read the Docs](http://amqtt.readthedocs.org/). 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). +## Project Status and Roadmap + +| Version | hbmqtt compatibility | Supported Python Versions | PyPi Release | +|---------|----------------------|---------------------------|--------------| +| 0.10.x | yes [^2] | 3.7 - 3.9 | 0.10.1 | +| 0.11.x | no [^3] | 3.10 - 3.13 | 0.11.0 | + + +[^1]: Forked from [HBMQTT](https://github.com/beerfactory/hbmqtt) after it was deprecated by the original author. +[^2]: drop-in replacement +[^3]: module renamed and small API differences diff --git a/docs/assets/amqtt.svg b/docs/assets/amqtt.svg index 1306950..6e3e11e 100644 --- a/docs/assets/amqtt.svg +++ b/docs/assets/amqtt.svg @@ -15,24 +15,20 @@ viewBox="0 0 17484.57 3960.9" - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + diff --git a/docs/assets/amqtt_bw.svg b/docs/assets/amqtt_bw.svg index c69ecf7..b02d25c 100644 --- a/docs/assets/amqtt_bw.svg +++ b/docs/assets/amqtt_bw.svg @@ -15,24 +15,20 @@ viewBox="0 0 16459.16 3728.61" - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + diff --git a/docs/docs/assets/amqtt.svg b/docs/docs/assets/amqtt.svg index 1306950..6e3e11e 100644 --- a/docs/docs/assets/amqtt.svg +++ b/docs/docs/assets/amqtt.svg @@ -15,24 +15,20 @@ viewBox="0 0 17484.57 3960.9" - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + diff --git a/docs/references/amqtt.md b/docs/references/amqtt.md index 67e7ab6..c19defb 100644 --- a/docs/references/amqtt.md +++ b/docs/references/amqtt.md @@ -39,47 +39,49 @@ Using the `-c` argument allows for configuration with a YAML structured file. Th ## Field Descriptions -### listeners (mapping) +### `listeners` -Defines network listeners for the MQTT server. +Defines network listeners for the MQTT server (list). -#### (mapping) -`default` for parameters to be used across all specified interfaces or user-specified name for the specific interface. -The listener configuration. +#### `` +`default` for parameters used across all interfaces _or_ name for the specific interface (mapping). -- **bind** (*string*, required) +Each entry supports these parameters: + +- `bind` (string, *required*) Address and port to bind to, in the form `host:port` (e.g., `0.0.0.0:1883`). -- **type** (*string*, optional) +- `type` (string, *required*) Protocol type. Typically `"tcp"` or `"ws"`. -- **max-connections** (*integer*, optional) +- `max-connections` (integer, *required*) Maximum number of clients that can connect to this interface -- **ssl** (*string*, default: `off`) - Enable (on) or disable (off) SSL. One of `cafile`, `capath`, `cadata` or `certfile`/`keyfile`. +- `ssl` (string, *optional, default: `off`*) + Disable (`off`) SSL/TLS or enable (`on`) with one of `cafile`, `capath`, `cadata` or `certfile`/`keyfile`. -- **cafile** (*string*, 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. -- **capath** (*string*, optional) +- `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/). -- **cadata** (*string*, optional) +- `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) +- `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) +- `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) +### timeout-disconnect-delay -Client disconnect timeout without a keep-alive +Client disconnect timeout without a keep-alive (integer, *optional*) -### plugins (*list of strings*) -A list of plugin names to load. Common values include: +### plugins + +Entry points for optional functionality (*list of strings*); included plugins are: - `auth_file` – Enables file-based authentication - `auth_anonymous` – Enables anonymous access @@ -89,15 +91,15 @@ A list of plugin names to load. Common values include: - `topic_acl` - `broker_sys` -### auth (mapping) +### auth -Authentication and authorization settings. +Authentication and authorization settings (mapping). -- **allow-anonymous** (*boolean*) - Whether to allow anonymous clients to connect (`true` or `false`). +- `allow-anonymous` (boolean, *optional for `auth_anonymous` plugin*) + Allow (`true`) or prevent (`false`) anonymous client to connections. -- **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: +- `password-file` (string, *required for `auth_file` plugin*) + Path to file which includes `username:password` pair, one per line. The password should be encoded using sha-512 with `mkpasswd -m sha-512` or: ```python import sys @@ -108,9 +110,9 @@ 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 -Interval in seconds to publish system statistics to `$SYS` topics. +Interval in seconds to publish system statistics to `$SYS` topics (integer, *optional for `broker_sys` plugin, defaults to TBD*). ## Configuration example diff --git a/mkdocs.yml b/mkdocs.yml index e9a0632..18a6d49 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,8 +1,8 @@ site_name: "" site_description: "Automatic documentation from sources, for MkDocs." site_url: http://github.com -repo_url: http://github.com/abc/amqtt -repo_name: abc/amqtt +repo_url: https://github.com/Yakifo/amqtt +repo_name: Yakifo/amqtt site_dir: "site" watch: [mkdocs.yml, README.md, CONTRIBUTING.md, docs, amqtt] copyright: TBD @@ -17,11 +17,11 @@ nav: - Home: - Overview: index.md - Quickstart: quickstart.md - - Usage: + - CLI Usage: - Broker: references/amqtt.md - Publisher: references/amqtt_pub.md - Subscriber: references/amqtt_sub.md - - API: + - API Usage: - Broker: references/broker.md - Client: references/client.md # - Changelog: changelog.md