DocumentationThe complete Manual

Basics

The controlStation connectes devices with ethernet or WiFi connection. If your device has an IP address in your home network, then you can write a device class#Link for it or, if somebody already did and shared his device class, be imported in class management. Subsequently, you can add your device in device management. There, its IP address can be found via network scan or can be manually inserted. Up next, select the appropriate device class and put it in a room. Now, the device can be controlled at the front page and sensor data can be read from the device. This fundamental functionality makes it possible to for example create detailed statistics or the execution of elaborate rules which make your home a smart home.

Rooms

To add a device, there must be a room that it can be assigned to. New rooms can be added in #Einstellungen -> Räume#. With user management enabled, you can also specify which users may control devices in this room. Administrators have access to all rooms and all devices.

Devices

If you ask yourself which devices are supported by the controlStation or how you can make devices yourself, please visit our Wiki#Link. There you can find devices and projects which you can buy our build yourself. You already own a device? Connect it with your controlStation! Add new device classes in #Einstellungen -> Klassen#, for example by importing them from the Wiki. Conclusively you can add your device in #Einstellungen -> Geräte#. Choose a name, select the room the device is in, the device’s IP address and the device class. Some classes need further device specific settings. After saving your settings you could create a rule for your new device…

Rules

Rules provide many possibilities to fulfill complex requirements. We split rules in three parts: triggers, conditions and actions. Briefly speaking, triggers define an event that should cause the rule to be triggered. Conditions perform check if all requirements for the rule to be executed are met. Actions define what should be done by the rule.

Triggers

Rules can be triggered by device push or by matching a time frame.

The following example shows a simple trigger which could cause the shutters to be opened at 7 am on weekdays: time sample image

Another option for timing is Cron. Cron is a little less intuitive, but more powerful. Possible triggers are, for example, “During the first two weeks of October, each tuesday, do something every 10 minutes between noon and 2 pm”. You can learn how to use cron here#Link. Here are two simple examples:

Triggered every minute: Cron sample image
Triggered every 5 minutes: Cron sample image

As mentioned, devices can be triggers, too. For this to work, the device must be able to send data to your controlStation via push. If it is, the device gets listed as possuble trigger.

Conditions

Conditions check if a triggered rule should be executed. First, decide wether all conditions must be met for the rule to be executed or if one is sufficient to trigger the rule. You may use any pull information available for your device. You can also check if the rule was triggered in a given time frame.

Actions

Every device registered with your controlStation can be used as an action. You may selec as many actions as you wish. Additionally, controlStation can send you an email when a rule is triggered.

Device Classes

Classes are the controlStation’s most important feature. They define how to communicate with your devices. Creation of device classes is primarily targeted at developers and people who build their own devices. Device classes are implemented so that little effort is neccessary to implement a device interface. No need to write additional code.

Essentially, a device class consists of thre parts which we call pull infos, executables and push infos.

Pull Infos

Pull info is all data that can be retrieved from your device by your controlStation. A pull info consists of the following:

Name
This is your pull info’s name which gets displayed at the front page for your devices.

Method
The method determines the type of communication. Options are HTTP(s) POST and GET as well as TCP and UDP sockets. For socket communcation, the command field is expected to contain hex encoded data which gets decoded to a binary stream before sending it.

Command
You define the actual request being made here. If the method is HTTP, the command is the part of the URL behind the IP address, e.g. #/temperature.html# or #?param=gettemperature#. For sockets input hex encoded raw data to be sent to the device.

Overview
If the box overview is checked, the pull information will be displayed on the front page directly. Devices which have pulls not having overview enabled will be displayed with an arrow icon which expands the device to show hidden pulls. By using this, you can hide pulls which are not used that frequently.

Parsing type
If the device does not return the actual data but structured or additional information, you can use parsing type. With this, you can apply a regular expresison#Link, an XML parser or shell parsing to retrieved data. Shell parsing works as if the pull info would have been piped into the expression. Available commands to process pull infos are #awk, grep, sed, tr#.

Parsing expression
Parsing expressions can be best explained by examples. You can find two examples for each parsing type in the table below.

Parsing type Raw pull info Expression Result
XML <temp>23</temp> temp 23
XML <PLUG><State>On</State></PLUG> State On
RegEx tv-channel:12 tv-channel:(\d+) 12
Shell SocketStates[1, 0, 1, 1] awk -F’[][,]’ ‘{ if ($2 == 1) { print “On” } }’ On

Executables

Executables are all commands which trigger an action on the device. Name, method, command and overview work the same as with pull infos. Varying control elements and its parameters are explaned below.

Button
The button is the simplest and most used type of control elements. The button’s label conforms to the executable’s name. On clicking the button, the command gets executed. So simple that it does not need additional parameters.

Color
Color is also used often. Für this type of executable, a colorpicker will be shown at the front page. The user has the possibility to send an RGB color code to the device. Contrary to buttons, the executable command must modify in order to send the RGB code. For the value, the placeholder “%%%” must be put in the command. A color command could look like this: #?rgbdata=%%%#

Text
To send a specific text to a device, for example to an LED matrix, you can generate text fields at the start page. The same placholder as for color is used, for example #?printText=%%%#

List
To send determined static data to a device, create a list executable. The list has an own parameter field into which accepts semicolon separated values. From these, the controlStation generates a select box at the front page and sends the command after selecting an element. Here, as in text and color, the placeholder “%%%” needs to be inserted in the command.

Integer
TODO

Push Infos

A push is a message from a device to your controlStation. Push infos trigger rules and get saved as statistics in your controlStation.

You want to make a toggle switch to control the light over your controlStation? Create a device, which contacts your controlStation’s push service. Afterwards, create a rule, which executes an action after receiving a push from your switch.

The push HTTP service is reachable at “http://[your-controlStation-ip]/report.cgi”. A push can be supplied as a GET parameter. Assumed your device class has push named Actiom with diagram type table and your controlStation’s IP address is 192.168.2.100. Your device can, by calling “http://192.168.2.100/report.cgi?Action=On", trigger the push “Action” with value “On”.

Your controlStation’s push service checks the IP address on receiving a push to determine the device the push comes from. If the device exists, it checks if a push with the provided name “Action” exists. Then it checks if the transmitted value “On” fits for a defined diagram type. The following diagram types are available:

Diagram type Strings Numbers Binary data (images)
Bar chart Yes Yes No
Pie chart Yes Yes No
Line chart No Yes No
Table Yes Yes No
Image No No Yes

Long story short: Images can be pushed with diagram type image. Aditionally, pushs with diagram type line chart don’t accept string.

Since a push named “Action” exists and the diagram type table accepts Strings, the submitted value “On” gets saved as a statistic. For security reasons, controlStation always returns “HTTP/1.1 200 OK”. If an error occurs, it appears in log files#Link as an entry in section “devices”.

Now controlStation checks for rules getting triggered by this push. If there are any, they are processed by controlStation.