Adapt to core changes (addon.xml) (#1872)
* Adjust to addon.xml Signed-off-by: Jan N. Klug <github@klug.nrw>pull/1995/head
J-N-K
GitHub
parent
7a87fdc06b
commit
71adc538ad
|
|
@ -146,6 +146,7 @@ module.exports = [
|
||||||
children: [
|
children: [
|
||||||
['developer/', 'Overview & Introduction'],
|
['developer/', 'Overview & Introduction'],
|
||||||
'developer/guidelines',
|
'developer/guidelines',
|
||||||
|
'developer/addons/',
|
||||||
'developer/bindings/',
|
'developer/bindings/',
|
||||||
'developer/module-types/',
|
'developer/module-types/',
|
||||||
'developer/transformations/',
|
'developer/transformations/',
|
||||||
|
|
|
||||||
|
|
@ -160,7 +160,7 @@ def process_main_docs(docs_source_dir)
|
||||||
puts " -> #{file}"
|
puts " -> #{file}"
|
||||||
process_file("#{docs_source_dir}/developers", file, "docs/developer", "#{$docs_repo_root}/developer/#{file}")
|
process_file("#{docs_source_dir}/developers", file, "docs/developer", "#{$docs_repo_root}/developer/#{file}")
|
||||||
}
|
}
|
||||||
["audio", "bindings", "ioservices", "legacy", "module-types", "osgi", "persistence", "transformations", "utils", "ide"].each { |subsection|
|
["addons", "audio", "bindings", "ioservices", "legacy", "module-types", "osgi", "persistence", "transformations", "utils", "ide"].each { |subsection|
|
||||||
Dir.glob("#{docs_source_dir}/developers/#{subsection}/*.md") { |path|
|
Dir.glob("#{docs_source_dir}/developers/#{subsection}/*.md") { |path|
|
||||||
file = File.basename(path)
|
file = File.basename(path)
|
||||||
puts " -> #{subsection}/#{file}"
|
puts " -> #{subsection}/#{file}"
|
||||||
|
|
|
||||||
|
|
@ -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>
|
||||||
|
```
|
||||||
|
|
@ -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.
|
||||||
|
|
@ -1,76 +0,0 @@
|
||||||
---
|
|
||||||
layout: developersguide
|
|
||||||
title: Binding Descriptions
|
|
||||||
---
|
|
||||||
|
|
||||||
# Binding Definitions
|
|
||||||
|
|
||||||
Every binding has to provide meta information such as binding id or name.
|
|
||||||
|
|
||||||
Background information: The meta information of all bindings is accessible through the `org.openhab.core.binding.BindingInfoRegistry` service.
|
|
||||||
|
|
||||||
Although binding definitions are usually specified in a declarative way (as described in this section),
|
|
||||||
they can also be provided as `org.openhab.core.binding.BindingInfo`.
|
|
||||||
Any `BindingInfo` must be registered as service at the _OSGi_ service registry.
|
|
||||||
The full Java API for binding definitions can be found in the Java package `org.openhab.core.binding`.
|
|
||||||
|
|
||||||
For the declarative way, you add your binding information in form of a `binding.xml` file to the bundle's folder `/src/main/resources/OH-INF/binding/binding.xml`.
|
|
||||||
|
|
||||||
## XML Structure for Binding Definitions
|
|
||||||
|
|
||||||
```xml
|
|
||||||
<?xml version="1.0" encoding="UTF-8"?>
|
|
||||||
<binding:binding id="bindingID"
|
|
||||||
xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
|
|
||||||
xmlns:binding="https://openhab.org/schemas/binding/v1.0.0"
|
|
||||||
xsi:schemaLocation="https://openhab.org/schemas/binding/v1.0.0
|
|
||||||
https://openhab.org/schemas/binding-1.0.0.xsd">
|
|
||||||
|
|
||||||
<name>String</name>
|
|
||||||
<description>String</description>
|
|
||||||
|
|
||||||
<config-description>
|
|
||||||
...
|
|
||||||
</config-description>
|
|
||||||
OR
|
|
||||||
<config-description-ref uri="{binding|thing-type|channel-type|any_other}:bindingID:..." />
|
|
||||||
|
|
||||||
</binding:binding>
|
|
||||||
```
|
|
||||||
|
|
||||||
| Property | Description | |
|
|
||||||
|----------------------------|----------------------------------------------|-----|
|
|
||||||
| binding.id | An identifier for the binding | mandatory |
|
|
||||||
| name | A human-readable name for the binding | mandatory |
|
|
||||||
| description | A human-readable description for the binding | 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 | 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 binding definitions is specified in the [Binding XSD](https://openhab.org/schemas/binding-1.0.0.xsd) file.
|
|
||||||
|
|
||||||
**Hints:**
|
|
||||||
|
|
||||||
- The attribute `uri` in the section `config-description` is optional, it _should not_ be specified in binding definition files because it's an embedded configuration. If the `uri` is _not_ specified, the configuration description is registered as `binding:bindingID`, otherwise the given `uri` is used.
|
|
||||||
- If a configuration description is already specified somewhere else and the binding 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 "binding.<binding.id>".
|
|
||||||
A binding 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 a binding definition.
|
|
||||||
|
|
||||||
```xml
|
|
||||||
<?xml version="1.0" encoding="UTF-8"?>
|
|
||||||
<binding:binding id="bindingID"
|
|
||||||
xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
|
|
||||||
xmlns:binding="https://openhab.org/schemas/binding/v1.0.0"
|
|
||||||
xsi:schemaLocation="https://openhab.org/schemas/binding/v1.0.0
|
|
||||||
https://openhab.org/schemas/binding-1.0.0.xsd">
|
|
||||||
|
|
||||||
<name>hue Binding</name>
|
|
||||||
<description>The hue Binding integrates the Philips hue system. It allows to control hue bulbs.</description>
|
|
||||||
|
|
||||||
</binding:binding>
|
|
||||||
```
|
|
||||||
|
|
@ -17,11 +17,6 @@ During development you might come back with specific questions.
|
||||||
|
|
||||||
[[toc]]
|
[[toc]]
|
||||||
|
|
||||||
## Structure of a Binding
|
|
||||||
|
|
||||||
Every binding needs to define a `binding.xml` file.
|
|
||||||
Find more information in the respective [binding XML reference](binding-xml.html).
|
|
||||||
|
|
||||||
## Describing Things
|
## Describing Things
|
||||||
|
|
||||||
External systems are represented as _Things_ in openHAB.
|
External systems are represented as _Things_ in openHAB.
|
||||||
|
|
@ -1022,58 +1017,3 @@ This is done by implementing the `getServices` method in your bridge handler:
|
||||||
## Frequently asked questions / FAQ
|
## Frequently asked questions / FAQ
|
||||||
|
|
||||||
Various binding related questions are answered in our [Binding development FAQ](faq.html).
|
Various binding related questions are answered in our [Binding development FAQ](faq.html).
|
||||||
|
|
||||||
## Include the Binding 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 binding folder. See the other bindings 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 binding.
|
|
||||||
|
|
||||||
> 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 bindings 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 binding's logo to the openHAB website
|
|
||||||
|
|
||||||
After your pull request has been merged and the next openHAB version is released, your binding will be available in the add-ons 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.
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue