Plugin mqtt

protocol plugin

Im folgenden sind etwaige Anforderungen und unterstützte Hardware beschrieben. Danach folgt die Beschreibung, wie das Plugin mqtt konfiguriert wird. Außerdem ist im folgenden beschrieben, wie das Plugin in den Item Definitionen genutzt werden kann. [1]

Beschreibung

Dieses Plugin implementiert die Funktionalität, damit SmartHomeNG als ein MQTT Client agieren kann.

Dieses Plugin ist ein kompletter Re-Write, der das initiale MQTT plugin aus smarthome.py ersetzt. MQTT ist ein leichtgewichtiges Maschinen-zu-Maschinen (M2M)/“Internet of Things“ Konnektivitäts-Protokoll. Das MQTT Protokoll wurde urspünglich von IBM entwickelt. Seit der Protokoll Version v3.1.1 wurde es im Jahre 2014 zum offiziellen OASIS Standard.

Details zu dem Protokoll können unter http://mqtt.org gefunden werden.

Anforderungen

Das Plugin benötigt die folgende Software:

  • MQTT python module: paho-mqtt - Auf Linux Systemen kann die Software mit pip3 install paho-mqtt installiert werden.
  • Ein MQTT Broker wird für die Kommunikation mit anderen MQTT Clients benötigt. Der Broker kann auf des selben Hardware laufen wie SmartHomeNG. Alternativ kann der Broker auf anderer per TCP/IP erreichbarer Hardwae laufen. Der Open Source Broker Mosquitto ist eine gute Wahl.
  • Minimum SmartHomeNG Version: 1.4

Konfiguration

Im folgenden ist beschrieben, wie das Plugin mqtt konfiguriert wird. Außerdem ist im folgenden beschrieben, wie das Plugin in den Item Definitionen genutzt werden kann.

Parameter

Das Plugin verfügt über folgende Parameter, die in der Datei ../etc/plugin.yaml konfiguriert werden:

acl

-> *Noch nicht implementiert*

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.

  • none=kein Zugriff
  • pub=Publiziere als Topic (Read-Only von anderen Clients aus)
  • sub=Abonniere (subscribe) ein Topic (Akzeptiere Daten von anderen Clients)
  • pubsub=Publiziere und Abonniere (publish and subscribe) ein Topic.

Dieser Parameter definert die Standard Zugriffskontrolle für Items, welche keine individuelle Zugriffskontrolle konfiguriert haben.

  • Datentyp: str
  • Standardwert: none
  • Mögliche Werte:
    • none
    • pub
    • sub
    • pubsub

birth_payload

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).

  • Datentyp: str

birth_topic

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.

  • Datentyp: str

broker_monitoring

Ermöglicht das Monitoring einiger Broker Werte durch das Web Interfase.

  • Datentyp: bool
  • Standardwert: False

host

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.

  • Datentyp: ip
  • Standardwert: 127.0.0.1

items_topic_prefix

-> *Noch nicht implementiert*

items_topic_prefix definiert den Präfix beim Erstellen des MQTT Topic vom Item Pathfrom item-path.

  • Datentyp: str
  • Standardwert: devices/shng

last_will_payload

Payload für die MQTT testament message. Wenn keine last_will_payload angegeben wird, wird kein Last-Will Telegramm gesendet.

  • Datentyp: str

last_will_topic

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).

-> Last-will-messages werden mit dem Standard QoS gesendet.

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).

  • Datentyp: str

password

Passwort zum Login beim MQTT Broker, falls der Broker für user/password Authentifizierung konfiguriert ist.

ACHTUNG:

  • Bis zur Implementierung von TLS, werden Username und Password unverschlüsselt übertragen.
  • Bei der jetzigen Implementierung wird das Passwort in ../etc/plugin.yaml im Klartext gespeichert.
  • Datentyp: str

port

Vom Broker benutzter Port: Port 1883 und 8883 sind bei der IANA reservierte Ports für MQTT.

  • 1883: Der Standard MQTT Port. Er ist bei IANA definiert als MQTT over TCP
  • 8883: Der Standard MQTT Port. Er ist bei IANA definiert als Secure MQTT

In einem Standard Setup muss dieser Parameter nicht angegeben werden.

  • Datentyp: int
  • Standardwert: 1883

publish_items

-> *Noch nicht implementiert*

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.

  • Datentyp: bool
  • Standardwert: False

qos

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.

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.

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).

  • Datentyp: int
  • Standardwert: 1
  • Mögliche Werte:
    • 0
    • 1
    • 2

user

Username zum Login beim MQTT Broker, falls der Broker für user/password Authentifizierung konfiguriert ist.

ACHTUNG: Bis zur Implementierung von TLS, werden Username und Password unverschlüsselt übertragen.

  • Datentyp: str

Item Attribute

Das Plugin unterstützt folgende Item Attribute, die in den Dateien im Verzeichnis ../items verwendet werden:

mqtt_qos

mqtt_qos definert den Quality of Service Level, der für dieses Item bei der Kommunikation mit dem Broker genutzt wird. Falls nicht angegeben, wird das globale Setting des Plugins genutzt.

  • Datentyp: int
  • Mögliche Werte:
    • 0
    • 1
    • 2

mqtt_retain

Wenn mqtt_retain auf True gesetzt ist, werden MQTT Messages für dieses Item mit gesetztem Reatin Flag gesendet.

  • Datentyp: bool

mqtt_topic

Wenn mqtt_topic konfiguriert ist, wird das Topic für ein- und ausgehende Messages verwendet. Dabei werden evtl. konfigurierte seperate Werte für mqtt_topic_out und mqtt_topic_in überschrieben.

  • Datentyp: str

mqtt_topic_in

mqtt_topic_in definiert das MQTT Topic, welches abonniert wird. Bei Empfang einer Message mit diesem Topic, wird die Payload benutzt um den Wert des Items zu setzen.

  • Datentyp: str

mqtt_topic_init

mqtt_topic_init ist äquivalent zu mqtt_topic_out, außer dass das Topic beim Start von SmartHomeNG initialisiert (also eine MQTT message gesendet) wird.

  • Datentyp: str

mqtt_topic_out

mqtt_topic_out definiert das MQTT Topic unter dem der Wert des Items als Payload publiziert wird.

  • Datentyp: str
[1]Diese Seite wurde aus den Metadaten des Plugins erzeugt. Für den Fall, dass diese Seite nicht alle benötigten Informationen enthält, bitte auf die englischsprachige README Datei des Plugins zugreifen.