This page is part of archived documentation for openHAB 4.3. Go to the current stable version
# 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:
automationfor add-ons that provide scripting languages or rule templatesbindingfor controlling physical devices or software systemsmiscfor other integrations like Apple's HomeKit or the openHAB cloudpersistencefor services that can be used to store and read historical datatransformfor add-on that provide a way to manipulate valuesuifor bundles that provide UIs or UI-additions (like widgets)voicefor 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.xmlfile 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 and the UI
After your pull request has been merged and the next openHAB version is released, your add-on will be available on the openHAB website and in the UI's add-on store with a default logo.
You can upload a logo to display it on the openHAB website (start page, add-on search and readme) and the UI.
These are the requirements for logos:
- SVG
- Less than 10 kB
In case you don't have an SVG version of the logo, you can instead provide a PNG version, these are the requirements for PNG 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:
SVG logos should normally be less than 10 kB, in case they are not, you may be able to shrink the file size be importing the SVG logo into a vector graphics software, e.g. Affinity Designer, and export it with a preset for small size.
To shrink the file size of PNG logos, 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.
You may use 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.