Developing an Add-on

An add-on is an extension to openHAB that integrates external components like software services or hardware devices. Depending on their use-case they have different types:

• automation for add-ons that provide scripting languages or rule templates
• binding for controlling physical devices or software systems
• misc for other integrations like Apple's HomeKit or the openHAB cloud
• persistence for services that can be used to store and read historical data
• transform for add-on that provide a way to manipulate values
• ui for bundles that provide UIs or UI-additions (like widgets)
• voice for add-ons that provide voice services

Every add-on needs to define a addon.xml file. Find more information in the respective Add-on XML reference.

Include the Add-on in the Build

Once you are happy with your implementation, you need to integrate it in the Maven build and add it to the official distro.

• Add a new line in the bundle pom.xml (opens new window).
• Add a new line in the binding pom.xml (opens new window).
• If you have a dependency on a transport bundle (e.g. upnp, mdns or serial) or an external library, make sure to add a line for this dependency in the /src/main/feature/feature.xml file in your add-on folder. See the other add-ons as an example.
• Add your binding to the CODEOWNERS (opens new window) file so that you get notified by GitHUB when someone adds a pull request towards your add-on.

Please make sure you add the above entries at their alphabetically correct position!

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 (that step takes about 30 minutes).

The build includes Tooling for static code analysis (opens new window) that will validate your code against the openHAB Coding Guidelines and some additional best practices. 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). to

You can always run the above command from within your add-on's directory to speed the build up and fix and check reported errors. Formatting error can be fixed by

mvn spotless:apply

Re-run the build to confirm that the checks are passing. If it does, it is time to contribute your work!

Add your add-on's logo to the openHAB website

After your pull request has been merged and the next openHAB version is released, your add-on will be available in the addons search on the openHAB website with a default logo.

You can upload a logo to display it on the openhab.org (opens new window) start page, the addon search and in the readme.

These are the requirements for logos:

• PNG (transparency is preferred)
• 512x512 pixels or smaller in one dimension, if it's not a square logo
• Less than 30kB

File size is key as the website displays hundreds of small logos on the same page. To shrink the file size, save your logo with Palette-Based Colors (sometimes called "Indexed-RGBA"). Also, JPEG compression artifacts from prior conversions or halo around the logo increases file size dramatically. There are online converters to convert your True Color PNG logo to Palette-Based Colors. E.g. https://compresspng.com/ (opens new window). Or use zopflipng: zopflipng -m --filters=0me --lossy_8bit --lossy_transparent -y logo.png logo.png

After your binding's pull request has been merged, you can upload your logo by filing another pull request to the openhab-docs/images/addons/ (opens new window) repository. Your logo will be available after the next website build.

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