78 lines
3.9 KiB
Markdown
78 lines
3.9 KiB
Markdown
---
|
|
layout: developersguide
|
|
title: Add-ons
|
|
---
|
|
|
|
# Developing an Add-on
|
|
|
|
{:.no_toc}
|
|
|
|
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](addon.html).
|
|
|
|
# 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](https://github.com/openhab/openhab-addons/blob/main/bundles/pom.xml).
|
|
- Add a new line in the [binding pom.xml](https://github.com/openhab/openhab-addons/blob/main/bom/openhab-addons/pom.xml).
|
|
- 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](https://github.com/openhab/openhab-addons/blob/main/CODEOWNERS) 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
|
|
|
|
```bash
|
|
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](https://github.com/openhab/static-code-analysis) 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
|
|
|
|
```bash
|
|
mvn spotless:apply
|
|
```
|
|
|
|
Re-run the build to confirm that the checks are passing.
|
|
If it does, it is time to [contribute your work](../contributing.html)!
|
|
|
|
# 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 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/>.
|
|
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/](https://github.com/openhab/openhab-docs/tree/main/images/addons) repository.
|
|
Your logo will be available after the next website build.
|