HowTo: Setup IntelliJ for binding development

Update: an updated and striped-down version of this tutorial is in the official docs:

Since I was not able to find a working HowTo to start developing (and most importantly debug) a binding in IntelliJ I thought I’d share my setup after finally get it working.


  • git is installed
  • Maven is installed
  • IntelliJ is installed (community edition should suffice, I recommend to use the Toolbox for installation for easier updates)
  • Java 8 is installed

What is the goal?

To develop a (existing) binding in IntelliJ and debug it using IntelliJ.

How is that achieved?

By cloning a fork of the openhab addons repository and building it using IntelliJ/Maven. Then a clone of the official openhab distribution project is built.
Finally, the distribution is started up in debug mode, the freshly built addon is copied into its addon directory and this running openhab instance is remote debugged with IntelliJ.


  1. clone & build the official openhab distro project into a new directory
    git clone
    cd openhab-distro
    mvn clean install
    … should result in:
    [INFO] ------------------------------------------------------------------------
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time:  07:23 min
    [INFO] Finished at: 2019-12-07T17:58:57+01:00
    [INFO] ------------------------------------------------------------------------
    • the target folder should contain the built distribution zip file
  2. extract the distribution zip file to directory of choice (hitherto <DISTRO_DIR>), e. g.
    • unzip distributions/openhab/target/ -d ~/openhab-test-distro
  3. change into <DISTRO_DIR> and start the distrobution in debug mode, e. g.:
    • cd ~/openhab-test-distro
    • be sure to run a Java 8 (you can check with java -version)
    • ./
    • the distribution will start up (OpenHAB console):
    Listening for transport dt_socket at address: 5005`
    Hit '<tab>' for a list of available commands
    and '[cmd] --help' for help on a specific command.
    Hit '<ctrl-d>' or type 'system:shutdown' or 'logout' to shutdown openHAB.
    • you can use “log:tail” on the openhab console to stream the openhab logs
    • open a webbrowser and locate to http://localhost:8080/ to configure the webinterfaces for the openhab instance
  4. clone your own fork of the openhab addons repository in a new directory (hitherto <ADDON_DIR>) (replace git user name accordingly)
    • git clone
  5. open IntelliJ and create a new Project from existing sources (File | New | Project from existing sources) and pick <ADDON_DIR>/pom.xml
    • IntelliJ will start importing, indexing and building, it will take while, wait until finished (see status bar)
  6. Use Maven to clean & install the addons project - there are several ways to do so:
    • mvn clean install in the root of <ADDON_DIR> using commandline Maven
    • or IntelliJ Maven view
    • or IntelliJ Maven Helper plugin
    • you might want to skip tests for a quicker build
    • you might want to build only the single addon you are interested in (the whole addons directory build can take quite a while)
    • I ran into build errors with an older master version - so try with the current master and check if the official master build is green:
    • some of the addons might fail to build - if it’s not the one, you’re interested in that should not bother you
    • you might later want to update the private fork of the openhab2-addons repository from the official repository master branch
      • git remote add openhab
      • git merge openhab/master
    • when the Maven project finished, you should find the freshly built addon JAR in the target directory
  7. copy the addon JAR to Openhab distribution created before
    • cp target/<ADDON_NAME>.jar <DISTRO_DIR>/addons
  8. The running instance of the openhab distiribution should pick up your new addon & start it
    • you can type log:tail in the openhab console to stream the openhab logs
  9. create a Remote Debug runtime configuration in IntelliJ:
    • Open menu Run | Edit configurations
    • click the + sign to add a “Remote” configuration
    • adapt the module setting to the root (org.openhab.addons.reactor)
    • click OK
    • start the debug configuration
    • the IntelliJ console should log: Connected to the target VM, address: ‘localhost:5005’, transport: ‘socket’

      You can now add breakpoints to your project now and your test distro should stop there…

Nice! I’m not familiar with IntelliJ but if this is the way to go, would you be interested to write this into the official docs?

1 Like

I’d like to get some feedback here first. I have no idea if this is the official way or maybe there are better methods, but this is the one I figured out working for me.
Please feel free to comment or to suggest improvements.

Here’s some propositions:

  • Simplify the steps by removing unnecessary side notes. For example installing java or verifying its version should be mentioned only in the beginning.
  • Provide an example binding and environment for the setup. E.g. Astro + Windows 10. As in vscode ide docs.

My guess is that there’s so few IntelliJ users who sees and comments this topic so you won’t get much feedback.

I am very thankful for this and will be testing it when I find the time.


even if it is a simple explanation, I do believe this has some place in the official docs.

Indeed, reducing the noise from your explanation. But I do believe that the actual steps are correct.



Hey, thank you for the guide. I get an error in step 6 that the package org.eclipse.smarthome cannot be found. Do you have any hint, how to solve this?

‘The import org.eclipse.smarthome cannot be resolved’

Make sure you checkout 2.5.x branch. Master is now repackaged to org.openhab package root. The org.eclipse.smarthome is gone.

Hey splatch,

do you mean the 2.5.x branch of the openhab-distro? I just did that, but i still get the same error if i run mvn clean install in the addon-dir

EDIT: Another weird thing is that the openhab-disto/distributions/openhab/target folder do not exist after a ‘mvn clean install’ in the distro folder :frowning:

Another EDIT: i executed ‘mvn clean install’ in the /distributions/openhab folder and now i got my jar file for openhab. But still the same at ‘mvn clean install’ at the bundles.

Note that these are 2 separate git projects (thus having each it’s own branch respectively):

  • steps 1 - 3 describe building of the distribution project, wich will be used to run the actual addon
  • steps 4 - 6 describe building of the addon(s) project
  • the remaining steps describe how to debug the addon using the distro

You’ll see the corresponding git branch in IntelliJ when you have a file of the project open in the editor (lower right, status bar).

From my understanding you have trouble building the addons (step 6).

  • make sure your addons project is up to date with the official openhab addons master branch (if you forked the repo with github, you need to merge the openhab addons master into your fork).
  • mvn clean will delete the target directory, mvn install will build the project. If the build fails due to some error, not everything (or nothing at all) will be built to the target directory

Hey, thanks for the hint. I forked the wrong branch of the addons. I think it is working now. Thank you!

I incoporated your comments, stripped down the tutorial and created a PR, which got accepted.
The result is now online:


Java version:1.8.0_221
Maven version: Apache Maven 3.6.3
Repository cloning from: (O.H distro).
Then I performed:

mvn clean install

Then I got this from Maven:

[ERROR] Failed to execute goal org.apache.karaf.tooling:karaf-maven-plugin:4.2.7:kar (default-kar) on project distro-kar: Failed to create archive: Failure to find org.openhab.ui.bundles:org.openhab.ui.dashboard:jar:2.5.5-SNAPSHOT in was cached in the local repository, resolution will not be reattempted until the update interval of carlspring has elapsed or updates are forced

Crearly Maven do not fin .dashboard:jar:2.5.5-SNAPSHOT. how can I fix that? Thanks

Hey there… If you don’t want to make changes to the distribution itself, you don’t need to build it. Just use the official distribution as described here:

I am interested in developping the core platform or, eventually the bindings, on intellij

I just checked out the repo (openhab-distro) into a fresh directory and was able to build it with mvn clean install.
Try the usual stuff (pull the latest version, you also might want to use mavens -U option), but actually I don’t know the distribution project - if you want to make changes there then start getting to know it by finding out the reason for the error :stuck_out_tongue:
Maybe you want to raise an issue on Github or contact one of the devs, but since it builds fine for me its probably not a (general) bug.

Thanks for your explanation but how to mvn clean install for only one addon?

Can you give me the argument that I have to write in the command?

Just cd into the addon directory and execute the command from there. Each addon has its own POM file. Note that you might have to build the whole project initially at least once.

1 Like

And how can I see that my jar addon is running in the openhab-distro?

here you can see my log:

Since your are already using the console you can list the bundles. Apart from that, use logging in your addon. Refer to the developer documentation to read up on that kind of stuff, e. g. Coding Guidelines | openHAB

1 Like