OpenHab

OpenHab2 is a centralized method to manage multiple IoT devices from a Web GUI.

How OpenHab Works (Short Version!)

There are three OpenHab2 components that concern us:

• Web interfaces, which accept user events and convert them into state change commands on Items
• Items, which define an IoT connected device for OpenHab--specifically, an internal name, one of several prebuilt types, and the protocol and address for sending commands to the device (and receiving updates from it)
• Rules, which define what action should occur when a specific command is received for an Item
  • More precisely, Rules allow definition of a high-priority handler for State changes. Most Items have a set of default commands already configured as a consequence of their selected Type. For example, the Switch type has ON and OFF states with associated default commands. If no custom behavior is found in the Rules, then the received command will just be sent out to the targeted protocol address. To continue the example, we can override the ON and OFF actions for a specific switch type--but if we don't, default on and off commands will be sent based on the appropriate bindings.)
  • Rules are generally used to modify the timing of actions or which items get switched, but they are theoretically far more powerful, able to modify accessible runtime objects via the Xtend language. It's never set out what's accessible via the runtime JVM and what's not--thus my usage of "theoretically". Personally, I'm still rooting for installation of Groovy on McClellan, which would allow me to do runtime reflection and object discovery via the OpenHab JSR 223 module.

All this said, OpenHab2 is just acting as a really big command dispatch, converting from a GUI event to an IoT protocol event. For most item types, it hides details of exactly what command gets sent out to the device, although one item type (the String item) allows you to specify a string command to be sent via the chosen protocol. The best way to choose a type to model your item is to consider what states need to be toggled in the receiving IoT device. Incidentally, most of I3's items are currently modeled as the Switch type.

Customization

Our installation has received a small amount of custom configuration:

• Most bindings are not initially installed; as of this writing, the Chromecast, Amazon Dash, and MQTT bindings have been added using PaperUI. (See http://10.13.0.22:8080/paperui/index.html#/extensions for the up-to-date list of bindings we have installed.)
• Other non-standard plugins include the JDBC persistence module and the Google calendar scheduler.
• Theoretically, JavaScript scripting of rules (and, as the documentation states, "general-purpose extension...[of openHAB])" has been enabled. It hasn't entered use yet, though.

Notes on configuration:

• Please do not uninstall plugins that have already been added! We're uncertain what effect it might have on the runtime and configuration files. (In two instances, I've observed the config files remaining unchanged when removing/re-adding plugins -- mkfink)
• While it is theoretically possible to add and remove items and rules via PaperUI, it's not stable. Edit items and rules directly on McClellan instead.
• The primary OpenHab configuration files are in the GitHub master branch of 'openhab2-config'.

About the McClellan Instance

Our instance of OpenHab is currently running on McClellan (10.13.0.22). As an internal-facing server, it can only be accessed from within the network.

As noted, the configuration has already been stored to GitHub. Not incidentally, these are precisely the files you need to modify to change how our instance behaves. The local repo lives in the configuration directory--/etc/openhab2.

Most of the configuration we've performed is in either the rules/ or items/ subfolders. As implied, items/ contains the mappings which let OpenHab talk over IoT; this is typically done using Modbus or MQTT command strings. rules/ contains most of the ways those items are controlled. Note that the MQTT topic must be provided by whoever set it up; see the MQTT hierarchy notes above.

To Modify Configuration

Samples of both MQTT and Modbus items are seen in this config file telling OpenHab how to talk to the Fab Lab ventilation fan:

FILE: /etc/openhab2/fablabVent.items
// Fab Lab Ventilation Fan
//Switch FLV_Request "Fab Lab Vent Fan Request Button" (ALL) {modbus="adam6060_3_di:5"}
//Switch FLV_Status "Fab Lab Vent Fan Status Indicator" (ALL) {modbus="adam6060_3_do:5"}
Switch FLV_Fan "Fab Lab Vent Fan Control Output" (ALL) {mqtt=">[mosquitto:cmnd/i3/inside/fablab/vent/power:command:*:default], <[mosquitto:stat/i3/inside/fablab/vent/POWER:state:default]" }

Note the comments on the Modbus items--at present all our IoT Items talk over MQTT.

Items may be grouped using an item file; this allows a single command to be dispatched to multiple items of the same type. Alternately, multiple commands to items of differing types may be dispatched at once using a rule against a String state change, such as in the following:

FILE: /etc/openhab2/rules/TrafficLightVirtualGroupCommandHandler.rules
val turnAllOff = [|
    sendCommand(TrafficLightRed,OFF)
    sendCommand(TrafficLightYellow,OFF)
    sendCommand(TrafficLightGreen,OFF)
    Thread::sleep(2000)

    null
]
    
val turnYellowOn = [|
    sendCommand(TrafficLightRed,OFF)
    sendCommand(TrafficLightYellow,ON)
    sendCommand(TrafficLightGreen,OFF)
    Thread::sleep(2000)

    null
]
    
rule "Off"
when
    Item TrafficLightVirtualGroupCommandHandler received command "Off"
then
    turnAllOff.apply()
end
    
rule "Caution"
when
    Item TrafficLightVirtualGroupCommandHandler received command "Caution"
then
    while(true)
    {
        turnAllOff.apply()
        turnYellowOn.apply()
    }
end

To Modify the GUI

To check item configuration or change which items are exposed in the GUI, you can use one of OpenHab's provided UIs. Alternately, you can use HabPanel, which allows users to configure the UI more extensively. HabPanel is recommended.

To view it:

1. Navigate any browser to http://10.13.0.22/start/index.
2. Select "HabPanel", at the right.
3. If no habpanel has been opened on this machine, you'll need to select one for use. Select the option named like "Select Custom"; select any of the members of the list which appears.
4. If someone has already opened a habpanel on this machine, you'll be directed to it. The title (like "Test Control Panel") will appear, but you'll need to select it before you can continue.
5. Eventually, you'll probably reach the main HabPanel test panel. It should look like the following. To access control configuration, and see what's being sent to OpenHab's rules, hover over the name ("Test Control Panel" in this case). A pencil will appear to the immediate right of the name label; select it.