DokumentationDas komplette Handbuch

Grundfunktion

Die controlStation unterstützt Geräte mit Ethernet oder W-Lan. Wenn ein Gerät also eine IP-Adresse hat, kann für diesen Gerätetypen eine Klasse geschrieben oder wenn bereits vorhanden über die Klassenverwaltung importiert werden. Anschließend wird das Gerät über die Geräteverwaltung zur controlStation hinzugefügt. Dazu wird die IP-Adresse entweder über einen Netzscan ausfindig gemacht oder manuell eingegeben. Als nächstes wird die zutreffende Geräteklasse ausgewählt und das Gerät wird einem Raum hinzugefügt. Ab jetzt kann das Gerät über die Startseite angesteuert und Sensorwerte können ausgelesen werden. Dieser grundsätzliche Funktionsumfang ermöglicht z.B. das Erstellen ausführlicher Statistiken und das Ausführen ausgefeilter Regeln die das Heim erst smart erscheinen lassen.

Räume

Bevor ein Gerät hinzugefügt werden kann musst du einen Raum anlegen, dem es zugewiesen werden kann. Neue Räume lassen sich unter #Einstellungen -> Räume# hinzufügen. Bei aktivierter Benutzerverwaltung kann zusätzlich angegeben werden welcher Benutzer Geräte in diesem Raum steuern darf. Administratoren haben Zugriff auf alle Räume und alle Geräte.

Geräte

Wenn du dir die Frage stellst welche Geräte von der controlStation unterstützt werden oder wie du dir selber Geräte bauen kannst besuche gerne unser Wiki. Dort werden einige Geräte und Projekte vorgestellt die Du kaufen oder nachbauen kannst. Du hast schon ein Gerät? Mache es mit deiner controlStation vertraut! Füge die Geräteklasse unter #Einstellungen -> Klassen# z.B. direkt über das Wiki hinzu. Abschließend kannst du das Gerät unter #Einstellungen -> Geräte# hinzufügen. Wähle hierzu einen treffenden Namen, den Raum, die IP-Adresse und die Geräteklasse aus. Einige Klassen erfordern weitere gerätespezifische Einstellungen. Nachdem die Einstellungen gespeichert wurden könnte als nächstes beispielsweise eine Regel für das neue Geräte angelegt werden…

Regeln

Das Regelwerk bietet viele Möglichkeiten um auch komplexeren Anforderungen gerecht zu werden. Dazu haben wir es in drei Felder unterteilt: Auslöser, Bedingungen und Aktionen. Schnell gesagt wird bei den Auslösern ein Ereignis angegeben wann diese Regel ausgeführt werden soll. Bei den Bedingungen wird geprüft ob sie ausgeführt werden soll und bei den Aktionen wird angegeben was ausgeführt werden soll.

Auslöser

Ausgelöst werden Regeln entweder von der controlStation über Zeitsteuerungen oder von Geräten die Push unterstützen.

So sieht ein Beispiel für einen einfachen zeitgesteuerten Auslöser aus, der Werktags 7 Uhr morgens die Rollläden öffnen könnte: time sample image

Eine andere Möglichkeit für Zeitsteuerung ist Cron. Diese lässt sich weniger intuitiv erstellen, ist aber weitaus mächtiger. Möglich wären Auslöser wie “In den ersten beiden Oktoberwochen je Dienstags alle 10 Minuten zwischen 12 und 14 Uhr”. Wie Cron im Detail zu bedienen ist kann auf dieser#Link Seite nachgelesen werden. Hier sind zwei einfache Beispiele die in der Praxis häufig Verwendung finden.

Wird jede Minute ausgelöst: Cron sample image
Wird alle 5 Minuten ausgelöst: Cron sample image

Wie schon erwähnt können auch Geräte Auslöser sein. Dazu muss ein Gerät von sich aus in der Lage sein, Daten an die controlStation zu senden. Ist dies gegeben taucht das Gerät als möglicher Auslöser auf und kann verwendet werden.

Bedingungen

Bei den Bedingungen wird geprüft ob eine ausgelöste Regel auch tatsächlich ausgeführt werden soll. Zuerst wird angegeben ob alle oder nur eine Bedingung erfüllt werden muss. Alle Geräte, von denen per Pull Daten abgerufen werden können, eignen sich als Bedingung. Wenn die Regel ausgelöst wird, werden aktuelle Werte des Geräts mit eingetragenen Werten verglichen. Es kann auch auf ein bestimmtes Zeitfenster geprüft werden.

Aktionen

Als Aktionen stehen alle in der controlStation registrierten Geräte zur Verfügung. Dabei lassen sich beliebig viele auswählen. Es ist außerdem möglich sich von der controlStation eine E-Mail senden zu lassen.

Geräteklassen

Klassen sind die wichtigste Eigenschaft der controlStation. Sie definieren wie die Kommunikation mit den Geräten ablaufen soll und sind somit hauptsächlich für Entwickler und Leute die ihre Geräte selber bauen gedacht. Sie sind so umgesetzt das es kaum mehr Arbeit ist eine bestehende Geräteschnittstelle zu integrieren. Code muss nämlich keiner mehr geschrieben werden. Eine Klasse besteht im wesentlichen aus drei Bestandteilen die wir Pull-Infos, Executables und Push-Infos nennen und werden hier im Einzelnen erklärt.

Pull-Infos

Pull-Infos sind alle Daten die sich die controlStation von deinem Gerät ziehen kann. Eine Pull-Info setzt sich aus folgenden Feldern zusammen:

Name
Dieser Wert wird als Name der Pull-Info auf der Startseite bei dem entsprechendem Gerät angezeigt.

Methode
Die Methode legt die Art der Kommunikation mit dem Gerät fest. Mögliche Methoden sind http(s) POST und GET sowie TCP und UDP Sockets. Bei Sockets wird das Kommando beim senden automatisch Hex Codiert.

Kommando
Hier wird die eigentliche Anfrage an das Gerät definiert. Ist die Methode Beispielsweise http so ist das Kommando der Teil der URL hinter der IP-Adresse. Also #/temperature.html# oder #?praram=gettemperature#. Bei Sockets werden raw Daten eingetragen.

Übersicht
Wenn die Übersicht Checkbox angehakt ist, wird die Pull Information (oder das Executable) direkt auf der Startseite angezeigt. Andernfalls gibt es bei Geräten die Pulls (oder Executables) ohne gesetzten Übersicht Haken haben einen Pfeil der das Gerät auf-/zuklappt um alle vorhandenen Informationen (oder Aktionen) einzublenden. So kann eine gewisse Ordnung auf der Startseite der controlStation gewahrt werden, indem Elemente, die nicht häufig genutzt werden, standardmäßig ausgeblendet werden.

Parsing-Typ
Für den Fall, dass ein Kommando nicht den direkten Wert zurück gibt sondern nur verschachtelte Informationen, hat man die Möglichkeit einen Parsing-Typ zu verwenden. So kann man auf die Pull-Info eine Regular Expression#Link, einen XML-Parser oder Shell-Parsing anwenden. Das Shell-Parsing funktioniert so als würde die Pull-Info über eine Unix Pipe in den Ausdruck geleitet. Mögliche Kommandos um die Pull-Info zu bearbeiten sind: #awk, grep, sed, tr#.

Parsing-Ausdruck
Parsing-Ausdrücke lassen sich am besten anhand von Beispielen erklären. Für jeden Parsing-Typ lassen sich aus der unteren Tabelle je zwei Beispiele entnehmen.

Parsing-Typ Unverarbeitete Pull-Info Ausdruck Ausgabe
XML <temp>23</temp> temp 23
XML <PLUG><State>On</State></PLUG> State On
Reg-Ex TV-Channel:12 TV-Channel:(\d+) 12
Shell SocketStates[1, 0, 1, 1] awk -F’[][,]’ ‘{ if ($2 == 1) { print “Ein” } }’ Ein

Executables

Executables sind alle Kommandos die eine Aktion an einem Gerät auslösen. Name, Methode, Kommando und Übersicht funktionieren nach dem gleichen Prinzip wie bei den Pull-Infos. Daher werden im folgenden nur noch die unterschiedlichen Bedienelemente und ihre Parameter erklärt.

Button
Der Button ist die einfachste und auch am häufigsten verwendete Form von den Bedienelementen. Die Beschriftung der Schaltfläche auf der Startseite ist gleich dem verwendetem Namen. Bei einem Klick auf den Button wird das Kommando ausgeführt. So simpel das es keine weiteren Parameter braucht.

Farbe
Auch die Farbe findet oft Verwendung. Bei der Farbe wird auf der Startseite ein Farbkreis gezeichnet. So erhält der Benutzer die Möglichkeit einen RGB Farbwert an ein Gerät zu senden. Im Gegensatz zu einem Button muss sich bei der Farbe das Kommando immer an den gesetzten Farbwert anpassen. Für den entsprechenden Wert muss der Platzhalter “%%%” im Kommando eingesetzt werden. Ein Farb-Kommando könnte also folgendermaßen aussehen: #?rgbdata=%%%#

Text
Um einen speziellen Text an ein Gerät zu senden, beispielsweise eine LED-Matrix, können mit dem Text Bedienelement Input Felder auf der Startseite generiert werden. Es wird der gleiche Platzhalter wie bei dem Feld Farbe verwendet. Ein Beispiel #?printText=%%%#

Liste
Sollten bei einem Kommando immer ein paar bestimmte statische Daten übertragen werden, wie z.B. bei einer Fernbedienung, ohne das man für jedes einen einzelnen Button anlegen möchte, ist man mit einer Liste gut beraten. Die Liste hat ein eigenes Parameter Feld in welches sich Semikolon separierte Werte eintragen lassen. Aus dieser Liste generiert die controlStation dann auf der Startseite eine Select-Box und versendet bei jedem Klick auf ein Element das Kommando. Auch hier muss der Platzhalter “%%%” in dem Kommando eingearbeitet werden.

Zahl
TODO

Push-Infos

Ein Push ist eine Meldung von einem Gerät an die controlStation. Push-Infos lösen Regeln aus und werden als Statistik in der controlStation gespeichert.

Du möchtest einen Wandschalter bauen der das Licht über die controlStation steuert? Richte ein Gerät ein, dass den Push-Service deiner controlStation kontaktiert. Erstelle dann eine Regel, die bei einem Push von deinem Schalter eine gewünschten Aktionen ausführt.

Der Push Service ist als HTTP-Dienst realisiert und erreichbar unter “http://[ip-deiner-controlStation]/report.cgi”. Jeder Push muss als GET-Parameter übergeben werden. Angenommen, deine Geräteklasse für Wandschalter enthält einen Push namens “Action” mit dem Diagrammtyp “Tabelle” und die IP-Adresse deiner controlStation ist “192.168.2.100”, dann kann dein Gerät durch aufrufen von “http://192.168.2.100/report.cgi?Action=On" einen Push für “Action” mit dem Wert “On” auslösen.

Der Push-Dienst der controlStation prüft beim Push anhand der IP-Adresse, um welches Gerät es sich handelt. Falls das Gerät existiert, wird überprüft, ob ein Push mit dem Namen “Action” existiert. Anschließend wird überprüft, ob der übermittelte Wert in den definierten Diagrammtyp passt. Folgende Typen stehen für Push-Infos zur Auswahl:

Diagrammtyp Strings Zahlen Binärdaten (Bilder)
Balkendiagramm Ja Ja Nein
Kreisdiagramm Ja Ja Nein
Liniendiagramm Nein Ja Nein
Tabelle Ja Ja Ja
Bild Nein Nein Ja

Kurzum: Bilder können nur mit dem Diagrammtyp “Bild” gepusht werden. Außerdem akzeptieren Pushs vom Typ Diagrammtyp “Liniendiagramm” keine Strings.

Da ein Push mit dem Namen “Action” existiert und der Diagrammtyp “Tabelle” Strings akzeptiert, wird der übermittelte Wert “On” als Statistik gespeichert. Aus Sicherheitsgründen antwortet die controlStation immer mit HTTP/1.1 200 OK. Sollte ein Fehler auftreten, erscheint bei den Logfiles#Link ein Eintrag in der Sektion Geräte.

Anschließend überprüft die controlStation, ob Regeln auf diesen Push auslösen. Ist dies der Fall, werden die entsprechenden Regeln von der controlStation bearbeitet.

Bad request from [ipadresse]
Der Push enthielt einen unerlaubten Wert
Received report from device with IP address [ipadresse], which is unknown
Ein Gerät mit der angegebenen IP-Adresse wurde nicht gefunden.
Received report for [deviceclassname]/[pushname], which is unknown
Ein Push mit dem angegebenen Namen existiert nicht.
Server Error while receiving push
Es ist ein Fehler beim Speichern des Push-Werts aufgetreten.