Schnittstelle Server – Client - GollmerSt/SolvisSmartHomeServer GitHub Wiki

Die Kommunikation zwischen Server und Client basiert auf JSON.

Stand: 26.05.2021, Format-Version: 03.00

1. Client -> Server: CONNECT mit Namen der Solvis-Anlage
2. Server -> Client: CONNECTED mit Client-ID
3. Server -> Client: CHANNEL_DESCRIPTIONS
4. Server -> Client: MEASUREMENTS
5. Server -> Client: SOLVIS_STATE

Anschließend treffen beim Client dann neue Datenpakete ein, wenn sich die entsprechenden Messwerte geändert haben (MEASUREMENTS ) oder der Status der Solvis-Anlage geändert hat (SOLVIS_STATE).

Der Client kann SET- und GET-Befehle senden. Ist der Name der Solvis-Anlage unbekannt, liefert der Server ein CONNECTION_STATE-Paket mit dem ConnectionStatus „CONNECTION_NOT_POSSIBLE“.

Nach einer Unterbrechung der Verbindung kann der Client die Verbindung wiederaufbauen oder einen ganz neue Verbindung initiieren. Letzteres entspricht dem obigen Ablauf, bei dem Client-spezifische Server-Einstellungen verloren gehen. Es empfiehlt sich daher die Verbindung wie folgt wieder herzustellen:

1. Client -> Server: RECONNECT mit Client-ID
2. Server -> Client: MEASUREMENTS
3. Server -> Client: SOLVIS_STATE

Ist der Wiederaufbau nicht erfolgreich (z.B. Client-ID unbekannt), wird ein CONNECTION_STATE-Paket vom Server zum Client gesendet mit den ConnectionStatus „CLIENT_UNKNOWN“.

War der Wieraufbau der Verbindung erfolgreich, werden wieder GET/SET/MEASUREMENTS/SOLVIS_STATE-Pakete ausgetauscht.

Die Schnittstelle zwischen Server und Client basiert auf JSON.

Da das JSON-Format hierarchisch aufgebaut ist und nicht jedes SmartHome-System den JSON-Parser mittels eines Streams versorgen kann, so dass der Parser selber das Ende der JSON-Daten erkennt, werden die JSON-Daten in einem Frame versendet.

Dieser Frame sie wie folgt aus:

• 3 Byte mit der Länge des JSON-Files liegt wie in Netzwerken üblich im Big-Endian-Reihenfolge vor (MSB zuerst, LSB zuletzt).
• JSON-Datensatz UTF-8 kodiert.

Folgende JSON-Datensätze sind definiert:

Der Connect-Datensatz wird vom Client versendet und initiiert den Verbindungsaufbau. Er ist wie folgt aufgebaut:

{"CONNECT":
     {"Id":"Name der Anlage"}
}

Der Name der Anlage ist die Id der Unit, welche im base.xml-File definiert ist.

Mit dem CONNECTED-Datensatz teilt der Server dem Client den Erfolg der Verbindung mit (Server existiert und Unit-Id ist im base.xml eingetragen). Er ist wie folgt aufgebaut:

{"CONNECTED":{"ClientId":427735588,"ServerVersion":"01.02.01","FormatVersion":"01.02" }}

Die Client-Id dient der künftigen Identifikation des Clients, falls die Übertragung zwischen Server und Client unterbrochen und wieder neu aufgebaut wird. Neben der Client-Id werden die aktuelle ServerVersion sowie die FormatVersion der JSON-Übertragung mitgeliefert. Wenn das JSON-Übertragungsformat in künftigen Versionen nicht mehr kompatibel ist, wird letztere angepasst. Damit erkennt der Client dass er zu den empfangenen JSON-Paketen nicht mehr kompatibel ist.

Nach dem der Client CONNECTED empfangen hat, ist der Server für Befehle (GET, SET, SERVER-Commands) des Clients empfangsbereit. Im Falle einer Verbindungs-Unterbrechung versucht der Client mittels RECONNECT diese wieder aufzubauen:

Ist die Verbindung unterbrochen worden, kann der Client die Verbindung zum Server durch senden des RECONNECT-Datensatzes wieder aufbauen. Er ist wie folgt aufgebaut:

{"RECONNECT":{"Id":Client-Id}}

Die Client-Id ist eine 32-Bit-Integer-Zahl (vorzeichenbehaftet), welche der Server im Datenpaket CONNECTED geliefert hatte. Eine Unterscheidung zwischen CONNECT und RECONNECT ist notwendig, da der Client bestimmte Einstellungen im Server durchführen kann (z.B. SCREEN_RESTORE_INHIBIT). Diese Einstellungen sind Client-bezogen, bei einem CONNECT würden diese verloren gehen. Ist die Verbindung zu lange unterbrochen, werden diese Client-abhängige Einstellungen zurück gesetzt und der Client erhält bei einem Verbindungsversuch über RECONNECT eine Abweisung. Er muss sich dann mittels CONNECT erneut verbinden, die vorherigen Einstellungen sind dann zurück gesetzt. Der Timeout ist im control.xml-File definiert und ist aktuell auf 5 Minuten gesetzt (connectionHoldTime_ms).

Der Client kann die Verbindung durch senden des DISCONNECT-Pakets abbrechen. Es ist wie folgt aufgebaut:

{"DISCONNECT": null }

Mit dieser Anweisung wird die Verbindung zwischen Server und Client endgültig getrennt. Die Client-spezifischen Einstellungen sowie die Client-Id auf der Server-Seite werden gelöscht.

Dieses Paket sendet der Server an den Client. Es ist wie folgt aufgebaut:

{"CONNECTION_STATE": {"State": "<state>", "Message": "<message>" }

<state> kann folgende Werte annehmen:

Die Status USER_ACCESS_DETECTED, SERVICE_ACCESS_DETECTED und HUMAN_ACCESS_FINISHED sind ab Version 01.02.11 (ab Format-Version 2.00) im SOLVIS_STATE zu finden. CONNECTION_STATE soll nur etwas über die Verbindung zwischen Server und Client etwas aussagen. Daher war einen Bereinigung notwendig.

<message> ist optional und liefert zusätzliche Information für den Log.

Nach dem Aufbau der Verbindung über CONNECT liefert der Server das Descriptions-Paket. Es enthält die Meta-Daten der Kanäle und der möglichen Server-Commands. Dieses Paket besitzt folgenden Aufbau:

{"DESCRIPTIONS": {
	"Name 1": {
		"Writeable":		boolean,
		"Type":			"type",
		"Unit":			"unit",
		"Accuracy":		float,
		"IsBoolean":		boolean,
		"Upper":		float,
		"Lower":		float,
		"Step":			float,
		"IncrementChange":	float,
		"ChangedIncrement":	float,
		"Modes": 		[
                                           {"Name":"mode1", "Handling": "handling"},
                                           {"Name":"mode2", "Handling": "handling"},
                                             …
                                        ]
		},
	"Name 2":…………………………
	}
}

DESCRIPTIONS enthält für jeden Kanal/Server-Command eine Eigenschaft, wobei der Schlüssel der Name des Kanals bzw. der Server-Befehl ist. Der Wert ist dann ein weiteres JSON-Objekt in dem die Eigenschaften des Kanals bzw. Server-Befehls beschrieben sind.

Es existieren folgende Schlüssel:

Zur Beschreibung einer Wertemenge von Zahlen dienen folgende Schlüssel:

Bei einer Beschreibung eines Modes (z.B. WW-Pumpe, Anlagenmodus) gibt es dann noch folgenden Schlüssel:

Ein Mode-Object besitz folgende Schlüssel:

Die meisten Schlüssel sind optional, nur die Schlüssel Writeable und Type müssen immer vorhanden sein. Nur wenn der Wert beschreibbar ist, existiert die Beschreibung der Wertemenge.

Folgende Typen sind aktuell definiert:

Dieses Paket sendet der Server an den Client und wird bei jeder Status-Änderung der Anlage versendet. Das Paket hat folgenden Aufbau:

{"SOLVIS_STATE": {"SolvisState": "<state>", "Message": "<message>" }

<state> kann folgende Werte annehmen:

<message> liefert zusätzliche Information im Fehlerfall.

Die gemessenen Werte sendet der Server bei Veränderungen an den Client in Form des MEASUREMENTS-Pakets. Es besitzt folgenden Aufbau:

{"MEASUREMENTS": { 
	"Kanalname 1": boolean/float/"String",
	"Kanalname 2": boolean/float/"String",
	……………
	"Kanalname n": boolean/float/"String",
	}
}

Zum Verändern der Anlagenwerte (Type CONTROL) sendet der Client an den Server das SET-Package. Es hat folgenden Aufbau:

{"SET":{"Kanalname": boolean/float/"String"}}

CONTROL-Werte werden nicht periodisch abgefragt, da immer ein Eingriff auf das GUI der Solvis-Anlage notwendig ist. Um die neuen Werte ermitteln zu können, kann der GUI-Auslesevorgang mit dem GET-Paket veranlasst werden. Dazu sendet der Client an den Server dieses Paket. Es hat folgenden Aufbau:

{"GET":{"Kanalname":null}} 

Der GET-Befehl aktualisiert sämtliche Kanäle, welche sich auf dem gleichen Bildschirm befinden, wie der Kanalname. So wird beim Leseen des Kanales C01.StartsBrenner auch die Werte der Kanäle C02.LaufzeitBrenner und C03.LaufzeitAnforderung2 aktualisiert.

Die Alternative zu GET ist der ServerCommand UPDATE_CHANNELS. Er aktualisiert mit einem Befehl genau die Kanäle, welche nur über das GUI zugänglich sind und welche sich ohne Anwenderzugriff geändert haben können.

Der GET-Befehl ist daher nur selten sinnvoll, z.B. dann wenn man im Zusammenhang mit dem ServerCommand SCREEN_RESTORE_INHIBIT genau einen Kanal in kurzen Abständen beobachten will. Denn in diesem Fall wechselt der Bildschirm nicht mehr und der GET-Command liefert schnell das Ergebnis, falls sich der Wert geändert hat (über das MEASUREMENTS-Paket). Im Anschluss darf man nicht vergessen SCREEN_RESTORE_ENABLE zu senden.

(Stand 25.02.2021)

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

Das Smarthome-System kann noch verschiedne Befehle an den Server senden. Sie haben Einfluss auf den weiteren Ablauf. Das vom Client zu sendende JSON-Paket besitzt folgenden Aufbau:

{"SERVER_COMMAND":{"Command": "String"}}

String ist der eigentliche Server-Befehl. Folgende sind aktuell definiert (Stand 17.05.2021):

Normalerweise wird vor Ausführung eines Gui-Befehls der aktuell auf der SolvisControl 2 dargestellte Bildschirm bestimmt und gemerkt. Nach Ausführung des Gui-Befehls wird zu diesem dann wieder zurückgegangen. Will man dieses Verhalten nicht haben, kann man es entweder mit dem Server-Command SCREEN_RESTORE_INHIBIT deaktivieren oder man bestimmt einen bestimmten Bildschirm, welcher entweder nach einem Gui-Befehl oder nach einem Anwenderzugriff angefahren werden soll. Letztres erfolgt durch den Befehl SELECT_SCREEN. Das vom Client zu sendende JSON-Paket besitzt folgenden Aufbau:

{"SELECT_SCREEN":{"Screen": "String"}}

String ist der dann Bildschirm im Ruhezustand immer angefahren wird.

Wird als String der Wert NONE gesendet, wird dieses Verhalten wieder deaktiviert.