MQTT Support Added

[caronc]

Description:

Related issue (if applicable): #388

Added MQTT Support for Apprise.

Syntax

This is still a work in progress, but basically it works like this...

• mqtt://{host}/{topic}
• mqtt://{host}:{port}/{topic}
• mqtt://{user}@{host}:{port}/{topic}
• mqtt://{user}:{password}@{host}:{port}/{topic}

For a secure connection, just use mqtts instead.

• mqtts://{host}:{port}/{topic}
• mqtts://{user}@{host}:{port}/{topic}
• mqtts://{user}:{password}@{host}:{port}/{topic}

Other things worth noting:

• You must install paho-mqtt for this plugin to work:

  pip install paho-mqtt

• If no port is specified, then the default is 1883 for un-encrypted connections and 8883 for the encrypted ones.
• You can specify more then one topic by simply adding a comma in your path... hence:
  • mqtts:/{host}:{port}/{topic1},{topic2},{topicN},...

Note: MQTT documents state that that you shouldn't start a topic with a leading slash. However, if your system requires it, just use the to argument as a keyword in the argument, eg:

• mqtt:/{host}?to=/topic/that/starts/with/a/slash

Parameter Breakdown

Variable	Required	Description
qos	No	The MQTT Quality of Service (Qos) setting. By default this is set to 0 (zero).
version	No	The MQTT Protocol Version to use. By default this is set to v3.1.1. The other possible values are v3.1 and v5.
client_id	No	The MQTT client identifier to use when establishing a connection with the server. By default this is not set and a unique ID is generated per message.
session	No	The MQTT session to maintain (associated with the client_id). If no client_id is specified, then this value is not considered. By default there is no session established and each connection made by apprise is unique. If you wish to enforce a session (associated with a provided client_id) then set this value to True.

Example:

# Assuming we're just running an MQTT Server locally on your box
# Assuming we want to post our message to the topic: `my/topic`
apprise -vvv -b "whatever-payload-want" "mqtt://localhost/my/topic"

New Service Completion Status

• apprise/plugins/NotifyMQTT.py
• setup.py
  • add new service into the keywords section of the setup() declaration
• README.md
  • add entry for new service to table (as a quick reference)
• packaging/redhat/python-apprise.spec
  • add new service into the %global common_description

Checklist

• The code change is tested and works locally.
• There is no commented out code in this PR.
• No lint errors (use flake8)
• 100% test coverage

Testing

Anyone can help test this source code as follows:

# Create a virtual environment to work in
# This way you can just destroy it after when it's all over.
# The below will create a directory called apprise
python3 -m venv apprise

# Change into our new directory
cd apprise

# Activate our virtual environment
source bin/activate

# Install the branch
pip install git+https://github.com/caronc/apprise.git@388-mqtt-support

# Give it a go:
apprise -b "test" "mqtt://localhost/my/topic"

[gaby]

Looking forward to this getting merged!

[codecov-commenter]

Codecov Report

Merging #443 (da7ad46) into master (e0f928f) will not change coverage.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##            master      #443    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files           95        96     +1     
  Lines        12148     12383   +235     
  Branches      2049      2101    +52     
==========================================
+ Hits         12148     12383   +235     

Impacted Files	Coverage Δ
apprise/plugins/NotifyMQTT.py	100.00% <100.00%> (ø)
apprise/plugins/NotifyTwilio.py	100.00% <0.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update e0f928f...da7ad46. Read the comment docs.

[caronc]

This PR is just pending actual user testing and feedback to see if everything works.