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

Merge commit '769c2abd492e24bcee0e59ef87bd7dc1b1614ece' into HEAD

pull/1325/head
openHAB Build Server 2020-12-13 19:16:15 +00:00
parent 670544f71d 769c2abd49
commit c84ad34cb3
5 changed files with 3 additions and 245 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
.vuepress/docs-sidebar.js
View File

@ -31,7 +31,7 @@ module.exports = [
'installation/armbian',
'installation/docker',
'installation/synology',
'installation/qnap',
// 'installation/qnap', // Remove until we get feedback about the current package state
['installation/security', 'Security']
]
},
@ -73,9 +73,7 @@ module.exports = [
title: 'Interfaces and Ecosystem',
collapsable: false,
children: [
'configuration/packages',
'configuration/editors',
'configuration/homebuilder',
['configuration/ui/habot/', 'HABot'],
'configuration/habpanel',
['configuration/ui/basic/', 'Basic UI'],
@ -86,7 +84,7 @@ module.exports = [
['ecosystem/alexa/', 'Amazon Alexa'],
['ecosystem/google-assistant/', 'Google Assistant'], // from v2.3 onwards
['../addons/integrations/homekit/', 'Apple HomeKit'],
['ecosystem/ifttt/', 'IFTTT'],
// ['ecosystem/ifttt/', 'IFTTT'], // Temporary remove until service gets reactivated
['ecosystem/mycroft/', 'Mycroft.AI'],
]
},
@ -129,7 +127,6 @@ module.exports = [
'developer/tests',
'developer/contributing',
'developer/governance',
'developer/legacy/compatibilitylayer',
{
title: 'Javadoc',
path: 'https://next.openhab.org/javadoc/latest/'

116
configuration/homebuilder.md
View File

@ -1,116 +0,0 @@
---
layout: documentation
title: Home Builder
source: https://github.com/openhab/openhab-core/blob/master/bundles/org.openhab.ui.homebuilder/USAGE.md
---
{% include base.html %}
<!-- Attention authors: Do not edit directly. Please add your changes to the appropriate source repository -->
# Home Builder
Boilerplate for the [Items](https://www.openhab.org/docs/configuration/items.html), [sitemap](https://www.openhab.org/docs/configuration/sitemaps.html) files and [HABPanel](https://www.openhab.org/docs/configuration/habpanel.html) dashboard.
## Features
- Classifies the objects within each room and creates groups for them
- Optionally adds icons from [Classic Icon Set](https://www.openhab.org/docs/configuration/iconsets/classic/) to the items
- Optionally adds Tags to the items - convenient for [HomeKit](https://www.openhab.org/addons/integrations/homekit/)/[Hue Emulation](https://www.openhab.org/addons/integrations/hueemulation/#device-tagging) add-ons users
- Automatically aligns the items vertically
- Generates a [Sitemap](https://www.openhab.org/docs/configuration/sitemaps.html) file
- Generates a set of HABPanel Dashboards corresponding with the Items
## Usage
### Localization
Home Builder recognizes the locale by itself by simply checking your existing language configuration through openHAB's REST API.
All the Item's labels generated with Home Builder will be translated to the language of your choice.
### Home Name
Provide your Home Name. It'll be a label for the `Home` Item, as well as the name of your Sitemap.
The `Home` item is the root item of your entire home structure - it contains all the floors as well as groups of Objects.
### Floors
After that you can select the number of stories (floors) comprising the building.
Each floor will have its own `Group` Item - Ground Floor will be called `GF`, First Floor `FF` and so on.
If there's only one floor, no additional `Group` Items shall be created.
### Rooms
Choose the rooms by simply selecting them on the list.
They contain the icons that you can adjust later.
If there's a custom room you'd like to add (e.g. a Piano room), provide its **label** to the field and hit Enter.
It will be added to the list.
The custom Item's **name** will be generated - e.g. for the "Piano Room" label the name would be `PianoRoom`
Note that the room doesn't appear on the Objects list right away - it's a known defect.
In order to add Objects to your custom room, simply remove the room from the list and re-add it again.
### Objects
Objects are the devices or sensors that physically exist in the room.
They are represented in Home Builder as singular Items (e.g. Light, Window, Motion Sensor, Temperature etc.)
Each Object is added to the Items list with its corresponding type, label, icon and list of Groups.
E.g. `Light` Object in the Bedroom will appear as:
```java
Switch Bedroom_Light "Light" <light> (Bedroom, gLight) {channel=""}
```
Note that the Objects have the `{channel=""}` prefilled for convenience.
You can turn it off with "Append channel to the non-Group items" option.
#### Custom Objects
You can use the existing Objects from the list, or create custom ones.
Simply typing the custom Object's label in the field will create it.
E.g. typing `Lamp` will result in:
```java
Switch Bedroom_Lamp "Lamp" <none> (Bedroom, gLamp) {channel=""}
```
Note that the default type for your custom Item is `Switch`.
You can, however, change it by typing `{type}:{label}`, e.g. `Number:Pressure` so it appears as:
```java
Number Bedroom_Pressure "Pressure" <none> (Bedroom, gPressure) {channel=""}
```
#### Grouping Objects
All Objects of the same kind are being grouped within Home Builder.
If you add a `Light` Object in bedroom, you'll see that there's an additional Item on the bottom:
```java
Group:Switch:OR(ON, OFF) gLight "Light" <light> (Home)
```
It doesn't matter if there's just one Object or dozens - they will be grouped within this `Group` Item.
## Items
You can choose to generate textual `*.items` file content or construct a request directly to the REST API that'll create the items for you.
## Sitemap
You can generate a simple sitemap with Home Builder too.
Sitemap name will be generated from "Home Setup Name" parameter that you've provided before.
Don't forget to save your sitemap with the correct file name.
Sitemaps generated with Home Builder contain a `Frame` for each floor.
Each one of those Frames contain corresponding rooms.
Last Frame inside the Sitemap is a list of Object's groups.
## HABPanel Dashboard
Home Builder will help you with creating your set of dashboards for [HABPanel](https://www.openhab.org/docs/configuration/habpanel.html) too.
It creates a separate dashboard for each group of Objects.
All you need to do is to copy the generated JSON structure and paste it in HABPanel settings page.
The page is located in the following URL: `http://{youropenHAB:8080}/habpanel/index.html#/settings/localconfig`
Note that it'll override the existing Panel configuration!

81
configuration/packages.md
View File

@ -1,81 +0,0 @@
---
layout: documentation
title: Initial Setup - Package Selection
---
{% include base.html %}
# Initial Setup Package Selection
When starting openHAB for the very first time, you are asked to select an initial package to start with.
There are four packages to choose from, which will be explained here in detail.
*Note*: If you are doing a headless installation, you can also choose the package by setting the `package` parameter in `$OPENHAB_CONF/services/addons.cfg`.
If you skipped the package installation, the system stays in a minimal setup without any add-ons which also means without any UIs. In such a case, you must configure the add-ons to install in `addons.cfg`.
## Standard Package (Recommended Setup)
![standard](images/package_standard.jpg){:style="float: right;margin-left: 20px;margin-top: 7px;margin-bottom: 20px"}
This is the recommended package for the normal user. It contains the most common UIs and leaves the rest to the user to decide what else he needs.
This package thus installs:
- [Home Builder](homebuilder.html){:target="_blank"} as a getting-started generator for your home
- [Paper UI](../addons/uis/paper/readme.html){:target="_blank"} for system administration, including item access
- [Basic UI](../addons/uis/basic/readme.html){:target="_blank"} as the new modern web UI for mobile devices
- [HABPanel](../addons/uis/habpanel/readme.html){:target="_blank"} as a dashboard UI for (e.g. wall-mounted) tablets
Additional add-ons can be installed through Paper UI or directly by defining them in `addons.cfg`.
## Expert Package (Best for 1.x Users)
![expert](images/package_expert.jpg){:style="float: right;margin-left: 20px;margin-top: 7px;margin-bottom: 20px"}
All users coming from openHAB 1.x should choose this package. It contains everything that was part of the core 1.x runtime, plus the tools that are specifically meant for power users.
This package thus installs:
- [Paper UI](../addons/uis/paper/readme.html){:target="_blank"} for system administration, including item access
- [Classic UI](../addons/uis/classic/readme.html){:target="_blank"} as the well-known web UI from openHAB 1.x
- [Basic UI](../addons/uis/basic/readme.html){:target="_blank"} as the new modern web UI for mobile devices
- [HABPanel](../addons/uis/habpanel/readme.html){:target="_blank"} as a dashboard UI for (e.g. wall-mounted) tablets
- [HABmin](../addons/uis/habmin/readme.html){:target="_blank"} as a powerful administration console, specifically suited for Z-Wave setups
- Interactive REST API that easily allows exploring the REST features through a documented UI
- all available transformations as they used to be part of the core 1.x runtime
## Simple Package (Purely UI)
![simple](images/package_simple.jpg){:style="float: right;margin-left: 20px;margin-top: 7px;margin-bottom: 20px"}
This package contains only components that allow a fully UI-driven setup and configuration process.
These are:
- [Paper UI](../addons/uis/paper/readme.html){:target="_blank"} for system administration, configured with "simple linking", i.e. no items are exposed to the user
- the [new rule engine](rules-ng.html){:target="_blank"} to set up automation rules without scripting
- [HABPanel](../addons/uis/habpanel/readme.html){:target="_blank"} as a dashboard UI for daily use
- only "native" openHAB 2 bindings are available, 1.x add-ons are excluded
**WARNING**: Note that the UI-driven configuration features are new and still under development, so many features will be enhanced in upcoming versions.
Specifically the rule engine is in an early stage and has several functional limitations.
Most features of openHAB still require textual configuration (e.g. the sitemaps and complex rules).
This package therefore should only be used for very simple setups or as a demonstration of what there is to come.
## Demo Package (Sample Setup)
![demo](images/package_demo.jpg){:style="float: right;margin-left: 20px;margin-top: 7px;margin-bottom: 20px"}
This package is suitable for demo purposes and for quickly checking out openHAB. It not only installs a few common bindings, but also defines sample textual configuration files, which are also used on the public [openHAB Demo Server](https://demo.openhab.org/){:target="_blank"}.
This includes:
- [Paper UI](../addons/uis/paper/readme.html){:target="_blank"} for system administration, configured in "simple" mode, such that newly added Things directly become available on the control UIs
- [Basic UI](../addons/uis/basic/readme.html){:target="_blank"} as the new modern web UI for mobile devices
- [HABPanel](../addons/uis/habpanel/readme.html){:target="_blank"} as a dashboard UI for tablets
- Bindings for Yahoo Weather, Belkin WeMo, Philips Hue, Sonos, IPP, Astro, AVM!Fritz and NTP
- RRD4j persistence service for storing time-series locally
- MAP transformation service as this is heavily used by the sample files
- Sample configurations files `demo.items`, `demo.things`, `demo.sitemap`, `demo.rules`, `demo.script`, `rrd4j.persist`, `de.map` and `en.map` for use with the MAP transformation

41
developers/legacy/compatibilitylayer.md
View File

@ -1,41 +0,0 @@
---
layout: developersguide
title: Compatibility Layer
---
{% include base.html %}
# Compatibility Layer for openHAB 1.x Add-ons
openHAB 2 introduced completely new APIs for add-ons, which use the namespace `org.eclipse.smarthome` - as a result, none of the existing 1.x add-ons would work on openHAB 2.
To still make it possible to use 1.x add-ons, there is a special bundle in openHAB 2, which serves as a compatibility layer. It effectively exposes and consumes all relevant classes and services from the `org.openhab` namespace and internally delegates or proxies them to the corresponding `org.eclipse.smarthome` classes and services.
Currently, the compatibility layer focuses on the official APIs. 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.
Testing 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
- 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_CONF/services/openhab.cfg`.
## How to solve problems with add-ons
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 the [openHAB 2 IDE](../#setup-the-development-environment).
- 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.
- 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 `<youraddon>.cfg` in `features/openhab-addons-external/src/main/resources/conf` with the same content as what is within `openhab.cfg`, but without the `<yourbinding>:` 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.
1. Note that with defining a Karaf feature, bindings are available for installation through the Paper UI in the "Extensions" menu, but they are not listed under "Configuration->Bindings" (although it is fully operational after installation). In order to have bindings listed there as well, you need to add some meta-information to the binding bundle. This information should be put into `ESH-INF/binding/binding.xml` and its content is [described here](/docs/developer/bindings/binding-xml.html#xml-structure-for-binding-definitions). Do not forget to add `ESH-INF` to your `build.properties`, so that it is packaged in the bundle. See a [real life example of such meta-data here](https://github.com/openhab/openhab/blob/master/bundles/binding/org.openhab.binding.nest/ESH-INF/binding/binding.xml) - note the `service-id` element in the XML, which needs to point to the service id of your binding, which is by default `org.openhab.<bindingId>` for all 1.x bindings.

3
installation/windows.md
View File

@ -46,8 +46,7 @@ To install it, follow these simple steps:
![Karaf_Windows](images/Karaf_Windows.png)
4. Point your browser to `http://localhost:8080`.
You should be looking at the openHAB [package selection page]({{base}}/configuration/packages.html).
When you've selected an appropriate package, this page will contain the UI selection screen, see [here]({{base}}/tutorial/1sttimesetup.html) for example.
You should now follow the first installation procedure.
### File Locations