mqttwarn


Namemqttwarn JSON
Version 0.35.0 PyPI version JSON
download
home_pagehttps://github.com/mqtt-tools/mqttwarn
Summarymqttwarn - subscribe to MQTT topics and notify pluggable services
upload_time2023-10-14 22:53:19
maintainer
docs_urlNone
authorJan-Piet Mens, Ben Jones, Andreas Motl
requires_python
licenseEPL 2.0
keywords mqtt notification plugins data acquisition push transformation engine mosquitto
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            ########
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"
}
        
Elapsed time: 0.13494s