Migration auf LogoControl v0.5

Achtung: Abwärtskompatibilität gebrochen

Ab LogoControl v0.5 wurden einige neue Features eingeführt, welche auch Änderungen am Format der config.xml sowie der REST/JSON-API erforderlich machten. Da durch diese Änderung eh die Abwärtskompatibilität gebrochen war, habe ich die Situation gleich genutzt und lange vor mir hergeschobene Aufräumarbeiten durchgeführt und alte Zöpfe abgeschnitten. Für bestehende Nutzer von LogoControl mit einer Version <0.5 bedeutet das, dass eure alte config.xml als auch Programme, welche die Webservice-API nutzen (wie z.B. NetIO), mit der aktuellen Version ab 0.5 nicht mehr kompatibel sind.

Bei einem professionell vertriebenen Produkt dürfte ich mir so etwas natürlich nicht erlauben und hätte mir die Mühe machen müssen eine Migrationsroutine zu schreiben, die beim ersten Programmstart der neuen Version das alte Dateiformat in das neue konvertiert, aber dafür fehlt mir bei diesem privaten Bastelprojekt schlicht die Zeit. Da ihr ja alle Bastler seid, denke ich, ich kann es euch zumuten für einige Minuten selbst Hand anzulegen um eure Konfiguration wieder kompatibel zur aktuellen Programmversion zu machen.

Da LogoControl v0.5 mit einer veralteten Konfiguration noch nicht einmal mehr startet, könnt ihr die Änderungen leider auch nicht über die Weboberfläche durchführen. Ihr könnt auch nicht die Änderungen zuerst mit der alten Version <0.5 über die Weboberfläche durchführen und dann updaten, weil die alte Version natürlich noch nicht das neue Format der config.xml kennt und so beim Speichern einen Fehler werfen wird. Einziger Ausweg: Ihr müsst also die config.xml mit einem Text-Editor eurer Wahl manuell anpassen.

Das Update von LogoControl auf Version 0.5 geht erst mal recht einfach. Ihr müsst nur alle Dateien aus dem Archiv (ZIP bei Windows, TGZ beim Raspi) in das LogoControl-Verzeichnis entpacken und dort damit alle existierenden Dateien überschreiben. Anschließend ist wie gesagt Handarbeit an der config.xml angesagt. Folgende Änderungen sind durchzuführen:

Definition PLCs statt Logo

Es werden nun mehrere Logo’s gleichzeitig unterstützt. Um in Zukunft evtl. auch andere SPSen (z.B. S7) neben der Logo unterstützen zu können, habe ich auf die Bezeichnung „Logo“ nun weitestgehend verzichtet und verwende fortan die generische Bezeichnung „PLC“ (Programable Logic Controller).

Ihr müsst daher in eurem <settings> block den Eintrag

<logo ip="192.168.178.201" />

durch

<plc id="ug" type="Logo7" ip="192.168.178.201" />

ersetzen. Die „id“ spielt, solange ihr nur eine PLC verwendet, noch keine Rolle, muss aber trotzdem gesetzt sein (Buchstaben, Zahlen, keine Leerzeichen). Bei Verwendung mehrerer PLCs muss diese ID dann bei jedem Attribute, Method und Trigger angegeben werden um die eindeutige Zuordnung zur PLC zu kennzeichnen. Näheres dazu in der regulären Anleitung. Bei nur einer einzigen definierten PLC kann auf diese Zuordnung verzichtet werden, was bei allen Alt-User ja der Fall sein dürfte.

Den „type“ bitte entsprechend eurer verwendeten Logo (Logo7 oder Logo8) setzen. Diese Angabe wird benötigt, da nun Speicheradressen in der config.xml auch in Form von I3, Q6, M12, AI1 usw. angegeben werden können. LogoControl übernimmt in diesem Fall die Auflösung der namentlichen Adressen in physikalische Adressen (diese Zuordnung ist bei Logo7 und Logo8 unterschiedlich).

ValueText Listen

Bisher lief die Zuordnung von Texten („ein“, „aus“) zu einem Wert (1,0) über valueText-Blöcke innerhalb eines jeden Attributs. Bei 20 Lampen mit dem gleichen möglichen Werten (an/aus) blähte das die config.xml nur unnötig auf. Da nun auch Umrechnungen von Werten (calculation) und nicht nur Textzuweisungen (textMapping) als Anzeigemöglichkeit für den Roh-Datenwert möglich sind, habe ich diese unter dem generischen Block „valueTextConverters“ in den Settings-Block verschoben. Hier mal ein Muster wie der Block aussehen könnte:

<settings>
	<plc id="1" type="Logo7" ip="0.0.0.0" />
	<httpWebservice port="8088" />
	<httpsWebservice port="8080" username="" passwordHash="" hashSalt="" />
	<valueTextConverter>
		<!-- Verschiedene Konverter zur Überführung von Value (ganzzahliger Rohwert aus der Logo) in ValueText (Anzeigewert für den Benutzer) -->
		<textMapping id="an_aus">
			<!-- Einfaches Text-Mapping für aus (0) und an (1) -->
			<valueText value="0" text="aus" />
			<valueText value="1" text="an" />
		</textMapping>
		<textMapping id="rollo">
			<!-- Einfaches Text-Mapping für Rolläden -->
			<valueText value="0" text="geschlossen" />
			<valueText value="1" text="mittel" />
			<valueText value="2" text="offen" />
		</textMapping>
		<textMapping id="auf_zu">
			<valueText value="0" text="zu" />
			<valueText value="1" text="auf" />
		</textMapping>
		<calculation id="minsec">
			<!-- Analogwert zu/von Zeitwert (Bsp: 4873 zu 81:13) -->
			<valueToText calculation="{Floor([value]/60)}:{if([value]%60>9,'','0')}{[value]%60}" />
			<textToValue valueParseRegex="(\d+):(\d+)" calculation="{[value1]*60+[value2]}" />
		</calculation>
		<calculation id="time">
			<!-- Analogwert zu/von Uhrzeit (4873 zu 13:09) -->
			<valueToText calculation="{Floor(LogoDec2Hex([value])/100)}:{if(LogoDec2Hex([value])%100>9,'','0')}{LogoDec2Hex([value])%100}" />
			<textToValue valueParseRegex="(\d+):(\d+)" calculation="{LogoHex2Dec([value1]*100+[value2])}" />
		</calculation>
	</valueTextConverter>
</settings>

Attribute die bisher valuetext listen verwendet haben sahen so aus:

<attribute id="1" name="state" address="106" datatype="dword">
	<valuetext value="0" text="geschlossen" />
	<valuetext value="1" text="mittel" />
	<valuetext value="2" text="offen" />
</attribute>

das muss nun in

<attribute id="1" name="state" address="106" datatype="dword" valueTextConverter="rollo" />

geändert werden. Über den Parameter „valueTextConverter“ wird hier nun auf das oben im Settings-Block definierte TextMapping für Rollläden verwiesen.

Auswirkungen auf Drittprogramme

Benutzer des Webservice bzw. der NetIO App

Da jegliche „id“ (egal ob von PLC, Device, Attribute, Method…) innerhalb LogoControl nun nicht mehr nur eine Zahl sondern ein String sein kann, hat sich dies leider auch auf das JSON-Format des Webservice ausgewirkt (id ist nun ein string statt int). Das führt dazu, dass Anwendung, welche den Webservice nutzen (wozu auch die NetIO-App zählt) nun nicht mehr korrekt funktionieren können. Da die Kompatibilität damit eh gebrochen war, habe ich bei der Gelegenheit gleich auch die Webservice-Requests „rest/attributes“ und „events/attributes“ überarbeitet, so dass diese nun eine deutlich kürzere Antwort (alle JSON-Namen werden nur noch mit 1 Buchstaben abgekürzt) liefern. Das reduziert den Traffic auf die Hälfte, was insbesondere der Nutzung bei langsamen Mobilfunkverbindungen zugute kommt. Genug der Hintergründe, was bedeutet das nun konkret für euch:

Bei NetIO betrifft dies den regulären Ausdruck in „parseResponse“, welcher verwendet wird um den „value“ und „valueText“ aus der JSON-Nachricht zu extrahieren. Bitte passt diesen in eurer NetIO-Config entsprechend der aktualisierten Anleitung zu NetIO an.

Benutzer der FHEM-Anbindung

Mit der Unterstützung von mehreren PLCs hat sich auch der WebService-Request zum direkten Setzen von Bits im LogoVM geändert, welcher von meinem Beispiel mit der FHEM-Anbindung genutzt wird. Neben Byte und Bit muss in Fhem auch die ID der PLC mit angegeben werden, in welche geschrieben werden soll. Bitte hier die aktualisierte Anleitung zu diesem Thema beachten  und auf das darin aktualisierte Perl-Skript umstellen.

rest/plcs/{plcId}/bytes/{byteNumber}/bits/{bitNumber}?set={value}