libgfaservices/mqttcl/topic.txt

////////////////////////////////////////////////////////////////////////////////////

Allgemeines Topic-Format:

<DeviceID>/<ShmID>/<Format>/<Command>/<VarPath>

<DeviceID>:	Kombination aus Device-Prefix (wird in der Config-Datei konfiguriert (default: "GfA")) und der MAC-Adresse der ersten Ethernetschnittstelle (falls vorhanden "eth0").
<ShmID>:	Kombination aus dem Prefix "SHM" und der UUID der SHM.

(MAC-Adresse und UUID in Großbuchstaben).


////////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////

Topic zum Publishen von Variablen-Werten:

<Format>:	"BINLE" (binär little endian), "BINBE" (binär big endian), "JSON" oder "PBUF" (Protocol Buffers, nicht implementiert).
<Command>:	"VALUE".

Beispiel:

"VarioNet-6C:EC:EB:67:5B:13/SHM-F93A047F-D3D0-40E3-965D-08D17E393A19/JSON/VALUE/struct1/struct2/var3": Wert von "struct1.struct2.var3" im JSON-Format.

"VarioNet-6C:EC:EB:67:5B:13/SHM-F93A047F-D3D0-40E3-965D-08D17E393A19/JSON/VALUE/struct1/array1/2": Wert von "struct1.array1[2]" im JSON-Format. ("array1" ist hier ein Array aus skalaren Werten.)

"VarioNet-6C:EC:EB:67:5B:13/SHM-F93A047F-D3D0-40E3-965D-08D17E393A19/BINLE/VALUE/struct1/array2/0/var3": Wert von "struct1.array2[0].var3" im Binärformat (little endian). ("array2" ist hier ein Array aus Strukturen.)



Das JSON-Format ist wie folgt definiert:

{
	"path": "/<VarPath>",
	"index": <Index oder -1>,
	"name": "<VarName>",
	"value": <Scalar>
}

Beispiel:

{
	"path": "/struct1/struct2/var3",	// vollständiger Pfad
	"index": -1,						// Variable ist kein Arrayelement
	"name": "var3",						// Variablenname
	"value": 1.25						// Wert von "struct1.struct2.var3"
}

{
	"path": "/struct1/array1/2",		// vollständiger Pfad
	"index": 2,							// Index des Arrayelementes
	"name": "array1",					// Variablenname (ohne Index)
	"value": "Hello world!"				// Wert von "struct1.array1[2]", ("array1" ist in diesem Beispiel ein Array aus Strings)
}

{
	"path": "/struct1/array2/0/var3",	// vollständiger Pfad
	"index": -1,						// Variable ist kein Arrayelement
	"name": "var3",						// Variablenname
	"value": 2563						// Wert von "struct1.array2[0].var3"
}



////////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////

Topic zum Setzen von Variablen-Werten:

<Format>:	"BINLE" (little endian), "BINBE" (big endian), "JSON" oder "PBUF" (Protocol Buffers, nicht implementiert).
<Command>:	"SET".
Beispiel:

"VarioNet-6C:EC:EB:67:5B:13/SHM-F93A047F-D3D0-40E3-965D-08D17E393A19/JSON/SET/struct1/struct2/var3", Payload: {"value":14.5}: Setzt den Wert von "struct1.struct2.var3" im JSON-Format.

"VarioNet-6C:EC:EB:67:5B:13/SHM-F93A047F-D3D0-40E3-965D-08D17E393A19/BINLE/SET/struct1/array2/1/var4", Payload: [binärer Wert]: Setzt den Wert von "struct1.array2[1].var4" im Binärformat (little endian).


////////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////

Topic-Format zum dynamischen Ein/Ausschalten des Publishing von Variablen und zum Setzen von Parametern.
Das Topic enthält hier keine <Format> Komponente:

<DeviceID>/<ShmID>/<Command>/<VarPath>

<Command>:	"CONTROL".
Payload:	JSON-Objekt:
			{
				"binLe":		<boolean>, // Binär Little Endian ein/aus
				"binBe":		<boolean>, // Binär Big Endian ein/aus
				"json":			<boolean>, // JSON ein/aus
				"pBuf":			<boolean>, // Protokol Buffers ein/aus (nicht implementiert)
				"qos":			<number>, // Quality Of Service. 0-2. Nur Integer! Ungültige Werte werden auf den Bereich 0-2 korrigiert.
				"retained":		<boolean>, // Retain ein/aus
				"delRetained"	<boolean> // Retained Werte dieser Variablen im Broker löschen (siehe Anmerkung).
			}

Anmerkung:

Mit "retained" wird bestimmt, ob eine Variable als retained gepublished wird oder nicht. Sobald das einmal geschehen ist, behält der Broker eine Kopie des Wertes in seinem Cache, welcher jedem Client beim Abonnieren des Topics automatisch gesendet wird. Ein späteres Setzen von "retained" auf false hat zur Folge, dass weiter publishings des Wertes als nicht retained erfolgen. Trotzdem behält der Broker aber den letzten Wert, der als retained gepublished wurde weiter im Cache und versendet den Wert auch weiterhin an neue Clients! Um eine "retained"-Variable komplett aus dem Broker zu löschen, wurde "delRetained" eingeführt. Wird "delRetained" auf false gesetzt, hat es keine Auswirkung, "delRetained":true löscht retained Variablen aller Formate aus dem Brkoer, allerdings muss "retained" für diese Variable im selben oder bereits einem vorigen Aufruf auf false gesetzt worden sein.

Beispiel:

"VarioNet-64:31:50:47:BA:DF/SHM-F93A047F-D3D0-40E3-965D-08D17E393A19/CONTROL/struct1/struct2/var3", Payload: {"binLe":false, "json":true, "qos":1}:
	Schaltet das Publishing der Variablen "struct1.struct2.var3" im Binärformat Little Endian aus und von JSON ein. Setzt QOS auf 1. Alle anderen Parameter bleiben unverändert.