Understanding the openHAB Event Bus

What is openHAB?

A Quick Overview

The open Home Automation Bus (openHAB) is an open source, technology agnostic home automation platform which runs as the center of your smart home!

openHAB communicates electronically with smart and not-so-smart devices, performs user-defined actions and provides web-pages with user-defined information as well as user-defined tools to interact with all devices. To achieve this, openHAB segments and compartmentalizes certain functions and operations. The following table gives a top-level description of the most important concepts as well as a link to more information:

While the table above gives an overview, please remember that it is incomplete and a simplification of openHAB for the sake of this overview. More elements will be introduced in the documentation.

Concepts

When first thinking about your home automation system, it may be helpful to bear in mind that there are two ways of thinking about or viewing your system: the physical view and the functional view.

The physical view will be familiar to you. This view focuses on the devices in your system, the connections between these devices (e.g. wires, Z-Wave, WiFi hardware), and other physical aspects of the system.

The functional view might be a new concept for you. The functional view focuses on how information about the devices, connections, and so on, is represented in user interfaces. The functional view includes focusing on how rules affect representations of physical devices in software. Perhaps most important to you, the functional view focuses on how an action in a user interface affects the software associated with the physical device it represents.

It is a bit of an over-simplification, but you can think of the physical view as being a view of the 'real world', and the functional view being a view of the 'software world'.

Things, Channels, Bindings, Items and Links

Things are entities that can be physically added to a system. Things may provide more than one function (for example, a Z-Wave multi-sensor may provide a motion detector and also measure room temperature). Things do not have to be physical devices; they can also represent a web service or any other manageable source of information and functionality.

Things expose their capabilities through Channels. Whether an installation takes advantage of a particular capability reflected by a Channel depends on whether it has been configured to do so. When you configure your system, you do not necessarily have to use every capability offered by a Thing. You can find out what Channels are available for a Thing by looking at the documentation of the Thing's Binding.

Bindings can be thought of as software adapters, making Things available to your home automation system. They are add-ons that provide a way to link Items to physical devices. They also abstract away the specific communications requirements of that device so that it may be treated more generically by the framework.

Items represent capabilities that can be used by applications, either in user interfaces or in automation logic. Items have a State and they may receive Commands.

The glue between Things and Items are Links. A Link is an association between exactly one Channel and one Item. If a Channel is linked to an Item, it is "enabled", which means that the capability the Item represents is accessible through that Channel. Channels may be linked to multiple Items and Items may be linked to multiple Channels.

To illustrate these concepts, consider the example below of a two-channel actuator that controls two lights:

The actuator is a Thing that might be installed in an electrical cabinet. It has a physical address and it must be configured in order to be used (remember the physical view introduced at the beginning of this article).

In order for the user to control the two lights, he or she accesses the capability of the actuator Thing (turning on and off two separate lights) through two Channels, that are Linked to two switch Items presented to the user through a user interface.

Channels

Channels are the logical link between a Thing and an Item. Channels originate from Things definition and define how your Thing can communicate with Item (and vice versa). You will create channels when defining your Thing.

During the definition of your Thing you will identify the channel to which your Item will be linked. These two steps ensure that openHAB can transmit the information from the Thing to the Item (and vice versa).

Bindings

Bindings are software packages that are installed by the user in openHAB. The main purpose of Bindings is to establish the connection between your device and your Thing. Bindings communicate with your device and translate all commands to and from openHAB between your device and your Thing.

Bindings are provided in the Add-on section (opens new window) of this website. Here you will find a searchable list of several hundred bindings to support as many devices as possible. New bindings are regularly added as developers integrate more devices into openHAB.

For each binding, detailed instructions and examples are provided that include guidance on configuration (if any) of the binding itself, the definition of Things supported by this binding and the Channels these Things provide. In most cases, the description also contains a fully worked out example that includes a definition of Things and its Channels, Items linked to those Channels and the use of these Items in a sitemap.

Event Bus

The openHAB framework provides an event bus for inter-component communication. The communication is based on events which can be sent and received through the event bus in an asynchronous way. Examples of openHAB event types are ItemCommandEvent, ItemStateEvent, ItemAddedEvent, ThingStatusInfoEvent, etc.

For us, only the items and the item events are relevant.

So if we simplify it a lot, then we have a device and as a Digital Twin for this we have a Thing. This device is connected via various bindings and a Thing is created in openHAB for this device on the basis of the binding, which you can imagine as an instance of the class of the binding for this device. For different manufacturers, communication technologies, etc. there is a corresponding binding. In this binding several classes are created, since e.g. a manufacturer owns several devices. Means for a device there are defined functions in a class and for another device there is accordingly another class with differently defined functions. Thus Things do not only differ on the basis of the Binding but many Binding offer for different devices also again different Things. In the end, an item is created via a Thing. An item refers to a function of the device. If this function is a pure sensor, then this item only receives a state. But if this function is also something that can be switched or a mode, a program or whatever can be changed, a state is assigned and a command can be sent to the device so that something changes.

Every changing state, but also every command runs through the event bus of openHAB.

The Interfaces

The EventPublisher posts Events through the openHAB event bus in an asynchronous way. The EventSubscriber defines the callback interface to receive events of specific types to which the event subscriber is subscribed. The EventPublisher and the EventSubscribers are registered as OSGi services. An event subscriber can provide an EventFilter in order to filter events based on the topic or the content. If there is no filter all subscribed event types are received. The event itself will be subclassed for each event type, which exists in the System (e.g. ItemCommandEvent, ItemUpdatedEvent, ThingStatusInfoEvent).

The Core Events

This section lists the core events provided by openHAB which can be divided into the categories Item Events, Thing Events and Inbox Events.

An event consists of a topic, a type, a payload and a source. The payload can be serialized with any String representation and is determined by its concrete event type implementation (e.g. ItemCommandEvent, ItemUpdatedEvent). The payloads of the openHAB core events are serialized with JSON. Each event implementation provides the payload as high level methods as well, usually presented by a data transfer object (DTO).

A topic clearly defines the target of the event and its structure is similar to a REST URI, except the last part, the action. The topics of openHAB events are divided into the following four parts: {namespace}/{entityType}/{entity}/{action}, e.g. openhab/items/{itemName}/command.

The type of an event is represented by a string, usually the name of the concrete event implementation class, e.g. ItemCommandEvent, ItemUpdatedEvent . This string type presentation is used by event subscribers for event subscription (see chapter "Receive Events") and by the framework for the creation of concrete event instances.

The event source is optional and represents the name of the source identifying the sender.

Item Events

There are the following item events in openHAB:

The ItemStateEvent is always sent if the state of an item is updated, even if the state did not change. ItemStateChangedEvent is sent only if the state of an item was really changed. It contains the old and the new state of the item.

The GroupItemStateChangedEvent is sent only if the state of a group item was changed by a member. It contains the old and the new state of the group item as well as the member.

As a note to the Topics, one can add that openhab could also be replaced by smarthome.

Interesting for us are the two events ItemStateEvent and ItemCommandEvent.

An ItemCommandEvent is executed when, for example, I switch in the sitemap a switch from OFF to ON or execute a sendCommand in a rule. An ItemStateEvent is triggered when the state of an item changes. This happens immediately, for example, after an ItemCommandEvent or when a binding performs a status update. I can also operate a device without openHAB and the item then recognizes that a state has changed. Or a temperature sensor changes the measured temperature as a state several times by itself.

The bridge from openhab to ROS works bidirectionally. A ROS device, such as a robot, should be able to subscribe to the items from openHAB. For this purpose, the state of an item is published. However, since one is not a binding that changes the information in an item, a sendCommand and no postUpdate must be performed. This means that the bridge must subscribe commands! Then openHAB will execute this command.

Item Types

To subscribe the items from openHAB or to publish an item including a command to openHAB you need the appropriate message types. These are based on the Item Types and Command Types of openHAB.

The Item type defines what kind of state can be stored in that Item and which commands the Item will accept. Item types are comparable to basic variable data types in programming languages. Each Item type has been optimized for a particular kind of component in your smart home. This optimization is reflected in the data and command types.

Available Item types are:

Command Types

In the last step we take a closer look at the Command Types and its Range of Values.

A command type like OnOff is ultimately an enum and contains the strings "ON" and "OFF" as constants (this is why they are written in UPPERCASE), so the other enum commands actually look the same. This means that there are only two constants per each enum type.

The Command Types are only used within openHAB. The openhab_msgs also have these enums in their field description, but you may have to work with a string in parts of your program!

The next chapter continues with Installing the openhab_static_examples.