-
-
Notifications
You must be signed in to change notification settings - Fork 708
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Adapt to core changes (addon.xml) #1872
Merged
Merged
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,86 @@ | ||
| --- | ||
| layout: developersguide | ||
| title: Add-on Descriptions | ||
| --- | ||
|
|
||
| # Add-on Definitions | ||
|
|
||
| Every add-on has to provide meta information such as add-on type, id or name. | ||
|
|
||
| Background information: The meta information of all add-ons is accessible through the `org.openhab.core.addon.AddonInfoRegistry` service. | ||
|
|
||
| Although add-on definitions are usually specified in a declarative way (as described in this section), they can also be provided as `org.openhab.core.addon.AddonInfo`. | ||
| Any `AddonInfo` must be registered as service at the *OSGi* service registry. | ||
| The full Java API for addon definitions can be found in the Java package `org.openhab.core.addon`. | ||
|
|
||
| For the declarative way, you add your add-on information in form of an `addon.xml` file to the bundle's folder `/src/main/resources/OH-INF/addon/`. | ||
| If the add-on consists of more than one bundle, only one `addon.xml` is allowed (in the main-bundle). | ||
|
|
||
| ## XML Structure for Add-on Definitions | ||
|
|
||
| ```xml | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <addon:addon id="addonID" | ||
| xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" | ||
| xmlns:addon="https://openhab.org/schemas/addon/v1.0.0" | ||
| xsi:schemaLocation="https://openhab.org/schemas/addon/v1.0.0 | ||
| https://openhab.org/schemas/addon-1.0.0.xsd"> | ||
|
|
||
| <type>String</type> | ||
| <name>String</name> | ||
| <description>String</description> | ||
|
|
||
| <service-id>String</service-id> | ||
|
|
||
| <config-description> | ||
| ... | ||
| </config-description> | ||
| OR | ||
| <config-description-ref uri="{addon|thing-type|channel-type|any_other}:addonID:..." /> | ||
|
|
||
| </addon:addon> | ||
| ``` | ||
|
|
||
| | Property | Description | | | ||
| |----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------| | ||
| | addon.id | An identifier for the add-on | mandatory | | ||
| | type | Either `automation`, `binding`, `misc`, `persistence`, `transform`, `ui` or `voice` | mandatory | | ||
| | name | A human-readable name for the add-on | mandatory | | ||
| | description | A human-readable description for the add-on | optional | | ||
| | author | In general be the organisation maintaining this add-on (e.g. openHAB), not an individual's name | optional | | ||
| | connection | `local` for add-ons that only interact locally, `cloud` for add-ons that require a cloud connection, `cloudDiscovery` for add-ons that require a cloud connection for set-up | optional | | ||
| | countries | List of two-letter ISO country codes that are supported (all countries if empty) | optional | | ||
| | service-id | The ID (service.pid or component.name) of the main binding service, which can be configured through OSGi configuration admin service. Should only be used in combination with a config description definition | optional | | ||
| | config-description | The configuration description for the binding within the ConfigDescriptionRegistry (cf. [Configuration Description](config-xml.html)) | optional | | ||
| | config-description-ref | The reference to a configuration description for the binding within the ConfigDescriptionRegistry | optional | | ||
| | config-description-ref.uri | The URI of the configuration description for the binding within the ConfigDescriptionRegistry | mandatory | | ||
|
|
||
| The full XML schema for add-on definitions is specified in the [Add-on XSD](https://openhab.org/schemas/addon-1.0.0.xsd) file. | ||
|
|
||
| **Hints:** | ||
|
|
||
| - The attribute `uri` in the section `config-description` is optional, it *should not* be specified in add-on definition files because it's an embedded configuration. If the `uri` is *not* specified, the configuration description is registered as `type:addonID`, otherwise the given `uri` is used. | ||
| - If a configuration description is already specified somewhere else and the add-on wants to (re-)use it, a `config-description-ref` should be used instead. | ||
| - Normally the service id must not be defined, because it is implicitly set to "type.<addonId>". | ||
| An add-on can register an OSGi service which implements the ManagedService interface and define the service.pid as e.g."binding.hue" to receive the configuration. | ||
|
|
||
| ## Example | ||
|
|
||
| The following code gives an example for an add-on definition used in bindings. | ||
|
|
||
| ```xml | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <addon:addon id="bindingID" | ||
| xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" | ||
| xmlns:addon="https://openhab.org/schemas/addon/v1.0.0" | ||
| xsi:schemaLocation="https://openhab.org/schemas/addon/v1.0.0 | ||
| https://openhab.org/schemas/addon-1.0.0.xsd"> | ||
|
|
||
| <type>binding</type> | ||
| <name>hue Binding</name> | ||
| <description>The hue Binding integrates the Philips hue system. It allows to control hue bulbs.</description> | ||
|
|
||
| <connection>local</connection> | ||
|
|
||
| </addon:addon> | ||
| ``` |
File renamed without changes.
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,77 @@ | ||
| --- | ||
| 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 (transparancy 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. |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would definitely suggest to keep the "bindings" menu in place, just as we have dedicated entries for other add-on types like automation addons, transformation services, voice add-ons etc.
What would imho make sense here is to add a new menu entry for everything that generally applies to all add-ons and this new page could then link to the different specific add-on pages as well.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The problem is that we don't have content for that page. Duplicating what is written on the general page makes no sense.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Well, a few parts could be moved from the binding page to the add-on page, like the description about the addon.xml, the info on how to add a logo for the add-on and similar.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
After I did that, there was no content left :-)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hm, I see your point, but I am a bit puzzled, because on https://www.openhab.org/docs/developer/bindings/ I see a lot more content about how to develop a binding. You seem to have moved all the files that contribute to this page to
/developer/addon.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sometimes I'm a bit slow... Is this version better?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, thanks - that look better!