Module mqtt
This module implements the MQTT protocol into the core of SmartHomeNG to make it usable for plugins.
README
A formatted version of the sample README.md can be found here:
A raw version of the README.md for copy and paste can be found below the metadata file.
Metadata
The meta data file:
module.yaml
# Metadata for the plugin
module:
# Global plugin attributes
classname: Mqtt
version: 1.7.6
sh_minversion: 1.6a
# sh_maxversion: # maximum shNG version to use this plugin (leave empty if latest)
description:
de: 'Modul implementiert das MQTT Protokoll zur Nutzung in Logiken und Plugins'
en: 'Module implements the MQTT protocol for use in logics and plugins plugins'
parameters:
# Definition of parameters to be configured in etc/module.yaml
enabled:
type: bool
default: False
description:
de: 'MQTT Unterstützung aktivieren oder deaktivieren'
en: 'Enable or disable MQTT support'
broker_host:
type: ip
default: '127.0.0.1'
description:
de: 'Adresse des MQTT Brokers'
en: 'Address of MQTT broker'
description_long:
de: '**Adresse des MQTT Brokers**: Spezifiziert die IP Adresse des MQTT Brokers.
Wenn der MQTT Broker auf dem selben Rechner auf dem auch SmartHomeNG läuft,
muss dieser Parameter nicht angegeben werden.
'
en: "**Address of MQTT broker**: 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.
"
broker_port:
type: int
default: 1883
valid_min: 0
valid_max: 65535
description:
de: 'Vom Broker benutzter Port'
en: 'Port used by broker'
description_long:
de: '**Vom Broker benutzter Port**: Port 1883 und 8883 sind bei der IANA reservierte Ports für MQTT.\n
\n
- 1883: Der Standard MQTT Port. Er ist bei IANA definiert als **MQTT over TCP**\n
- 8883: Der Standard MQTT Port. Er ist bei IANA definiert als **Secure MQTT**\n
\n
In einem Standard Setup muss dieser Parameter nicht angegeben werden.
'
en: '**Port used by broker**: Port 1883 and 8883 are the IANA reserved ports for MQTT.\n
\n
- 1883: This is the default MQTT port. It is defined at IANA as MQTT over TCP\n
- 8883: This is the default MQTT port for MQTT over TLS. It’s registered at IANA for Secure MQTT\n
\n
In a standard setup you should not need to configure this parameter.
'
broker_client:
type: str
default: 'MQTT-module'
description:
de: 'Client Name für die Broker Kommunikation - Muss nur angegeben werden, falls mehrere SmartHomeNG Installationen zeitgleich mit dem selben Broker kommunizieren sollen'
en: 'Client name for broker communication - Must only be specified if multiple SmartHomeNG installations should communicate concurrently with the same broker'
user:
type: str
default: ''
description:
de: 'Username für das Broker Login (optional)'
en: 'Username for login to the broker (optional)'
description_long:
de: 'Username zum Login beim MQTT Broker, falls der Broker für user/password Authentifizierung konfiguriert ist.\n
\n
**ACHTUNG**: Bis zur Implementierung von TLS, werden Username und Password unverschlüsselt übertragen.
'
en: 'Username to login to the MQTT broker, if the broker is configured for user/password authentication.\n
\n
**NOTICE**: Until Implementation of TLS, username and password are transmitted unencrypted.
'
password:
type: str
default: ''
hide: True
description:
de: 'Passwort für das Broker Login (optional)'
en: 'Password for login to the broker'
description_long:
de: 'Passwort zum Login beim MQTT Broker, falls der Broker für user/password Authentifizierung konfiguriert ist.\n
\n
**ACHTUNG**:\n
\n
- Bis zur Implementierung von TLS, werden Username und Password unverschlüsselt übertragen.\n
- Bei der jetzigen Implementierung wird das Passwort in **../etc/plugin.yaml** im Klartext gespeichert.\n
\n
\n
'
en: 'Password to login to the MQTT broker, if the broker is configured for user/password authentication.\n
\n
**NOTICE**:\n
\n
- Until Implementation of TLS, username and password are transmitted unencrypted.\n
- At this stage of implementation the Password is stored in the plugin.yaml file as clear text.\n
\n
\n
'
broker_monitoring:
type: bool
default: False
description:
de: 'Ermöglicht das Monitoring einiger Broker Werte durch das Web Interfase.'
en: 'Enables monitoring some broker data through the web interface.'
qos:
type: int
default: 1
valid_list:
- 0
- 1
- 2
description:
de: 'Quality of Service'
en: 'Quality of Service'
description_long:
de: '**Quality-Of-Service**: QoS definiert den Standard Quality-of-Service Level für die Kommunikation mit dem Broker. Der Level kann durch setzen des ** mqtt_qos** Attributes in den individuellen Items überschrieben werden.\n
\n
MQTT unterstützt drei Level für den Quality-of-Service (0=at most once, 1=at least once, 2=excactly once). QoS 2 hat den meisten Overhead und sollte nur genutzt werden, wenn unbedingt nötig.\n
\n
Eine gute Erläuterung zu QoS im MQTT Protokoll kann hier gefunden werden: http://www.hivemq.com/blog/mqtt-essentials-part-6-mqtt-quality-of-service-levels (Englisch).\n
'
en: "**Quality-Of-Service**: 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.\n
\n
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.\n
\n
A good explanation about Quality-of-Service in MQTT can be found here: http://www.hivemq.com/blog/mqtt-essentials-part-6-mqtt-quality-of-service-levels.\n
"
bool_values:
type: list
default: None*
description:
de: "Gewünschte Werte (im MQTT Payload) für Publish und Subscribe von boolsche Werten (z.B. ['Falsch','Wahr'])"
en: "Values (in MQTT payload) for publish and subscribe of boolean values (e.g. ['Wrong','Right'])"
last_will_topic:
type: str
gui_type: wide_str
default: ''
description:
de: 'Topic für Last-Will Telegramm'
en: 'Topic for the last will telegram'
description_long:
de: '**MQTT testament Message**: Wenn kein **last_will_topic** angegeben wird,
wird keine MQTT last-will-message gesendet. Als Standard wird eine last-will
message durch den Broker nur versendet wenn die Verbindung des Clients zum Broker
abbricht (sie also nicht ordnungsgemäß geschlossen wird).\n
\n
-> Last-will-messages werden mit dem Standard QoS gesendet.\n
\n
Falls eine birth-message konfiguriert ist, wird die last-will-message mit
gesetztem retain Flag gesendet und die last-will-message wird auch gesendet
wenn die Verbindung ordnungsgemäß geschlossen wird (z.B. beim Beenden
von SmartHomeNG).
'
en: '**MQTT testament message**: if **last_will_topic** is not specified, there will
be no MQTT 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).\n
\n
Last-will-messages will be sent with the default QoS.\n
\n
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).
'
last_will_payload:
type: str
gui_type: wide_str
default: ''
description:
de: 'Payload für die MQTT testament message. Wenn keine **last_will_payload** angegeben wird, wird kein Last-Will Telegramm gesendet.'
en: 'Payload for the MQTT testament message. If **last_will_payload** is not specified, there will be no last-will message sent.'
birth_topic:
type: str
gui_type: wide_str
default: ''
description:
de: 'Topic für das Birth Telegramm'
en: 'Topic for the birth telegramm'
description_long:
de: 'Die birth-Message ist das Gegenteil zur MQTT Testament Message und wird gesendet, wenn das Plugin startet. Falls kein **birth_topic** konfiguriert ist, wird das **last_will_topic** auch für die Birth-Message verwendet. Birth-Messages werden mit der Standard QoS und gesetztem Retain Flag gesendet.'
en: '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.'
birth_payload:
type: str
gui_type: wide_str
default: ''
description:
de: 'Payload für das Birth Telegramm. Wenn keine birth_payload konfiguriert ist, wird keine Birth Message gesendet. In diesem Fall wird auch keine last-will message gesendet, falls die Verbindung ordnungsgemäß geschlossen wird (beim Beenden von SmartHomeNG).'
en: 'Payload for the birth telegram. 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).'
# publish_items:
# type: bool
# default: False
# description:
# de: 'Publiziere die Items'
# en: 'Publish Items'
# description_long:
# de: '-> ***Noch nicht implementiert***\n
# \n
# **publish_items** steuert ob die Items mit ihrem Item-Path publiziert werden
# sollen. Falls publish_items auf True gesetzt ist, werden Items publiziert (unter
# Verwendung von **items_topic_prefix**), falls die ACL-Settings für das Item es
# erlauben.
# '
# en: '-> ***not yet implemented***\n
# \n
# **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.
# '
# items_topic_prefix:
# type: str
# default: 'devices/shng'
# description:
# de: 'Prefix für die publizierten Items'
# en: 'Prefix for the published items'
# description_long:
# de: '-> ***Noch nicht implementiert***\n
# \n
# items_topic_prefix definiert den Präfix beim Erstellen des MQTT Topic vom Item Pathfrom item-path.
# '
# en: '-> ***not yet implemented***\n
# \n
# items_topic_prefix defines the prefix when building the MQTT topic from item-path.
# '
# tls: # Not yet implemented
# type: bool
# default: False
# description:
# de: 'tls zur Verschlüsselung nutzen'
# en: 'Use tls for encyption'
# description_long:
# de: '
# '
# en: '
# '
# ca_certs: # Not yet implemented
# type: str
# default: '/etc/'
# description:
# de: ''
# en: ''
# description_long:
# de: '
# '
# en: '
# '
# acl:
# type: str
# default: 'none'
# valid_list:
# - 'none'
# - 'pub'
# - 'sub'
# - 'pubsub'
# description:
# de: 'Zugriffskontrolle (none/publish/subscribe)'
# en: 'Accesscontrol (none/publish/subscribe)'
# description_long:
# de: '-> ***Noch nicht implementiert***\n
# \n
# **acl** definiert den globalen Default für die Zugriffskontrolle zu den Items.
# Access control ist nur aktiv, wenn die Item-Tree Struktur von SmartHomeNG publiziert wird.\n
# \n
# - none=kein Zugriff\n
# - pub=Publiziere als Topic (Read-Only von anderen Clients aus)\n
# - sub=Abonniere (subscribe) ein Topic (Akzeptiere Daten von anderen Clients)\n
# - pubsub=Publiziere und Abonniere (publish and subscribe) ein Topic.\n
# \n
# Dieser Parameter definert die Standard Zugriffskontrolle für Items, welche keine individuelle Zugriffskontrolle konfiguriert haben.
# '
# en: '-> ***not yet implemented***\n
# \n
# **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.\n
# \n
# - none=no access\n
# - pub=publish as topic (read only from other client)\n
# - sub=subscribe to topic (accept data from other clients)\n
# - pubsub=publish and subscribe topic.\n
# \n
# This parameter defines the default access control for items, which have no individual access control configured.
# '
README.md
# Module mqtt (README)
This module allows plugins to utilize the MQTT protocol. The API is described below.
## Requirements
This module is running under SmartHomeNG versions beyond v1.6.
> Note: This module needs the module handling in SmartHomeNG to be activated. Make sure, that `use_modules`in `etc/smarthome.yaml` is **not** set to False!
## Configuration
### etc/module.yaml
```yaml
# etc/module.yaml
http:
module_name: mqtt
# port: 8383
# servicesport: 8384
# showpluginlist: False
# showservicelist: True
# starturl: backend
# threads: 8
# showtraceback: True
```
#### user (optional
username for the web access. By default username `admin` is used.
#### password (optional)
password for the web access. By default empty. Without a password access is available for everyone.
#### hashed_password (optional)
hashed password for the web access. By default empty. Without a hashed password the parameter password is used.
#### service_user (optional
username for the access to webservices. By default username `serviceuser` is used.
#### service_password (optional)
password for the access to the web services. By default empty. Without a password access is available for everyone.
#### service_hashed_password (optional)
hashed password for access to the web services. By default empty. Without a hashed password the parameter Service_password is used.
#### port (optional)
The port on which the html interface listens. By default port **`8383`** is used.
#### servicesport (optional)
The port on which the html interface listens. By default port **`8384`** is used.
#### showpluginlist
If set to `False` no list of pluins with web interface is shown under `smarthomeNG.local:8383/plugins`. By default, **showpluginlist** is **True**.
#### showservicelist
If set to `True` a list of webservices is shown under `smarthomeNG.local:8384/services`. By default, ** showservicelist** is **False**.
#### starturl (optional)
The name of the plugin that is started when calling url `smarthomeNG.local:8383` without further detailing that url. If you want to startup the **backend** plugin for example: You set `starturl: backend`. That results in a redirect which redirects `smarthomeNG.local:8383` to `smarthomeNG.local:8383/backend`.
if `starturl` is not specified or point to an url that does not exist, a redirect to `smarthomeNG.local:8383/plugins` will take place (if ** showpluginlist** is **True**). It points to a page that lists all plugins that have registered a html interface and allows you to start those interfaces.
> Note: If you have redirected to a specific plugin, you can always get to the page with the list of all plugins that have registered a html interface, by entering the url `smarthomeNG.local:8383/plugins`.
#### threads (optional)
Number of worker threads to start by cherrypy (default 8, which may be too much for slow CPUs)
#### showtraceback
If set to **True, error-pages (except for error 404) will show the Python traceback for that error.
## API of module mqtt
### Test if module mqtt is loaded
`mqtt` is a loadlable module. Therefore there is no guarantiee that it is present in every system. Before you can use this module, you have to make sure ist is loaded. You can do it by calling a method of the main smarthome object. Do it like this:
```
self.classname = self.__class__.__name__
try:
self.mod_mqtt = self._sh.get_module('mqtt')
except:
self.mod_mqtt = None
if self.mod_mqtt == None:
# Do what is necessary if you can't use the mqtt protocol
# for your plugin. For example:
self.logger.error('{}: Module ''mqtt'' not loaded - Abort loading of plugin {0}'.format(self.classname))
return
```
### Methods for implementing a web interface
#### get_local_ip_address()
Returns the ip address under which the web interface is listening.
#### get_local_hostname()
Returns the hostname (with domain) under which the web interface is listening.
#### get_local_port()
Returns the port under which the implemented web interfaces can be reached.
#### get_local_servicesport( ... )
Returns the port under which the implemented webservices can be reached.
#### register_app()
##### Parameters
- **app** - Instance of the CherryPy App
- **pluginname** - Standard would be: Shortname of the plugin (name of the plugin's directory)
- **conf** - dict with CherryPy App-Config
- **pluginclass** - Class of the plugin
- **instance** - Optional: Instance of the plugin (if multi-instance)
- **description** - Optional: Description to be shown on page with plugin-list
#### register_service( ... )
##### Parameters
- **service** - Instance of the CherryPy App
- **servicename** - Standard would be: Shortname of the plugin (name of the plugin's directory)
- **conf** - dict with CherryPy App-Config
- **pluginclass** - Class of the plugin
- **instance** - Optional: Instance of the plugin (if multi-instance)
- **description** - Optional: Description to be shown on page with services-list