Konfiguration

Konfiguration der LOGO

Server-Verbindung hinzufügen

Für den Zugriff auf die LOGO verwende ich intern die libnodave-Bibliothek. Diese verbindet sich quasi wie ein HMI über Port 102 auf die LOGO. Jedoch müssen wir dazu diese Verbindungsart erst in der LOGO freischalten. Wenn ihr mehrere LOGOs im Einsatz habt ist dies für jede LOGO separat durchzuführen, die ihr mit LogoControl steuern möchtet. In der LogoSoft klickt ihr dazu in der Netzwerksicht mit der rechten Maustaste auf die Logo und wählt „Serververbindung hinzufügen“. Anschließend konfiguriert ihr die neue Verbindung wie folgt:

Logo1-netconfig-libnodave

In der Netzwerkansicht sieht das ganze dann so aus:

Logo-serververbindung-libnodave

Was muss am LOGO-Schaltprogramm geändert werden?

Sollen nur Daten aus der LOGO gelesen werden so ist dafür i.d.R. keine Änderung des Programms nötig. Der Status aller Ein-/Ausgänge und Merker ist bereits automatisch im VM-Speicher enthalten. Sie liegen im Speicherbereich oberhalb des 850sten Byte (Details siehe VM-Adressen der LOGO). Alle anderen Daten wie Parameter von Blöcken (Aktualwerte, Parameterwerte) liegen nicht automatisch im VM-Speicher. Sie müssen per Parameter-VM-Zuordnung in der LogoSoft erst mit dem VM verknüpft werden. Hierfür steht der Benutzer-Speicherbereich von 0-850 Byte zur Verfügung. Achtet darauf den Speicher nicht zu sehr zu fragmentieren und Daten im Benutzer-Bereich des VM möglichst zusammenhängend abzulegen. Das verbessert die Ausleseperformance.

LogoControl liest nun alle in seiner Konfiguration angegebenen Adressen im Speicher gezielt aus und stellt die Werte bereit.

Bis zur Version 0.5 von LogoControl war es noch nötig die genaue Speicheradresse für Ein-/Ausgänge/Merker zu kennen, wobei erschwerend hinzu kam, dass diese für Logo7 und Logo8 auch noch unterschiedlich waren. Dies ist nun nicht mehr nötig. Ein-/Ausgänge/Merker können nun in der LogoControl-Konfiguration über ihren Namen (z.B. I4, Q6, M22 etc.) adressiert werden.

Folgende benannte Adressen stehen zur Verfügung:

Logo7: I1-I24, Q1-Q16, AI1-AI8, AQ1-AQ2, M1-M27, AM1-AM16

Logo8: I1-I24, Q1-Q20, AI1-AI8, AQ1-AQ8, M1-M64, AM1-AM64, NI1-NI64, NQ1-NQ64, NAI1-NAI32, NAQ1-NAQ16

In Logo schreiben bzw. Ausgänge schalten

Die Ausgänge der Logo können nicht direkt geschaltet werden, wenn sie in einem Schaltprogramm enthalten sind, was in der Regel der Fall sein dürfte. Das liegt daran, dass die Logo zyklisch arbeitet. Alle x Millisekunden durchläuft sie ihren kompletten Schaltplan und schaltet die Ausgänge entsprechend. Würde nun von außen (z.B. über LogoControl oder libnodave) ein Ausgang gesetzt, so würde dieser Zustand bereits nach einigen Millisekunden (eben beim nächsten Zyklus) wieder mit dem der Schaltung entsprechenden Wert überschrieben werden.

Das heißt ohne die Schaltung zu ändern ist es nicht möglich direkt Ausgänge zu steuern. Wir können dies nur indirekt vom Schaltprogramm erledigen lassen indem wir es von außen irgendwie informieren, dass es nun den Ausgang schalten soll. Dazu nutzen wir den VM-Speicher der LOGO wo uns üppige 850 Bytes (Adresse 0 – 850) im Benutzerbereich frei zur Verfügung stehen. Einzelne Bits dieses Speichers können über den Block „Netzwerkeingang“ im Schaltprogramm abgefragt werden. Folgendes Minimal-Beispiel zeigt wie dies für eine Lampe aussehen kann:

Lampe-Netzwerkeingang

Das impulsartige Setzen eines Netzwerkeingangs (bzw. des Bits 300.5, welches hinter dem  Netzwerkeingang steckt) geschieht dann durch LogoControl, genauer gesagt durch eine dort definierte „Methode“. Wie solche Methoden in LogoControl definiert werden beschreibe ich im nächsten Kapitel. Beim Aufruf einer Methode setzt LogoControl das in der Konfiguration angegebene Bit (hier 300.5) für eine Dauer von 250ms auf 1.

Konfiguration von LogoControl

Nachdem nun alle Vorbereitungen getroffen und LogoControl in der Lage ist Daten zu lesen und zu schreiben, ist es nun an der Reihe LogoControl mitzuteilen welche. Dazu ist es zuerst notwendig die Grundidee zu verstehen, die hinter LogoControl steckt. Die Anwendung versucht die Arbeit mit dem VM-Speicher der LOGO möglichst vor dem Anwender zu verstecken. Man bekommt als User des Webservice also nicht irgendwelche nichtssagenden Adressen, Eingänge oder Ausgänge zu sehen. Stattdessen gibt es in LogoControl nur konkrete Geräte (Device) zu sehen. Ein Beispiel:

Wir haben eine einfache Rollladensteuerung mit einem Rollladenmotor, der auf und ab fahren kann. In der LOGO hätten wir dazu 2 Ausgänge Q1 und Q2 die den Motor in Bewegung versetzen. Zusätzlich vermutlich noch 2 Taster an den Eingängen I1 und I2, wobei die Eingänge aus Sicht von LogoControl keine Rolle spielen. Für die Ansteuerung des Motors über LogoControl nutzen wir Netzwerkeingänge, die die Adressen 150.0 (öffnen) und 150.1 (schließen) verwendet. Die LOGO soll außerdem den aktuellen Zustand (1=offen, 0=geschlossen, 2=dazwischen) des Rollladens an VM-Adresse 106 schreiben. Bemerkung: die Adressen sind frei wählbar, es muss also nicht die 150 oder 106 sein, sondern ist nur hier im Beispiel so.

LogoControl macht daraus nun ein Gerät „Rollladen Küche“, mit einem Attribut „Status“ das den lesbaren Wert „offen“, „geschlossen“ oder „dazwischen“ enthält, sowie zwei Methoden „öffnen“ und „schließen“. Über den Webservice sieht man nur das Gerät mit Attributen und Methoden, keine Ein-/Ausgänge oder Adressen. Um die Übersetzung/Umwandlung z.B. beim Aufruf einer Methode kümmert sich LogoControl. Diese Zuordnung von LOGO-Adressen zu Geräten muss einmalig festgelegt werden und nennt sich im weiteren „Infrastruktur“.

Die gesamte Konfiguration von LogoControl sowie die Beschreibung dieser Infrastruktur (Devices, Methoden, Attributen, Logo-Speicheradressen) erfolgt in der XML-Datei „config.xml“ die sich im LogoControl-Verzeichnis befindet. Nach der Installation ist bereits eine Beispielkonfiguration aktiv, die natürlich an die eigenen Gegebenheiten angepasst werden muss. Die config.xml editiert ihr am komfortabelsten über die Weboberfläche unter http://logocontrol:8088/config.st (Raspberry Pi) bzw. http://localhost:8088/config.st (Windows). Dort gibt es auch eine rudimentäre Code-Vervollständigung und Syntaxüberprüfung. (Ob die URL http://logocontrol… bei euch funktioniert ist natürlich davon abhängig ob der Hostname des Rechners auf „logocontrol“geändert wurde. Nach Befolgen der Raspberry Pi Installationsanleitung sollte dies der Fall sein, bei der Windows Anleitung jedoch nicht.)

LogoControl-Config

Aufbau der config.xml

<configuration>
  <settings>
    ...
  </settings>
  <infrastructure>
    ...
  </infrastructure>
</configuration>

Der Wurzelknoten der config.xml ist das „configuration“-Element. Darunter gibt es 2 Unterelemente „settings“ und „infrastructure“. In „settings“ sind grundlegende Einstellungen von LogoControl (Daten der PLC/LOGO, IP-Adresse, Ports, Benutzer, Konverter) enthalten, unter „infrastructure“ dagegen die Definition der Geräte, Methoden und Attribute sowie deren Zuordnung zu LOGO-Speicheradressen.

Der Settings-Block

<settings>
  <plc id="myLogo" type="Logo7" ip="192.168.178.201" />
  <httpWebservice port="8088" />
  <httpsWebservice port="8080" username="hugo" passwordHash="4712ec435c5a4aeccf18b646a4cbb3494aa5ea24" hashSalt="8d2sd931" />
  <valueTextConverter>
    ...
  </valueTextConverter>
</settings>
<plc>

Dieses Element definiert die Verbindung zu eurer PLC (Programmable Logic Controller) also eurer LOGO. Mindestens ein <plc> Element ist zwingend erforderlich. Es können auch mehrere PLC Elemente angelegt werden, wenn ihr mehrere LOGOs im Einsatz habt (z.B. eine im Dachgeschoss, eine im Erdgeschoss).

Bei „id“ vergebt einen eindeutigen Namen für eure PLC ein (z.B. „LOGO_EG“ oder „LOGO_DG“). Diese ID wird später referenziert um Attribute und Methoden eines Geräts einer PLC zuzuordnen (also lieber keine zu lange ID wählen, wenn ihr Tippfaul seid). Als Zeichen für die ID sind Klein- und Großbuchstaben, Ziffern und _ zugelassen. Die ID ist Case-Sensitiv.

Bei „type“ muss der Typ der PLC angegeben werden, aktuell werden die Werte „Logo7“ und „Logo8“ unterstützt.

Bei „ip“ tragt ihr die IP-Adresse eurer PLC ein unter der sie im Netzwerk für LogoControl erreichbar ist.

Webservice

Die beiden 2 Elemente (httpWebservice und httpsWebservice) sind optional. Ihr Vorhandensein entscheidet, ob die Funktion in LogoControl aktiv ist oder nicht. Die Weboberfläche ist abhängig vom Webservice und unter dem selben Port erreichbar. Sind also weder httpWebservice noch httpsWebservice aktiviert, so ist auch kein Zugriff auf die Weboberfläche möglich. Ist nur der httpWebservice aktiv, so ist die Weboberfläche auch nur über den HTTP-Port erreichbar.

<httpWebservice>

Stellt einen unverschlüsselten REST/JSON Webservice unter dem im Attribut „port“ angegeben Port bereit. Es gibt auch keine Benutzerauthentifizierung für den HTTP-Service. Warnung: dieser Port darf nicht ins Internet freigegeben werden! Er ist lediglich fürs interne Netzwerk gedacht und wird z.B. zur Anbindung von FHEM benötigt.

<httpsWebservice>

Stellt einen per TLS1.0 verschlüsselten REST/JSON Webservice unter dem im Attribut „port“ angegeben Port bereit. Dieser Dienst erfordert eine Benutzeranmeldung mittels HTTP-Basic-Auth. Im Attribut „username“ bitte einen Benutzernamen nach Wahl eintragen. Dass Passwort wird „gesalzen“ und als SHA-1 Hash eingetragen. Erzeugt werden kann der Hash z.B. unter http://www.fileformat.info/tool/hash.htm
Salzen bedeutet: Ihr nehmt euer Passwort und hängt den Salt einfach hinten dran, also wenn das Passwort „sesamöffnedich“ sein soll und hashSalt=“2d5sd231″ dann bildet daraus „sesamöffnedich2d5sd231“ und erzeugt daraus den Hash „ea0cb4dd910543662ef5d6c58550c1b0119bdc26“. Zu späteren Login reicht dann „sesamöffnedich“. Der Salt soll nur davor schützen falls jemandem zufällig eure config.xml in die Hände fällt und die Hashwerte mit irgendwelchen Rainbow-Tabellen vergleicht. Der Salt selbst ist frei wählbar und muss im Attribut „hashSalt“ hinterlegt werden.

<valueTextConverter>

In diesem Bereich können Konverter definiert werden, die für die Umwandlung  von Werten (im Falle der LOGO ein ganzzahliger Wert) in menschenlesbaren Text und umgekehrt genutzt werden können. Einfachstes Beispiel: aus dem Wert 0 und 1 in der Logo wird in der Anzeige „an“ und „aus“. Oder aus 225 wird in der Anzeige „22,5 °C“. Oder aus dem Wert 4873 (der Einschaltzeit des Blocks „Wochenschaltuhr“) wird die deutlich besser lesbare Uhrzeit „13:09“. In der Standard-Konfiguration sind bereits einige Konverter vordefiniert. Ähnlich wie bei der PLC müssen alle Konverter über eine eindeutige ID verfügen auf welche später Attribute eines Geräts referenzieren können. Wie eigene Konverter erstellt werden können erkläre ich in einem separaten Artikel.

Der Infrastructure-Block

Wie bereits erwähnt ist das Ziel von LogoControl das Handling mit Speicheradressen weitestgehend zu verstecken. Nach außen sichtbar sind nur (virtuell definierte) Geräte mit Methoden und Attributen. Er sieht z.B. nur ein Gerät „Wohnzimmerlampe“ mit einem Attribut „Status“. In welchem Byte und Bit des LOGO-Speichers sich nun der aktuelle Zustand der Wohnzimmerlampe befindet soll den Benutzer des Webservice gar nicht erst wissen müssen. Diese Zuordnung erledigen wir in der config.xml.

Gruppen <group>

<group name="Dachgeschoss">
  <group name="Schlafzimmer">
    <device ... />
  </group>
</group>
XML-Attribut Beschreibung
name Beliebiger Name zur Anzeige
Die einzelnen Geräte können in Gruppen („group“-Element) strukturiert werden (z.B. hierarchisch nach Stockwerk, Raum, etc). Dabei ist mindestens eine Gruppe nötig, da Devices nicht direkt unter einem Infrastructure-Element abgelegt werden können, sondern nur innerhalb einer Gruppe. „group“-Elemente können beliebig tief ineinander verschachtelt werden.

 Geräte <device>

<device id="1" name="Bad" type="shutter">
  <attribute ... />
  <method ... />
  <trigger ... />
</device>
XML-Attribut Beschreibung
id Systemweit eindeutige „id“ für dieses Gerät (darf in der config.xml für ein Device nur ein mal vorkommen). Der Webservice verwendet diese ID später zur Adressierung (je kürzer desto besser). Als Zeichen sind Klein- und Großbuchstaben, Ziffern und _ zugelassen. Die ID ist Case-Sensitiv.
name Beliebiger Name zur Anzeige
type Typ des Gerät. Wird nur zur Anzeige der HTML-Status-Seite benötigt um den Status farblich darstellen zu können. Mögliche Werte: shutter, light, custom. Das Attribut kann auch weggelassen werden, in diesem Fall gilt der type „custom“.
Devices abstrahieren von Logo-Eingängen/Ausgängen/Merkern oder VM-Speicheradressen. Wie bereits erwähnt lag der Focus bei der Entwicklung von LogoControl auf der Heimautomation. Sensoren und Aktoren lassen sich unter dem Begriff „Device“ zusammenfassen. Ein Device kann dabei Attribute (Sensor) und Methoden (Aktor) in beliebiger Anzahl besitzen. Zusätzlich kann dem Gerät ein beliebiger Name in der „name“ Eigenschaft zugewiesen werden.

Methode <method>
<method id="1" name="open" plc="myLogo" address="150.0" />
XML-Attribut Beschreibung
id Innerhalb des Geräts eindeutige „id“ für diese Methode (darf in dieser Geräte-Definition nur ein mal vorkommen). Der Webservice verwendet diese ID später zur Adressierung. Als Zeichen sind Klein- und Großbuchstaben, Ziffern und _ zugelassen. Die ID ist Case-Sensitiv.
name Beliebiger Name zur Anzeige
plc Die ID der PLC von welcher das Attribut gelesen werden soll. Es muss im <settings> Block der config.xml eine entsprechende PLC mit dieser ID existieren.
address VM-Speicheradresse der LOGO, welche für 250ms auf 1 gesetzt werden soll um die Aktion zu starten. Die Adresse wird in der Form [byte].[bit] angegeben, z.B. 150.2
script Optionaler Parameter zum Starten eines Shell-Scriptes beim Aufruf der Methode. Siehe separater Artikel „Für Fortgeschrittene„.
Eine Methode gehört zu einem Aktor und führt eine Aktion aus. Ein Rollladen z.B. kann 2 Aktionen durchführen: rauf und runter. Diese Aktionen werden von einem LOGO-Schaltprogramm durchgeführt, welches z.B. den Rollladen 30 Sekunden lang runter fährt. Eine solche in der LOGO programmierte Aktion heißt in LogoControl „Methode“. (Ich habe die Bezeichnungen aus der Objektorientierten Programmierung entlehnt, mag sein, dass diese dem ein oder anderen Nicht-Programmierer etwas seltsam vorkommen.) Es könnte z.B. noch eine dritte Methode existieren, die den Rollladen auf halbe Höhe zwecks Sonnenschutz fährt. Alle diese Methoden gehören trotz evtl. verschiedener angesteuerter LOGO-Ausgänge zu ein und demselben Gerät. Ausgeführt werden sie indem LogoControl das unter „address“ definierte Bit im VM-Speicher der LOGO impulsartig (für 250ms) setzt und dieses Bit wiederum über einen Netzwerkeingang in das Schaltprogramm eingebunden wird (siehe dazu Absatz „Was muss am LOGO-Schaltprogramm geändert werden?“).

Neben dem Setzen von Bits im VM der LOGO kann eine Methode auch ein Shell-Script starten, welches dann beliebig andere, von der LOGO unabhängige, Aktionen durchführen kann. Diese Funktionalität wird in einem separaten Artikel für „Fortgeschrittene“ behandelt.

Attribut <attribute>
<attribute id="1" name="state" plc="myLogo" address="106" datatype="dword" valueTextConverter="rollo" />
XML-Attribut Beschreibung
id Innerhalb des Geräts eindeutige „id“ für dieses Attribut (darf in dieser Geräte-Definition nur ein mal vorkommen). Der Webservice verwendet diese ID später zur Adressierung (je kürzer desto besser). Als Zeichen sind Klein- und Großbuchstaben, Ziffern und _ zugelassen. Die ID ist Case-Sensitiv.
name Beliebiger Name zur Anzeige
plc Die ID der PLC von welcher das Attribut gelesen werden soll. Es muss im <settings> Block der config.xml eine entsprechende PLC mit dieser ID existieren.
address VM-Speicheradresse der LOGO, ab welcher das Attribut gelesen werden kann. Dabei können sowohl benannte Adressen (z.B. I6,Q4,M22…) als auch direkte Speicheradressen verwendet werden. Bei direkter Adressierung steht je nach Datentyp (siehe „datatype“) hier nur das byte (z.B. 254 für byte, word, dword) oder in der Form [byte].[bit] (z.B. 150.2 für den Datentyp „bit“)
datatype Datentyp des Attributs. Bestimmt die Länge der zu lesenden Bytes an der durch „address“ angegeben Start-Position. Mögliche Werte: bit, byte, word, dword, uword. Die Angabe des Datentyps ist optional. Für benannte Adressen (z.B. I6,Q4,M22…) erkennt LogoControl den Datentyp automatisch und die Angabe kann entfallen. Für alle andere Adressen wird bei fehlendem „datatype“ der Standard „byte“ bzw.  bei Vorhandensein eines Punktes (.)  in „address“ der Standard „bit“ gewählt. Ist die Standard-Logik nicht ausreichend muss der „datatype“ explizit gesetzt werden.
gain Multiplikator für analoge Messwerte. Siehe Kasten „Analogwerte“ unten.
offset Offset-Verschiebung für analoge Messwerte. Siehe Kasten „Analogwerte“ unten.
valueTextConverter Die ID des valueTextConverter welcher für die Konvertierung von Werten zu Text und umgekehrt genutzt werden soll. Es muss im <settings> Block der config.xml ein entsprechender Konverter mit dieser ID existieren.
Ein Attribut repräsentiert einen Status/Wert/Messwert eines Gerät (z.B. Lampe an/aus, Rollo geöffnet/geschlossen, Zählerwert, Temperaturwert…). Es befindet sich im VM-Speicher der Logo und kann vom Typ Bit, Byte, Word oder DWord sein und ist entsprechend 1 Bit, 1 Byte, 2 Byte oder 4 Byte lang. Zusätzlich existiert noch der unsigned Typ „UWord“ mit 2 Bytes Länge. LogoControl liest diese Adresse (zusammen mit allen anderen Attributen gebündelt) alle 250ms aus und kopiert den Inhalt in einen internen Cache. Eingehende Anfragen nach dem Attribut Wert werden auf Basis des Caches beantwortet. Somit wird vermieden, dass die LOGO mit Lese-Operationen überflutet wird. In der Regel wird auf ein Attribut nur lesend zugegriffen, z.B. zur Status-Anzeige. In bestimmten Fällen (z.B. setzen eines Temperatur-Sollwertes) macht es jedoch auch Sinn „schreibend“ darauf zugreifen zu  können. Analoge Messwerte können für eine menschenlesbare Darstellung mittels der „gain“ und „offset“ Parameter skaliert werden (siehe Kasten „Analogwerte“).

Analogwerte
Analoge Werte werden in der LOGO in Form des Datentyps „word“ abgelegt und belegen somit 2 Bytes. Zum Lesen und Schreiben dieser Werte verwendet man in LogoControl normale Attribute vom Datentyp „word“. Da jedoch der nominelle Analogwert nur selten der menschenlesbaren Darstellung entspricht, gibt es in LogoControl die Möglichkeit den Wert zu skalieren. Dazu verwendet man die „gain“ und „offset“ Eigenschaften. Dabei gilt die Formel:

skalierter_wert = (word_wert * gain) + offset

Der Wert von „gain“ ist eine Fließkommazahl vom Typ „double“, der von „offset“ eine ganze Zahl.

Beispiel:

An der Logo hängt ein Temperatursensor mit einem Messbereich von -50 bis +50 °C. Der Analogwert 0 entspricht dabei -50.0 °C, der Wert 1000 +50.0 °C, der Nullpunkt liegt also bei Analogwert 500. Für die Anzeige des korrekten Celsius-Wertes benötigen wir nun folgende Attribut-Eigenschaften:

<attribute id="1" name="Temp" plc="myLogo" address="150" datatype="word" gain="0.1" offset="-50" />

Bei einem Analogwert von 725 wäre die Rechnung somit (725*0.1)+(-50)  was 22.5 °C ergibt. Die „gain“ und „offset“ Eigenschaften gelten nicht nur für die Umrechnung beim Lesen von Werten aus der LOGO, sondern auch für das Schreiben von Attributen. Dann allerdings in inverser Logik, sprich ein Setzen des Attributwertes auf 22.5 wird vor dem Schreiben in die LOGO wieder auf 725 umgerechnet. Weitergehende Umrechnungs- und Formatierungsmöglichkeiten bieten sich durch die Verwendung eigener valueTextConverter.

Trigger <trigger>

Ein Trigger besteht aus einer Speicheradresse und einer Liste von Bedingungen und damit verknüpften Methoden des Geräts. Er überwacht den Wert der Speicheradresse und kann bei Änderungen des Wertes prüfen, ob nun eine der zuvor definierten Bedingungen (ausgelöst durch die Wertänderung) zutrifft. Ist dies der Fall, ruft der Trigger die dazugehörige Methode auf. Das Thema Trigger wird in einem separaten Artikel für „Fortgeschrittene“ behandelt.