Need some help with setup to create new binding using maven/bnd

Starting to develop my very first binding (I know, bad timing for a newbie…), I am struggling a bit to get going. My serious programming skills date back to the 90’s and 00’s (when make was king…), so I watched an online course to better understand Maven. Obviously, I need some guidance and practice to make that ‘knowledge’ actionable.

I read a lot of fragmented issues and solutions, but I cannot put all the pieces of the puzzle together. :sunglasses:

What I’ve done:

  1. Install Maven (verified path settings with mvn -version).
  2. Git and Zulu JDK were already installed. Will Zulu 8 work for this?
  3. Install Eclipse IDE (Photon version) with just the OpenHAB Addons.
  4. Let the workbench run its startup tasks, followed by automated build (resulting in 2 errors in the bluetooth binding and 976 warnings).
  5. Disable ‘Build automatically’.
  6. Start OpenHAB runtime.launch; noticed various errors and warnings in the console window, but it started the OH environment since http://localhost:8080 was accessible, including Paper UI.
  7. Run the create_openhab_binding_skeleton command (is that still the valid approach?).
  8. Tried to follow the instructions for moving the empty addon to the /bundle directory here, but I am missing some details.
  9. “Move your addon to /bundles/. Adapt the addons/pom.xml and /bundles/pom.xml”
    –> Not sure what to ‘adapt’ here…
  10. “Copy over .project, .settings and .classpath from an already migrated bundle. Adapt the name in .project.”
    –> Done.
  11. “Edit the pom.xml: Adapt the name, artifactId and <parent>.”
    –> Done.
  12. “Add maven dependencies to the pom.xml file…”
    –> Not needed at this stage (starting to create first lines of code).
  13. “Remove META-INF and OSGI-INF and”
    –> Done.
  14. “Move ESH-INF to src/main/resources/ESH-INF”
    –> Done.
  15. “Move unit tests from a potential separate .test project into src/test.”
    –> Not yet at this stage (need some code first).
  16. “Move integration tests into a new bundle, see the itests/ directory for examples.”
    –> Not yet at this stage (need some code first).
  17. “Change CODEOWNERS (this notifies maintainers when a pull request happens on their binding)”
    –> Where?
  18. “Adapt features/karaf/openhab-addons/src/main/feature/feature.xml”
    –> Done (added entry for my binding).
  19. “Adapt bom/openhab-addons/pom.xml”
    –> Done (added dependency entry for my binding).

Is this approach (starting with create skeleton) still the right one? What (and how) to handle steps 9 and 17?
And once that is solved, should I run a mvn build in the bundle directory?

I have just created a PR for the official documentation that DEPRECATED the binding development paragraph and explained the situation. It is indeed a bad timing :smiley:

That was the first mistake actually. The scripts behind that are setting up eclipse for using the old buildsystem which is totally incompatible to the new one.

Follow the steps of the openhab2-addons repository readme file instead.
The caveat: You can start openHAB, but PaperUI and the REST interface are not loaded. The demo repository still needs some tweaks for that.

Nope. The skeletons are broken. You want rather copy an existing binding from “bundles/” (pick a small one) and edit “.project” and “pom.xml” to your needs. From there on you can import that copied directory with the “Import -> Import existing maven project” menu.


Thanks! That should get me started.

Some tips I wish I knew when I started.

Maven is only when you want to create your jar file. You can compile and run to debug in eclipse and this is where you see the warnings and errors in your code, that is inside eclipse.

When you want to create the standalone jar you then run mvn clean install inside your binding folder and it only looks at your binding. Up a folder and that command runs on all bindings and takes ages. Only needed if you are about to do a PR to add the binding to the openhab github.

First up in eclipse make sure you close all projects that are not yours, they have errors and warnings that get listed, closing them cleans it up so you only see the errors for your binding. Select bindings and right hand click and select close project.

Also if your binding does not show up when you run openhab inside eclipse you need to tick your binding to be started with openhab by going to the runtime configuration I think it is called.

The other thing was how to deal with external jar dependancies, too complex when I don’t have the ide in front of me.

1 Like

Thanks for all the support and patience so far. Bear with me a little longer, please… :grin:

To test my understanding of the build process, I simply started with an existing binding (Air Quality) to see if I can go through the process of building and running it (without making code changes at all). I got stuck at step 8 where I should add the binding to the Run Requirements in bndrun.

I imported the Air Quality binding as existing Maven project and added the Air Quality binding to /pom.xml in But if I drag the binding to the Run Requirements, Eclipse comes with an error popup: “Error adding one or more requirements. Unable to derive identity from an object of type JavaProject”.

Looks like I need more guidance here (being totally new to Eclipse IDE).
BTW, if I drag&drop a binding from the Repositories list within the app.bdnrun window, it succeeds.

Have you edited the pom.xml file of the demo app and included the airquality as dependency?
If auto-build is disabled (it is for me, because it ends up in an endless rebuild loop), you also need to right click the demo app, look for “Maven->Update project”.

Unfortunately we need to wait for Markus to come back from his holiday to edit his demo app and add a proper readme file. I also started with guessing and testing out.

Thanks David for your continued support!

Yes, I did add the binding in the pom.xml, and already had auto-build disabled (I had an endless loop as well).
Will run Maven->Update project and see what happens.

Meanwhile I will dive into the structure, classes, etc. for creating a binding.

UPDATE: I ran Maven->Update project and added the binding ‘manually’ to app.bndrun (edit text file instead of via the plugin) because I had the same error. Did a mvn clean install in the binding directory and successfully generated the .jar file. So far, so good.
Next step is to figure out how to test, run and debug a binding… :sunglasses:

There is an OSGi run and OSGi debug button in that bnd UI. But apparently paper UI and the dashboard bundle are not part of this demo app.

@noppes123 could You help me?
I’m trying to set a development environment but without luck.
I’ve installed eclipse for Java Developers.
I’ve imported demo-app folder using Import->General->Projects from Folder or Archive
Unfortunately, I get this error:

Do You know what might be the cause of this?

You need Eclipse installer, see video and also the documentation.

Sorry but that is absolute outdated information in that video.
We have changed the buildsystem and if you use the “openhab2-addons” section in the installer,
you will get the old buildsystem setup, which will utterly break anything for the new system.


Where did you find that video? It should be removed.

I’ve installed eclipse for Java Developers.
I’ve imported demo-app folder using Import->General->Projects from Folder or Archive

Have you followed the openhab2-addons readme file steps? You need the bnd-something plugin to be installed and you cannot simply click the bndrun->Run file without the build succeeding (which it clearly did not if I look at your errors list).

You need a very recent checkout of the demo. Click on “Project->Build all” to rebuild. It is also known that the allplay binding at the moment is causing problems for the build for some not yet discovered reason.

Hi @Misiu, did you install the latest (201903) version of Eclipse IDE? And also, without any of the repositories during install? Only import as existing Maven project afterwards?

As David said, the README in the Addons Github repository should get you going, at least to come to a setup without those compile/build errors.

Yes I’ve installed the latest version.
After launch I’ve created a new workspace then in Package Explorer I right click and choose Import.
I’ve picked up Maven->Existing Maven Projects and selected folder where I git openhab-demo.
After that I got this errors:

Then I’ve added org.openhab.binding.airquality binding (using the same steps as above).

I’ve added all the missing binding’s but I still have 3 errors:

Missing artifact org.openhab.bundles:org.openhab.binding.synopanalyzer:jar:2.5.0-SNAPSHOT

The container ‘Maven Dependencies’ references non existing library ‘C:\Users\Tomek.m2\repository\org\openhab\bundles\org.openhab.binding.synopanalyzer\2.5.0-SNAPSHOT\org.openhab.binding.synopanalyzer-2.5.0-SNAPSHOT.jar’

The project cannot be built until build path errors are resolved

I found that I miss one library:

but I don’t know how to fix that.

Video is on (I guess )official Youtube channel -

I know it might not be best timing for this but you can do your binding alone without pulling in entire openhab. You need to pull in all necessary dependencies. Until addons are bnd-nized you can rely on simplistic maven approach. Take a look on below project - it has literally ONE line which set ups OSGi bundle activator.

If you want to have a proper binding create ESH-INF in your resources directory. OSGI-INF contents are generated by maven-bundle-plugin thus you just need to re-use existing annotations.

Most importantly - it works out of the box (with IntelliJ) and it should also work for other part of universe (Eclipse). Main drawback is - you need to install and update binding manually inside running openHAB instance via install file:/foo/bar/binding.jar and update <binding-id> or watch commands (you can find reference in Karaf manual).

Above way is less convenient than IDE driven development, but works quite reliability for most of people.


1 Like

Binding (MCP23017) that I want to base my new binding on is already building on BND, so I’ll try with eclipse.
I’ll check Your suggestions tommorow, maybe it will be easier for me to get started.
The whole process of setting up everything is complicated. In Visual Studio it is simple - You click on csproj file and Your ready to go. This should be as easy with openhab :slight_smile:

P. S.
I’m running openHAB 2.4, will I be ae to add binding based on BND to it?

Yes, it’s gonna work. BND changes way how build is organized but does not change runtime. As long as output of compilation contains all necessary metadata it will pass.
If yo uused Visual Studio before then its worth to try IntelliJ anyway, sometimes its less verbose and seems to be easier for new comers. It is able to import most of maven projects. I’m not sure if it properly supports BND workspaces, but that’s something which is not required to work inside IDE to write your Java code.

I’m not so sure. I think @J-N-K has found out that a version restriction is currently compiled in (minimum OH 2.5-snapshot), but maybe he can elaborate more on this topic.

Ok, I have a clean PC.
Here are the steps I made:

  1. Install Eclipse for Java Developers
  2. Clone demo repo using git clone --depth=1
  3. Import that project into Eclipse:
  4. Then the project start building
  5. And I got this:

What should I do next? Should I remove those missing dependencies? If yes, then how should I do that?

@David_Graeff, as You mentioned on GitHub a sample binding project that could be opened in VS Code, would be awesome!

I think the version was an earlier problem but that has been removed. I at least had no problem using newer versions on a 2.4

However, if the binding now gets the jar from maven dependencies, were it before had that jar in the lib directory. I think these need to be installed manually because that information is in the feature file.