From 228e74fa83af001980619ccd58e5851c53911b63 Mon Sep 17 00:00:00 2001 From: Thomas Dietrich Date: Fri, 5 Aug 2016 12:10:20 +0200 Subject: [PATCH] Add title to most pages, fixes (#60) minor spelling and format inconsistencies upper case headlines deletes spaces and lines at the end Signed-off-by: Thomas Dietrich --- administration/bundles.md | 1 + administration/console.md | 7 ++- administration/index.md | 24 +------ administration/logging.md | 1 + administration/runtime.md | 1 + community/contributing.md | 4 +- concepts/discovery.md | 35 ++++++----- concepts/event-type-definition.md | 27 ++++---- configuration/jetty.md | 66 +++++++++++--------- developers/contributing/contributing.md | 38 +++++------ developers/development/bindings.md | 7 ++- developers/development/compatibilitylayer.md | 19 +++--- developers/development/evolution.md | 5 +- developers/development/guidelines.md | 11 ++-- developers/development/ide.md | 5 +- developers/index.md | 3 +- developers/prerequisites/OSGi.md | 15 ++--- features/addons.md | 3 +- features/automation/ngrules.md | 1 + features/automation/ruledsl.md | 39 ++++++------ features/bindings.md | 5 +- features/compatibilitylayer.md | 25 +++++--- features/iconsets/classic/readme.md | 1 + features/index.md | 1 + features/io.md | 3 +- features/io/homekit/readme.md | 1 + features/io/hueemulation/readme.md | 3 +- features/paperui.md | 7 +++ features/persistence.md | 3 +- features/uis.md | 1 + features/uis/basic/readme.md | 2 +- 31 files changed, 191 insertions(+), 173 deletions(-) diff --git a/administration/bundles.md b/administration/bundles.md index 90b909d35..d52405b03 100644 --- a/administration/bundles.md +++ b/administration/bundles.md @@ -1,5 +1,6 @@ --- layout: documentation +title: Bundle Management --- {% include base.html %} diff --git a/administration/console.md b/administration/console.md index f2ff66975..656880c79 100644 --- a/administration/console.md +++ b/administration/console.md @@ -1,10 +1,11 @@ --- layout: documentation +title: Karaf Console --- {% include base.html %} -# Karaf console +# Karaf Console The Karaf console offers the option to: @@ -12,7 +13,7 @@ The Karaf console offers the option to: * manage [bundles](bundles.html) * [runtime commands](runtime.html) -# Accessing the console +# Accessing the Console Accessing the Karaf console depends on the start mode of openHAB. The manually start using shell/batch script ends directly in the Karaf console. @@ -82,7 +83,7 @@ The Karaf session is ended by using the logout command: openhab> logout ``` -# Configuring the console +# Configuring the Console By default due to security reasons openhab binds it's shell to localhost. If you are using local network or you are fully aware of all risks of exposing your system to public network you can change bind address in **org.apache.karaf.shell.cfg** config file. It can be found in the **runtime/karaf/etc/** folder (in case openHAB was installed via apt, the full path is: /usr/share/openhab2/runtime/karaf/etc/), replace line: diff --git a/administration/index.md b/administration/index.md index 244cfc03c..b30c10fe2 100644 --- a/administration/index.md +++ b/administration/index.md @@ -1,5 +1,6 @@ --- layout: documentation +title: Administration --- {% include base.html %} @@ -13,26 +14,3 @@ Therefore some of the administration tasks are performed in the [Karaf console]( - [Logging](logging.html) - [Bundle Management](bundles.html) - [Runtime Commands](runtime.html) - -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- diff --git a/administration/logging.md b/administration/logging.md index d18f5ed3d..72aab91fa 100644 --- a/administration/logging.md +++ b/administration/logging.md @@ -1,5 +1,6 @@ --- layout: documentation +title: Logging --- {% include base.html %} diff --git a/administration/runtime.md b/administration/runtime.md index 096af9116..b756c3846 100644 --- a/administration/runtime.md +++ b/administration/runtime.md @@ -1,5 +1,6 @@ --- layout: documentation +title: Runtime Commands --- {% include base.html %} diff --git a/community/contributing.md b/community/contributing.md index 5d124c395..aa4bbc14e 100644 --- a/community/contributing.md +++ b/community/contributing.md @@ -1,5 +1,6 @@ --- layout: documentation +title: Contribution --- # Contributing to openHAB @@ -74,7 +75,7 @@ your documentation changes for clarity, concision, and correctness, as well as a clean documentation build. Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. +and maintenance. Pull requests descriptions should be as clear as possible and include a reference to all the issues that they address. @@ -209,4 +210,3 @@ general guidelines for the community as a whole: respond to an email you are potentially sending to a large number of people. Please consider this before you update. Also remember that nobody likes spam. - diff --git a/concepts/discovery.md b/concepts/discovery.md index bc3228625..7be28dd97 100644 --- a/concepts/discovery.md +++ b/concepts/discovery.md @@ -1,5 +1,6 @@ --- layout: documentation +title: Thing Discovery --- {% include base.html %} @@ -12,29 +13,29 @@ In Eclipse SmartHome bindings can therefore implement _Discovery Services_ for t ## Glossary -- _Discovery_: Search for available things in the smart home environment. -- _Discovery Result_: Result of a _Discovery_ stored in the _Inbox_. -- _Discovery Service_: Implements a service to discover things, typically based on a specialized protocol (e.g. UPnP). -- _Inbox_: List of all discovered things, constantly updated by all running discoveries. +- _Discovery_: Search for available things in the smart home environment. +- _Discovery Result_: Result of a _Discovery_ stored in the _Inbox_. +- _Discovery Service_: Implements a service to discover things, typically based on a specialized protocol (e.g. UPnP). +- _Inbox_: List of all discovered things, constantly updated by all running discoveries. ## Inbox -The inbox represents a list of all discovered things (`DiscoveryResult`) from all known discovery services. Bindings can register new discovery services to discover new thing types (e.g. the Hue binding registers a new discovery service to search for Hue lights). Technically the inbox is an OSGi service which manages the discovery results. Notification about new things added to or things removed from the inbox will be sent as events. +The inbox represents a list of all discovered things (`DiscoveryResult`) from all known discovery services. Bindings can register new discovery services to discover new thing types (e.g. the Hue binding registers a new discovery service to search for Hue lights). Technically the inbox is an OSGi service which manages the discovery results. Notification about new things added to or things removed from the inbox will be sent as events. -### Discovery Result +### Discovery Result -A discovery result represents a discovered thing of a specific thing type, that could be instantiated as things in Eclipse SmartHome. The result usually contains properties that identify the discovered things further like IP address or a serial number. Each discovery result also has a timestamp when it was added to or updated in the inbox and it may also contain a time to live, indicating the time after which it will be automatically removed from the inbox. +A discovery result represents a discovered thing of a specific thing type, that could be instantiated as things in Eclipse SmartHome. The result usually contains properties that identify the discovered things further like IP address or a serial number. Each discovery result also has a timestamp when it was added to or updated in the inbox and it may also contain a time to live, indicating the time after which it will be automatically removed from the inbox. -The following table gives an overview about the main parts of a `DiscoveryResult`: +The following table gives an overview about the main parts of a `DiscoveryResult`: | Field | Description | |-------|-------------| -| `thingUID` | The `thingUID` is the unique identifier of the specific discovered thing (e.g. a device's serial number). It *must not* be constructed out of properties, that can change (e.g. IP addresses). A typical `thingUID` could look like this: `hue:bridge:001788141f1a` -| `thingTypeUID` | Contrary to the `thingUID` is the `thingTypeUID` that specifies the type the discovered thing belongs to. It could be constructed from e.g. a product number. A typical `thingTypeUID` could be the following: `hue:bridge`. -| `bridgeUID` | If the discovered thing belongs to a bridge, the `bridgeUID` contains the UID of that bridge. -| `properties` | The `properties` of a `DiscoveryResult` contain the configuration for the newly created thing. +| `thingUID` | The `thingUID` is the unique identifier of the specific discovered thing (e.g. a device's serial number). It *must not* be constructed out of properties, that can change (e.g. IP addresses). A typical `thingUID` could look like this: `hue:bridge:001788141f1a` +| `thingTypeUID` | Contrary to the `thingUID` is the `thingTypeUID` that specifies the type the discovered thing belongs to. It could be constructed from e.g. a product number. A typical `thingTypeUID` could be the following: `hue:bridge`. +| `bridgeUID` | If the discovered thing belongs to a bridge, the `bridgeUID` contains the UID of that bridge. +| `properties` | The `properties` of a `DiscoveryResult` contain the configuration for the newly created thing. -Discovery results can either be ignored or approved, where in the latter case a thing is created for them and they become available in the application. The configuration of that created thing contains the values from the `properties`of the approved `DiscoveryResult`. If an entry is ignored, it will be hidden in the inbox without creating a thing for it. +Discovery results can either be ignored or approved, where in the latter case a thing is created for them and they become available in the application. The configuration of that created thing contains the values from the `properties`of the approved `DiscoveryResult`. If an entry is ignored, it will be hidden in the inbox without creating a thing for it. ### Active Scan vs. Background Discovery @@ -46,11 +47,11 @@ There are different ways how a thing can be discovered: ## Available Discovery Services -Eclipse SmartHome already comes with some discovery services. These are: +Eclipse SmartHome already comes with some discovery services. These are: -- `UPnPDiscoveryService`: This discovery service discovers all IP devices using the UPnP protocol. The bindings must implement a `UpnpDiscoveryParticipant` to support this discovery service. The [UPnP discovery service documentation](../development/bindings/discovery-services.html#upnp-discovery) explains in detail, how to do that. -- `MDNSDiscoveryService`: All devices supporting the mDNS protocol are discovered by this service. +- `UPnPDiscoveryService`: This discovery service discovers all IP devices using the UPnP protocol. The bindings must implement a `UpnpDiscoveryParticipant` to support this discovery service. The [UPnP discovery service documentation](../development/bindings/discovery-services.html#upnp-discovery) explains in detail, how to do that. +- `MDNSDiscoveryService`: All devices supporting the mDNS protocol are discovered by this service. -Bindings implement more discovery services, e.g. the search for Hue lights in the Hue binding or the search for the local weather in the Yahoo weather binding. +Bindings implement more discovery services, e.g. the search for Hue lights in the Hue binding or the search for the local weather in the Yahoo weather binding. The [Implement Discovery Service](../development/bindings/discovery-services.html) chapter describes how to implement DiscoveryServices in a binding. diff --git a/concepts/event-type-definition.md b/concepts/event-type-definition.md index ab29f06db..d06f4e216 100644 --- a/concepts/event-type-definition.md +++ b/concepts/event-type-definition.md @@ -1,16 +1,17 @@ --- layout: documentation +title: Event Type Definition --- {% include base.html %} # Event Type Definition -Eclipse SmartHome provides the possibility to easily implement new event types and event factories. +Eclipse SmartHome provides the possibility to easily implement new event types and event factories. ## Define new Event Type -Events can be added by implementing the `Event` interface or the `AbstractEvent` class which offers a default implementation. Both classes are located in the Eclipse SmartHome core bundle. +Events can be added by implementing the `Event` interface or the `AbstractEvent` class which offers a default implementation. Both classes are located in the Eclipse SmartHome core bundle. The following Java snippet shows a new event type extending the class `AbstractEvent`. @@ -18,7 +19,7 @@ The following Java snippet shows a new event type extending the class `AbstractE public class SunriseEvent extends AbstractEvent { public final static String TYPE = SunriseEvent.class.getSimpleName(); - + private final SunriseDTO sunriseDTO; SunriseEvent(String topic, String payload, SunriseDTO sunriseDTO) { @@ -30,7 +31,7 @@ public class SunriseEvent extends AbstractEvent { public String getType() { return TYPE; } - + public SunriseDTO getSunriseDTO() { return sunriseDTO; } @@ -45,7 +46,7 @@ public class SunriseEvent extends AbstractEvent { The listing below summarizes some coding guidelines as illustrated in the example above: - Events should only be created by event factories. Constructors do not have any access specifier in order to make the class package private. -- The serialization of the payload into a data transfer object (e.g. `SunriseDTO`) should be part of the event factory and will be assigned to a class member via the constructor. +- The serialization of the payload into a data transfer object (e.g. `SunriseDTO`) should be part of the event factory and will be assigned to a class member via the constructor. - A public member `TYPE` represents the event type as string representation and is usually the name of the class. - The `toString()` method should deliver a meaningful string since it is used for event logging. - The source of an event can be null if not required. @@ -55,7 +56,7 @@ For more information about implementing an event, please refer to the Java docum ## Define new Event Factory Event factories can be added by implementing the `EventFactory` interface or the `AbstractEventFactory` class. The `AbstractEventFactory` provides some useful utility for parameter validation and payload serialization & deserialization with JSON. The classes are located in the Eclipse SmartHome core bundle. -```java +```java public class SunEventFactory extends AbstractEventFactory { private static final String SUNRISE_EVENT_TOPIC = "smarthome/sun/{time}/sunrise"; @@ -69,15 +70,15 @@ public class SunEventFactory extends AbstractEventFactory { Event event = null; if (eventType.equals(SunriseEvent.TYPE)) { createSunriseEvent(topic, payload); - } + } return event; } - + private createSunriseEvent(String topic, String payload) { SunriseDTO sunriseDTO = deserializePayload(payload, SunriseDTO.class); return new SunriseEvent(topic, payload, sunriseDTO); } - + public static SunriseEvent createSunriseEvent(Sunrise sunrise) { String topic = buildTopic(SUNRISE_EVENT_TOPIC, sunrise.getTime()); SunriseDTO sunriseDTO = map(sunrise); @@ -88,9 +89,9 @@ public class SunEventFactory extends AbstractEventFactory { ``` The listing below summarizes some guidelines as illustrated in the example above: -- Provide the supported event types (`SunriseEvent.TYPE`) via an `AbstractEventFactory` constructor call. The supported event types will be returned by the `AbstractEventFactory.getSupportedEventTypes()` method. +- Provide the supported event types (`SunriseEvent.TYPE`) via an `AbstractEventFactory` constructor call. The supported event types will be returned by the `AbstractEventFactory.getSupportedEventTypes()` method. - The event factory defines the topic (`SUNRISE_EVENT_TOPIC`) of the supported event types. Please ensure that the topic format follows the topic structure of the Eclipse SmartHome core events, similar to a REST URI (`{namespace}/{entityType}/{entity}/{sub-entity-1}/.../{sub-entity-n}/{action}`). The namespace must be `smarthome`. -- Implement the method `createEventByType(String eventType, String topic, String payload, String source)` to create a new event based on the topic and the payload, determined by the event type. This method will be called by the framework in order to dispatch received events to the corresponding event subscribers. If the payload is serialized with JSON, the method `deserializePayload(String payload, Class classOfPayload)`can be used to deserialize the payload into a data transfer object. -- Provide a static method to create event instances based on a domain object (Item, Thing, or in the example above `Sunrise`). This method can be used by components in order to create events based on domain objects which should be sent by the EventPublisher. If the data transfer object should be serialized into a JSON payload, the method `serializePayload(Object payloadObject)` can be used. +- Implement the method `createEventByType(String eventType, String topic, String payload, String source)` to create a new event based on the topic and the payload, determined by the event type. This method will be called by the framework in order to dispatch received events to the corresponding event subscribers. If the payload is serialized with JSON, the method `deserializePayload(String payload, Class classOfPayload)`can be used to deserialize the payload into a data transfer object. +- Provide a static method to create event instances based on a domain object (Item, Thing, or in the example above `Sunrise`). This method can be used by components in order to create events based on domain objects which should be sent by the EventPublisher. If the data transfer object should be serialized into a JSON payload, the method `serializePayload(Object payloadObject)` can be used. -For more information about implementing an event factory, please refer to the Java documentation. \ No newline at end of file +For more information about implementing an event factory, please refer to the Java documentation. diff --git a/configuration/jetty.md b/configuration/jetty.md index fb4fd8765..bb577fed1 100644 --- a/configuration/jetty.md +++ b/configuration/jetty.md @@ -1,5 +1,6 @@ --- layout: documentation +title: Eclipse Jetty --- {% include base.html %} @@ -7,30 +8,32 @@ layout: documentation # Eclipse Jetty Configuration -## Running openHAB behind an NGinX reverse proxy +## Running openHAB Behind an NGINX Reverse Proxy Running openHAB behind a reverse proxy offers you the possibility to access your openHAB runtime via port 80 (http)/ 443 (https). As these port numbers are below 1024 it's not possible for "normal users" to run servers on them. NGinX is a lightweight HTTP server. Of course you can use Apache HTTP server or any other HTTP server which supports reverse proxying as well. -### Running openHAB from a subdomain (like http://openhab.mydomain.tld) +### Running openHAB from a Subdomain (like http://openhab.mydomain.tld) Using this configuration you can proxy connections to http://openhab.domain.tld to your openHAB runtime. You just have to replace openhab.domain.tld with your host name. This host name has to be equal to the one you open in your web browser. The configuration assumes that you run the reverse proxy on the same machine as your openHAB runtime. If this doesn't fit for you, you just have to replace proxy_pass http://localhost:8080/ by your openHAB runtime hostname (http://youropenhabhostname:8080/). - server { - listen 80; - server_name openhab.domain.tld; - - location / { - proxy_pass http://localhost:8080/; - proxy_set_header Host $http_host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Scheme $scheme; - } - } +``` +server { + listen 80; + server_name openhab.domain.tld; -### Running openHAB from a subdomain with SSL (like https://openhab.mydomain.tld) + location / { + proxy_pass http://localhost:8080/; + proxy_set_header Host $http_host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Scheme $scheme; + } +} +``` + +### Running openHAB from a Subdomain with SSL (like https://openhab.mydomain.tld) Using this configuration you can proxy connections to https://openhab.domain.tld to your openHAB runtime. You just have to replace openhab.domain.tld with your host name. This host name has to be equal to the one you open in your web browser. @@ -40,20 +43,21 @@ The configuration assumes that you run the reverse proxy on the same machine as Maybe you do not trust the local network. In this case it's possible to pass the request to openHAB's SSL port using proxy\_pass https://youropenhabhostname:8443/ instead of proxy\_pass http://youropenhabhostname:8080/. - server { - listen 443; - server_name openhab.domain.tld; - - ssl on; - ssl_certificate /etc/nginx/ssl/server.crt; - ssl_certificate_key /etc/nginx/ssl/server.key; - - location / { - proxy_pass http://localhost:8080/; - proxy_set_header Host $http_host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Scheme $scheme; - } +``` +server { + listen 443; + server_name openhab.domain.tld; + + ssl on; + ssl_certificate /etc/nginx/ssl/server.crt; + ssl_certificate_key /etc/nginx/ssl/server.key; + + location / { + proxy_pass http://localhost:8080/; + proxy_set_header Host $http_host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Scheme $scheme; } - +} +``` diff --git a/developers/contributing/contributing.md b/developers/contributing/contributing.md index bf2ae387b..dc66f208d 100644 --- a/developers/contributing/contributing.md +++ b/developers/contributing/contributing.md @@ -1,24 +1,25 @@ --- layout: developersguide +title: Contribution --- {% include base.html %} -# Contributing to the development of openHAB +# Contributing to the Development of openHAB -## The repositories +## The Repositories Note that the openHAB distribution repository does not contain any source code, but it rather aggregates features from different repos: -- [Eclipse SmartHome Framework](https://github.com/eclipse/smarthome): This repo holds the major parts of the core functionality. -- [openHAB 2 Core](https://github.com/kaikreuzer/openhab-core): This repo contains a few small bundles that are not part of Eclipse SmartHome, but required for the openHAB runtime. This e.g. contains a compatibility layer for supporting openHAB 1 add-ons. -- [openHAB 2 Add-ons](https://github.com/openhab/openhab2): Add-ons of openHAB that use the Eclipse SmartHome APIs can be found within this repository. They cannot be used with an openHAB 1.x runtime, since they provide features that the old runtime does not support. -- [openHAB 1 Add-ons](https://github.com/openhab/openhab): Add-ons developed for openHAB 1.x. Most of them are working smoothly on the openHAB 2 runtime and thus they are packaged within the distribution. -- [Eclipse SmartHome Extensions](https://github.com/eclipse/smarthome/tree/master/extensions): Since openHAB uses the Eclipse SmartHome framework, it is automatically compatible with all extensions that are available for it and maintained within the Eclipse SmartHome repository. These are usually high-quality extensions that might be even used in commercial products. +* [Eclipse SmartHome Framework](https://github.com/eclipse/smarthome): This repo holds the major parts of the core functionality. +* [openHAB 2 Core](https://github.com/kaikreuzer/openhab-core): This repo contains a few small bundles that are not part of Eclipse SmartHome, but required for the openHAB runtime. This e.g. contains a compatibility layer for supporting openHAB 1 add-ons. +* [openHAB 2 Add-ons](https://github.com/openhab/openhab2): Add-ons of openHAB that use the Eclipse SmartHome APIs can be found within this repository. They cannot be used with an openHAB 1.x runtime, since they provide features that the old runtime does not support. +* [openHAB 1 Add-ons](https://github.com/openhab/openhab): Add-ons developed for openHAB 1.x. Most of them are working smoothly on the openHAB 2 runtime and thus they are packaged within the distribution. +* [Eclipse SmartHome Extensions](https://github.com/eclipse/smarthome/tree/master/extensions): Since openHAB uses the Eclipse SmartHome framework, it is automatically compatible with all extensions that are available for it and maintained within the Eclipse SmartHome repository. These are usually high-quality extensions that might be even used in commercial products. -## Contribution guidelines +## Contribution Guidelines -### Pull requests are always welcome +### Pull Requests are Always Welcome We are always thrilled to receive pull requests, and do our best to process them as fast as possible. Not sure if that typo is worth a pull @@ -33,21 +34,21 @@ to do everything for everybody. This means that we might decide against incorporating a new feature. However, there might be a way to implement that feature *on top of* openHAB. -### Discuss your design on the mailing list +### Discuss your Design on the Mailing List -We recommend discussing your plans [in the discussion forum](https://community.openhab.org/) +We recommend discussing your plans [in the discussion forum](https://community.openhab.org) before starting to code - especially for more ambitious contributions. This gives other contributors a chance to point you in the right direction, give feedback on your design, and maybe point out if someone else is working on the same thing. -### Create issues... +### Create Issues... Any significant improvement should be documented as [a GitHub issue](https://github.com/openhab/openhab-distro/issues?labels=enhancement&page=1&state=open) before anybody starts working on it. -### ...but check for existing issues first! +### ...but Check for Existing Issues First! Please take a moment to check that an issue doesn't already exist documenting your bug report or improvement proposal. If it does, it @@ -72,7 +73,7 @@ your documentation changes for clarity, concision, and correctness, as well as a clean documentation build. Write clean code. Universally formatted code promotes ease of writing, reading, -and maintenance. +and maintenance. Pull requests descriptions should be as clear as possible and include a reference to all the issues that they address. @@ -102,7 +103,7 @@ name and email address match your git configuration. The AUTHORS file is regenerated occasionally from the git commit history, so a mismatch may result in your changes being overwritten. -### Merge approval +### Merge Approval openHAB maintainers use LGTM (Looks Good To Me) in comments on the code review to indicate acceptance. @@ -112,7 +113,7 @@ component affected. For example, if a change affects `docs/` and `distributions/ needs an absolute majority from the maintainers of `docs/` AND, separately, an absolute majority of the maintainers of `addons/`. -### Sign your work +### Sign your Work The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to @@ -165,14 +166,14 @@ then you just add a line to every git commit message: using your real name (sorry, no pseudonyms or anonymous contributions.) -#### Small patch exception +#### Small Patch Exception There are several exceptions to the signing requirement. Currently these are: * Your patch fixes spelling or grammar errors. * Your patch is a single line change to documentation. -### How can I become a maintainer? +### How can I Become a Maintainer? * Step 1: learn the component inside out * Step 2: make yourself useful by contributing code, bugfixes, support etc. @@ -205,4 +206,3 @@ general guidelines for the community as a whole: respond to an email you are potentially sending to a large number of people. Please consider this before you update. Also remember that nobody likes spam. - diff --git a/developers/development/bindings.md b/developers/development/bindings.md index b6d64239c..af2f06b7b 100644 --- a/developers/development/bindings.md +++ b/developers/development/bindings.md @@ -1,10 +1,11 @@ --- layout: developersguide +title: Developing bindings --- {% include base.html %} -# Developing a new binding for openHAB 2 +# Developing a New Binding for openHAB 2 This page describes the necessary steps in order to implement a new binding for openHAB 2. @@ -12,14 +13,14 @@ _Note:_ Please note that in contrast to openHAB 1.x, openHAB 2 is based on the [ For information about code style and naming conventions, please see the [guidelines of Eclipse SmartHome](https://www.eclipse.org/smarthome/documentation/development/guidelines.html). -## Choosing a namespace +## Choosing a Namespace As a first step, you need to decide in which namespace you want to develop your binding - assuming that you want to contribute it back to the community, you have two options: * You can choose `org.eclipse.smarthome`, if you want to directly contribute it to the Eclipse SmartHome project. The advantage of this option is that you make it available to a wider audience as your binding will also be available for other solutions than openHAB that are based on Eclipse SmartHome. The disadvantage is that the contribution process is stricter as it involves intellectual property checks and in general makes it harder or even impossible to include third-party libraries with copy-left licenses such as LGPL or code that you have written by reverse engineering some protocol. * You can choose `org.openhab`, if you want it to be used for openHAB only. This is the better option, if your binding is not interesting for other solutions, requires special libraries or has technical dependencies on openHAB specific things (although this should be avoided as much as possible). -## Creating a skeleton +## Creating a Skeleton For the openHAB namespace: Choose the option "openHAB 2 Add-ons" in [your IDE setup](ide.html), and go ahead and create a skeleton for your binding. For this, go into your git repository under `git/openhab2-addons/addons/binding` and call the script `create_openhab_binding_skeleton.sh` with a single parameter, which is your binding name in camel case (e.g. 'ACMEProduct' or 'SomeSystem'). When prompted, enter your name as author and hit "Y" to start the skeleton generation. diff --git a/developers/development/compatibilitylayer.md b/developers/development/compatibilitylayer.md index b5db98345..a9af4f0d1 100644 --- a/developers/development/compatibilitylayer.md +++ b/developers/development/compatibilitylayer.md @@ -1,5 +1,6 @@ --- layout: developersguide +title: Compatibility --- {% include base.html %} @@ -13,27 +14,27 @@ To still make it possible to use 1.x add-ons, there is a special bundle in openH Currently, the compatibility layer focuses on the official APIs, i.e. an add-ons that does no dirty things should be able to run. Taking the huge number of 1.x add-ons into account, it is likely that there are a couple of problems with one or another. Some problems might be due to bugs in the compatibility bundle, others might be solvable within the add-on. ## How to use openHAB 1.x Add-ons that are not part of the distribution - + While the openHAB distribution already contains many add-ons of openHAB 1, there are still quite some of them missing - please help testing them - if they are confirmed to be working, they can be included in the distribution. -Test a not included add-on is very straight forward: +Test a not included add-on is very straight forward: - Start your runtime - - Install the 1.x compatibility layer by running `feature:install openhab-runtime-compat1x` in the openHAB console + - Install the 1.x compatibility layer by running `feature:install openhab-runtime-compat1x` in the openHAB console - As with openHAB 1.x, simply take the jar file of your add-on and place it in the `${openhab.home}/addons` folder. - Copy your personal `openhab.cfg` file to `${openhab.home}/conf/services/openhab.cfg`. - + ## How to solve problems with a certain add-on? - + All developers are encouraged to help on this in order to quickly make as many 1.x add-ons compatible with the openHAB 2 runtime as possible. Here is what you need to do: - Setup a the [openHAB 2 IDE](../development/ide.html). - Import your 1.x add-on from your local openHAB 1 git clone into your workspace. - - If it compiles, the first major step is already done. If not, try to figure out why there are compilation problems and if you cannot solve them, ask on the mailing list for help. + - If it compiles, the first major step is already done. If not, try to figure out why there are compilation problems and if you cannot solve them, ask on the mailing list for help. - After adding some configuration, start up the runtime through the launch configuration (make sure your bundle is activated and started by default) from within the IDE. - Go and test and report your findings by creating issues or pull requests for the [add-on in openHAB 1](https://github.com/openhab/openhab/issues). - + ## How to add a successfully tested 1.x Add-on to the distribution - -1. The first step is to create a "Karaf feature" for it, in which required dependencies (i.e. to io.transport bundles) can also be declared. Such a feature can also include the required configuration, therefore you should create a file `.cfg` in `features/openhab-addons-external/src/main/resources/conf` with the same content as what is within `openhab.cfg`, but without the `:` prefix on the lines of the parameters. + +1. The first step is to create a "Karaf feature" for it, in which required dependencies (i.e. to io.transport bundles) can also be declared. Such a feature can also include the required configuration, therefore you should create a file `.cfg` in `features/openhab-addons-external/src/main/resources/conf` with the same content as what is within `openhab.cfg`, but without the `:` prefix on the lines of the parameters. This config file then needs to be added to `features/openhab-addons-external/pom.xml` so that the build is aware of it. The feature itself is then added to `features/openhab-addons/src/main/feature/feature.xml`, referencing the bundle, the config file and its dependencies (if any). The result should look [similar to this](https://github.com/openhab/openhab/pull/3988/files). This will automatically make the add-on a part of the distro with the next build. diff --git a/developers/development/evolution.md b/developers/development/evolution.md index ea0e5a4a6..f9bf2346f 100644 --- a/developers/development/evolution.md +++ b/developers/development/evolution.md @@ -1,12 +1,13 @@ --- layout: developersguide +title: Evolution --- {% include base.html %} # Technical Difference to openHAB 1 - + There are a few technical changes in openHAB 2 that are not compatible with openHAB 1: - the REST API does NOT support XML nor JSON-P anymore. It is now fully realized using JSON. - - the REST API does not support websocket access anymore - it actually completely drops "push" support and only has a simple long-polling implementation to provide a basic backward-compatibility for clients. + - the REST API does not support websocket access anymore - it actually completely drops "push" support and only has a simple long-polling implementation to provide a basic backward-compatibility for clients. diff --git a/developers/development/guidelines.md b/developers/development/guidelines.md index 9f203a703..69702f775 100644 --- a/developers/development/guidelines.md +++ b/developers/development/guidelines.md @@ -1,5 +1,6 @@ --- layout: developersguide +title: Coding Guidelines --- {% include base.html %} @@ -16,11 +17,11 @@ Note that this list also serves as a checklist for code reviews on pull requests 1. The [Java naming conventions](http://java.about.com/od/javasyntax/a/nameconventions.htm) should be used. 1. Every Java file must have a license header. You can run ```mvn license:format``` on the root of the repo to automatically add missing headers. 1. Every class, interface and enumeration should have JavaDoc describing its purpose and usage. -1. Every class, interface and enumeration must have an @author tag in its JavaDoc for every author that wrote a substantial part of the file. +1. Every class, interface and enumeration must have an `@author` tag in its JavaDoc for every author that wrote a substantial part of the file. 1. Every constant, field and method with default, protected or public visibility should have JavaDoc (optional, but encouraged for private visibility as well). 1. Code must be formatted using the provided code formatter and clean up settings. They are set up automatically by the official [IDE setup](ide.html). 1. Generics must be used where applicable. -1. Code should not show any warnings. Warnings that cannot be circumvented should be suppressed by using the @SuppressWarnings annotation. +1. Code should not show any warnings. Warnings that cannot be circumvented should be suppressed by using the `@SuppressWarnings` annotation. 1. For dependency injection, OSGi Declarative Services should be used. 1. Packages that contain classes that are not meant to be used by other bundles should have "internal" in their package name. @@ -28,11 +29,11 @@ Note that this list also serves as a checklist for code reviews on pull requests 7. Every bundle must contain a Maven pom.xml with a version and artifact name that is in sync with the manifest entry. The pom.xml must reference the correct parent pom (which is usually in the parent folder). 1. Every bundle must contain an [about.html](https://eclipse.org/legal/epl/about.php) file, providing license information. -1. Every bundle must contain a build.properties file, which lists all resources that should end up in the binary under ```bin.includes```. +1. Every bundle must contain a build.properties file, which lists all resources that should end up in the binary under `bin.includes`. 1. The manifest must not contain any "Require-Bundle" entries. Instead, "Import-Package" must be used. 1. The manifest must not export any internal package. 1. The manifest must not have any version constraint on package imports, unless this is thoughtfully added. Note that Eclipse automatically adds these constraints based on the version in the target platform, which might be too high in many cases. -1. The manifest must include all services in the Service-Component entry. A good approach is to put OSGI-INF/*.xml in there. +1. The manifest must include all services in the Service-Component entry. A good approach is to put `OSGI-INF/*.xml` in there. 1. Every exported package of a bundle must be imported by the bundle itself again. ## C. Language Levels and Libraries @@ -49,5 +50,5 @@ Note that this list also serves as a checklist for code reviews on pull requests 14. Overridden methods from abstract classes or interfaces are expected to return fast unless otherwise stated in their JavaDoc. Expensive operations should therefore rather be scheduled as a job. 1. Creation of threads must be avoided. Instead, resort into using existing schedulers which use pre-configured thread pools. If there is no suitable scheduler available, start a discussion in the forum about it rather than creating a thread by yourself. -1. Bundles need to cleanly start and stop without throwing exceptions or malfunctioning. This can be tested by manually starting and stopping the bundle from the console (```stop ``` resp. ```start ```). +1. Bundles need to cleanly start and stop without throwing exceptions or malfunctioning. This can be tested by manually starting and stopping the bundle from the console (`stop ` resp. `start `). 1. Bundles must not require any substantial CPU time. Test this e.g. using "top" or VisualVM and compare CPU utilization with your bundle stopped vs. started. diff --git a/developers/development/ide.md b/developers/development/ide.md index df72c22c1..5b8a14ebd 100644 --- a/developers/development/ide.md +++ b/developers/development/ide.md @@ -1,5 +1,6 @@ --- layout: developersguide +title: IDE setup --- {% include base.html %} @@ -30,7 +31,7 @@ The Eclipse IDE is used for openHAB developments. The Eclipse Installer automati 4. Expand the "Github.com/openHAB" entry, double click "openHAB Development" (the double click is important: The entry has to appear in the empty table at the bottom). Furthermore double-click all entries that you would want to have available in your workspace (you can select multiple/all of them). Make sure that all of them are listed in the table at the bottom and select "Next". 5. Now provide an installation folder (don't use spaces in the path on Windows!) and your Github id (used to push your changesets to) and select "Next". 6. The installation will now begin when pressing "Finish". -7. Once it is done, you will see the Eclipse Welcome Screen, which you can close by clicking "Workbench" on the top right. You will see that the installer not only set up an Eclipse IDE instance for you, but also checked out all selected git repositories and imported all projects into the workspace. +7. Once it is done, you will see the Eclipse Welcome Screen, which you can close by clicking "Workbench" on the top right. You will see that the installer not only set up an Eclipse IDE instance for you, but also checked out all selected git repositories and imported all projects into the workspace. 8. Your workspace should now fully compile and you can start the runtime by launching the "openHAB_Runtime" launch configuration. Note that you will find the sources in a subfolder called "git" within your selected installation folder. You can use any kind of git client here, if you do not want to use the git support from within the Eclipse IDE. @@ -65,5 +66,3 @@ Add some text to the string and save the file. Now put a breakpoint on this line Debugging is done in the same way as running, but instead of Run as, select "Debug as > openHAB_Runtime". OpenHAB will launch, and the debugger will stop at the breakpoint, but our change won't be there. To fix this we need to let eclipse know that we've made changes to this binding. Right click on openHAB_Runtime.launch > Run as > Run configurations ... Go to the Plug-ins tab. Notice that under "Target Platform" org.eclipse.smarthome.binding.yahooweather is checked. But, under Workspace the same org.eclipse.smarthome.binding.yahooweather is not checked. Do so now. Try the debug session again. You should now see the modified code show up in the debugger. - - diff --git a/developers/index.md b/developers/index.md index c4eb1ad11..df45e6573 100644 --- a/developers/index.md +++ b/developers/index.md @@ -1,5 +1,6 @@ --- layout: developersguide +title: Developer Guide --- @@ -16,4 +17,4 @@ This manual is an on-going work. . -. \ No newline at end of file +. diff --git a/developers/prerequisites/OSGi.md b/developers/prerequisites/OSGi.md index f40a2deb1..17806d221 100644 --- a/developers/prerequisites/OSGi.md +++ b/developers/prerequisites/OSGi.md @@ -1,5 +1,6 @@ --- layout: developersguide +title: OSGi --- {% include base.html %} @@ -42,7 +43,7 @@ More details about the OSGi architecture can be found at Bug: There seem to be [some issues](https://github.com/eclipse/smarthome/issues/1393#issuecomment-223764080) with global variables that still need to be fixed. @@ -93,8 +94,8 @@ The ***Rules*** section contains a list of rules. Each rule has the following sy ```java rule "rule name" when - or - or + or + or ... then @@ -127,7 +128,7 @@ Item received update [] Item changed [from ] [to ] ``` -> A simplistic explanation of the differences between `command` and `update` (useful if you are new to openHAB) can be found on the [Actions page](https://github.com/openhab/openhab/wiki/Actions#sendcommand-vs-postupdate) +> A simplistic explanation of the differences between `command` and `update` (useful if you are new to openHAB) can be found on the [Actions page](https://github.com/openhab/openhab/wiki/Actions#sendcommand-vs-postupdate) ### Time-based Triggers @@ -151,7 +152,7 @@ A cron expression takes the form of six or optionally seven fields: for more information see the [Quartz documentation](http://www.quartz-scheduler.org/documentation/quartz-2.1.x/tutorials/tutorial-lesson-06). -You may also use [CronMaker](http://www.cronmaker.com/) to generate cron expressions. +You may also use [CronMaker](http://www.cronmaker.com/) to generate cron expressions. ### System-based Triggers @@ -168,7 +169,7 @@ The expression language used within scripts is the same that is used in the Xten The syntax is very similar to Java, but has many nice features that allows writing concise code. It is especially powerful in handling collections. What makes it a good match for openHAB from a technical perspective is the fact that there is no need to compile the scripts as they can be interpreted at runtime. -To be able to do something useful with the scripts, openHAB provides access to +To be able to do something useful with the scripts, openHAB provides access to - all defined items, so that you can easily access them by their name - all enumerated states/commands, e.g. `ON, OFF, DOWN, INCREASE` etc. @@ -239,16 +240,16 @@ Taking all the information together, an example rule file could look like this: ```java var Number counter - + // setting the counter to some initial value // we could have done this in the variable declaration already rule Startup -when +when System started then counter = 0 end - + // increase the counter at midnight rule "Increase counter" when @@ -256,16 +257,16 @@ when then counter = counter + 1 end - + // tell the number of days either at noon or if a button is pressed rule "Announce number of days up" when - Time is noon or + Time is noon or Item AnnounceButton received command ON then say("The system is up since " + counter + " days") end - + // sets the counter to the value of a received command rule "Set the counter" when diff --git a/features/bindings.md b/features/bindings.md index 14ba6b0e6..08cbe6079 100644 --- a/features/bindings.md +++ b/features/bindings.md @@ -1,10 +1,11 @@ --- layout: documentation +title: Bindings --- {% include base.html %} -# List of available bindings +# List of Available Bindings ## 2.0 Bindings {% assign bindings = site.data.bindings | sort: 'label.toLowerCase()' %} @@ -86,7 +87,7 @@ layout: documentation | GoogleTTS | TTS engine | | MaryTTS | TTS engine | -## Currently incompatible 1.x Add-ons: +## Currently Incompatible 1.x Add-ons: | Add-on | Type | Reason |--------|------|------| diff --git a/features/compatibilitylayer.md b/features/compatibilitylayer.md index 271cd9094..395628674 100644 --- a/features/compatibilitylayer.md +++ b/features/compatibilitylayer.md @@ -1,3 +1,10 @@ +--- +layout: documentation +title: Compatibility +--- + +{% include base.html %} + # Compatibility Layer for openHAB 1.x Add-ons openHAB 2 used [Eclipse SmartHome](https://www.eclipse.org/smarthome/) as its core framework. Although many classes are similar, all of them have at least a different namespace (`org.eclipse.smarthome` instead of `org.openhab`) - as a result, none the existing 1.x add-ons would work on openHAB 2. @@ -7,27 +14,27 @@ To still make it possible to use 1.x add-ons, there is a special bundle in openH Currently, the compatibility layer focuses on the official APIs, i.e. an add-ons that does no dirty things should be able to run. Taking the huge number of 1.x add-ons into account, it is likely that there are a couple of problems with one or another. Some problems might be due to bugs in the compatibility bundle, others might be solvable within the add-on. ## How to use openHAB 1.x Add-ons that are not part of the distribution - + While the openHAB distribution already contains many add-ons of openHAB 1, there are still quite some of them missing - please help testing them - if they are confirmed to be working, they can be included in the distribution. -Test a not included add-on is very straight forward: +Test a not included add-on is very straight forward: - Start your runtime - - Install the 1.x compatibility layer by running `feature:install openhab-runtime-compat1x` in the openHAB console + - Install the 1.x compatibility layer by running `feature:install openhab-runtime-compat1x` in the openHAB console - As with openHAB 1.x, simply take the jar file of your add-on and place it in the `${openhab.home}/addons` folder. - Copy your personal `openhab.cfg` file to `${openhab.home}/conf/services/openhab.cfg`. - + ## How to solve problems with a certain add-on? - + All developers are encouraged to help on this in order to quickly make as many 1.x add-ons compatible with the openHAB 2 runtime as possible. Here is what you need to do: - Setup a the [openHAB 2 IDE](../development/ide.md). - Import your 1.x add-on from your local openHAB 1 git clone into your workspace. - - If it compiles, the first major step is already done. If not, try to figure out why there are compilation problems and if you cannot solve them, ask on the mailing list for help. + - If it compiles, the first major step is already done. If not, try to figure out why there are compilation problems and if you cannot solve them, ask on the mailing list for help. - After adding some configuration, start up the runtime through the launch configuration (make sure your bundle is activated and started by default) from within the IDE. - Go and test and report your findings by creating issues or pull requests for the [add-on in openHAB 1](https://github.com/openhab/openhab/issues). - + ## How to add a successfully tested 1.x Add-on to the distribution - -1. The first step is to create a "Karaf feature" for it, in which required dependencies (i.e. to io.transport bundles) can also be declared. Such a feature can also include the required configuration, therefore you should create a file `.cfg` in `features/openhab-addons-external/src/main/resources/conf` with the same content as what is within `openhab.cfg`, but without the `:` prefix on the lines of the parameters. + +1. The first step is to create a "Karaf feature" for it, in which required dependencies (i.e. to io.transport bundles) can also be declared. Such a feature can also include the required configuration, therefore you should create a file `.cfg` in `features/openhab-addons-external/src/main/resources/conf` with the same content as what is within `openhab.cfg`, but without the `:` prefix on the lines of the parameters. This config file then needs to be added to `features/openhab-addons-external/pom.xml` so that the build is aware of it. The feature itself is then added to `features/openhab-addons/src/main/feature/feature.xml`, referencing the bundle, the config file and its dependencies (if any). The result should look [similar to this](https://github.com/openhab/openhab/pull/3988/files). This will automatically make the add-on a part of the distro with the next build. diff --git a/features/iconsets/classic/readme.md b/features/iconsets/classic/readme.md index 722bf1ffc..24f447167 100644 --- a/features/iconsets/classic/readme.md +++ b/features/iconsets/classic/readme.md @@ -1,5 +1,6 @@ --- layout: documentation +title: Classic Icon Set --- {% include base.html %} diff --git a/features/index.md b/features/index.md index dfe88a9c3..b4b9cef61 100644 --- a/features/index.md +++ b/features/index.md @@ -1,5 +1,6 @@ --- layout: documentation +title: Features --- {% include base.html %} diff --git a/features/io.md b/features/io.md index 241eb71e3..73622c153 100644 --- a/features/io.md +++ b/features/io.md @@ -1,10 +1,11 @@ --- layout: documentation +title: System Integrations --- {% include base.html %} -# List of System integrations +# List of System Integrations ## System Integration diff --git a/features/io/homekit/readme.md b/features/io/homekit/readme.md index 663d799a7..c8b93373d 100644 --- a/features/io/homekit/readme.md +++ b/features/io/homekit/readme.md @@ -1,5 +1,6 @@ --- layout: documentation +title: HomeKit Add-on --- {% include base.html %} diff --git a/features/io/hueemulation/readme.md b/features/io/hueemulation/readme.md index 34b83df80..d32e877fe 100644 --- a/features/io/hueemulation/readme.md +++ b/features/io/hueemulation/readme.md @@ -1,5 +1,6 @@ --- layout: documentation +title: Hue Emulation --- {% include base.html %} @@ -12,7 +13,7 @@ Hue Emulation exposes openHAB items as Hue devices to other Hue HTTP API compati ## Features: -* UPNP automatic discovery +* UPNP automatic discovery * Support ON/OFF and Percent/Decimal item types * Can expose any type of item, not just lights * Pairing (security) can be enabled/disabled in real time using the configuration service (under services in the PaperUI for example) diff --git a/features/paperui.md b/features/paperui.md index 6ae2735a3..9f0d9483a 100644 --- a/features/paperui.md +++ b/features/paperui.md @@ -1,3 +1,10 @@ +--- +layout: documentation +title: PaperUI +--- + +{% include base.html %} + # Paper UI The Paper UI is a new interface that helps setting up and configuring your openHAB instance. diff --git a/features/persistence.md b/features/persistence.md index 6a1bed55c..a1a6cc836 100644 --- a/features/persistence.md +++ b/features/persistence.md @@ -1,9 +1,10 @@ --- layout: documentation +title: Persistence --- {% include base.html %} # Sitemaps -to be done... \ No newline at end of file +to be done... diff --git a/features/uis.md b/features/uis.md index 5c2795c8e..bf9fc5fe9 100644 --- a/features/uis.md +++ b/features/uis.md @@ -1,5 +1,6 @@ --- layout: documentation +title: UI Features --- {% include base.html %} diff --git a/features/uis/basic/readme.md b/features/uis/basic/readme.md index 2367bdd5e..72e2b1032 100644 --- a/features/uis/basic/readme.md +++ b/features/uis/basic/readme.md @@ -1,5 +1,6 @@ --- layout: documentation +title: BasicUI --- {% include base.html %} @@ -31,4 +32,3 @@ Screenshots: [![Screenshot 1](doc/screenshot-1.png)](doc/screenshot-1-full.png) [![Screenshot 2](doc/screenshot-2.png)](doc/screenshot-2-full.png) -