########
mqttwarn
########
.. image:: https://cloud.githubusercontent.com/assets/2345521/6320105/4dd7a826-bade-11e4-9a61-72aa163a40a9.png
To *warn*, *alert*, or *notify*.
.. image:: https://raw.githubusercontent.com/mqtt-tools/mqttwarn/main/assets/google-definition.jpg
******
Status
******
.. image:: https://github.com/mqtt-tools/mqttwarn/workflows/Tests/badge.svg
:target: https://github.com/mqtt-tools/mqttwarn/actions?workflow=Tests
.. image:: https://codecov.io/gh/mqtt-tools/mqttwarn/branch/main/graph/badge.svg
:target: https://codecov.io/gh/mqtt-tools/mqttwarn
.. image:: https://img.shields.io/pypi/pyversions/mqttwarn.svg
:target: https://pypi.org/project/mqttwarn/
|
.. image:: https://img.shields.io/pypi/l/mqttwarn.svg
:target: https://pypi.org/project/mqttwarn/
.. image:: https://img.shields.io/pypi/status/mqttwarn.svg
:target: https://pypi.org/project/mqttwarn/
.. image:: https://img.shields.io/pypi/v/mqttwarn.svg
:target: https://pypi.org/project/mqttwarn/
.. image:: https://pepy.tech/badge/mqttwarn/month
:target: https://pepy.tech/project/mqttwarn
|
`GitHub <https://github.com/mqtt-tools/mqttwarn>`_
| `PyPI <https://pypi.org/project/mqttwarn/>`_
| `Documentation <https://mqttwarn.readthedocs.io>`_
| `Issues <https://github.com/mqtt-tools/mqttwarn/issues>`_
| `Changelog <https://github.com/mqtt-tools/mqttwarn/blob/main/CHANGES.rst>`_
*****
About
*****
mqttwarn - subscribe to MQTT topics and notify pluggable services.
Description
===========
*mqttwarn* subscribes to any number of MQTT topics and publishes received
payloads to one or more notification services after optionally applying
sophisticated transformations.
A picture says a thousand words.
.. image:: https://raw.githubusercontent.com/mqtt-tools/mqttwarn/main/assets/mqttwarn.png
:target: #
Notification service coverage
=============================
*mqttwarn* comes with **over 70 notification handler plugins**, covering a
wide range of notification services and is very open to further contributions.
You can enjoy the alphabetical list of plugins on the `mqttwarn notifier
catalog`_ page.
On top of that, it integrates with the excellent `Apprise`_ notification
library. `Apprise notification services`_ has a complete list of the **80+
notification services** supported by Apprise.
*************
Documentation
*************
The `mqttwarn documentation`_ is the right place to read all about *mqttwarn*'s
features and integrations, and how you can leverage all its framework components
for building custom applications. Its service plugins can be inspected on the
`mqttwarn notifier catalog`_ page.
************
Installation
************
Using pip
=========
Synopsis::
pip install --upgrade mqttwarn
You can also add support for a specific service plugin::
pip install --upgrade 'mqttwarn[xmpp]'
You can also add support for multiple services, all at once::
pip install --upgrade 'mqttwarn[apprise,asterisk,nsca,desktopnotify,tootpaste,xmpp]'
See also: `Installing mqttwarn with pip`_.
OCI container image
===================
For running ``mqttwarn`` on a container infrastructure like Docker or
Kubernetes, corresponding images are automatically published to the
GitHub Container Registry (GHCR).
- ``ghcr.io/mqtt-tools/mqttwarn-standard:latest``
- ``ghcr.io/mqtt-tools/mqttwarn-full:latest``
To learn more about this topic, please follow up reading the `Using the OCI image
with Docker or Podman`_ documentation section.
*************
Configuration
*************
In order to learn how to configure mqttwarn, please head over to the documentation
section about the `mqttwarn configuration`_.
*****
Usage
*****
Interactive service
===================
Just launch ``mqttwarn``::
# Run mqttwarn
mqttwarn
To supply a different configuration file or log file, optionally use::
# Define configuration file
export MQTTWARNINI=/etc/mqttwarn/acme.ini
# Define log file
export MQTTWARNLOG=/var/log/mqttwarn.log
# Run mqttwarn
mqttwarn
System daemon
=============
There are different ways to run mqttwarn as a system daemon. There are examples
for systemd, traditional init, OpenRC, and Supervisor_ in the ``etc`` directory
of this repository, for example `supervisor.ini`_ (Supervisor) and
`mqttwarn.service`_ (systemd).
Standalone
==========
In order to directly invoke notification plugins from custom programs, or for
debugging them, see `Running notification plugins standalone`_.
Development sandbox
===================
For hacking on mqttwarn, please install it in development mode, using a
`mqttwarn development sandbox`_ installation.
*******************
Project information
*******************
About
=====
These links will guide you to the source code of *mqttwarn* and its documentation.
- `mqttwarn on GitHub <https://github.com/mqtt-tools/mqttwarn>`_
- `mqttwarn on the Python Package Index (PyPI) <https://pypi.org/project/mqttwarn/>`_
- `mqttwarn documentation <https://mqttwarn.readthedocs.io/>`_
Requirements
============
You will need at least the following components:
* Python 3.x or PyPy 3.x.
* An MQTT broker. We recommend `Eclipse Mosquitto`_.
* For invoking specific service plugins, additional Python modules may be required.
See ``setup.py`` file.
Contributing
============
We are always happy to receive code contributions, ideas, suggestions
and problem reports from the community.
So, if you would like to contribute, you are most welcome.
Spend some time taking a look around, locate a bug, design issue or
spelling mistake, and then send us a pull request or create an `issue`_.
Thank you in advance for your efforts, we really appreciate any help or feedback.
License
=======
mqttwarn is copyright © 2014-2023 Jan-Piet Mens and contributors. All
rights reserved.
It is and will always be **free and open source software**.
Use of the source code included here is governed by the `Eclipse Public License
2.0 <EPL-2.0_>`_, see LICENSE_ file for details. Please also recognize the
licenses of third-party components.
***************
Troubleshooting
***************
If you encounter any problems during setup or operations or if you have further
suggestions, please let us know by `opening an issue on GitHub`_. Thank you
already.
************
Attributions
************
Acknowledgements
================
Thanks to all the contributors of *mqttwarn* who helped to conceive it in one
way or another. You know who you are.
Legal stuff
===========
"MQTT" is a trademark of the OASIS open standards consortium, which publishes the
MQTT specifications. "Eclipse Mosquitto" is a trademark of the Eclipse Foundation.
----
Have fun!
.. _Apprise: https://github.com/caronc/apprise
.. _Apprise notification services: https://github.com/caronc/apprise/wiki#notification-services
.. _backlog: https://github.com/mqtt-tools/mqttwarn/blob/main/doc/backlog.rst
.. _Eclipse Mosquitto: https://mosquitto.org
.. _EPL-2.0: https://www.eclipse.org/legal/epl-2.0/
.. _hacking: https://github.com/mqtt-tools/mqttwarn/blob/main/doc/hacking.rst
.. _How do your servers talk to you?: https://jpmens.net/2014/04/03/how-do-your-servers-talk-to-you/
.. _Installing mqttwarn with pip: https://mqttwarn.readthedocs.io/en/latest/usage/pip.html
.. _issue: https://github.com/mqtt-tools/mqttwarn/issues/new
.. _LICENSE: https://github.com/mqtt-tools/mqttwarn/blob/main/LICENSE
.. _MQTTwarn\: Ein Rundum-Sorglos-Notifier: https://web.archive.org/web/20140611040637/http://jaxenter.de/news/MQTTwarn-Ein-Rundum-Sorglos-Notifier-171312
.. _mqttwarn configuration: https://mqttwarn.readthedocs.io/en/latest/configure/
.. _mqttwarn development sandbox: https://mqttwarn.readthedocs.io/en/latest/workbench/sandbox.html
.. _mqttwarn documentation: https://mqttwarn.readthedocs.io/
.. _mqttwarn notifier catalog: https://mqttwarn.readthedocs.io/en/latest/notifier-catalog.html
.. _mqttwarn.service: https://github.com/mqtt-tools/mqttwarn/blob/main/etc/mqttwarn.service
.. _opening an issue on GitHub: https://github.com/mqtt-tools/mqttwarn/issues/new
.. _Running notification plugins standalone: https://mqttwarn.readthedocs.io/en/latest/usage/standalone.html
.. _Schwarmalarm using mqttwarn: https://hiveeyes.org/docs/system/schwarmalarm-mqttwarn.html
.. _Supervisor: https://jpmens.net/2014/02/13/in-my-toolbox-supervisord/
.. _supervisor.ini: https://github.com/mqtt-tools/mqttwarn/blob/main/etc/supervisor.ini
.. _Using the OCI image with Docker or Podman: https://mqttwarn.readthedocs.io/en/latest/usage/oci.html
Raw data
{
"_id": null,
"home_page": "https://github.com/mqtt-tools/mqttwarn",
"name": "mqttwarn",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "mqtt notification plugins data acquisition push transformation engine mosquitto",
"author": "Jan-Piet Mens, Ben Jones, Andreas Motl",
"author_email": "jpmens@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/12/8d/86a6c5325876390966565eef5e297a66dc9aa8635605f0c94c3f7176cc21/mqttwarn-0.35.0.tar.gz",
"platform": null,
"description": "########\nmqttwarn\n########\n\n.. image:: https://cloud.githubusercontent.com/assets/2345521/6320105/4dd7a826-bade-11e4-9a61-72aa163a40a9.png\n\nTo *warn*, *alert*, or *notify*.\n\n.. image:: https://raw.githubusercontent.com/mqtt-tools/mqttwarn/main/assets/google-definition.jpg\n\n\n******\nStatus\n******\n\n.. image:: https://github.com/mqtt-tools/mqttwarn/workflows/Tests/badge.svg\n :target: https://github.com/mqtt-tools/mqttwarn/actions?workflow=Tests\n\n.. image:: https://codecov.io/gh/mqtt-tools/mqttwarn/branch/main/graph/badge.svg\n :target: https://codecov.io/gh/mqtt-tools/mqttwarn\n\n.. image:: https://img.shields.io/pypi/pyversions/mqttwarn.svg\n :target: https://pypi.org/project/mqttwarn/\n\n|\n\n.. image:: https://img.shields.io/pypi/l/mqttwarn.svg\n :target: https://pypi.org/project/mqttwarn/\n\n.. image:: https://img.shields.io/pypi/status/mqttwarn.svg\n :target: https://pypi.org/project/mqttwarn/\n\n.. image:: https://img.shields.io/pypi/v/mqttwarn.svg\n :target: https://pypi.org/project/mqttwarn/\n\n.. image:: https://pepy.tech/badge/mqttwarn/month\n :target: https://pepy.tech/project/mqttwarn\n\n|\n\n`GitHub <https://github.com/mqtt-tools/mqttwarn>`_\n| `PyPI <https://pypi.org/project/mqttwarn/>`_\n| `Documentation <https://mqttwarn.readthedocs.io>`_\n| `Issues <https://github.com/mqtt-tools/mqttwarn/issues>`_\n| `Changelog <https://github.com/mqtt-tools/mqttwarn/blob/main/CHANGES.rst>`_\n\n\n*****\nAbout\n*****\n\nmqttwarn - subscribe to MQTT topics and notify pluggable services.\n\n\nDescription\n===========\n\n*mqttwarn* subscribes to any number of MQTT topics and publishes received\npayloads to one or more notification services after optionally applying\nsophisticated transformations.\n\nA picture says a thousand words.\n\n.. image:: https://raw.githubusercontent.com/mqtt-tools/mqttwarn/main/assets/mqttwarn.png\n :target: #\n\n\nNotification service coverage\n=============================\n\n*mqttwarn* comes with **over 70 notification handler plugins**, covering a\nwide range of notification services and is very open to further contributions.\nYou can enjoy the alphabetical list of plugins on the `mqttwarn notifier\ncatalog`_ page.\n\nOn top of that, it integrates with the excellent `Apprise`_ notification\nlibrary. `Apprise notification services`_ has a complete list of the **80+\nnotification services** supported by Apprise.\n\n\n\n*************\nDocumentation\n*************\n\nThe `mqttwarn documentation`_ is the right place to read all about *mqttwarn*'s\nfeatures and integrations, and how you can leverage all its framework components\nfor building custom applications. Its service plugins can be inspected on the\n`mqttwarn notifier catalog`_ page.\n\n\n************\nInstallation\n************\n\nUsing pip\n=========\n\nSynopsis::\n\n pip install --upgrade mqttwarn\n\nYou can also add support for a specific service plugin::\n\n pip install --upgrade 'mqttwarn[xmpp]'\n\nYou can also add support for multiple services, all at once::\n\n pip install --upgrade 'mqttwarn[apprise,asterisk,nsca,desktopnotify,tootpaste,xmpp]'\n\nSee also: `Installing mqttwarn with pip`_.\n\nOCI container image\n===================\n\nFor running ``mqttwarn`` on a container infrastructure like Docker or\nKubernetes, corresponding images are automatically published to the\nGitHub Container Registry (GHCR).\n\n- ``ghcr.io/mqtt-tools/mqttwarn-standard:latest``\n- ``ghcr.io/mqtt-tools/mqttwarn-full:latest``\n\nTo learn more about this topic, please follow up reading the `Using the OCI image\nwith Docker or Podman`_ documentation section.\n\n\n*************\nConfiguration\n*************\n\nIn order to learn how to configure mqttwarn, please head over to the documentation\nsection about the `mqttwarn configuration`_.\n\n\n*****\nUsage\n*****\n\nInteractive service\n===================\nJust launch ``mqttwarn``::\n\n # Run mqttwarn\n mqttwarn\n\n\nTo supply a different configuration file or log file, optionally use::\n\n # Define configuration file\n export MQTTWARNINI=/etc/mqttwarn/acme.ini\n\n # Define log file\n export MQTTWARNLOG=/var/log/mqttwarn.log\n\n # Run mqttwarn\n mqttwarn\n\nSystem daemon\n=============\n\nThere are different ways to run mqttwarn as a system daemon. There are examples\nfor systemd, traditional init, OpenRC, and Supervisor_ in the ``etc`` directory\nof this repository, for example `supervisor.ini`_ (Supervisor) and\n`mqttwarn.service`_ (systemd).\n\nStandalone\n==========\n\nIn order to directly invoke notification plugins from custom programs, or for\ndebugging them, see `Running notification plugins standalone`_.\n\nDevelopment sandbox\n===================\n\nFor hacking on mqttwarn, please install it in development mode, using a\n`mqttwarn development sandbox`_ installation.\n\n\n*******************\nProject information\n*******************\n\nAbout\n=====\nThese links will guide you to the source code of *mqttwarn* and its documentation.\n\n- `mqttwarn on GitHub <https://github.com/mqtt-tools/mqttwarn>`_\n- `mqttwarn on the Python Package Index (PyPI) <https://pypi.org/project/mqttwarn/>`_\n- `mqttwarn documentation <https://mqttwarn.readthedocs.io/>`_\n\n\nRequirements\n============\nYou will need at least the following components:\n\n* Python 3.x or PyPy 3.x.\n* An MQTT broker. We recommend `Eclipse Mosquitto`_.\n* For invoking specific service plugins, additional Python modules may be required.\n See ``setup.py`` file.\n\n\nContributing\n============\n\nWe are always happy to receive code contributions, ideas, suggestions\nand problem reports from the community.\n\nSo, if you would like to contribute, you are most welcome.\nSpend some time taking a look around, locate a bug, design issue or\nspelling mistake, and then send us a pull request or create an `issue`_.\n\nThank you in advance for your efforts, we really appreciate any help or feedback.\n\n\nLicense\n=======\n\nmqttwarn is copyright \u00a9 2014-2023 Jan-Piet Mens and contributors. All\nrights reserved.\n\nIt is and will always be **free and open source software**.\n\nUse of the source code included here is governed by the `Eclipse Public License\n2.0 <EPL-2.0_>`_, see LICENSE_ file for details. Please also recognize the\nlicenses of third-party components.\n\n\n***************\nTroubleshooting\n***************\n\nIf you encounter any problems during setup or operations or if you have further\nsuggestions, please let us know by `opening an issue on GitHub`_. Thank you\nalready.\n\n\n************\nAttributions\n************\n\nAcknowledgements\n================\nThanks to all the contributors of *mqttwarn* who helped to conceive it in one\nway or another. You know who you are.\n\nLegal stuff\n===========\n\"MQTT\" is a trademark of the OASIS open standards consortium, which publishes the\nMQTT specifications. \"Eclipse Mosquitto\" is a trademark of the Eclipse Foundation.\n\n----\n\nHave fun!\n\n\n.. _Apprise: https://github.com/caronc/apprise\n.. _Apprise notification services: https://github.com/caronc/apprise/wiki#notification-services\n.. _backlog: https://github.com/mqtt-tools/mqttwarn/blob/main/doc/backlog.rst\n.. _Eclipse Mosquitto: https://mosquitto.org\n.. _EPL-2.0: https://www.eclipse.org/legal/epl-2.0/\n.. _hacking: https://github.com/mqtt-tools/mqttwarn/blob/main/doc/hacking.rst\n.. _How do your servers talk to you?: https://jpmens.net/2014/04/03/how-do-your-servers-talk-to-you/\n.. _Installing mqttwarn with pip: https://mqttwarn.readthedocs.io/en/latest/usage/pip.html\n.. _issue: https://github.com/mqtt-tools/mqttwarn/issues/new\n.. _LICENSE: https://github.com/mqtt-tools/mqttwarn/blob/main/LICENSE\n.. _MQTTwarn\\: Ein Rundum-Sorglos-Notifier: https://web.archive.org/web/20140611040637/http://jaxenter.de/news/MQTTwarn-Ein-Rundum-Sorglos-Notifier-171312\n.. _mqttwarn configuration: https://mqttwarn.readthedocs.io/en/latest/configure/\n.. _mqttwarn development sandbox: https://mqttwarn.readthedocs.io/en/latest/workbench/sandbox.html\n.. _mqttwarn documentation: https://mqttwarn.readthedocs.io/\n.. _mqttwarn notifier catalog: https://mqttwarn.readthedocs.io/en/latest/notifier-catalog.html\n.. _mqttwarn.service: https://github.com/mqtt-tools/mqttwarn/blob/main/etc/mqttwarn.service\n.. _opening an issue on GitHub: https://github.com/mqtt-tools/mqttwarn/issues/new\n.. _Running notification plugins standalone: https://mqttwarn.readthedocs.io/en/latest/usage/standalone.html\n.. _Schwarmalarm using mqttwarn: https://hiveeyes.org/docs/system/schwarmalarm-mqttwarn.html\n.. _Supervisor: https://jpmens.net/2014/02/13/in-my-toolbox-supervisord/\n.. _supervisor.ini: https://github.com/mqtt-tools/mqttwarn/blob/main/etc/supervisor.ini\n.. _Using the OCI image with Docker or Podman: https://mqttwarn.readthedocs.io/en/latest/usage/oci.html\n",
"bugtrack_url": null,
"license": "EPL 2.0",
"summary": "mqttwarn - subscribe to MQTT topics and notify pluggable services",
"version": "0.35.0",
"project_urls": {
"Homepage": "https://github.com/mqtt-tools/mqttwarn"
},
"split_keywords": [
"mqtt",
"notification",
"plugins",
"data",
"acquisition",
"push",
"transformation",
"engine",
"mosquitto"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f0c1d7fb1d217e2df1f467fd43000c1e90f430dcd446924f92aa74ce010dd5be",
"md5": "4dbde9ace6cf4d7f60ac432e4ee0dd10",
"sha256": "e53523fe3bcb54681a47896cf5052c3b80117f61daea944b7a95ea44637d2771"
},
"downloads": -1,
"filename": "mqttwarn-0.35.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4dbde9ace6cf4d7f60ac432e4ee0dd10",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 117928,
"upload_time": "2023-10-14T22:53:16",
"upload_time_iso_8601": "2023-10-14T22:53:16.060331Z",
"url": "https://files.pythonhosted.org/packages/f0/c1/d7fb1d217e2df1f467fd43000c1e90f430dcd446924f92aa74ce010dd5be/mqttwarn-0.35.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "128d86a6c5325876390966565eef5e297a66dc9aa8635605f0c94c3f7176cc21",
"md5": "b63dd8055762c389242ac4b52994fe86",
"sha256": "3a66ec2a1aed60177973894c99125d838de1eeed1f2f1e98025d91c682091e21"
},
"downloads": -1,
"filename": "mqttwarn-0.35.0.tar.gz",
"has_sig": false,
"md5_digest": "b63dd8055762c389242ac4b52994fe86",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 978344,
"upload_time": "2023-10-14T22:53:19",
"upload_time_iso_8601": "2023-10-14T22:53:19.272120Z",
"url": "https://files.pythonhosted.org/packages/12/8d/86a6c5325876390966565eef5e297a66dc9aa8635605f0c94c3f7176cc21/mqttwarn-0.35.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-14 22:53:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mqtt-tools",
"github_project": "mqttwarn",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "mqttwarn"
}
JSON
