Bisher war in SmartHomeNG das eigentliche MQTT Protokoll im mqtt Plugin implementiert.

In SmartHomeNG v1.7 wurde die Unterstützung des eigentlichen MQTT Protokolls in den Core verlagert. Die Implementierung erfolgte als ein ladbares Modul. Es gibt nun ein neues mqtt Plugin, welches die Protokoll Unterstützung des Core nutzt.

Diese Änderung bringt neue Funktionalitäten mit sich:

• Logiken können das MQTT Protokoll nutzen. Wie das genau geht, ist in der Anwender Dokumentation zu SmartHomeNG beschrieben.
• Weitere Plugins können das MQTT Protokoll nutzen und darauf aufbauend Payload-Protokolle zu verschiedenen Devices implementieren, ohne das eigentliche MQTT Protokoll selbst implementieren zu müssen. Ein Beispiel hierfür ist das shelly Plugin, welches mit SmartHomeNG v1.7 hinzugekommen ist und die einfache Ansteuerung verschiedener Shelly Devices über MQTT ermöglicht. Details zu diesem Plugin sind in der Anwender Dokumentation zu SmartHomeNG beschrieben.

Konfiguration des MQTT Moduls

Durch die Verlagerung in den Core, ist auch die Konfiguration des MQTT Protokolls an eine andere Stelle gewandert. Die Konfiguration kann über die graphische Oberfläche oder direkt in der entsprechenden Konfigurationsdatei erfolgen:

In der GUI finden sich die Einstellungen unter System/Konfiguration im Tab MQTT Modul:

Damit die Konfiguration wirksam wird und das MQTT Modul beim Restart von SmartHomeNG geladen wird, muss der Parameter enabled auf true gesetzt werden.

Alternativ kann die Konfiguration direkt in der Datei ../etc/module.yaml erfolgen. In der Datei muss ein Abschnitt mqtt: angelegt werden, der einen Eintrag module_name: mqtt enthält. In diesem Abschnitt können dann die Parameter konfiguriert werden.

Beispiel:

mqtt:
    module_name: mqtt
    # broker_host: smarthomeng.local
    broker_monitoring: true
    # qos: 1
    # acl: ''
    last_will_topic: devices/shng-module/$online
    last_will_payload: 'False'
    birth_topic: devices/shng-module/$online
    birth_payload: 'True'
    # bool_values: ['Falsch', 'Wahr']
    # user: user
    # password: geheim

Konfiguration des MQTT Plugins

Die Funktionalität, die das MQTT Plugin zur Verfügung stellte, gibt es weiterhin. Das MQTT Plugin ist entsprechend angepasst worden und nutzt zur Kommunikation jetzt die MQTT Unterstützung des Core. Das Plugin hat jedoch keine Parameter mehr, die konfiguriert werden müssten. Die Item Attribute (mqtt_topic, mqtt_topic_in, mqtt_topic_out, etc.) sind unverändert erhalten geblieben.

Eine Konfiguration des mqtt Plugins in der Plugin Konfigurationsdatei ../etc/plugin.yaml sieht folgendermaßen aus:

mqtt:
    plugin_name: mqtt

Eine Reihe von Devices liefert Antworten bzw. Stati in Form von JSON formatierten Daten zurück. Diese Daten können in Items verwendet werden, wenn sie in Items vom Typ dict oder vom Typ list eingelesen werden können.

Einlesen von JSON Messages in dicts mit dem MQTT Plugin

Besonders einfach ist das Einlesen von Daten in Items der Typs dict, wenn man MQTT Messages mit dem aktuellen MQTT Plugin empfängt. Das MQTT Protokoll bis zur Version 3.1x unterstützt keine Datentypen. Die Payload, also die übertragenen Daten, werden immer als Array of Byte übertragen.

Das aktuelle MQTT Plugin unterstützt das Casting in den Datentyp des Items. Wenn also z.B. das Item vom Typ str ist, wird beim Empfang das Array of Byte in einen String gewandelt.

Wenn man in der Payload der MQTT Message JSON formatierte Daten in ein Item vom Typ dict empfängt, werden die Daten in Form eines Python dict gespeichert und können in Logiken und eval-Ausdrücken entsprechend weiter verarbeitet werden.

Bei komplexen JSON Strukturen ist die Weiterverarbeitung mit einer Logik zu empfehlen. Bei einfacheren Strukturen kann die Weiterverarbeitung jedoch auch sehr gut in Items mit Hilfe von eval oder on_change erfolgen.

Ein einfaches JSON Beispiel

Wenn eine MQTT Message z.B. folgende Daten liefert:

{  
   "key1":"value1",
   "key2":"value2",
   "key3":"value3"
}

und Du nur den Wert von key2 benötigst, kannst Du das über ein Hilfs-Item lösen, in dem Du die MQTT Payload einliest und den entsprechenden Wert in das Ziel-Item schreibst. Dazu musst Du die Items folgendermaßen definieren:

test:
    hilfs_item:
        type: dict
        mqtt_topic_in: test/test
        on_change: ..ziel_item = value['key2']

    ziel_item:
        type: str

Das MQTT Topic musst Du durch einen sinnvollen Wert ersetzen. Natürlich kann im on_change Attribut anstelle der relativen Item Adressierung auch die absolute Adressierung (test.ziel_item) verwendet werden.

Alternativ kannst Du das auch mit eval / eval_trigger lösen:

test:
    hilfs_item:
        type: dict
        mqtt_topic_in: test/test

    ziel_item:
        type: str
        eval: sh.test.hilfs_item()['key2']
        eval_trigger: test.hilfs_item

Diese Variante kannst Du natürlich auch mit relativer Item-Adressierung realisieren.

Einlesen von JSON Messages in lists mit dem MQTT Plugin

Wenn man in der Payload der MQTT Message JSON formatierte Daten in ein Item vom Typ list empfängt, werden die Daten in Form eines Python list gespeichert und können in Logiken und eval-Ausdrücken entsprechend weiter verarbeitet werden.

Ein einfaches JSON Beispiel

Wenn eine MQTT Message z.B. folgende Daten liefert:

[  
   "value1",
   "value2",
   "value3"
]

und Du nur den zweiten Wert von benötigst, kannst Du das über ein Hilfs-Item lösen, in dem Du die MQTT Payload einliest und den entsprechenden Wert in das Ziel-Item schreibst.

Listen sind so definiert, dass das ersten Element den Index 0 hat. Um den zweiten Wert zu adressieren, musst Du den Index 1 verwenden. Dazu musst Du die Items folgendermaßen definieren:

test:
    hilfs_item:
        type: list
        mqtt_topic_in: test/test
        on_change: ..ziel_item = value[1]

    ziel_item:
        type: str

Auswertung komplexerer Datenstrukturen

Ein dict oder eine list kann statt einfacher Daten auch dicts oder lists enthalten. Auch diese Daten lassen sich auswerten und es können Einzelwerte dieser Datenstruktur in Items gespeichert werden.

Wenn eine MQTT Message z.B. folgende Daten liefert:

{  
   "key1":"value1",
   "key2":[  
      "value21",
      "value22",
      "value23"
   ],
   "key3":{  
      "key31":"value31",
      "key32":"value32",
      "key33":"value33"
   }
}

kannst Du folgendermaßen auf den value22 oder den value33 zugreifen:

test:
    hilfs_item:
        type: dict
        mqtt_topic_in: test/test
        on_change: 
          - ..ziel_item1 = value['key2'][0]
          - ..ziel_item2 = value['key3']['key33']

    ziel_item1:
        type: str

    ziel_item2:
        type: str