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

Just to clarify this even more: On September 21, when we switch to the master branch of openhab-addons as the default branch, we will migrate all existing add-ons with our script - so there is no need for any of you to do this manually. The steps described by @hilbrand in this post are really only necessary for anybody working on an add-on that is not in the official repo. All others that might want to play around with the migrated version of the code can also just grap it from

Syntax for macOS is

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

My understanding is that OH3 / the new UI doesn’t provide anymore

  • Simple Item Linking and
  • A view comparable to PaperUI::Control

This would have a significant impact of development turn arounds (at least for me). For example

  • I’m developing the Shelly binding (beside others)
  • My test environment has 20+ devices=20+ things, with various channels (stand+advance)
  • Usually I’m testing with a limited numbers of devices
  • sometimes, esp. before a new build I do add all of them and have a visual cross-check with PaperUI if all channels are initialized, do some clicking to verify control functions etc.

For now I have no idea how to perform that with OH3.

  • Manually defining items and linking all those channels manually is a night mare
  • Even this is done, sometimes I need to reset the config or do a fresh IDE installm which would lead into the same hazzel
  • Importing predefined textual items linking to the existing channels… :frowning:

@hilbrand @Kai (and others)
Maybe I missed something, could you give an advice or is something like the old features on the remaining roadmap?


look for “add thing as equipment” feature.

I was able to copy over my .things, .items and sitemap from OH2 to OH3 and it appeared to work.

Thanks for recommendations, but

  • I have 25 different thing types (and new are coming)
  • with up to 20 channels each

so any kind of manual definitions is a lot of effort and result in a static setup.
I’m not sure if the recommended approach will help here, also avoiding a static test setup.

1 Like

Just iun case you didnt already know… if you use the VSC openhab extenstion… you can automaticlly create the item file from the things… Take a look on the gif images in the extension description…

Have a look at

@Kai Long short short, I have finally some time to do some improvements on some of the bindings I have been using of the years. Question : Now that the port happened to 3.0, I see commits happening on both the 2.5.x as well as the main branch. What is the policy to follow here? Can any modification still be pushed to 2.5.x. or should everything go to 3.x? Is there a cut-off date? I prefer developing against 2.5.x. since that is running in my production environment, at least, for the time being. 3.x broke quite a few things for me, also bindings like helios, even if in the official bistro, are not working anymore (and I understand this, as I might be the only one/one of the few using it, so it never got tested properly in a prod env)…

Pls enlighten us :wink:


He already did in

So all changes go to main/3.x and only fixes are cherry picked to 2.5.x.

Hey @kgoderis, great to hear from you again! Yes, it would be wonderful if you could help fixing the bugs that you encounter in bindings in 3.x - let me know if there are any further questions besides the ones I have answered in the issue that @wborn has linked already.

1 Like

Cool! I definitely have to read up on a lot of changes

1 Like

What the status of commons-io commons-lang? Should they be avoided in bindings? My bindings compile with them, saw that the reason why they were removed (relative large footprint and java11 being able to solve most of the cases).

Yes, these should be avoided. We’re in a systematic removal process on these libraries

1 Like

Help needed to include sqlite support into a binding.
The binding downloads a sqlite db, and performs some queries against it.

I’m migrating a binding from OH2, to OH3. This binding relies on a library JDBC-sqlite, this library is included in the OH2.5 binding-jar, and it works.

in OH3:
I have tried to include the dependencie using feature.xml:


To make the binding work, I had to install the feature for sqlite persistence, but this solution has other side effects.
feature:install openhab-persistence-jdbc-sqlite

In OH2.5, the library was included using, like below.
bin.includes = META-INF/,

Either add the sqlite library dependency to the pom.xml with scope compile or add to feature.xml (use the same dependency as in persistence binding feature.xml) and build a jar file with mvn karaf:kar

1 Like

Updated pom.xml, and compiled archive with karaf:kar, fixed the dependenci.


Thanks fot the tip.
Binding (kar - file) now loads without manually loading the artifact for sqlite persistence.
However, I see a strange “bundle” with ID 245 in the console, is there something wrong in my config?

242 │ Active │  80 │ 3.16.1                  │ SQLite JDBC
245 │ Active │  80 │ 0                       │ wrap_file__var_lib_openhab_tmp_kar_org.openhab.binding.samsungdigitalinverter-3.1.0-SNAPSHOT_org_lastnpe_eea_eea-all_2.2.1_eea
246 │ Active │  80 │      │ openHAB Add-ons :: Bundles :: Samsung Digital Inverter Binding

I just forgot to adapt the version.
So if you get

Cannot find directory for project: org.openhab.addons:org.openhab.addons.reactor -> [Help 1]

you should adapt your pom.xml

+++ b/bundles/org.openhab.binding.mqtt.tasmota/pom.xml
@@ -7,7 +7,7 @@
-    <version>2.5.9-SNAPSHOT</version>
+    <version>3.1.0-SNAPSHOT</version>

Long time OpenHAB user taking my first shot at bringing the ISY binding up to version 3. Made the necessary changes, compiled, packaged, added to the addons directory and the bundle shows as active in the console. But it doesn’t show up in the Paper UI as an installed binding nor does it appear as an option when adding a thing.

Probably a bad combination, trying both the new UI and binding development at the same time. Should I assume that the binding isn’t registering properly or have I missed an installation step? Nothing in the logs (first try resulted in some missing dependancies but now it appears to be clean).