Working Repository of OpenHAB adapter for VICINITY
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


About OpenHAB

OpenHAB is a widely known, open-source solution for IoT Gateways, specifically targeting the home automation domain. However the concept behind is not strictly limited to this domain, as it is build upon the modular Open Services Gateway Initiative (OSGi) Architecture and already supports a broad variety of protocols available on the market.

The openHAB project follows the OSGi specification and consists of OSGi bundles. The OSGi architecture describes a modular Java-based system where modules can be started, stopped, remotely installed and updated during system runtime. One main concept of openHAB is the distinction between Things and Items. Things are the internal representation of physical Objects and Devices, integrated into openHAB. Each Things comes with a variety of channels, mapped to specific properties of the devices. E.g. one channel of a Lightbulb would represent the brightness of this Lightbulb, another channel could then represent the color of it.

However, a user never directly interacts with these Things and Channels directly. Instead, the concept of Items is used. Items can be linked to specific channels (and more than one Item can be linked to the same channel) and offer ways to interact with the physical objects in a unified way. E.g. one Item could be of a Switch-Type, allowing the user to turn this switch on and off. The resulting on/off-command is then sent to the corresponding channel and hence to the corresponding item and is on the way translated into a Thing-specific format. Thus Items abstract the functionality from the actual interface to the devices. The user only needs to interact with Items to control certain functionalities and properties, without knowing the actual technical details involved in communication between them.

Adopting the OpenHAB concepts and mapping to VICINITY

The abstraction and the concept of Items maps onto the VICINITY infrastructure quite nicely. The VICINITY Adapter is implemented as an openHAB Binding (OSGI-Bundle). At the time of writing, only exporting Items and exposing them to VICINITY is implemented. In future releases of this Adapter, the opposite way (e.g. showing and controlling shared VICINITY objects inside openHAB) is also possible.

In its current implementation, this adapter interprets every Item as potential VICINITY object property or action. As Items can be grouped in openHAB, this adapter relies on Item groups and Item Tags to identify which object should be exposed and to which VICINITY object it belongs. See Item Configuration for more details.

Adapter Deployment in Development Environment

The VICINITY adapter for openHAB is implemented as an ordinary openHAB Binding. It can be used just as any other Binding. Follow the Instructions provided by openHAB, set up your IDE and openHAB installation accordingly: openHAB IDE Setup

After setting up your IDE this repository is supposed to be cloned as

<your IDE root>/openhab2-addons/addons/binding/org.openhab.binding.vicinityadapter

From there it can be importe as existing project into your IDE. Finally, update the runtime configuration to build and include this VICINITY adapter as well.

Adapter Deployment on Standalone Device (e.g. RaspberryPi)

The VICINITY adapter for openHAB is implemented as an ordinary openHAB Binding. It can be used just as any other Binding. Follow the Instructions provided by openHAB to set up your openHAB Device, depending on your Hardware Platform: openHAB Installation

Afterwards, the binding .jar should be placed into openHAB's addon folder. E.g. for Debian Package-based Installation at:


OpenHAB should dynamically load new addons. Otherwise, the binding needs to be enabled manually, via command-line:

# openhab-cli console
(log in as openhab:habopen)

openhab> bundle:list
(find the ID of the VICINITY Adapter, e.g.)

180 │ Active   │  80 │     │ VICINITYadapter Binding
(in case the bundle is not yet loaded and active, start the bundle)

openhab> bundle:start <id of VICINITY adapter. 180 in the above example>

Item configuration

In order for this adapter to find all Items you intend to expose to the VICINITY, Item Tags need to be added. Additionally the Adapter needs to know, how to group the selected Items together and form VICINTY objects. In order to do so, all Items that belong to the same VICINITY object need to be grouped together:

Dimmer  Bulb1_Dimmer    "Helligkeit"  (vcntBulb1)  ["vcntpropBrightness"] {channel = xxx}
Switch  Bulb1_OnOff    "Farbe"  (vcntBulb1)  ["vcntpropColor"] {channel = xxx}

The above example will expose on VICINITY Object called Bulb1 with two properties Brightness and Color. At this moment, all Properties are exported with Read and Write Links. Object name and Object ID (oid) are called Bulb1. For each property, the pid is called according to the single item names.

Connecting openHAB into VICINITY

Right now, each tagged and group item will be exposed according to the VICINITY Thing Description (TD) Format. Once started, the VICINITY Adapter (not included in this Binding) can be started and can read the TD from


Further improvements need to be implemented. User config parameters will be added to control read/write to properties, control the object type and human readable object names.

Stay tuned!