This plugin implements the the functionality for SmartHomeNG to act as a MQTT client.
This plugin is a complete rewrite, replacing the initial MQTT plugin from smarthome.py.
MQTT is a lightweight machine-to-machine (M2M)/"Internet of Things" connectivity protocol. The MQTT protocol was initially developed by IBM. Since protocol version v3.1.1 it has become an official OASIS standard.
Details on the protocol can be found on mqtt.org.
Support is provided trough the support thread within the smarthomeNG forum: Support-Thread
- Fixed error with empty last_will_topic
- allowed Muilti-Instance
- Login to broker with user/password is supported
- Log the type and version of the broker
- configure host by dns-name or ip address
- Added functions to allow other plugins to use this plugin for MQTT communication (documented at the end of this document)
This plugin needs the following following software to be installed and running:
- MQTT python module: paho-mqtt
In Linux systems can use: pip3 install paho-mqtt
- A MQTT broker for communication with other MQTT clients. The broker may be running on the hardware SmartHomeNG is running on, or on another hardware that can be reached via TCP/IP. The open souce broker Mosquitto is a good choice.
If want to run the broker on a Raspberry Pi you should be aware, that the broker on the raspbian repository is quite old. You should add the morquito.org repository as a trusted site to your apt-get to get a recent version of mosquitto installed.
To setup the MQTT plugin only three parameters need to be defined in plugin.yaml:
mqtt:
class_name: Mqtt
class_path: plugins.mqtt
host: '192.168.0.55'All other parameters are optional and only used, if you want to use advanced features. When not configuring the advanced parameters, this plugin should be compatible in usage to the old MQTT plugin from smarthome.py.
mqtt:
class_name: Mqtt
class_path: plugins.mqtt
host: '192.168.0.55'
# port: 1883
# qos: 1
# last_will_topic: 'shng/$online'
# last_will_payload: False
# birth_topic: 'shng/$online'
# birth_payload: True
# user: None # username (or None)
# password: None # password (or None)
# hashed_password: 1245a9633edf47b7091f37c4d294b5be5a9936c81 ...
# === The following parameters are not yet implemented:
# publish_items: no # NEW: publish using item-path
# items_topic_prefix: 'shng' # NEW: prefix for publishing items
# acl: pub # NEW: access control (none, pub, sub, pubsub)
# tls: None # use TLS version (v1 or None)
# ca_certs: '/etc/...' # path to the Certificate Authority certificate files All entries that are commented out are optional and don't have to be specified to get the plugin up and running.
host specifies the IP adress of the MQTT broker to use. If you use a broker on the computer you are running SmartHomeNG on, you don't need to specify this parameter. In this case it is assumed, that the MQTT broker runs on the same machine as SmartHomeNG and 127.0.0.1 (for localhost) is used.
Port 1883 and 8883 are the IANA reserved ports for MQTT.
- 1883: This is the default MQTT port. It is defined at IANA as MQTT over TCP.
- 8883: This is the default MQTT port for MQTT over TLS. It’s registered at IANA for Secure MQTT.
In a standard setup you should not need to configure this parameter.
qos defines the default quality of service level used when communicating with the broker. It can be overwritten by setting the mqtt_qos attribute on an individual item.
You don't have to specify a settings for qos. The default value used will be QoS 1.
MQTT supports three levels for Quality-Of-Service (0=at most once, 1=at least once, 2=excactly once). QoS 2 has the most overhead and should be used only if needed.
A good explanation about Quality-of-Service in MQTT can be found here.
if last_will_topic is not specified, there will be no last-will-message sent. As a standard the last-will message will only be sent if the connection to the broker aborts (is not closed in an orderly manner).
Last-will-messages will be sent with the default QoS.
If you specify a birth-message, the last-will-message will be sent with the retain flag set and the last-will-message will also be sent if the connection is closed orderly (by shutting down SmartHomeNG).
if last_will_payload is not specified, there will be no last-will message sent.
The birth message is the opposite to the MQTT Testament message and sent, when the plugin starts up. if birth_topic is not specified, the last_will_topic will be used for the birth message too. Birth-messages will be sent with the default QoS and the retain flag set.
if birth_payload is not specified, no birth message will be sent. In this case there will be no last-will message sent, if the connection is closed orderly (by shutting down SmartHomeNG).
Username to login to the MQTT broker, if the broker is configured for user/password authentication.
NOTICE: Until Implementation of TLS, username and password are transmitted unencrypted.
Password to login to the MQTT broker, if the broker is configured for user/password authentication.
NOTICE:
- Until Implementation of TLS, username and password are transmitted unencrypted.
- At this stage of implementation the Password is stored in the plugin.yaml file as clear text.
The password for broker login as hash value. Can be used instead of "password" if you do not want a plaintext password in your config file. Currently hashed_password is the SHA-512 hash value of the password. To create the hash for your password, you can use function "Create password hash" on page "Services" in the backend.
-> ***not yet implemented***
publish_items controls weather the items should be published by their item-path. If publish_items is set to True, items are published (using items_topic_prefix) if the acl-setting for that items allows it.
-> ***not yet implemented***
items_topic_prefix defines the prefix when building the MQTT topic from item-path.
Example: If you have the following items:
root:
parent:
testitem:
name: Test Item for publishing
type: numand have set
mqtt:
items_topic_prefix: 'item_tree'The item testitem would be published with the MQTT topic
item_tree/root/parent/testitem
-> ***not yet implemented***
acl defines the global default setting for the access control to the items. Access control is only active, when publishing the item-tree structure of SmartHomeNG.
- none=no access (default, if parameter is not configured)
- pub=publish as topic (read only from other client)
- sub=subscribe to topic (accept data from other clients)
- pubsub=publish and subscribe topic.
This parameter defines the default access control for items, which have no individual access control configured.
-> ***not yet implemented***
Use tls for encryption
-> ***not yet implemented***
path to certificate files
Example configuration in yaml-format:
alarm_in_
# messages coming from the alarm panel
# (called 'alarm/out' by the alarm panel)
name: alarm_test_mqtt_in
type: foo
mqtt_topic_in: 'alarm/out'
alarm_out:
# messages published, to be read by the alarm panel
name: alarm_test_mqtt_out
type: foo
mqtt_topic_out: 'alarm/in'
Example configuration in the old conf-format:
[[alarm_in_]]
# messages coming from the alarm panel
# (called 'alarm/out' by the alarm panel)
name = alarm_test_mqtt_in
type = foo
mqtt_topic_in = 'alarm/out'
[[alarm_out]]
# messages published, to be read by the alarm panel
name = alarm_test_mqtt_out
type = foo
mqtt_topic_out = 'alarm/in'
Datatype foo delivers the raw data from the MQTT message to the item (as an array of bytes).
NEW: You can use any of the other datatypes. If you use any of those datatypes, the data from the mqtt message will be casted to the desired format.
mqtt_topic_out defines the MQTT topic under which the items value is to be published as payload.
mqtt_topic_init is equivalent to mqtt_topic_out, except it initializes the topic when SmartHomeNG ist started.
mqtt_topic_in defines the MQTT topic to subscribe to. Upon receiving a message with this topic, the payload is used to set the item's value.
If you specify mqtt_topic, it set this topic for in- and outgoing messages. Thus it overwrites seperate values you might have specified for mqtt_topic_out or mqtt_topic_in.
-> ***not yet implemented***
mqtt_acl defines the access control setting for this item. If not specified, the plugin's default is used. Access control is only active, when publishing the item-tree structure of SmartHomeNG.
mqtt_qos defines the quality of service level for this item used when communicating with the broker. If not specified, the plugin's default is used.
When set to True, the MQTT message is sent with the retain flag set.
Now you could simply use:
sh.alarm_out(arm) to send a mqtt message via the topic 'alarm/out'.
sh.alarm_in() to see messages coming from mqtt bus via topic 'alarm/in'
You can specify a MQTT topic to trigger a logic. The logic is triggered every time a message with this topic is received.
Alarm:
mqtt_watch_topic: alarm_in # monitor for changes
# mqtt_payload_type: strmqtt_watch_topic specifies the MQTT topic which triggers the logic. A logic that is triggered by the MQTT plugin gets the following information:
- trigger['by']
MQTTorMQTT@<instance> - trigger['source'] topic of the MQTT message
- trigger['value'] payload of the MQTT message
if mqtt_payload_type is specified, the payload is converted to the SmartHomeNG datatype before being handed to the logic. Otherwise the payload is handed over as raw data (array of bytes).
Version 1.3.2 added functions to allow other plugins to use this plugin for MQTT communication.
Example: A plugin (enow) to communicate with an EnOcean gateway over MQTT.
(Links to this example will be added later.)
function to publish a topic
this function is to be called from other plugins, which are utilizing
the mqtt plugin
:param topic: topic to publish to
:param payload: payload to publish
:param qos: quality of service (optional) otherwise the default of the mqtt plugin will be used
:param retain: retain flag (optional)
function set a callback function
this function is to be called from other plugins, which are utilizing
the mqtt plugin
:param plug: identifier of plgin/logic using the MQTT plugin
:param sub: topic(s) which should call the callback function
example: 'device/eno-gw1/#'
:param callback: quality of service (optional) otherwise the default of the mqtt plugin will be used
function to subscribe to a topic
this function is to be called from other plugins, which are utilizing
the mqtt plugin
:param topic: topic to subscribe to
:param qos: quality of service (optional) otherwise the default of the mqtt plugin will be used