Guide: Binding development changes for openHAB 3 (from 2.5.x)

This description is specific for new bindings targetted for openHAB 3 or not yet merged when we switch the main branch over to openHAB 3 or bindings not part of the openHAB-addons repo. See also the post of Kai below.

As you may have read in the announcement of the 2.5.8 release, openHAB 3 is on the horizon. A big version number suggests big changes. So what does this mean for binding development. In short: not whole lot. Because the core binding interface functionality hasn’t changed much since 2.5. But there are some changes that cause bindings compiled for 2.5 not work for 3.0 and the other way around. So you need to make some changes to make your binding compile and run on openHAB 3.

So what did change related to binding development?

Java 11

openHAB 3 will require Java 11 (No older or newer version). Therefor you need to install and use Java 11 in your Eclipse (or other) IDE in order to be able to run openHAB 3. The easiest is to do a new installation of Eclipse with the Eclipse installer and select 3.0 as branch on openHAB configuration in the installer. During installation make sure to select Java 11 (In 2 places. currently the installer will ask for the java 8 environment, but you can simply select java 11). If you build on the command line with maven also make sure you maven uses the correct Java version in case you run both Java 8 and 11. It should be possible to have 2 Java versions installed, but you need to make sure to set the right path for the specific Java version when you run maven.

Namespace change of openHAB core classes

With the migration of Eclipse Smart Home to openHAB the namespace of all classes in openHAB core needed to be changed. This means all imports done by bindings that refer to org.eclipse.smarthome have been changed to org.openhab.core. With your binding code you can simply do a file level replace of this text string in the java source files to migrate the binding. On linux you can use the following commands in you src/main/java directory:

find . -name *.java -exec sed -i "s/org.eclipse.smarthome.core/org.openhab.core/g" {} \;
find . -name *.java -exec sed -i "s/org.eclipse.smarthome/org.openhab.core/g" {} \;

(2 commands are needed because all classes where moved to core, but some where already in core and thus would be moved incorrectly if the second command would be done first).

Additional the class SmartHomeUnits has been renamed to Units. You can globally replace it with:

find . -name *.java -exec sed -i "s/SmartHomeUnits/Units/g" {} \;

ESH-INF renamed to OH-INF

The resources directory ESH-INF of the xml files located in src/main/resources has been renamed to OH-INF. You can simply change this by renaming this directory.

Migrate to JUnit 5

Part of the changes in openHAB 3 is the upgrade of the unit tests to JUnit 5. Therefor if you have any unit tests these should be migrated to JUnit 5. There are some differences between JUnit 4 and 5, like import changes and the message in asserts moved from first parameter to the last.


With these changes in place you should be able to start developing bindings for openHAB 3 and also test drive the new user interface.


Thanks for this great summary, @hilbrand!
I’d just like to add that the described steps are currently done automatically on almost all add-ons with the build plan, so that they are already now available in the 3.0-SNAPSHOT distro. It is hence really an easy and straight-forward change that should not mean any issue for most contributors - just to make sure that nobody is afraid of this upcoming change :sunglasses:.


Thanks to all involved and looking forward to checking out the results of all your hard work on V3.

Just have one question and that is what to do with bindings that are currently waiting for review in the V2.5.x branch? Will some/all get merged before the change to V3 branch or will this need to be done? I have the IpCamera binding waiting so hopefully V2.5.9 can benefit as well as V3.x

1 Like

Code may also need to be updated for dependency changes, most notably:


  • JUnit: 4.12 -> 5.6.2 (#1580)
  • Swagger: 1.5.5 -> 2.1.0 (#1576)


  • Jersey -> JAX-RS Whiteboard (#1443)


To be removed:


To be realistic. Most new bindings in review will probably not be merged before the change to openHAB 3 branch becomes active. We’ll probably try to get as much as possible merged. But it also depends on the quality of the submitted new bindings. The more issues (that can be as simple as not having included the right files, or accidentally change unrelated files) the longer it takes, because the iteration process going back and forth between developer and review can take some time. In general if you write clean code and neat documentation your binding can be merged quickly.

Looking forward to OH 3, and then some question, which version of Eclipse is best to use?
I’m just trying to install 2020-06, but still not there with an working IDE yet.

What do you mean by not working? For openHAB 3 development I’ve installed 2020-06 and that seems to work. For 2.5.x development I had problems with 2020-06 (gives an error on the pom.xml file) and use 2020-03.

I have an working 2.5.x (2020-03 I will remember) installation and I can develop and run OH just as normal.

I have installed 2020-06 in the very same way as you described in an earlier thread.( I have used this for 2020-03)
But I am now been waiting for a couple of hours of Perform Setup Tasks… and the installation are still on Building: (93%)

Invoking ‘Maven Project Builder’ on ‘/org.openhab.ui’.
Refershing workspace (Blocked: The user operation is waiting for “Building” to complete

I use Eclipse 2020-06 for oH 2.5.x without any issues.
What repos did you select ?

Eclipse 2020-06 and OH 3.0 Stream
openHAB Development
openHAB Web UIs
openHAB Core Framework

Do you plan to develop on core and ui’s? For ui I’m not sure if eclipse is the best environment. I use vscode.

1 Like

Is 3.0-SNAPSHOT being built in to APT or RPM packages? I see a bunch of build artifacts from it, but no distribution packages.


It would be great if there is an installation package just for testing and playing around

I agree to what Dibbler42 say.
My plan is to test to redesign an still not merged binding, (there is an ongoing review) as your description above.
The binding I am thinking of is Kostalinverter which I have extended with functionality for Second generation.

I think I have found an possible reason, there is something not right with Java version. I will check and make a new try to install.
Thank’s to all so far!!

Regarding binding development. There certainly is an environment available. Just install Eclipse and only select openHAB Development.

I’m under the impression people just click checkboxes for other development topics during installation of Eclipse, like core and ui because they are under the impression that it’s needed (and overread that part in the documentation that says you don’t). But you don’t need those. And yes make sure you have the right Java (11) version.

Did you see @ysc’s post:

1 Like

Note that page ( only provides a link to download the snapshot’s .zip file, but there are other options which aren’t listed there yet - for instance there are Docker images available (3.0.0-snapshot-debian & 3.0.0-snapshot-alpine).

To be honest i didn’t saw Yannicks post, but i found it using google.

As Yannick wrote actually ther is only a zip file and i did’nt saw the docker files yet.

So my question was more in the direction: Will we find some kind of alpha repo to use apt or yum or what ever to install the package.

We don’t linux packages build yet, but let’s follow up on that on

1 Like