moved and updated documentation from openhab/openhab2

Signed-off-by: Kai Kreuzer <[email protected]>

README.md

@@ -1,9 +1,43 @@
-## openHAB Distribution
-
-This project aggregates all different parts of openHAB and builds a distribution from it.
-The different sources are:
-- Eclipse SmartHome
-- SHK Karaf Features
-- openHAB 2 Core
-- openHAB 1 Add-ons
-- openHAB 2 Add-ons
+## Introduction
+
+The open Home Automation Bus (openHAB) project aims at providing a universal integration platform for all things around home automation. It is a pure Java solution, fully based on OSGi.
+
+It is designed to be absolutely vendor-neutral as well as hardware/protocol-agnostic. openHAB brings together different bus systems, hardware devices and interface protocols by dedicated bindings. These bindings send and receive commands and status updates on the openHAB event bus. This concept allows designing user interfaces with a unique look&feel, but with the possibility to operate devices based on a big number of different technologies. Besides the user interfaces, it also brings the power of automation logics across different system boundaries.
+
+For further Information please refer to our homepage [www.openhab.org](http://www.openhab.org). 
+
+## openHAB 2 Distribution
+
+openHAB 2 is the successor of [openHAB 1](https://github.com/openhab/openhab/wiki). It is an open-source solution based on the [Eclipse SmartHome]() framework. It is fully written in Java and uses [Apache Karaf](http://karaf.apache.org/) together with [Eclipse Equinox](https://www.eclipse.org/equinox/) as an OSGi runtime and bundles this with [Jetty](https://www.eclipse.org/jetty/) as an HTTP server.
+
+openHAB is a highly modular software, which means that the base installation (the "runtime") can be extended through "add-ons". The openHAB distribution includes add-ons from different sources and makes them all available.
+
+![distribution overview](docs/sources/images/distro.png)
+
+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.
+
+The distribution is available in two flavors:
+ - offline: This package contains all available add-ons and allows installing them locally, i.e. completely offline.
+ - online: This package only contains the core runtime and downloads any add-on from a remote repository.
+
+For the latest snapshot builds, please see to our [cloudbees job](https://openhab.ci.cloudbees.com/job/openHAB-Distribution/).
+
+## Community: How to Get Involved
+
+As any good open source project, openHAB welcomes community participation in the project. Read more in the [how to contribute](CONTRIBUTING.md) guide.
+
+If you are a developer and want to jump right into the sources and execute openHAB from within Eclipse, please have a look at the [IDE setup](docs/sources/development/ide.md) procedures.
+
+You can also learn [how openHAB 2 bindings are developed](docs/sources/development/bindings.md).
+
+In case of problems or questions, please join our vibrant [openHAB community](https://community.openhab.org/).
+
+
+## Trademark Disclaimer
+
+Product names, logos, brands and other trademarks referred to within the openHAB website are the property of their respective trademark holders. These trademark holders are not affiliated with openHAB or our website. They do not sponsor or endorse our materials.

docs/sources/.project

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>docs</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+	</buildSpec>
+	<natures>
+	</natures>
+</projectDescription>

docs/sources/addons.md

@@ -0,0 +1,111 @@
+# List of openHAB 2 Add-ons
+
+All optional add-ons for openHAB 2 are [available in a separate download](https://bintray.com/artifact/download/openhab/bin/openhab-2.0.0.alpha2-addons.zip). This file contains all new 2.0 bindings as well as all 1.x add-ons that were reported to be compatible. If you are successfully using a 1.x add-on with the 2.0 runtime, which is not yet on this list, please create a PR for adding it.
+
+## 2.0 Bindings
+
+| Binding | Description |
+|-------|----------------------|
+| [Astro Binding](../../addons/binding/org.openhab.binding.astro/README.md) | Astronomical calculations for sun and moon positions |
+| [Autelis Binding](../../addons/binding/org.openhab.binding.autelis/README.md) | Pool controller |
+| [AVM Fritz!Box Binding](../../addons/binding/org.openhab.binding.avmfritz/README.md) | currently only supports FRITZ AHA devices |
+| [DSCAlarm Binding](../../addons/binding/org.openhab.binding.dscalarm/README.md) | DSC PowerSeries alarm systems |
+| [Freebox Binding](../../addons/binding/org.openhab.binding.freebox/README.md) | the french [Freebox Revolution](http://www.free.fr/adsl/freebox-revolution.html) server |
+| [HDanywhere Binding](../../addons/binding/org.openhab.binding.hdanywhere/) | HDMI matrix |
+| [IPP Binding](../../addons/binding/org.openhab.binding.ipp/README.md) | Internet Printing Protocol (replaces 1.x CUPS Binding) |
+| [KEBA Binding](../../addons/binding/org.openhab.binding.keba/README.md) | Electric vehicle charging station |
+| [LIFX Binding](https://github.com/eclipse/smarthome/blob/20150525/addons/binding/org.eclipse.smarthome.binding.lifx/README.md) | Wifi-enabled LED bulbs |
+| [Lutron Binding](../../addons/binding/org.openhab.binding.lutron/README.md) | Dimmers And Lighting Controls |
+| [MAX! Binding](../../addons/binding/org.openhab.binding.max/README.md) | Heater control solution by eQ-3 |
+| [Network Binding](../../addons/binding/org.openhab.binding.network/) | Scans local network (replaces 1.x networkhealth Binding) |
+| [NTP Binding](https://github.com/eclipse/smarthome/blob/master/extensions/binding/org.eclipse.smarthome.binding.ntp/README.md) | NTP time servers |
+| [PioneerAVR Binding](../../addons/binding/org.openhab.binding.pioneeravr/README.md) | AV receivers by Pioneer |
+| [Philips Hue Binding](https://github.com/eclipse/smarthome/blob/20150525/addons/binding/org.eclipse.smarthome.binding.hue/README.md) | LED lighting system |
+| [Pulseaudio Binding](../../addons/binding/org.openhab.binding.pulseaudio/README.md) | software-based audio distribution |
+| [Rfxcom Binding](../../addons/binding/org.openhab.binding.rfxcom/README.md) | 433MHz radio transceiver and devices |
+| [SamsungTV Binding](../../addons/binding/org.openhab.binding.samsungtv/README.md) | Samsung Smart TVs |
+| [SMAEnergyMeter Binding](../../addons/binding/org.openhab.binding.smaenergymeter/README.md) | SMA Energy Meter for photovoltaic systems |
+| [Sonos Binding](../../addons/binding/org.openhab.binding.sonos/README.md) | Multi-room audio system |
+| [Squeezebox Binding](../../addons/binding/org.openhab.binding.squeezebox/README.md) | Logitech's connected speakers |
+| [Tesla Binding](../../addons/binding/org.openhab.binding.tesla/README.md) | Teslas Model S Electric Vehicle |
+| [Vitotronic Binding](../../addons/binding/org.openhab.binding.vitotronic/README.md) | Heating systems by Viessmann |
+| [WeMo Binding](https://github.com/eclipse/smarthome/blob/20150525/addons/binding/org.eclipse.smarthome.binding.wemo/README.md) | Switchable sockets by Belkin |
+| [YahooWeather Binding](https://github.com/eclipse/smarthome/blob/20150525/addons/binding/org.eclipse.smarthome.binding.yahooweather/README.md) | Weather information from Yahoo |
+
+## Compatible 1.x Add-ons
+
+| Add-on | Type |
+|--------|------|
+| Anel | Binding |
+| Astro | Binding |
+| CalDAV | Binding |
+| Comfo Air | Binding |
+| Denon | Binding |
+| DMX (OLA) | Binding |
+| Ecobee | Binding |
+| EDS OWServer | Binding |
+| Energenie | Binding |
+| Enocean | Binding |
+| Enphaseenergy | Binding |
+| Epsonprojector | Binding |
+| Exec | Binding |
+| Freeswitch | Binding |
+| FS20 | Binding |
+| Heatmiser | Binding |
+| Homematic | Binding |
+| HTTP | Binding |
+| IHC | Binding |
+| InsteonPLM | Binding |
+| KNX | Binding |
+| LCN | Binding |
+| Milight | Binding |
+| Modbus | Binding |
+| MQTT | Binding |
+| Nest | Binding |
+| Networkhealth | Binding |
+| Nibeheatpump | Binding |
+| NTP | Binding |
+| Onkyo | Binding |
+| OpenEnergyMonitor | Binding |
+| OneWire | Binding |
+| RWE SmartHome | Binding |
+| RFXCOM | Binding |
+| Samsung AC | Binding |
+| Sapp | Binding |
+| Satel | Binding |
+| SNMP | Binding |
+| SwegonVentilation | Binding |
+| SystemInfo | Binding |
+| Tinkerforge | Binding |
+| Tellstick | Binding |
+| Weather | Binding |
+| WOL | Binding |
+| XBMC | Binding |
+| ZWave | Binding |
+| InfluxDB | Persistence |
+| rrd4j | Persistence |
+| MySQL | Persistence |
+| MongoDB | Persistence |
+| Logging | Persistence |
+| JPA | Persistence |
+| Ecobee | Action |
+| Mail | Action |
+| Pushover | Action |
+| Telegram | Action |
+| XBMC | Action |
+| XMPP | Action |
+| GoogleTTS | TTS engine |
+| MaryTTS | TTS engine |
+
+## Currently incompatible 1.x Add-ons:
+
+| Add-on | Type | Reason
+|--------|------|------|
+| Twitter | Action | [Hardcoded path for local file storage](https://github.com/openhab/openhab/issues/3454)
+
+
+## Compatible Applications
+
+| Application | Description |
+|-------|----------------------|
+| [iot_bridge](https://github.com/openhab/openhab/wiki/ROS-Robot-Operating-System) | Bridge between ROS Robot Operating System and OpenHAB |

docs/sources/configuration/jetty.md

@@ -0,0 +1,54 @@
+
+# Eclipse Jetty Configuration
+
+
+## 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)
+
+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;		
+		}
+	}
+
+### 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.
+
+Of course you have to reference the SSL certificate (ssl\_certificate) and the private key (ssl\_certificate\_key) that should be used to establish and encrpyt the connection.
+
+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/).
+
+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;		
+		}
+	}
+

docs/sources/development/bindings.md

@@ -0,0 +1,47 @@
+# Developing a new binding for openHAB 2
+
+This page describes the necessary steps in order to implement a new binding for openHAB 2.
+
+_Note:_ Please note that in contrast to openHAB 1.x, openHAB 2 is based on the [Eclipse SmartHome](http://eclipse.org/smarthome/) project. So the APIs and concepts have changed, so please read this documentation carefully, if you are coming from openHAB 1.x development.
+
+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
+
+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
+
+_Note:_ Here you can find a [screencast of the binding skeleton creation](http://youtu.be/30nhm0yIcvA).
+
+For the openHAB namespace: Once you have [set up your IDE](ide.md), you can go ahead and create a skeleton for your binding. For this, go into your git repository under `<your repository>/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.
+
+For the Eclipse SmartHome namespace: You need to have a private fork of the Eclipse SmartHome project (https://github.com/eclipse/smarthome). In the local checkout of this git repository, go to `<your eclipse smarthome repository>/extensions/binding` and call the script `create_esh_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.
+
+Now switch in Eclipse and choose `File->Import->General->Existing Projects into Workspace`, enter the folder of the newly created skeleton as the root directory and press "Finish".
+
+This should give you an easy starting point for your developments. To learn about the internal structure and the concepts of a binding, please see the [Eclipse tutorial on binding development](https://www.eclipse.org/smarthome/documentation/development/bindings/how-to.html).
+
+## Setup and Run the Binding
+
+To setup the binding you need to configure at least one *Thing* and link an *Item* to it. Inside the `openhabhome/conf/things` folder of the distribution project you can define and configure *Things* in file with a `*.things` extensions. The following file defines a thing for the Yahoo Weather binding:
+
+```
+yahooweather:weather:berlin     [ location="638242" ]
+```
+
+In this example a *Thing* of the *ThingType* `yahooweather:weather` is defined with a configuration for the location.
+
+Next you need to create *Items* and link them to the *Channel* of your binding. Here is the example of the Yahoo Weather binding:
+
+```
+Number Berlin_Temperature       "Temperature in Berlin [%.1f °C]"   { channel="yahooweather:weather:berlin:temperature" }
+Number Berlin_Humidity          "Humidity in Berlin [%d %%]"        { channel="yahooweather:weather:berlin:humidity" }
+```
+
+The syntax for a channel link is `{ channel = "<binding-id>:<thing-type-id>:<thing-id>:<channel-id>" }`.
+
+If you start the openHAB runtime including the binding now (make sure that your binding is checked in the launch configuration dialog!), the code inside your `ThingHandler` implementation is executed.

docs/sources/development/evolution.md

@@ -0,0 +1,14 @@
+# Technical Difference to openHAB 1
+
+There are a few changes in openHAB 2 that you should be aware of, if you are coming from openHAB 1:
+
+ - the Classic UI URL has changed from `/openhab.app` to `/classicui/app`, so you can access your sitemaps at `http://<server>:8080/classicui/app?sitemap=<yoursitemap>`
+ - a new default sitemap provider is in place, which provides a dynamic sitemap with the name `_default`, which lists all group items that are not contained within any other group.
+ - the `configuration` folder has been renamed to `conf`
+ - instead of the global `configuration/openhab.cfg` file, there is now an individual file per add-on in `conf/services`
+ - The OSGi console commands are now available as "smarthome", not as "openhab" anymore.
+ - 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 webapps folder has been discontinued, but static resources can be placed in `conf/html`.
+ - It is possible to provide your own custom icons in the `conf/icons/classic` folder - no need to overwrite the icons that come with the runtime
+ - the rule syntax has slightly changed, you e.g. do not need import statements anymore for the most common classes (see the [Migration Guide](../migration.md) for details). At the same time, there is no openHAB Designer anymore, but the Eclipse SmartHome designer can be used.