diff --git a/.vuepress/docs-sidebar.js b/.vuepress/docs-sidebar.js index 56c779876..87c52d678 100644 --- a/.vuepress/docs-sidebar.js +++ b/.vuepress/docs-sidebar.js @@ -146,6 +146,7 @@ module.exports = [ children: [ ['developer/', 'Overview & Introduction'], 'developer/guidelines', + 'developer/addons/', 'developer/bindings/', 'developer/module-types/', 'developer/transformations/', diff --git a/.vuepress/process_main_docs.rb b/.vuepress/process_main_docs.rb index 138f031fc..4f7205b0e 100644 --- a/.vuepress/process_main_docs.rb +++ b/.vuepress/process_main_docs.rb @@ -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}" diff --git a/developers/addons/addon.md b/developers/addons/addon.md new file mode 100644 index 000000000..74f63d3d5 --- /dev/null +++ b/developers/addons/addon.md @@ -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 + + + + String + String + String + + String + + + ... + + OR + + + +``` + +| 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 + + + + binding + hue Binding + The hue Binding integrates the Philips hue system. It allows to control hue bulbs. + + local + + +``` diff --git a/developers/bindings/config-xml.md b/developers/addons/config-xml.md similarity index 100% rename from developers/bindings/config-xml.md rename to developers/addons/config-xml.md diff --git a/developers/bindings/faq.md b/developers/addons/faq.md similarity index 100% rename from developers/bindings/faq.md rename to developers/addons/faq.md diff --git a/developers/addons/index.md b/developers/addons/index.md new file mode 100644 index 000000000..26bab2d50 --- /dev/null +++ b/developers/addons/index.md @@ -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. . +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. diff --git a/developers/bindings/binding-xml.md b/developers/bindings/binding-xml.md deleted file mode 100644 index d7746457f..000000000 --- a/developers/bindings/binding-xml.md +++ /dev/null @@ -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 - - - - String - String - - - ... - - OR - - - -``` - -| 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 - - - - hue Binding - The hue Binding integrates the Philips hue system. It allows to control hue bulbs. - - -``` diff --git a/developers/bindings/index.md b/developers/bindings/index.md index 74045c5d4..56d24396f 100644 --- a/developers/bindings/index.md +++ b/developers/bindings/index.md @@ -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. . -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.