# 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 templates
bindingfor controlling physical devices or software systems
miscfor other integrations like Apple's HomeKit or the openHAB cloud
persistencefor services that can be used to store and read historical data
transformfor add-on that provide a way to manipulate values
uifor bundles that provide UIs or UI-additions (like widgets)
voicefor add-ons that provide voice services
Every add-on needs to define a
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
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.