Developing a Binding for openHAB

This page describes the necessary steps in order to implement a new binding for openHAB.

For information about code style and naming conventions, please see the coding guidelines.

Choose the option "openHAB 2 Add-ons" in your IDE setup, and create a skeleton for your binding. To do this, use a command line terminal and go to your Git repository folder under git/openhab2-addons/addons/binding and call the script create_openhab_binding_skeleton.sh with two arguments. It is important that your binding name is in camel case (e.g. 'ACMEProduct' or 'SomeSystem'). After the binding name, provide your name as the author (surrounded by quotes if you want to use whitespaces to separate your first and last name). Example: ~/git/openhab2-addons/addons/binding/create_openhab_binding_skeleton.sh BindingName "Firstname Lastname"

Now go back to the IDE and choose File->Import->General->Existing Projects into Workspace, enter the folder of the newly created skeleton as the root directory, and press "Finish".

Note: Here you can find a screencast of the binding skeleton creation.

Before You Start

If you plan to contribute your binding to openHAB through a PR, here is what we suggest to help keeping the potential effort for changes due to reviews low:

  • Before you start with the implementation, create an issue on GitHub and talk about your plan to come up with a PR. Maybe there are others that have privately a similar binding before and would be ready to contribute it. Also, it might help finding collaborators for the implementation.
  • It is a good idea to start with modelling the Things for your binding, i.e. what kind of Bridge-Types, Thing-Types and Channel-Types it should have. Also, you should create the classes for the handlers that you need as well as potential discovery services (but no need to implement any working code at that stage). With this in place, you are invited to already create a PR and mark it as [WIP] (for: work in progress) and ask for a first review. You might get valuable input from maintainers and other experts and you avoid having to refactor all details of an implementation.
  • Once the general architecture/modelling of your binding is approved, go for the implementation details and ask for a final review in the end.

Implement the Binding

The skeleton should give you an easy starting point for your developments. To learn about the internal structure and the concepts of a binding, please see the Eclipse tutorial on binding development.

Please especially note our coding guidelines, which must be respected for having pull requests approved. If you have any special dependencies in your code, please check the library recommendations at Eclipse SmartHome. This will ensure that everyone uses the same libraries for e.g. JSON and XML processing or for HTTP and websocket communication.

Setup and Run the Binding

To setup the binding you need to configure at least one Thing and link an Item to it. In your workspace in distro-resources/src/main/resources/things, you can define and configure Things in files with a *.things extension. The following file defines a thing for the Yahoo Weather binding:

yahooweather:weather:berlin     [ location="638242" ]

In this example a Thing of the ThingType yahooweather:weather is defined with a configuration for the location.

Next you need to create Items and link them to the Channel of your binding. Here is the example of the Yahoo Weather binding:

Number Berlin_Temperature       "Temperature in Berlin [%.1f °C]"   { channel="yahooweather:weather:berlin:temperature" }
Number Berlin_Humidity          "Humidity in Berlin [%d %%]"        { channel="yahooweather:weather:berlin:humidity" }

The syntax for a channel link is { channel = "<binding-id>:<thing-type-id>:<thing-id>:<channel-id>" }.

If you start the openHAB runtime including the binding now (make sure that your binding is checked in the launch configuration dialog!), the code inside your ThingHandler implementation is executed.

Include the Binding in the Build and the Distro

Once you are happy with your implementation, you need to integrate it in the Maven build and add it to the official distro. For the Maven build, please add a new line in the binding pom.xml at the alphabetically correct position. In order to have the binding being included by the distro, you furthermore need to add it to the feature.xml, again at the alphabetically correct position. If you have a dependency on a transport bundle (e.g. upnp, mdns or serial), make sure to add a line for this dependency as well (see the other bindings as an example).

Before you create a pull request on GitHub, you should now run

mvn clean install

from the repository root to ensure that the build works smoothly. If it does, it is time to contribute your work!

Static Code Analysis

The build includes Tooling for static code analysis that will validate your code against the openHAB Coding Guidelines and some additional best practices. Information about the checks can be found here.

The tool will generate an individual report for each binding, which you can find in .../your_binding_directory/target/code-analysis/report.html file and a report for the whole build that contains links to the individual reports in the ../openhab2-addons/target/summary_report.html. The tool categorizes the found issues by priority: 1(error), 2(warning) or 3(info). If any error is found within your code the Maven build will end with failure. You will receive detailed information (path to the file, line and message) listing all problems with priority 1 on the console:

...
[ERROR] Failed to execute goal org.openhab.tools:static-code-analysis:0.0.4:report (default) on project org.openhab.binding.example: Code Analysis Tool has found 1 error(s)!
[ERROR] Please fix the errors and rerun the build.
[ERROR] Errors list:
[ERROR] ERROR found by checkstyle: .binding.example.test/build.properties:0 Missing build.properties file.
[ERROR] Detailed report can be found at: file////path_to_openhab/openhab2-addons/addons/binding/org.openhab.binding.example/target/code-analysis/report.html
...

Please fix all the priority 1 issues and all issues with priority 2 and 3 that are relevant (if you have any doubt don't hesitate to ask). Re-run the build to confirm that the checks are passing.