OpenHAB
/
openhab-docs
mirror of https://github.com/openhab/openhab-docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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 2023-01-16 20:37:08 +01:00 committed by GitHub
parent 7a87fdc06b
commit 71adc538ad
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 165 additions and 137 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.vuepress/docs-sidebar.js
View File

@ -146,6 +146,7 @@ module.exports = [
children: [
['developer/', 'Overview & Introduction'],
'developer/guidelines',
'developer/addons/',
'developer/bindings/',
'developer/module-types/',
'developer/transformations/',

2
.vuepress/process_main_docs.rb
View File

@ -160,7 +160,7 @@ def process_main_docs(docs_source_dir)
puts " -> #{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|
file = File.basename(path)
puts " -> #{subsection}/#{file}"

86
developers/addons/addon.md Normal file
View 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.&lt;addonId&gt;".
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
developers/bindings/config-xml.md → developers/addons/config-xml.md
View File

0
developers/bindings/faq.md → developers/addons/faq.md
View File

77
developers/addons/index.md Normal file
View File

@ -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.

76
developers/bindings/binding-xml.md
View File

@ -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.&lt;binding.id&gt;".
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>
```

60
developers/bindings/index.md
View File

@ -17,11 +17,6 @@ During development you might come back with specific questions.
[[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
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
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.