# Overview

A variety of different parts of openHAB can be extended. We will cover the most important ones here.

openHAB uses git (opens new window) as its version control system and GitHub (opens new window) for hosting the different repositories and source code. You will come in contact with git in many places, and it makes sense to familiarize yourself with its basic commands and concepts. There are many places to learn about Git. Try git - the simple guide (opens new window) as a start.

Add-ons and the openHAB core itself are written in Java. Java is not hard to learn, but it helps if you have a general technical understanding of programming languages.

The different guides of this chapter assume that you are somewhat familiar with Java 17 and that you have a rough understanding of Git's workflow (e.g. "checkout", "branches", "push").

# Choose the Right Concept

openHAB allows you to build upon the following concepts:

Bindings: A binding connects to external services or devices.
Automation engine module: A trigger, condition, or action that can be used in automation rules (or scripts).
Transformation / Profiles: Can be used to transform a Thing Channel- value before it is assigned to an Item.
An IO service: Exposes openHAB internals via a defined interface (for example the REST interface, HomeKit or Hue Emulation Service).
A Persistence service: Persist item state updates and/or changes and allows them to be retrieved for specific points in time.
Natural language processing skill: Executes something depending on the understood Intents and returns something back to the user.
Audio sinks/sources: Control where audio can be played or implement audio sources.
and many more (not covered yet).

First think about what you want to achieve! Check our community forum (opens new window) and discuss your concept. Sometimes it may not even be worth writing a binding or other addon if you can achieve your goal in an easier way. For example, you may be better off using an http action in a rule or script to retrieve some values.

Find the right abstraction and the corresponding link on the left navigation panel. General coding guidelines apply to all types of addon development.

# Setup the Development Environment

Development can happen on any of the supported operating systems (Windows, macOS, Linux).

Please ensure that you have the following prerequisites installed as well:

Git (opens new window) For retrieving our source code and push changes back. On Windows: Must be available in %PATH%
Maven 3.x (opens new window) Our build system tool. On Windows: Must be available in %PATH%
Java JDK 17 or JDK 21, for example from Oracle Oracle JDK 17 (opens new window) or Oracle JDK 21 (opens new window). On Windows: %JAVA% must be set.

Note

Whereas we recommend Java 17 for running openHAB, development can be safely done on Java 21. With default settings, the Java 21 compiler will generate Java objects compatible with JRE 17. If you run your openHAB server on Java 21, you can enable native Java 21 objects by adding -Pj21 to the Maven command line. Note that our CI checks Java 17 and Java 21 compatibility, and we only use language features available in Java 17.

You can use any IDE that is suitable for OSGi/Java development. We have prepared some step-by-step guides for the following IDEs:

Not sure what to choose?: openHAB maintainers use Eclipse IDE (opens new window).

# Make your own copy of the code base

openHAB has several repositories (opens new window) on GitHub. The most important ones are listed in the Contribution section of the Developer Appendix.

For developing a new binding, you'll need to fork the openhab-addons (opens new window) repository (see GitHub Docs: Fork a repository (opens new window)) and then clone your fork to your development machine. Next, create a new branch for your work on the new binding.

# Read the guidelines

Before starting your work, please have a look at the Coding Guidelines and the overall Contribution docs. It is always better to know the guidelines before starting coding than having to change your code afterwards.

# Develop a NEW binding

To help start developing a new binding, a script is available to generate the basic skeleton for you. This script is specific for binding add-ons. Follow these steps to generate your binding:

From the command line in openhab-addons/bundles directory to create a skeleton of a new binding mynewbinding run:

On Linux:
```
./create_openhab_binding_skeleton.sh  MyNewBinding "<Author>" <GitHubUsername>
```
On Windows:
```
create_openhab_binding_skeleton.cmd MyNewBinding "<Author>" <GitHubUsername>
```
Add your binding to the bundles/pom.xml file

Use your full name for <Author>.
Accept with Y when the skeleton configuration asks for it.
From openhab-addons root you can build only your binding with Maven using the -pl option:
```
mvn clean install -pl :org.openhab.binding.mynewbinding
```
Where mynewbinding is the name of your new binding. Some additional Maven options that may help:
- -U: Forces all dependencies to be downloaded again.
- -am: Builds all projects in openhab-addons your project dependends on.
- -o: Won't update any dependencies.
- -DskipChecks: Skips the static analysis checks
- -DskipTests: Skips the unit tests
- -Dspotless.check.skip=true : Skips the spotless file formatting checks
- -Dohc.version=3.0.2 : The version of openhab you are building for
To start your new binding it's a good practice to commit your code on a new git branch:
```
git checkout -b <mynewbranch>
```
Open Eclipse or your favorite editor and import your new binding project

Now you can start developing your NEW binding. We're looking forward to your pull request!

In case the new binding has dependencies to other bundles/libraries see Adding Dependencies for more information.

If developing on Windows, git will convert line endings from LF to CRLF automatically. The repo uses LF, and spotless will object, and throw errors. If you use mvn spotless:apply to fix formatting, it will add CRLF to all files dirtying the entire branch. Adding a .gitattributes file to the openhab-addons folder with the following will tell git and spotless to use LF endings:

* text eol=lf

Further documentation about binding development can be found in the Bindings Developer Guide.

# Contribute your changes back to openHAB

When you are finished with your new binding (or in the process of development and need help), you need to create a pull request (PR) to the so-called upstream repository, in this case openhab-addons. Have a look at GitHub Docs: Creating a pull request (opens new window) if you need help.

Once you have created your PR, the maintainers will review your code and provide feedback. Please be patient and be prepared to make changes to your code based on the feedback you receive.

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)

← Serial Port Configuration Eclipse IDE →