MQTT Schnittstelle - GollmerSt/SolvisSmartHomeServer GitHub Wiki

Der SolvisSmartHomeServer unterstützt neben seiner proprietären Server-Client-Schnittstelle noch das MQTT-Protokoll. Aktuell jedoch nur die nichtverschlüsselte Version. Sollte bzgl. einer SSL-Verschlüsselung Bedarf bestehen, bitte eine PM an mich: [email protected]

Bei MQTT kennen sich die Clients untereinander nicht. Für den Server (ist ebenfalls ein MQTT-Client, wird aber weiterhin als Server benannt) ist dies jedoch für bestimmte Befehle notwendig. So muss beispielsweise der Server Informationen an den Client liefern können, wenn der Client selber bei Publish einen Befehl fehlerhaft angewendet hat. Daher muss der Client eine im System eindeutige Id besitzen.

Alle Publish-Befehle des Client müssen daher die Id des Clients im Topic besitzen. Der Aufbau der Topics, den die Clients versetzen muss immer folgenden Aufbau besitzen:

prefix/client/……

Hierbei ist prefix in base.xml unter dem Attribut topicPrefix definiert.

client ist die eindeutige ID des Clients im MQTT-Netzwerk.

Topics, welche der Server versendet sind immer im folgenden Format:

prefix/……

Hierbei ist prefix in base.xml unter dem Attribut topicPrefix definiert.

Eine Ausnahme hierzu ist die Rückmeldung des Servers bei einem Fehler auf Grund eines Publish eines Clients. In diesem Fall wird die Fehlermeldung in folgendes Topic geschrieben:

prefix/client/error

Wichtig:

Das Smarthome-System sollte seinen Online-Status dem Server übermitteln. Wenn er mit dem Server sich "verbindet", sollte er zu Beginn das Online-Topic SolvisSmartHomeServer/ClientId/online auf true setzen. Als MQTT-Last-Will sollte man diesen Wert dann auf "false" setzen.

Bis zur Version 1.3.x war dies zwingend erforderlich, da andernfalls Änderungen der Anlagenparameter nicht möglich waren. Mit Version 1.4.0 wurde dieses Verhalten abgeändert. Von dieser Version an ist das Setzen auf den Wert false nach wie vor wichtig, da damit dann Client-spezifische Einstellungen im Server wieder zurück gesetzt werden.

Die verwendeten Topics des SolvisSmartHomeServers mit einer Kurzbeschreibung kann über die Dokumentationsfunktion erzeugt werden. Das wird vermutlich für die Erstellung der Smarthome-System-Anpassung hilfreich sein. Wie diese Dokumentation zu erstellen ist und der Inhalt dieser Dokumentation wird hier beschrieben.

Alle Topics, welche der Server schreibt (publish) sind vom Typ „present“ mit Ausnahme von „prefix/ client /error“.

Folgende rein Server-spezifischen Topics existieren:

Die JSON-Meta-Beschreibung der Server Befehle sieht folgendermaßen aus:

["backup","restart"]

Folgende Topics sind Anlagen-abhängige den Server-Einstellungen/-Status:

Die JSON-Beschreibung der Anlage-spezifischen Befehle sieht folgendermaßen aus:

["SCREEN_RESTORE_INHIBIT","SCREEN_RESTORE_ENABLE","COMMAND_OPTIMIZATION_INHIBIT","COMMAND_OPTIMIZATION_ENABLE","GUI_COMMANDS_ENABLE",
"GUI_COMMANDS_DISABLE","SERVICE_RESET","UPDATE_CHANNELS"]

Die JSON-Beschreibung der Screen-Namen sieht folgendermaßen aus (bei einem Heizkreis):

["Heizkreis1-4_11","Wasser-Bereitschaft","Zeiteinstellung","NachttemperaturSelected_HK1","Schornsteinfeger","Anlagenstatus-HK","Heizkreis1-1_11","Uhrzeit/Datum","Anlagenstatus-WW","Heizkreise","Installateur-Menue","Brenner-Stufe-2","Sonstiges_Nutzerauswahl","Heizkreis1-2_5","Tagestemperatur_HK1","Wasser-Installateur","Heizkreis1-4_5","Wasser-Anforderung-2/2","Nutzerauswahl","TagestemperaturSelected_HK1","Heizung-Anforderung","Heizung-Installateur","Zirkulation","Home","Sonstiges-3","Heizkreis1-3_11","Sonstiges-2","Solar","Sonstiges-1","Zaehlfunktion","Heizkreis1-3_5","Warmwasser","Heizkreis1-1_5","Heizkreis1-5_5","Heizkreis1-2_11","Wasser-Anforderung-1/2","Nachttemperatur_HK1"]

Folgende Unit-spezifische Topics existieren:

Die JSON-Meta-Beschreibung eines Kanalnamens besitzt folgenden Aufbau:

{
	"Writeable":		boolean,
	"Type":			"type",
	"Unit":			"unit",
	"Accuracy":		float,
	"IsBoolean":		boolean,
	"Upper":		float,
	"Lower":		float,
	"Step":			float,
	"IncrementChange":	float,
	"ChangedIncrement":	float,
	"Modes": 		["mode1","mode2", …, "moden"]
}

Nähere Beschreibung hierzu hier

Mit Version 1.03.00 kann man mittels des Servers die Liste vom Programm selber erstellen lassen. Diese ist immer aktuell und an die durch das base.xml vorgebene Anlagenkonfiguration angepasst. Die Erstellung dieser Liste und die Bedeutung der Spalten ist hier beschrieben. Diese Datei enthält zusätzlich eine Aufstellung aller vom SolvisSmartHomeServer verwendeten Topics mit einer Kurzbeschreibung (ab V1.04.00).

Die Kanäle C*:* werden aus dem GUI der SolvisControl2 ermittelt.