Tutorial: Migrate your binding to the Maven + Bnd based build system

Good tutorial. In https://www.openhab.org/docs/developer/buildsystem.html#adding-dependencies, it mentions about putting all relevant lib files into /lib, where exactly is this with relative to the bundle root? Is it in src/main/resources/lib? or same lvel as src?

It’s in the bundle root itself, so next to src


Let’s say i need to use “org.openhab.core.io.transport.mqtt” in my custom bundle, but during “Resolve” on app.bndrun, i am getting this error:

osgi.wiring.package: (&(osgi.wiring.package=com.hivemq.client.mqtt.datatypes)(&(version>=1.1.0)(!(version>=2.0.0))))
⇒ [com.hivemq.client.mqtt version=1.1.2]
⇒ osgi.wiring.package: (&(osgi.wiring.package=dagger))
how do i attach this “dagger” package into my custom bundle in order to have a successful “Resolve”? I tried Step 8, but still can’t get through this problem.


I still don’t understand why the folder name is used as project name and not the artifact id.
Anyway I tried Eclipse 2019-9 and it worked the same for me as 2019-3. So it might be a mac thing, or just some specific option we use differently. Hopefully you won’t experience problems anymore.

Without knowing how your feature.xml and poms look like I would be guessing. So I don’t know the answer other than look at the other bindings that use mqtt io.

Sure. Even org.openhab.binding.mqtt have the similar problem. Here are my POM.xml and features.xml.


<?xml version="1.0" encoding="UTF-8"?>
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">




  <name>openHAB Add-ons :: Bundles :: TestMQTT Binding</name>


<?xml version="1.0" encoding="UTF-8"?> mvn:org.openhab.core.features.karaf/org.openhab.core.features.karaf.openhab-core/${project.version}/xml/features
<feature name="openhab-binding-testmqtt" description="TestMQTT Binding" version="${project.version}">
    <bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.testmqtt/${project.version}</bundle>
    <bundle dependency="true">mvn:com.google.dagger/dagger/2.0</bundle>

@hilbrand This has also been discussed on another thread (struggling-with-mqtt-in-development-of-new-binding). @J-N-K is aware of it, but has no time to look into it, which I fully understand.
A released binding affected by it is the nikohomecontrol binding. I did some further development, but can’t get it to run inside Eclipse anymore since the move to HiveMQ. I tried doing remote debugging, but for a reason I don’t understand yet, Eclipse does not connect to the locally running OH instance on my Windows laptop.
The binding compiles fine and I can run it in an OH install, just not debug at this time.
If you have any suggestions, I would very much appreciate it.

@hilbrand i tried to follow your guide with regards to external libraries. My bundle has several dependencies in POM and FEATURE:

The bundle works on Eclipse IDE debug but fail to resolve on snapshot 2.5.0 because of missing of above libraries. I thought with these definitions that will be downloaded automatically by Karaf? Thanks

  	<!-- https://mvnrepository.com/artifact/javax.websocket/javax.websocket-api -->

Q1) Can someone explain how to to use libraries in .m2/repository? Assume that i want to use websocket-server.jar, how do i define this in my binding and also openhab.demo.app? By doing this, do i still have to manually this websocket-server.jar into “/add-ons” folder of openhab-distro in another system?

Q2) I see that “https://openhab.jfrog.io/openhab/libs-release” repository has many libs in there, how do i force IDE or openhab-distro to automatically pull those libs?

Sorry, i am not really 100% with this maven or bnd in openhab. Cheers

When putting a jar file in an addons folder it doesn’t automatically install the dependencies. I think this is still something we need to improve (Has something to do with it must be a kar file. I’m not familiar with the specifics) I also have this problem. I always create a jar specific for testing this, by creating a lib folder in the binding directory and put the jars in it. This is then only for testing. When such a binding is part of openHAB installation itself it will work as expected via the feature dependencies.
It’s also possible to install the dependent jars via the karaf console.

Btw you mentioned only websocket libraries. openHAB has default support for websocket and then you don’t need those libraries. So maybe that might also be a possible solution.

You could use

mvn clean install -pl :org.openhab.binding.<your binding> karaf:kar

command to kreate a .kar file with included dependencies and put it into addons folder.


Rather than copying to /addons/, you can use…

bundle:install -s file://<path to jar>

… and…

bundle:update org.openhab.<the rest of the bundle's name> file:///<path to jar>

… and Karaf will resolve the dependencies.

1 Like

I also have some issues related to what @lsafelix75 is describing wrt dependencies/lib folder:

Have a binding (ABB Free@Home) which is based on xmpp.rocks (xmpp over websocket), i.e. libs from mvn rep, however, as the gateway for this binding is not following official websocket/xmpp protocol, the xmpp library is customized to fit the binding. Thus not considered an option to swap to default OpenHab libraries.

Following the implementation of rocks.xmpp from mvn rep, with some customized classes, the dependencies end up requiring in total of 21 libraries. As part of initial migration to mvn + bnd, the only solution to follow was to add these libraries/jars to a lib/ folder and include in build path, Initially this also worked wrt mvn clean install and runtime.

Althoug, suddenly, after having done some adjustments, recently mvn clean install started to generate error:

Failed to execute goal org.apache.maven.plugins:maven-jar-plugin:3.0.2:jar (default-jar) on project org.openhab.binding.freeathome: Error assembling JAR: Unable to read manifest file (invalid manifest format)

Would assume this would relate to my messy classpath with all the included jar files in lib folder? And have no clue how to sort this issue out?

Kept the customized classes (jar files) in the lib folder, and included remaining dependencies in the binding pom file, and everything now build as expected.

@hilbrand sorry to bring this up again. I’m trying to test updated ZigBee libraries. I have everything (seemingly) resolving correctly to the latest version (1.2.7) - everything in Eclipse looks fine and if I view the source, it shows the correct version. However, the demo app runs with the wrong JAR version (as far as I can tell).

The demo app resolves the dependencies ok and shows the correct version (1.2.7) in the resolution results. However, when I run this, it fails with a java.lang.NoSuchMethodError. I’m assuming therefore that when the demo app actually runs, it is using the wrong version.

If I look in the list of maven dependencies in the demo app project, I have both the new JAR and the old JAR being listed - this is presumably because openHAB pulls in this version of the dependency through openhab-distro repository. The zigbee reactor POM has 1.2.7, the openhab-distro has 1.2.3 and it seems to pick 1.2.3.

I’m trying to work out how to resolve this - any thoughts?

I also saw that there was some work done to resolve the issue that maggu reported in the bnd repo a week or so back - is that likely to improve this (I think it was related) and are we running the latest bnd (I guess probably not as it was quite a recent change).


1 Like

@hilbrand I’m still struggling on with this for the past few days. I tried forcing the library version through the manifest / bnd, but that didn’t help. I’ve found that the resolved versions of the binding in demo app is resolving to the 2.5.0 version of the binding and not the version that is in the IDE (2.5.1-SNAPSHOT) -:

I have found that the reactor is also still using a parent of 2.5.0 which I thought may explain this.


  <!-- do not delete the version here as it is required by the release process -->

I’ve updated the reactor pom and cleaned everything, but now I’m back to another problem I’ve had in the past where the list of repositories available in demo app does not include zigbee at all! Edit: I resolved this, but still can’t get the IDE to run the version in the IDE - it continues to want to run a pre-2.5 version).

I was thinking that maybe that is caused by the pom version in the demo app being 2.5.0-SNAPSHOT -:


All/most other poms in the openhab-distro seem to have been changed to 2.5.1-SNAPSHOT except for this one. Changing this gives me errors though -:

I’m not sure why it can’t find these dependencies - are they not available for 2.5.1-SNAPSHOT?

I’d really welcome any thoughts on this as I’ve spent a large chunk of the past 3 1/2 days looking at this.

did you find a solution to this?
I also fail to run my binding in the eclipse environment as it seems whatever I do it does not use the one from the workspace, but instead the 2.5.0-SNAPSHOT one…

The development environment was not updated after 2.5 was released - this should have been fixed last night but I’ve not had the chance to test it yet. Hopefully I’ll get the chance tomorrow.

@marcel_verpaalen I’ve done a quick test, and it seems to work now if you pull the 2.5.x branch from openhab-distro.

1 Like

thanks @chris… I’ll pull the latest 2.5 branch.
I finally did manage to run my dev binding, but that was with dark vodoo, lots of manual path settings etc…
Will try to restore it back to normal and try again

@hilbrand Could you give me some advise how to include a zip (containing script code) into the bundle. The zip sits in the lib folder. The jar file in that folder gets picked up and is part of the bundle, that’s ok.

To include the zip I added


to pom.xml, but “mvn clean install” reports

[ERROR] .../bundles/org.openhab.binding.appletv/target/com.googlecode.addjars.mojo.AddJarsMojo/pom.xml [0:0]: Input file does not exist: lib/pyatv.zip

Also taking out lib/ from the resource path doesn’t make the trick.

Secondly I need to include a folder with sub directories (resource data), the folder structure gets copied to the bundle, but in each sub directory a file <<<EMPTY>>> is created instead of including the file. This could be solved by making a zip out of it and include this into the jar when I got the above running.

Any ideas?