The OpenHAB (Open Home Automation Bus) project

  • Print
Details
Published on Tuesday, 31 December 2013 12:52

    Imagine that you open you email calendar and create a new event for let's say 19:00 that turns on your oven, turns on the smoke detector (just in case) and turns on the camera in the kitchen in case the smoke detector is triggered. You also create a new calendar event that at 19:30 turns off the oven and the smoke detector. When you are back home at 19:40 you have a hot meal waiting for you in the kitchen. Or in the more straight-forward scenario - you can use your smartphone or laptop to directly manipulate your home devices and link them in any possible way you can think of. The number of practical use cases is just enormous to list. Now imagine that you put these "home automation" in the more global context of "Internet of Things" where device interaction is not restricted only to the PAN (Personal Area Network) of your home. The number of use cases grows much larger.
   Lack of standartization and rivalship among device vendors however still impede rapid developments in the field but this may proove not to be so bad after all - more time for polishing other aspects such as security, performance and resource consumption is available. 
   What mechanism should be used to implement such types of systems ?Definitely a highly modular and distributed approach is required for the implementation of a home automation system that provides an acceptable level of abstraction and allows for a seemless integration and remote control of devices.
    In this article I will present you the architecture of the OpenHAB (Home Automation Bus) award-winning (Duke's Choice Award 2013) project that has the potential to become a de-facto standard for the integration of devices in a connected world. For a modular runtime system it uses the Equinox OSGi implementation. I also assume that the reader has basic understanding on the principles of OSGi (that are now being applied in a number of implementations adapted for the needs of many other industries such as car manufacturing, e-health, mobile applications and others). 
   In order to make full use of the article you should already have prepared a development environment as desribed in the project's wiki (see references).

Architecture

  The architecture of OpenHAB is pretty clear and well-documented in the project's wiki (see references). However my focus will be to provide some more explanations on some of the concepts and an architectural review from the point of a developer willing to contribute or research the internals of the project. The following diagram is provided from the OpenHAB wiki and provides an overview of the high level architecture along with its components:

 architecture

Some important terms used throughout the project: 

  • binding - a binding is an adapter OSGi bundle that allows you to connect to a device or a series of devices that can communicate via a particular protocol (and hence each binding may require particular configuration based on that protocol such as host name and port or any other protocol-specific configuration). If you look into the sources each binding is provided in a separate bundle project in the format: org.openhab.binding.<binding_name>. The bundle of the binding can be deployed to the OpenHAB runtime by copying it to the 'addons' folder;
  • action - an action in terms of OpenHAB can be used to "plug" additional functionality in the OpenHAB system that can be manipulated via scripts in the automation engine or directly from the runtime. Each action is typically a separate Java class that provides simple methods that provide the particular functionality. This class is then registered as an OSGi service to the OpenHAB runtime and methods become available for execution from the script engine. Xbase is used to provide the scripting mechanism that allows execution of scripts at runtime and hence - has access to the registered actions and other internal OpenHAB data (such as items). If you look into the sources each action is provided in a separate bundle project in the format: org.openhab.action.<action_name>. Current list of actions include sending of email, sending notification to an Android device, sending status updates to twitter and others. Action bundles are also deployed to the OpenHAB runtime in the "addons" directory.
  • item - in terms of OpenHAB you can think of an item as some some particular particle that can be linked to a binding (such as colors, strings, numbers, switches (on/off) and others). Items can also be combined in groups (that are also a particular type of items). Items are declared using a specific DSL language in a separate file. The DSL is implemented by means of the XText library. The grammar is very easy to understand and is described in org.openhab.model.item/src/org/openhab/model/Items.xtext. This declaration of items allows for easy generation of UI from the item declarations thus saving effort in writing UI for each item and enforcing homogenous UI;
  • sitemap - sitemaps allow to describe your UI declaratively using another DSL language that is created again with XText. The grammar is described in org.openhab.model.sitemap/src/org/openhab/model/Sitemap.xtext.

   All of the project components are also installed as OSGi bunbles in the Equinox runtime. Bundles are grouped into features - we have three features provided by the following projects:

  • org.openhab.runtime.feature (groups OpenHAB runtime bundles)
  • org.openhab.runtime.feature (groups OpenHAB designer bundles)
  • org.openhab.dependencies.feature (groups common bundles used by both the runtime and the designer)

Note: The OpenHAB designer is an Eclipse RCP application that is not listed in the above diagram but is provided by the org.openhab.designer.* projects. It serves to provide an interactive application for the configuration of the OpenHAB runtime. 

   Features are further grouped along with external features from the p2 repositories to define the two products (OpenHAB runtime and designer) that are provided by the org.openhab.runtime.product and the org.openhab.runtime.designer projects.

Other projects include:

  • org.openhab.archetype.action - defines a Maven archetype for generating a stub action;

  • org.openhab.archetype.binding - defines a Maven archetype for generating a stub binding;

  • org.openhab.core.* - OpenHAB runtime core functionality (that builds on top of the Equinox container) - the org.openhab.core project provides the implementation of the OpenHAB event mechanishm (that uses the OSGi EventAdmin to produce/consume events), the item provider that provides the representation of an item, the internal item registry, internal types and the binding abstractions;

  • org.openhab.core.autoupdate - provides a mechanism for triggering updates for items upon reception of item commands;

  • org.openhab.core.library - provides the core library of items and item types;

  • org.openhab.core.persistence - provides the persistence mechanism for storing item states using different storage services - the concrete storage services should implement the org.openhab.core.persistence.PersistenceService interface and the various supported services are provided by the org.openhab.persistence.* projects;

  • org.openhab.core.scriptengine - provides the interface for the OpenHAB script engine. The only implementation of the script engine interface is currently provided by the org.openhab.model.persistence project;

  • org.openhab.core.transform - provides a mechanism to transform an input according to various types of mechanisms (e.g. XPath expression over the input, XSLT transformation, JavaScript function executed over the input and others). Transformations must implement the org.openhab.core.transform.TransformationService interface and current implementations are available in the org.openhab.core.transform.internal.service package;

  • org.openhab.io.* - provide mechanisms for receiving input/sending output from/to external systems. This includes integration with the Equinox OSGi console (by registering the 'openhab' namespace for the OpenHAB commands), the RESTful web services exposes by the OpenHAB runtime (using Apache Jersey with embedded Jetty web server) and others - you can look into the various projects for more details;

  • org.openhab.model.* - provide common models for the various modules of the system that are that are declared by means of XText-provided DSL language configurations (such as the items, the persistence module, the rule engine, the script engine and the sitemaps module). The models are used by both the runtime and the designer - the projects org.openhab.model.*.ui provide model UI for use only by the designer. Moreover additional generation of sources and the EMF models of the OpenHAB modules is performed by means of the Modeling Worflow Engine 2 generator engine that is part of Xtext (generator logic for the various models is declared in *.mwe2 files in the corresponding projects - code is generated for both the module and the module UI projects);

  • org.openhab.ui.* - provide the web UI of OpenHAB that is also deployed as an OSGi bundle and makes use of the OSGi HTTP service in order to serve content from servlets;

  • targetplatform - provides various run configurations for the OpenHAB runtime and the designer;

  • distribution - the distribution project that provides the directory structure, additional configurations and scripts that are part of the deployment package.

The build of the system is pretty straightfoward - Maven is used along with Tycho (that is used to align the OSGi dependency system with the one used by Maven) and the root of the OpenHAB repository is a parent project that builds its child modules in the following order:

  • bundles - all projects are build in the proper order as specified in bundles/pom.xml

  • features - all feature projects are build in the proper order as specified in features/pom.xml

  • products - all product projects are build in the proper order as specified in products/pom.xml

  • targetplatform - the targetplatform project is being build as specified in  targetplatform/pom.xml

  • distribution - the various deployment packages are being created based on the build output of the other projects and the contents of the distribution project as specified in distribution/pom.xml

   The GitHub repo is linked to a Jenkins CI server (see references) so that you can directly download and try out the latest build of the project without building it manually. 

   Other OSGi implementations (other then Equinox) that are more suited for embedded devices are also easy to experiment with. One of them is Eclipse Concierge which is a small-footprint OSGi container that is optimized for embedded devices.

Contribution

   Based on the above information you can cantribute a number of things such as new bindings. At the time of writing of this article a new project under the name of Eclipse SmartHome (currently in "Proposal" phase - see references) is underway. Its initial contribution will be from the OpenHAB codebase. So if you want to contribute to project you may also consider SmartHome when it enters the Incubation phase and has the initial contribution.  

References

1) OpenHAB GitHub project repository
https://github.com/openhab/openhab/

2) OpenHAB wiki
https://github.com/openhab/openhab/wiki

3) OpenHAB 1.0 - Home Automation for Geeks
http://kaikreuzer.blogspot.com/2012/08/openhab-1.html

4) Home Automation using OpenHAB, Geecon 2013
http://vimeo.com/77279721

5) Eclipse SmartHome project proposal
http://eclipse.org/proposals/technology.smarthome/

6) Wikipedia's entry on Home Automation
http://en.wikipedia.org/wiki/Home_automation

7) Wikipedia's entry on Internet of Things
http://en.wikipedia.org/wiki/Internet_of_Things

8) Eclipse SmartHome project
http://www.eclipse.org/smarthome/

Share