new module: notification/mqtt for publishing a topic to an MQTT broker

library/notification/mqtt

@@ -0,0 +1,177 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+# (c) 2013, Jan-Piet Mens <jpmens () gmail.com>
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+DOCUMENTATION = '''
+---
+module: mqtt
+short_description: Publish a message on an MQTT topic for the IoT
+version_added: "1.2"
+description:
+   - Publish a message on an MQTT topic.
+options:
+  server:
+    description:
+      - MQTT broker address/name
+    required: false
+    default: localhost
+  port:
+    description:
+      - MQTT broker port number
+    required: false
+    default: 1883
+  username:
+    description:
+      - Username to authenticate against the broker.
+    required: false
+  password:
+    description:
+      - Password for C(username) to authenticate against the broker.
+    required: false
+  client_id:
+    description:
+      - MQTT client identifier
+    required: false
+    default: hostname + pid
+  topic:
+    description:
+      - MQTT topic name
+    required: true
+    default: null
+  payload:
+    description:
+      - Payload. The special string C("None") may be used to send a NULL
+        (i.e. empty) payload which is useful to simply notify with the I(topic)
+        or to clear previously retained messages.
+    required: true
+    default: null
+  qos:
+    description:
+      - QoS (Quality of Service)
+    required: false
+    default: 0
+    choices: [ "0", "1", "2" ]
+  retain:
+    description:
+      - Setting this flag causes the broker to retain (i.e. keep) the message so that
+        applications that subsequently subscribe to the topic can received the last
+        retained message immediately.
+    required: false
+    default: False
+
+# informational: requirements for nodes
+requirements: [ mosquitto ]
+notes:
+ - This module requires a connection to an MQTT broker such as Mosquitto
+   U(http://mosquitto.org) and the C(mosquitto) Python module (U(http://mosquitto.org/python)).
+author: Jan-Piet Mens
+'''
+
+EXAMPLES = '''
+local_action: mqtt
+              topic=service/ansible/{{ ansible_hostname }}
+              payload="Hello at {{ ansible_date_time.iso8601 }}"
+              qos=0
+              retain=false
+              client_id=ans001
+'''
+
+# ===========================================
+# MQTT module support methods.
+#
+
+HAS_MOSQUITTO = True
+try:
+    import socket
+    import mosquitto
+except ImportError:
+    HAS_MOSQUITTO = False
+import os
+
+def publish(module, topic, payload, server='localhost', port='1883', qos='0',
+        client_id='', retain=False, username=None, password=None):
+    '''Open connection to MQTT broker and publish the topic'''
+
+    mqttc = mosquitto.Mosquitto(client_id, clean_session=True)
+
+    if username is not None and password is not None:
+        mqttc.username_pw_set(username, password)
+
+    rc = mqttc.connect(server, int(port), 5)
+    if rc != 0:
+        module.fail_json(msg="unable to connect to MQTT broker")
+
+    mqttc.publish(topic, payload, int(qos), retain)
+
+    mqttc.disconnect()
+
+
+# ===========================================
+# Main
+#
+
+def main():
+
+    if not HAS_MOSQUITTO:
+        module.fail_json(msg="mosquitto is not installed")
+
+
+    module = AnsibleModule(
+        argument_spec=dict(
+            server = dict(default = 'localhost'),
+            port = dict(default = 1883),
+            topic = dict(required = True),
+            payload = dict(required = True),
+            client_id = dict(default = None),
+            qos = dict(default="0", choices=["0", "1", "2"]),
+            retain = dict(default='no', choices=BOOLEANS, type='bool'),
+            username = dict(default = None),
+            password = dict(default = None),
+        ),
+        supports_check_mode=True
+    )
+
+    server     = module.params["server"]
+    port       = module.params["port"]
+    topic      = module.params["topic"]
+    payload    = module.params["payload"]
+    client_id  = module.params["client_id"]
+    qos        = module.params["qos"]
+    retain     = module.params["retain"]
+    username   = module.params["username"]
+    password   = module.params["password"]
+
+    if client_id is None:
+        client_id = "%s_%s" % (socket.getfqdn(), os.getpid())
+
+    if payload and payload == 'None':
+        payload = None
+
+    try:
+        publish(module, topic, payload, server, port, qos, client_id, retain,
+                username, password)
+    except Exception, e:
+        module.fail_json(msg="unable to publish to MQTT broker %s" % (e))
+
+    module.exit_json(changed=True, topic=topic)
+
+# this is magic, see lib/ansible/module_common.py
+#<<INCLUDE_ANSIBLE_MODULE_COMMON>>
+main()