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

Merge 2.5.x into main (#1266) 

* Update README (2.5.x) (#1153)

Change branch name.

Signed-off-by: Yannick Schaus <github@schaus.net>

* Update items.md (#1156)

* Added var and VA units to UoM (#1146)

VA (Volt-Ampere - apparent power) and var (Volt-Ampere reactive) are used to measure power and energy consumption in AC circuits.


Signed-off-by: Nagy Attila Gabor <mrbig@sneaker.hu>

* Fix filepath to keystore (#1148)

Default openHAB userdata environment variable should be `$OPENHAB_USERDATA`, not `$USER_DATA` shouldn't it? At least, this is the default on my fresh openHABian and also the most popular variant to find in the docs.

* Slight language corrections (#1150)

I think it reads better this way

Signed-off-by: Richard Davies <rwdrich@gmail.com>

* additional example for non default persistence service (#1152)

For me it was confusing how to pass on the serviceId into methods that already had an argument. An extra example is always good.

Signed-off-by: jaco <jaco.waes@gmail.com>

* Adding 12 new logos for OH Add-Ons page on website (#1158)

Signed-off-by: bracklanna bracklanna@users.noreply.github.com

* Added missing preset variables (#1104)

* Added missing preset variables

Signed-off-by: Scott Rushworth <openhab@5iver.com>

* Cleaned up blank lines, fixed table, and added file name for SimpleRule

Signed-off-by: Scott Rushworth <openhab@5iver.com>

* Fix broken link (#1165)

* Added Hotlink from "label" section to "state presentation" (#1167)

* Added note about broken action (#1164)

* Added note about broken action

See https://github.com/openhab/openhab-core/issues/1374

Signed-off-by: Christoph Weitkamp <github@christophweitkamp.de>

* Incorporated changes from review

Signed-off-by: Christoph Weitkamp <github@christophweitkamp.de>

* Incorporated changes from review

Signed-off-by: Christoph Weitkamp <github@christophweitkamp.de>

* Update index.md (#1170)

Link appears to be wrong and does not work when I click on it in Edge. Loads the same page again instead of loading the correct new page from the hyperlink.

https://www.openhab.org/docs/developer/guidelines.html

* Added Airthings logo (#1171)

* typo in exambp (#1172)

`Temperature.averageSince(now.minusMinutes(5),"influxdb")`

* file.encoding=UTF-8 (#1173)

* Update demo URL and add demo.rules URL (#1174)

Based on: https://community.openhab.org/t/demo-setup-missing/94850
Old Link is broken leading to 404.
The link to the demo.rules on github is an extra :)

* Replace outdated zulu.org link. (#1177)

* Replace outdated zulu.org link.

As of 3/23/2020 zulu.org has an SSL cert that expired on 9/28/2019. Changed link to azul.com/downloads, since that appears to be the new official source.

Signed-off-by: Billy Stevens <contact@wasv.me>

* Changed all http links to https for installation/index.md.

All changed links working, tested on 3/24/2020.

Signed-off-by: Billy Stevens <contact@wasv.me>

* Minor language tweak (#1178)

* Ending an active scan/stopScan (#1179)

Signed-off-by: Mark Theiding <mark.theiding@gmail.com>

* Add files via upload (#1184)

* Update persistence.md (#1185)

Clarify return objects for max/min rules extensions.

Signed-off-by: Ross Kennedy rossko@culzean.clara.co.uk

* Update things.md (#1186)

Amended example code to include using label and location when defining a Thing with a bridge that is defined elsewhere.

* Correct typos (#1190)

* Correct usage of its/it's

"It's" is always a contraction of "it is" or "it has".  "Its" is a
possessive.  Correct a few places where they were used backwards.

Signed-off-by: Bjorn Helgaas <bjorn@helgaas.com>

* Correct "Z-Wave" spelling

Per https://www.z-wave.com/, the canonical spelling appears to be "Z-Wave".
Most places use "Z-Wave" already; change the remaining references to match.

Signed-off-by: Bjorn Helgaas <bjorn@helgaas.com>

* Correct typos and grammatical errors

Correct some typos and grammatical errors.

Signed-off-by: Bjorn Helgaas <bjorn@helgaas.com>

* Update sitemap.md section charts (#1191)

I observed that the unique first word in the labels of items charted in a group isn't causing an empty chart anymore. I'm on openHAB 2.5.1.

Signed-off-by: Juergen Baginski opus42@gmx.de

* Add image for insteon binding (#1196)

Signed-off-by: Rob Nielsen <rob.nielsen@yahoo.com>

* typo (#1198)

Signed-off-by: Mark Theiding <mark.theiding@gmail.com>

* Installation details (#1197)

Added more details around the installation and configuration process.
Fixed that engine no longer logs "Activated scripting support..."

Signed-off-by: Mark Theiding <mark.theiding@gmail.com>

* Update sitemaps.md (#1202)

Added full item definition for usage of visibility. See https://community.openhab.org/t/sitemap-visibility-basic-ui/97304/9

* Updated ecobee logo (https://brand.ecobee.com/) (#1203)

Signed-off-by: Rob Nielsen <rob.nielsen@yahoo.com>

* tutorial: Fix description of sitemap 'type' (#1204)

In the tutorial, the generic sitemap description says that ItemType has
to be the same as the type defined in default.items.
Looking at
https://www.openhab.org/docs/configuration/items.html#type and
https://www.openhab.org/docs/configuration/sitemaps.html#element-types
this is incorrect as they take different values.
The example is even mislading as `Switch` is one of the only types which
is common between items and sitemaps. Might be better to describe
`Default` instead.

Signed-off-by: Christophe Fergeau <cfergeau@redhat.com>

* Added information about DateTime Group functions LATEST/EARLIEST (#1206)

Signed-off-by: Christoph Weitkamp <github@christophweitkamp.de>

* Add section for documentation contributions (#1205)

Hopefully this will lower the hurdle for people to submit documentation contributions. I know from myself that I didn't submit various documentation improvements, because I didn't know git and thought it would be a much more involved process. 
Ideally there would be a separate documentation section, but submitting this under the development contribution page for now (as per discussion with @Confectrician in https://github.com/openhab/openhab-docs/pull/1179#issuecomment-605642091).
Note that I am addressing the issue of DCO failures wrt specifying the full name that I ran into myself in https://github.com/openhab/openhab-docs/pull/1197#issuecomment-615597308. I found a good discussion of the issue at https://github.com/probot/dco/issues/43.

Signed-off-by: Mark Theiding <mark.theiding@gmail.com>

* fix typo (#1209)

* add description of Ephemeris localization support (#1210)

Add a new section to describe the localization support and how-to steps

Signed-off-by: Michael Roßner Schrott.Micha@web.de

* Line 115 broken link - should be: (#1217)

* Line 115 broken link - should be:

({{base}}/docs/configuration/sitemaps.html#element-types)

was:
({{base}}/configuration/configuration/sitemaps.html#element-types)

* Removed diplicated docs breadcrumb

Signed-off-by: Jerome Luckenbach <github@luckenba.ch>

Co-authored-by: Jerome Luckenbach <github@luckenba.ch>

* add missing space between words (#1212)

* Update configuration.md (#1215)

I'm a beginner myself. Though I liked this tutorial very much, it took me some time trying and erroring and finally reading forum posts to get behind this. I didn't even know there was something like a more modern ping. So maybe others are happy to learn this right from the beginning.

* Remove architecture from Docker tags (#1220)

Docker automatically detects the architecture and downloads the appropriate image (openhab/openhab-docker#213).
BuildKit will no longer generate new tags having the architecture (openhab/openhab-docker#293).

Signed-off-by: Wouter Born <github@maindrain.net>

* slight readability improvements (#1221)

* slight readability improvements

* Update introduction.md

* Update introduction.md

* minor wording update

* Update eclipse.md (#1225)

Clarifying that it's no longer possible to make changes in the Core Framework for 2.5.x.

Signed-off-by: Mark Theiding <mark.theiding@gmail.com>

* [fmiweather] logo for FMI Weather binding (#929)

Signed-off-by: Sami Salonen <ssalonen@gmail.com>

* Update eclipse.md (#1226)

Added additional structure around install, run, debug and update steps. Provided more pointers to interactions with Eclipse, Maven and Git.

Signed-off-by: Mark Theiding <mark.theiding@gmail.com>

* Update contributing.md (#1227)

Need to escape \< and \> in the sign off message format so users see them explicitly in the Contributing to the Documentation section. 

Signed-off-by: Mark Theiding <mark.theiding@gmail.com>

* Update contributing.md (#1228)

Small refinement on documentation change submission flow. 

Signed-off-by: Mark Theiding <mark.theiding@gmail.com>

* Add doc folder to the binding directory structure (#1230)

Signed-off-by: Fabian Wolter <github@fabian-wolter.de>

* Make Subheadings Use Proper Subheading Syntax (#1234)

This way they render out as proper markdown and don't look weird on the website

Signed-off-by: Stefan Zabka <zabkaste@informatik.hu-berlin.de>

* Remove unnecessary isCancelled() from code example (#1235)

Cancelling an already canceled task has no effect. IMHO this check is not necesssary and removal would simplify the code. I came to this because I saw this pattern in many bindings during reviewing.

Signed-off-by: Fabian Wolter <github@fabian-wolter.de>

* Update thing-xml.md (#1236)

Signed-off-by: Christoph Weitkamp <github@christophweitkamp.de>

* Fix broken ESH links (#1231)

Signed-off-by: Wouter Born <github@maindrain.net>

* Update logging.md (#1238)

Add information on how to find out the symbolic names of the bundles

* Remove Apache Commons from Default Libraries (#1229)

See openhab/openhab-addons#7722
Signed-off-by: Fabian Wolter <git@fabian-wolter.de>

* Update introduction.md (#1239)

* Update introduction.md

Signed-off-by: Markus Storm markus.storm@gmx.net

* Update introduction.md

* Revise Java recommendations (#1240)

* Revise Java recommendations

* Delete pine.md

Do not recommend PINE, it's not supported any longer by openHABian.

* Removed sidebar link in config

Signed-off-by: Jerome Luckenbach <github@luckenba.ch>

Co-authored-by: Jerome Luckenbach <github@luckenba.ch>

* Update security.md (#1241)

Been using FreeDNS for many years (ever since all these companies got rid of their free tiers) and never an issue!

* Fix DecimalType hex conversion example (#1243)

See: https://github.com/openhab/openhab-core/issues/1526

Signed-off-by: Wouter Born <github@maindrain.net>

* Fix typo (#1244)

Signed-off-by: Wouter Born <github@maindrain.net>

* Update persistence.md (#1246)

Fixes link to quartz docs page.

* Revision. (openhab#1187) (#1237)

* Revision. (openhab#1187)

- Update of screenshots, removal of old screenshots
- Chapters for better formatting
- Removal of ZWave chapter (one example of adding things should be enough IMHO)
- Adding items in simple mode and in "manual" mode

Signed-off-by: Sascha Billian <sascha.billian@googlemail.com>

* Use one line per sentence
Signed-off-by: Sascha Billian <sascha.billian@googlemail.com>

Co-authored-by: Jerome Luckenbach <github@luckenba.ch>

* Add notes for configuring Synology Diskstation (#1219)

* Add notes for configuring Synology Diskstation

I have a working set up for SSL enabled remote access on a Synology diskstation, taking advantage of the GUI as much as possible, to ensure automatic renewal of certs from Let's Encrypt, etc. It took me about 8 hours to suss it all out, but it could be achieved in about 30 mins if you knew exactly what to do... may not be widely useful, but since Synology is officially supported, I figured this might be a good addition.

There's also a minor error in the 'allow' masks - these should be 192.168.0.0/24 to allow access to anything in the 192.168.0.xxx range.

* Updated to use one line per sentence

Updated to use one line per sentence - sorry for the delay!

* Update security.md

* Updated for one line per sentence

Updated for one line per sentence

Signed-off-by: Andrew Mills mills@prettymachine.co.nz

* Bad subnet (#1245)

Nginx warns about low address bits of `192.168.0.1/24` because they are meaningless.
The correct subnet mask should be `192.168.0.0/24`

Signed-off-by: Olivier Béraud <olivierberaud@free.fr>

* Fixed broken images. (#1247)

* Fixed broken images.

Signed-off-by: Jerome Luckenbach <github@luckenba.ch>

* Fix image path

Signed-off-by: Jerome Luckenbach <github@luckenba.ch>

* [documentation] clarification of representation property (#1248)

* [documentation] clarification of representation property

Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>

* [documentation] typo

Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>

* [documentation] adopt suggestions of reviewers

Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>

* [documentation] commas

Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>

* [documentation] typo

Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>

* [documentation] addopted suggestions of @bobadair

Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>

* [documentation] typo

Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>

* [documentaion] example added back

Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>

* [documentaion] simplified text

Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>

* [documentation] typo

Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>

* [documentation] adopted reviewer comment

Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>

* Add Alexa mapping along side a channel mapping (#1249)

* Add Alexa mapping along side a channel mapping

It took me a while to find this https://community.openhab.org/t/tagging-devices-for-alexa-support/98155/3 on the Forum and its not clearly documented in the openHAB Amazon Alexa Smart Home Skill or here in Item Metadata.
I originally suggested this as an update to the openHAB Amazon Alexa Smart Home Skill documentaion, but it fits better here, then other integrations using metadata (e.g. HomeKit or Google Assistant) could refer to it as well.

* Update items.md

* Mention defaults for element type setpoint. (#1250)

Mention defaults for min, max and step value for element type setpoint.

Signed-off-by: Thomas Weiler <toweosp@gmail.com>

* Update index.md (#1251)

I thought 'workl' was probably intended to be 'work'.

* Items - Bedroom_Light written as Light_Bedroom (#1252)

Fix small error which might mislead some readers.

* Added example for time-weighted averages (#1253)

Signed-off-by: Christoph Weitkamp <github@christophweitkamp.de>

* Remove deprecated UIs, Eclipse Marketplace from sidebar

Signed-off-by: Yannick Schaus <github@schaus.net>

* Update branch name in README

Signed-off-by: Yannick Schaus <github@schaus.net>

Co-authored-by: Markus Storm <markus.storm@gmx.net>
Co-authored-by: Nagy Attila Gábor <mrbig@sneaker.hu>
Co-authored-by: Christoph Thiede <38782922+LinqLover@users.noreply.github.com>
Co-authored-by: Richard Davies <rwdrich@gmail.com>
Co-authored-by: jwaes <50528773+jwaes@users.noreply.github.com>
Co-authored-by: bracklanna <16140600+bracklanna@users.noreply.github.com>
Co-authored-by: Scott Rushworth <openhab@5iver.com>
Co-authored-by: cpmeister <mistercpp2000@gmail.com>
Co-authored-by: Ross Kennedy <rossko@culzean.clara.co.uk>
Co-authored-by: Christoph Weitkamp <github@christophweitkamp.de>
Co-authored-by: Skinah <32607303+Skinah@users.noreply.github.com>
Co-authored-by: pali <pauli.anttila@gmail.com>
Co-authored-by: ljsquare <laurens-jan@merkx-ewals.nl>
Co-authored-by: PatrikG <40170469+PatrikG8@users.noreply.github.com>
Co-authored-by: Elias H <E.Hackradt@web.de>
Co-authored-by: Billy Stevens <contact@wasv.me>
Co-authored-by: theiding <mark.theiding@gmail.com>
Co-authored-by: jadcx <60408305+jadcx@users.noreply.github.com>
Co-authored-by: Bjorn Helgaas <bjorn@helgaas.com>
Co-authored-by: Jürgen Baginski <opus42@gmx.de>
Co-authored-by: robnielsen <rob.nielsen@yahoo.com>
Co-authored-by: GumbyMan82 <40233411+GumbyMan82@users.noreply.github.com>
Co-authored-by: Christophe Fergeau <teuf@gnome.org>
Co-authored-by: Paulo "JCranky" Siqueira <paulo.siqueira@gmail.com>
Co-authored-by: Michael Rossner <Schrott.Micha@web.de>
Co-authored-by: BugSmurF <52825547+bugsmurf@users.noreply.github.com>
Co-authored-by: Jerome Luckenbach <github@luckenba.ch>
Co-authored-by: josefscript <64727123+josefscript@users.noreply.github.com>
Co-authored-by: Wouter Born <github@maindrain.net>
Co-authored-by: Sami Salonen <ssalonen@gmail.com>
Co-authored-by: Fabian Wolter <github@fabian-wolter.de>
Co-authored-by: Stefan Zabka <zabkaste@informatik.hu-berlin.de>
Co-authored-by: TRS-80 <25938297+TRSx80@users.noreply.github.com>
Co-authored-by: sihui <10405486+sihui62@users.noreply.github.com>
Co-authored-by: Andrew Mills <amil109@users.noreply.github.com>
Co-authored-by: Olivier Béraud <olivbd@users.noreply.github.com>
Co-authored-by: Andrew Fiddian-Green <software@whitebear.ch>
Co-authored-by: LeeC77 <LeeC77@users.noreply.github.com>
Co-authored-by: Thomas Weiler <18066810+toweosp@users.noreply.github.com>
Co-authored-by: garretcook <garretcook@gmail.com>
Co-authored-by: Michael Fielding <michael.fielding@gmail.com>
pull/1270/head
Yannick Schaus 2020-09-21 13:29:39 +02:00 committed by GitHub
parent 5348b22a2c
commit d72156a6c0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
93 changed files with 785 additions and 423 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.vuepress/docs-sidebar.js
View File

@ -28,7 +28,6 @@ module.exports = [
['installation/macos', 'macOS'],
'installation/openhabian',
'installation/rasppi',
'installation/pine',
'installation/armbian',
'installation/docker',
'installation/synology',
@ -77,15 +76,10 @@ module.exports = [
'configuration/packages',
'configuration/editors',
'configuration/homebuilder',
['configuration/paperui', 'Paper UI'],
['configuration/ui/habmin/', 'HABmin'],
['configuration/ui/habot/', 'HABot'],
'configuration/habpanel',
['configuration/ui/basic/', 'Basic UI'],
['configuration/ui/classic/', 'Classic UI'],
'configuration/rules-ng',
'configuration/eclipseiotmarket',
['configuration/restdocs', 'REST API'],
['apps/android', 'Android App'],
'apps/ios',
'apps/windows',

4
README.md
View File

@ -9,7 +9,7 @@ The result is available at [https://next.openhab.org/docs/](https://www.openhab.
## How it works
In this repo you can find and improve all *general* documentation contents.
In fact that is all you can see in the `2.5.x` branch.
In fact that is all you can see in the `main` branch.
There are also other *read-only* branches, which hold external content like the *add-ons* and *concepts* documentation.
We will read about them later.
@ -40,7 +40,7 @@ will help you to get it right.
We use them to bring together all relevant articles or to archive versioned content.
Mostly those branches will get updated automatically through our continuous integration builds.
You can read a bit more below about our external ressources and how we get them.
You can read a bit more below about our external resources and how we get them.
### Automatically Generated Parts

21
addons/actions.md
View File

@ -210,7 +210,7 @@ Action | Returns
`getNextBankHoliday` | name of the next bank holiday
`getNextBankHoliday(<file>)` | name of the next bank holiday defined in `<file>`
`getNextBankHoliday(<offset>)` | name of the next bank holiday after `<offset>` days from today
`getNextBankHoliday(<offset>, <file>)` | name of the next bank holiday after `<offset>` days from today defined in `<file>`
`getNextBankHoliday(<offset>, <file>)` | name of the next bank holiday after `<offset>` days from today defined in `<file>`. :warning: This action is broken in OH 2.5.x. Use `getNextBankHoliday(<datetime>, <file>)` instead by replacing `<datetime>` with `ZonedDateTime.now().plusDays(<offset>)`
`getNextBankHoliday(<datetime>)` | name of the next bank holiday after the day defined by the `ZonedDateTime` `<datetime>`
`getNextBankHoliday(<datetime>, <file>)` | name of the next bank holiday after the day defined by the `ZonedDateTime` `<datetime>` defined in `<file>`
`isBankHoliday` | `true` if today is a bank holiday (see below), `false` otherwise
@ -298,6 +298,25 @@ You can place these XML files anywhere on your file system that openHAB has perm
In the calls to the Actions, use the fully qualified path.
We recommend placing these custom files somewhere inside your `$OH_CONF` folder, such as `$OH_CONF/services`.
#### Localisation
Ephemeris supports translation of holidays into many languages. Localization support files can be found in the [GitHub repo](https://github.com/svendiedrichsen/jollyday/tree/master/src/main/resources/descriptions). Currently these language supports are available:
1. [Dutch](https://github.com/svendiedrichsen/jollyday/blob/master/src/main/resources/descriptions/holiday_descriptions_nl.properties)
1. [English](https://github.com/svendiedrichsen/jollyday/blob/master/src/main/resources/descriptions/holiday_descriptions_en.properties)
1. [French](https://github.com/svendiedrichsen/jollyday/blob/master/src/main/resources/descriptions/holiday_descriptions_fr.properties)
1. [German](https://github.com/svendiedrichsen/jollyday/blob/master/src/main/resources/descriptions/holiday_descriptions_de.properties)
1. [Portuguese](https://github.com/svendiedrichsen/jollyday/blob/master/src/main/resources/descriptions/holiday_descriptions_pt.properties)
1. [Swedish](https://github.com/svendiedrichsen/jollyday/blob/master/src/main/resources/descriptions/holiday_descriptions_sv.properties)
Feel free to extent this list by providing additional language support files.
To enable localization,
* copy the file for your language to your OH setup.
* again a folder in `$OH_CONF` folder, such as `$OH_CONF/services` is proposed.
* use function 'Ephemeris.getHolidayDescription' to convert the name according to your localization file.
## Installable Actions
The following actions are available as installable add-ons.

4
addons/index.md
View File

@ -23,7 +23,7 @@ These are described under *Installation of Add-ons* below
## Installation of Add-ons
Depending on the [package]({{base}}/configuration/packages.html) you have choosen during your first time setup, there are already some pre-installed add-ons.
Depending on the [package]({{base}}/configuration/packages.html) you have chosen during your first time setup, there are already some pre-installed add-ons.
Additional add-ons can be installed in the different ways, described below.
### Through Paper UI
@ -79,7 +79,7 @@ With this information we can now edit the *addons.cfg* file in the `$OPENHAB_CON
The path is depending on your installation.
You can find out the correct locations on the corresponding documentation pages, e.g. [Linux]({{base}}/installation/linux.html#file-locations) or [Windows]({{base}}/installation/windows.html#file-locations).
The file could look like this (depending on your choosen package and already installed add-ons):
The file could look like this (depending on your chosen package and already installed add-ons):
```text
package = standard

26
administration/logging.md
View File

@ -92,12 +92,38 @@ The levels build a hierarchy with **ERROR** logging critical messages only and *
**ALL** includes every log level from weight 100 to 600.
Setting the log level to **DEFAULT** will log to the level defined in the package.subpackage (in most cases a binding).
If the name of `package.subpackage` is not known, the name can be found out in the console:
```text
list -s
```
returns a list of all modules and the last column contains the information about the symbolic name of the bundle:
```text
openhab> list -s
START LEVEL 100 , List Threshold: 50
ID │ State │ Lvl │ Version │ Symbolic name
────┼────────┼─────┼─────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────
19 │ Active │ 80 │ 5.3.1.201602281253 │ com.eclipsesource.jaxrs.publisher
20 │ Active │ 80 │ 2.8.2.v20180104-1110 │ com.google.gson
21 │ Active │ 80 │ 18.0.0 │ com.google.guava
22 │ Active │ 80 │ 27.1.0.jre │ com.google.guava
23 │ Active │ 80 │ 1.0.1 │ com.google.guava.failureaccess
24 │ Active │ 80 │ 3.0.0.v201312141243 │ com.google.inject
```
The list can be also filtered with grep. To find out the Z-Wave binding the following command can be used
```Text
openhab> list -s | grep zwave
253 x Active x 80 x 2.5.5 x org.openhab.binding.zwave
```
Following example sets the logging for the Z-Wave binding to **DEBUG**
```text
log:set DEBUG org.openhab.binding.zwave
```
Note that the log levels set using the `log:set` commands are persistent and will be applied upon restart.
To modify the stored log levels, use the console or edit the [configuration file](#config-file).

6
concepts/audio.md
View File

@ -9,14 +9,14 @@ title: Audio & Voice
Audio and voice features are an important aspect of any smart home solution as it is a very natural way to interact with the user.
openHAB comes with a very modular architecture that enables all kinds of different use cases.
openHAB has a very modular architecture that enables many different use cases.
At its core, there is the notion of an *audio stream*.
Audio streams are provided by *audio sources* and consumed by *audio sinks*.
![](images/audio.png)
- *Audio Streams* are essentially a byte stream with a given *audio format*.
They do not need to be limited in size, i.e. it is also allowed to have continuous streams, e.g. the input from a microphone or from an Internet radio station.
- *Audio Streams* are essentially byte streams with a given *audio format*.
They do not need to be limited in size, i.e. it is allowed to have continuous streams, e.g. the input from a microphone or from an Internet radio station.
- *Audio Formats* define the container (e.g. WAV), encoding, bit rate, sample frequency and depth and the bit order (little or big endian).
- *Audio Sources* are services that are capable of producing audio streams.
They can support different formats and provide a stream in a requested format upon request.

13
concepts/discovery.md
View File

@ -9,11 +9,11 @@ title: Thing Discovery
Many devices, technologies and systems can be automatically discovered on the network or browsed through some API. It therefore makes a lot of sense to use these features for a smart home solution.
In openHAB bindings therefore implement _Discovery Services_ for Things, which provide _Discovery Results_. All _Discovery Results_ are regarded as suggestions to the user and are put into the _inbox_.
openHAB bindings therefore implement _Discovery Services_ for Things, which provide _Discovery Results_. All _Discovery Results_ are regarded as suggestions to the user and are put into the _inbox_.
### Background Discovery
A couple of discovery services support automatic discovery in the background, while for others a scan needs to be triggered manually.
Some discovery services support automatic discovery in the background, while for others a scan needs to be triggered manually.
Services that support background discovery usually have it enabled by default.
It is possible to override this setting and deactivate background discovery for individual services by setting `discovery.<serviceid>:background=false`, where `serviceid` is usually identical to a binding id, e.g. the LIFX background discovery can be disabled through `discovery.lifx:background=false`.
@ -27,13 +27,14 @@ Each discovery result also has a timestamp when it was added to or updated in th
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.
If an entry is ignored, it will be hidden in the inbox without creating a Thing for it.
openHAB offers a service to automatically ignore discovery results in the inbox, whenever a Thing is created manually, that represents the same Thing, as the respective discovery result would create.
This Thing would either have the same Thing UID or the value of its representation property is equal to the representation property's value in the discovery result.
This service is enabled by default but can be disabled by setting `org.eclipse.smarthome.inbox:autoIgnore=false`.
openHAB offers a service to automatically ignore duplicate discovery results in the inbox whenever, a) a Thing has been created manually, that represents the same Thing as the respective discovery result would create, or b) whenever a Thing has been discovered separately by two alternate discovery services.
Such duplicate Things are identified as either Things with the same Thing UID, or Things with an identical `representation property`.
For a manually created Thing, its representation property is either a `property` or a `configuration parameter` of the Thing.
This auto-ignore service is enabled by default but can be disabled by setting `org.eclipse.smarthome.inbox:autoIgnore=false`.
### Auto Approve
If the manual acceptance of discovery results by the user is not wished, it is possible to turn on the auto-approval feature of the inbox.
If the manual acceptance of discovery results by the user is not desired, it is possible to turn on the auto-approval feature of the inbox.
In this case, every new entry gets automatically approved immediately (unless it has been marked as ignored as a duplicate).
The auto approval can be enabled by the setting `org.eclipse.smarthome.inbox:autoApprove=true`; the default is false.

4
concepts/index.md
View File

@ -7,7 +7,7 @@ title: Concepts
# Concepts
When first thinking about your home automation system, it may be helpful to bear in mind that there are two ways of thinking about or viewing your system; the physical view and the functional view.
When first thinking about your home automation system, it may be helpful to bear in mind that there are two ways of thinking about or viewing your system: the physical view and the functional view.
The physical view will be familiar to you.
This view focuses on the devices in your system, the connections between these devices (e.g. wires, Z-Wave, WiFi hardware), and other physical aspects of the system.
@ -49,4 +49,4 @@ To illustrate these concepts, consider the example below of a two-channel actuat
The actuator is a Thing that might be installed in an electrical cabinet.
It has a physical address and it must be configured in order to be used (remember the physical view introduced at the beginning of this article).
In order for the user to control the two lights, he or she access the capability of the actuator Thing (turning on and off two separate lights) through two Channels, that are Linked to two switch Items presented to the user through a user interface.
In order for the user to control the two lights, he or she accesses the capability of the actuator Thing (turning on and off two separate lights) through two Channels, that are Linked to two switch Items presented to the user through a user interface.

29
concepts/items.md
View File

@ -49,25 +49,9 @@ Example for a Group Item as a simple collection of other Items:
Group Items can derive their own state from their member Items.
To derive a state the Group Item must be constructed using a base Item and a Group function.
When calculating the state, Group functions recursively traverse the Group's members and also take members of subgroups into account.
If a subgroup however defines a state on its own (having base Item & Group function set) traversal stops and the state of the subgroup member is taken.
If a subgroup however defines a state on its own (having base Item & Group function set) traversal stops and the state of the subgroup member is taken.
Available Group functions:
| Function | Parameters | Base Item | Description |
|--------------------|-------------------------------|---------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| EQUALITY | - | \<all\> | Sets the state of the members if all have equal state. Otherwise UNDEF is set. In the Item DSL `EQUALITY` is the default and may be omitted. |
| AND, OR, NAND, NOR | <activeState>, <passiveState> | \<all\> (must match active & passive state) | Sets the \<activeState\>, if the member state \<activeState\> evaluates to `true` under the boolean term. Otherwise the \<passiveState\> is set. |
| SUM, AVG, MIN, MAX | - | Number | Sets the state according to the arithmetic function over all member states. |
| COUNT | <regular expression> | Number | Sets the state to the number of members matching the given regular expression with their states. |
| LATEST, EARLIEST | - | DateTime | Sets the state to the latest/earliest date from all member states |
Examples for derived states on Group Items when declared in the Item DSL:
- `Group:Number:COUNT(".*")` counts all members of the Group matching the given regular expression, here any character or state (simply count all members).
- `Group:Number:AVG` calculates the average value over all member states which can be interpreted as `DecimalTypes`.
- `Group:Switch:OR(ON,OFF)` sets the Group state to `ON` if any of its members has the state `ON`, `OFF` if all are off.
- `Group:Switch:AND(ON,OFF)` sets the Group state to `ON` if all of its members have the state `ON`, `OFF` if any of the Group members has a different state than `ON`.
- `Group:DateTime:LATEST` sets the Group state to the latest date from all its members states.
For available Group functions and examples see [Configuration Guide](../configuration/items.html#group-type).
## State and Command Type Formatting
@ -99,12 +83,12 @@ Examples for derived states on Group Items when declared in the Item DSL:
### QuantityType
A numerical type which carries a unit in addition to its value.
The framework is capable of automatic conversion between units depending on the users locale settings.
The framework is capable of automatic conversion between units depending on the user's locale settings.
See the concept on [Units of Measurement](units-of-measurement.html) for more details.
### HSBType
HSB string values consist of three comma-separated values for hue (0-360°), saturation (0-100%), and value (0-100%) respectively, e.g. `240,100,100` for blue.
HSB string values consist of three comma-separated values for hue (0-360°), saturation (0-100%), and brightness (0-100%) respectively, e.g. `240,100,100` for "maximum" blue.
### PointType
@ -149,6 +133,11 @@ There can be metadata attached to an Item for as many namespaces as desired, lik
Switch MyFan "My Fan" { homekit="Fan.v2", alexa="Fan" [ type="oscillating", speedSteps=3 ] }
The metdata can be included with the channel linking, an Alexa metadata mapping is added after the channel linking separated with a comma in the example for a ZWave switch below.
```
Switch LightSwitch "Light Switch" {channel="zwave:device:22c99d1e:node3:switch_binary", alexa="PowerController.powerState"}
```
The metadata can be maintained via a dedicated REST endpoint and is included in the `EnrichedItemDTO` responses.
Extensions which can infer some metadata automatically need to implement and register a `MetadataProvider` service in order to make them available to the system.

10
concepts/things.md
View File

@ -41,12 +41,12 @@ The following table provides an overview of the different statuses:
| Status | Description |
|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| UNINITIALIZED | This is the initial status of a Thing, when it is added or the framework is being started. This status is also assigned, if the initializing process failed or the binding is not available. Commands which are sent to Channels will not be processed. |
| INITIALIZING | This status is assigned while the binding initializes the Thing. It depends on the binding how long the initializing process takes. Commands which are sent to Channels will not be processed. |
| UNINITIALIZED | This is the initial status of a Thing when it is added or the framework is being started. This status is also assigned if the initializing process failed or the binding is not available. Commands sent to Channels will not be processed. |
| INITIALIZING | This status is assigned while the binding initializes the Thing. It depends on the binding how long the initializing process takes. Commands sent to Channels will not be processed. |
| UNKNOWN | The handler is fully initialized but due to the nature of the represented device/service it cannot really tell yet whether the Thing is ONLINE or OFFLINE. Therefore the Thing potentially might be working correctly already and may or may not process commands. But the framework is allowed to send commands, because some radio-based devices may go ONLINE if a command is sent to them. The handler should take care to switch the Thing to ONLINE or OFFLINE as soon as possible. |
| ONLINE | The device/service represented by a Thing is assumed to be working correctly and can process commands. |
| OFFLINE | The device/service represented by a Thing is assumed to be not working correctly and may not process commands. But the framework is allowed to send commands, because some radio-based devices may go back to ONLINE if a command is sent to them. |
| REMOVING | The device/service represented by a Thing should be removed, but the binding did not confirm the deletion yet. Some bindings need to communicate with the device to unpair it from the system. Thing is probably not working and commands cannot be processed. |
| REMOVING | The device/service represented by a Thing should be removed, but the binding has not confirmed the deletion yet. Some bindings need to communicate with the device to unpair it from the system. Thing is probably not working and commands cannot be processed. |
| REMOVED | This status indicates that the device/service represented by a Thing was removed from the external system after the REMOVING was initiated by the framework. Usually this status is an intermediate status because the Thing gets removed from the database after this status was assigned. |
The statuses UNINITIALIZED, INITIALIZING and REMOVING are set by the framework, whereas the statuses UNKNOWN, ONLINE and OFFLINE are assigned from a binding.
@ -73,7 +73,7 @@ The following table lists the different status details for each status:
<table>
<tr valign="top"><td rowspan="7">UNINITIALIZED</td><td>NONE</td><td>No further status details available.</td></tr>
<tr valign="top"> <td>HANDLER_MISSING_ERROR</td><td>The handler cannot be initialized, because the responsible binding is not available or started.</td></tr>
<tr valign="top"> <td>HANDLER_MISSING_ERROR</td><td>The handler cannot be initialized because the responsible binding is not available or started.</td></tr>
<tr valign="top"> <td>HANDLER_REGISTERING_ERROR</td><td>The handler failed in the service registration phase.</td></tr>
<tr valign="top"> <td>HANDLER_CONFIGURATION_PENDING</td><td>The handler is registered but cannot be initialized because of missing configuration parameters.</td></tr>
<tr valign="top"> <td>HANDLER_INITIALIZING_ERROR</td><td>The handler failed in the initialization phase.</td></tr>
@ -98,7 +98,7 @@ The following table lists the different status details for each status:
To provide additional information about the current status a description is used.
The status description is to be specified by the binding.
This description can be used for debugging purposes and should not be presented to the user, as it might contain unreadable technical information (e.g. an HTTP status code, or any other protocol specific information, which helps to identify the current problem).
This description can be used for debugging purposes and should not be presented to the user, as it might contain unreadable technical information (e.g. an HTTP status code, or any other protocol-specific information, which helps to identify the current problem).
### Thing Status API

16
concepts/units-of-measurement.md
View File

@ -17,8 +17,8 @@ This way the framework and/or the user is able to convert the quantified value t
A weather binding which reads temperature values in °C would use the `QuantityType` to indicate the unit as °C.
The framework is then able to convert the values to either °F or Kelvin according to the configuration of the system.
The default conversion the framework will use is locale based:
Depended on the configured locale the framework tries to convert a `QuantityType` to the default unit of the matching measurement system.
The default conversion the framework will use is locale-based:
The framework tries to convert a `QuantityType` to the default unit of the configured locale.
This is the imperial system for the United States (locale US) and Liberia (language tag "en-LR").
The metric system with SI units is used for the rest of the world.
This conversion will convert the given `QuantityType` into a default unit for the specific dimension of the type.
@ -39,19 +39,19 @@ This is:
In addition to the automated conversion the `NumberItem` linked to a Channel delivering `QuantityTypes` can be configured to always have state updates converted to a specific unit.
The unit given in the state description is parsed and then used for conversion (if necessary).
The framework assumes that the unit to parse is always the last token in the state description.
If the parsing failed the locale based default conversion takes place.
If the parsing failed the locale-based default conversion takes place.
Number:Temperature temperature "Outside [%.2f °F]" { channel="...:current#temperature" }
In the example the `NumberItem` is specified to bind to Channels which offer values from the dimension `Temperature`.
Without the dimension information the `NumberItem` only will receive updates of type `DecimalType` without a unit and any conversion.
The state description defines two decimal places for the value and the fix unit °F.
In case the state description should display the unit the binding delivers or the framework calculates through locale based conversion the pattern will look like this:
In case the state description should display the unit the binding delivers or the framework calculates through locale-based conversion the pattern will look like this:
"Outside [%.2f %unit%]"
The special placeholder `%unit%` will then be replaced by the actual unit symbol.
In addition the placeholder `%unit%` can be placed anywhere in the state description.
The placeholder `%unit%` can be placed anywhere in the state description.
#### Defining ChannelTypes
@ -99,7 +99,7 @@ SI:
| Type | Unit | Symbol |
|------------------------|----------------------------------|--------|
| Acceleration | Metre per square Second | m/s² |
| Acceleration | Metre per Second squared | m/s² |
| Acceleration | Standard Gravity | ɡₙ |
| AmountOfSubstance | Mole | mol |
| AmountOfSubstance | Deutscher Härtegrad | °dH |
@ -145,6 +145,8 @@ SI:
| Energy | Watt Hour | Wh |
| Energy | Kilowatt Hour | kWh |
| Energy | Megawatt Hour | MWh |
| Energy | Volt-Ampere Hour | VAh |
| Energy | Volt-Ampere Reactive Hour | varh |
| Energy | Kilovar Hour | kvarh |
| Force | Newton | N |
| Frequency | Hertz | Hz |
@ -160,6 +162,8 @@ SI:
| Mass | Kilogram | kg |
| Mass | Gram | g |
| Power | Watt | W |
| Power | Volt-Ampere | VA |
| Power | Volt-Ampere Reactive | var |
| Power | Kilovar | kvar |
| Power | Decibel-Milliwatts | dBm |
| Pressure | Pascal | Pa |

10
configuration/addons.md
View File

@ -6,8 +6,8 @@ layout: documentation
# Installation of Add-ons
Depending on the [package](/docs/configuration/packages.html) you have choosen during your first time setup, there are already some pre-installed add-ons.
Additional add-ons can be installed in the different ways, described below.
Depending on the [package](/docs/configuration/packages.html) you have chosen during your first time setup, there are already some pre-installed add-ons.
Additional add-ons can be installed in different ways, described below.
## Through Paper UI
@ -59,10 +59,10 @@ The trailing `1` has to be appended for `binding`- and `misc`-addons.
It is *not needed* for other addon types like `persistence`.
With this information we can now edit the *addons.cfg* file in the `$OPENHAB_CONF/services` folder on the machine you are running openHAB on.
The path is depending on your installation.
The path depends on your installation.
You can find out the correct locations on the corresponding documentation pages, e.g. [Linux](/docs/installation/linux.html#file-locations) or [Windows](/docs/installation/windows.html#file-locations).
The file could look like this (depending on your choosen package and already installed add-ons):
The file could look like this (depending on your chosen package and already installed add-ons):
```text
package = standard
@ -93,5 +93,5 @@ For this installation option you need a bundles `.jar` file.
One way of retrieving those files is mentioned above in the openHAB console part.
Place the `.jar` file in the `addons` folder on the machine you are running openHAB on.
As described already for the addons.cfg option, the path is depending on your installation.
As described already for the addons.cfg option, the path depends on your installation.
Place the .jar file in the folder Additional add-on files as described in File Locations ([Linux](/docs/installation/linux.html#file-locations), [Windows](/docs/installation/windows.html#file-locations) or [macOS](/docs/installation/macos.html#file-locations)).

60
configuration/items.md
View File

@ -119,7 +119,7 @@ More details about all of the available Item types and their commands are availa
[Item Types Overview]({{base}}/concepts/items.html)
To learn about the technical internals of the individual Item types, please refer to:
[Javadoc on Generic Item and its subclasses](https://eclipse.org/smarthome/documentation/javadoc/org/eclipse/smarthome/core/items/GenericItem.html)
[Javadoc on Generic Item and its subclasses](https://www.openhab.org/javadoc/v2.5/org/openhab/core/items/genericitem)
<!-- TODO: Random content. Doesn't make sense here. Might be changed to be a more general example for diverse Items
@ -207,7 +207,7 @@ Label text is used to describe an Item in a human-readable way.
Graphical UIs will display the label text when the Item is included, e.g. in [Basic UI]({{base}}/configuration/ui/basic.html) in a [Sitemap]({{base}}/configuration/sitemaps.html) definition.
Some I/O services (e.g. the Amazon Alexa skill) also use the label to match an external voice command to an Item.
In textual configurations the label, in quotation marks, appears next to the optional state presentation field in square brackets (see below).
In textual configurations the label, in quotation marks, appears next to the optional [state presentation](#state-presentation) field in square brackets (see below).
The label for the Item in the following example is "Temperature" and the optional state representation is set to be displayed, e.g. as "23.9 °C":
```java
@ -270,7 +270,7 @@ The state presentation for the Item in the following example is "`%.1f °C`":
Number Livingroom_Temperature "Temperature [%.1f °C]"
```
If no state presentation and no square brackets are given, the Item will not provide a textual presentation of it's internal state (i.e. in UIs no state is shown).
If no state presentation and no square brackets are given, the Item will not provide a textual presentation of its internal state (i.e. in UIs no state is shown).
This is often meaningful when an Item is presented by a non-textual UI elements like a switch or a diagram.
Formatting of the presentation is done applying [Java formatter class syntax](http://docs.oracle.com/javase/7/docs/api/java/util/Formatter.html#syntax).
@ -457,7 +457,7 @@ Because of the hierarchical structure of your group items, the rule will be clea
Additionally, the rule will not need to be modified when a new Item is added to the `Temperatures` group.
{: #group-type}
#### Group Type and State
### Derive Group State from Member Items
As you are now aware, an Item can have a state (e.g. "ON", "OFF").
A Group Item can also have a state.
@ -474,17 +474,13 @@ Group[:itemtype[:function]] groupname ["labeltext"] [<iconname>] [(group1, group
Group state aggregation functions can be any of the following:
| Function | Description |
|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `EQUALITY` | Default if no function is specified. If ALL members have state X the group state will be X, otherwise the group state will be `UNDEF`. |
| `AND(value1,value2)` | [Boolean](https://en.wikipedia.org/wiki/Boolean_algebra) AND operation. If all item states are 'value1', 'value1' is returned, otherwise 'value2' is returned. |
| `OR(value1,value2)` | [Boolean](https://en.wikipedia.org/wiki/Boolean_algebra) OR operation. If at least one item state is of 'value1', 'value1' is returned, otherwise 'value2' is returned. |
| `NAND(value1,value2)` | [Boolean](https://en.wikipedia.org/wiki/Boolean_algebra) NAND (not AND) operation. Returns the opposite of the AND operation. |
| `NOR(value1,value2)` | [Boolean](https://en.wikipedia.org/wiki/Boolean_algebra) NOR (not OR) operation. Returns the opposite of the OR operation. |
| `AVG` | Calculates the numeric average over all Item states of decimal type. |
| `MAX` | Calculates the maximum value of all Item states of decimal type. |
| `MIN` | Calculates the minimum value of all Item states of decimal type. |
| `SUM` | Calculates the sum of all Item states in the Group. |
| Function | Parameters | Base Item | Description |
|----------------------------|-------------------------------|---------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `EQUALITY` | - | \<all\> | Default if no function is specified. Sets the state of the members if all have equal state. Otherwise `UNDEF` is set. In the Item DSL `EQUALITY` is the default and may be omitted. |
| `AND`, `OR`, `NAND`, `NOR` | <activeState>, <passiveState> | \<all\> (must match active & passive state) | [Boolean](https://en.wikipedia.org/wiki/Boolean_algebra) operation. Sets the \<activeState\>, if the members state \<activeState\> evaluates to `true` under the boolean term. Otherwise the \<passiveState\> is set. |
| `SUM`, `AVG`, `MIN`, `MAX` | - | Number | [Arithmetic](https://en.wikipedia.org/wiki/Arithmetic) operation. Sets the state according to the arithmetic function over all members states. |
| `COUNT` | <regular expression> | Number | Sets the state to the number of members matching the given regular expression with their states. |
| `LATEST`, `EARLIEST` | - | DateTime | Sets the state to the latest/earliest date from all members states |
Boolean group state functions additionally return a number representing the count of member Items of value 'value1' (see example below).
@ -495,26 +491,38 @@ Incompatible Item types within a Group may result in the invalid aggregation res
**Examples:**
Examples for derived states on Group Items when declared in the Item DSL:
```java
Group:Number Lights "Active Lights [%d]" // e.g. "2"
Group:Switch:OR(ON,OFF) Lights "Active Lights [%d]" // e.g. ON and "2"
Group:Number:AVG Temperatures "All Room Temperatures [%.1f °C]" // e.g. "21.3 °C"
Group:Number Lights "Active Lights [%d]" // e.g. "2"
Group:Switch:OR(ON,OFF) Lights "Active Lights [%d]" // e.g. ON and "2"
Group:Switch:AND(ON,OFF) Lights "Active Lights [%d]" // e.g. ON and "2"
Group:Number:AVG Temperatures "All Room Temperatures [%.1f °C]" // e.g. "21.3 °C"
Group:DateTime:EARLIEST LatestUpdate "Latest Update [%1$tY.%1$tm.%1$tY %1$tH:%1$tM:%1$tS]"
Group:DateTime:LATEST LastSeen "Last Seen [%1$tY.%1$tm.%1$tY %1$tH:%1$tM:%1$tS]"
Group:String:COUNT("OFFLINE") OfflineDevices "Offline Devices [%d]" // e.g. "2"
```
The first two examples above compute the number of active lights and store them as group state.
However, the second group is of type switch and has an aggregation function of OR.
The first three examples above compute the number of active lights and store them as group state.
However, the second group is of type switch and has an aggregation function of `OR`.
This means that the state of the group will be `ON` as soon as any of the member lights are turned on.
The third uses `AND` and sets the Group state to `ON` if all of its members have the state `ON`, `OFF` if any of the Group members has a different state than `ON`.
Groups do not only aggregate information from individual member Items, they can also accept commands.
Sending a command to a Group causes the command to be sent to all Group members.
An example of this is shown by the second group above; sending a single `ON` or `OFF` command to that group turns all lights in the group on or off.
The third example computes the average temperature of all room temperature Items in the group.
The fourth example computes the average temperature of all room temperature Items in the group.
Assuming we have a Group containing three timestamps: `now().minusDays(10)`, `now()` and `now().plusSeconds(30)`.
The `EARLIEST` function returns `now().minusDays(10)`, the `LATEST` function returns `now().plusSeconds(30)`.
The last Group counts all members of it matching the given regular expression, here any character or state (simply counts all members).
{: #tags}
### Tags
Tags added to an Item definition allow a user to characterize the specific nature of the Item beyond it's basic Item type.
Tags added to an Item definition allow a user to characterize the specific nature of the Item beyond its basic Item type.
Tags can then be used by add-ons to interact with Items in context-sensitive ways.
Example:
@ -597,7 +605,7 @@ There are two different kinds of channels:
For example, if you have a `Player` Item, a State Channel could be responsible for propagating the state of an audio player (`PLAYING`, `PAUSED`) to your Item as well as listening for proper Commands (`PLAY`, `PAUSE`, `PREVIOUS`, `NEXT`)
- Trigger Channels will only send events that won't have any effect on the Item unless you treat them with Rules or use a Trigger Profile to do state changes or commands based on your event.
For example, when you use a Binding that integrates buttons or wall switches, a Trigger Channel could be responsible for sending a `PRESSED` event when someone is pressing the button of the device.
This event on it's own won't change anything on the Item, but you could use, for example, the Trigger Profile "rawbutton-toggle-switch" to toggle a lamp on or off when the button is clicked.
This event on its own won't change anything on the Item, but you could use, for example, the Trigger Profile "rawbutton-toggle-switch" to toggle a lamp on or off when the button is clicked.
Also, you could e.g. define a Rule that is triggered by this event and calculates the color of the lamp based on the sun position.
Some Bindings support automatic discovery of Things, in which case discovered Things will appear in the Inbox in the Paper UI.
@ -702,10 +710,10 @@ and a [Rule]({{base}}/configuration/rules-dsl.html) to toggle this light with a
when
Channel "serialbutton:button:mybutton:button" triggered PRESSED
then
if (Light_Bedroom.getStateAs(OnOffType) != ON)
Light_Bedroom.sendCommand(ON)
if (Bedroom_Light.getStateAs(OnOffType) != ON)
Bedroom_Light.sendCommand(ON)
else
Light_Bedroom.sendCommand(OFF)
Bedroom_Light.sendCommand(OFF)
end
```

18
configuration/jsr223-jython.md
View File

@ -10,8 +10,10 @@ title: JSR223 Jython Scripting
## Configuration
[Download](https://jython.github.io/index) the Jython 2.7.0 standalone or installer package, or install through a package repository.
Newer versions are not yet supported.
Install Jython on the local filesystem and make note of the installation directory location.
Install Jython on the local filesystem into a directory of your choice.
A good installation directory is `/etc/openhab2/automation/jython`.
For the easiest installation mechanism simply download `jython-standalone-2.7.0.jar` and copy it into your installation directory. Alternatively you can execute the installer and specify your installation directory during the install.
Note that newer versions than 2.7.0 are not yet supported.
The Jython implementation will need to be added to openHAB's Java classpath.
How this is done depends on the specific installation technique and operating system.
@ -26,6 +28,9 @@ EXTRA_JAVA_OPTS="-Xbootclasspath/a:/etc/openhab2/automation/jython/jython-standa
This will add the Jython library to the Java classpath,
set the Jython home directory and specify the initial Python path for the Jython runtime.
Specifically `bootclasspath` must point to your installation directory plus the Jython library, which is
`jython-standalone-2.7.0.jar` if you copied the jar directly or `jython.jar` if you ran the installer.
Similarly `python.home` points to your installation directory.
Python modules and packages can be installed into the `python.path` locations and imported from scripts.
Note that library modules and packages are not automatically reloaded when they change.
@ -44,16 +49,9 @@ or viewing the `openhab.log` file directly).
You should see a log line with information similar to:
```text
... [INFO ] [s.i.GenericScriptEngineFactory:28 ] - Activated scripting support for ECMAScript
... [INFO ] [s.i.GenericScriptEngineFactory:28 ] - Activated scripting support for python
...
... [INFO ] [.a.m.s.r.i.l.ScriptFileWatcher:150 ] - Loading script 'test.py'
```
::: tip Note
ECMAScript is Javascript
:::
Look for any potentially related error messages.
To enable debug logging, use the [Karaf logging]({{base}}/administration/logging.html) commands to
@ -133,7 +131,7 @@ In this case, the `RuleSimple` extension is used to import the `SimpleRule` base
The `RuleSupport` extensions provides the `automationManager` that allows you to register rule instances with openHAB.
The Jython rule class uses the `SimpleRule` subclass to simplify some aspects of the openHAB interface for use with JSR223.
n the constructor, the triggers atribute is set to a list of [triggers](jsr223.html#trigger_types).
In the constructor, the `triggers` atribute is set to a list of [triggers](jsr223.html#trigger_types).
In this example, the trigger is a state update trigger.
The trigger name identifies the trigger and the configuration direction provides trigger-specific options.
For the item update trigger, the configuration provides the item name of the monitored item.

86
configuration/jsr223.md
View File

@ -147,7 +147,7 @@ For example, with the following scripts and directory structure...
To faciliate JSR223 scripting, several openHAB-related variables are automatically predefined within `ScriptExtension` presets.
They can be loaded into the script context using `scriptExtension.importPreset(String preset)`, e.g. `scriptExtension.importPreset("RuleSimple")`.
The Default preset is preloaded, so it does not require importing.
The `default` preset is preloaded, so it does not require importing.
- [`Default`](#default_presets)
- [`RuleSimple`](#rulesimple_presets)
@ -159,19 +159,16 @@ The Default preset is preloaded, so it does not require importing.
#### Default Preset (`importPreset` not required)
| Variable | Description |
|---------|-------------|
| `State` | `org.eclipse.smarthome.core.types.State` |
| `Command` | `org.eclipse.smarthome.core.types.State` |
|----------|-------------|
| `DateTime` | `org.joda.time.DateTime` (if Jodatime is available) |
| `LocalTime` | `org.joda.time.LocalTime` (if Jodatime is available) |
| `State` | `org.eclipse.smarthome.core.types.State` |
| `Command` | `org.eclipse.smarthome.core.types.State` |
| `StringUtils` | `org.apache.commons.lang.StringUtils` |
| `URLEncoder` | `java.net.URLEncoder` |
| `FileUtils` | `org.apache.commons.io.FileUtils` |
| `FilenameUtils` | `org.apache.commons.io.FilenameUtils` |
| `File` | `java.io.File` |
| `UnDefType` | `org.eclipse.smarthome.core.library.types.UnDefType` |
| `NULL` | `UnDefType` enum item |
| `UNDEF` | `UnDefType` enum item |
| `IncreaseDecreaseType` | `org.eclipse.smarthome.core.library.types.IncreaseDecreaseType` |
| `DECREASE` | `IncreaseDecreaseType` enum item |
| `INCREASE` | `IncreaseDecreaseType` enum item |
@ -184,34 +181,46 @@ The Default preset is preloaded, so it does not require importing.
| `StopMoveType` | `org.eclipse.smarthome.core.library.types.StopMoveType` |
| `STOP` | `StopMoveType` enum item |
| `MOVE` | `StopMoveType` enum item |
| `RewindFastforwardType` | `org.eclipse.smarthome.core.library.types.RewindFastforwardType` |
| `REWIND` | `RewindFastforwardType` enum item |
| `FASTFORWARD` | `RewindFastforwardType` enum item |
| `UpDownType` | `org.eclipse.smarthome.core.library.types.UpDownType` |
| `UP` | `UpDownType` enum item |
| `DOWN` | `UpDownType` enum item |
| `UnDefType` | `org.eclipse.smarthome.core.library.types.UnDefType` |
| `NULL` | `UnDefType` enum item |
| `UNDEF` | `UnDefType` enum item |
| `RefreshType` | `org.eclipse.smarthome.core.library.types.RefreshType` |
| `REFRESH` | `RefreshType` enum item |
| `NextPreviousType` | `org.eclipse.smarthome.core.library.types.NextPreviusType` |
| `NEXT` | `NextPreviousType` enum item |
| `PREVIOUS` | `NextPreviousType` enum item |
| `PlayPauseType` | `org.eclipse.smarthome.core.library.types.PlayPauseType` |
| `PLAY` | `PlayPauseType` enum item |
| `PAUSE` | `PlayPauseType` enum item |
| `UpDownType` | `org.eclipse.smarthome.core.library.types.UpDownType` |
| `UP` | `UpDownType` enum item |
| `DOWN` | `UpDownType` enum item |
| `DecimalType` | `org.eclipse.smarthome.core.library.types.DecimalType` |
| `RewindFastforwardType` | `org.eclipse.smarthome.core.library.types.RewindFastforwardType` |
| `REWIND` | `RewindFastforwardType` enum item |
| `FASTFORWARD` | `RewindFastforwardType` enum item |
| `QuantityType` | `org.eclipse.smarthome.core.library.types.QuantityType` |
| `StringListType` | `org.eclipse.smarthome.core.library.types.StringListType` |
| `RawType` | `org.eclipse.smarthome.core.library.types.RawType` |
| `DateTimeType` | `org.eclipse.smarthome.core.library.types.DateTimeType` |
| `DecimalType` | `org.eclipse.smarthome.core.library.types.DecimalType` |
| `HSBType` | `org.eclipse.smarthome.core.library.types.HSBType` |
| `PercentType` | `org.eclipse.smarthome.core.library.types.PercentType` |
| `PointType` | `org.eclipse.smarthome.core.library.types.PointType` |
| `StringType` | `org.eclipse.smarthome.core.library.types.StringType` |
| `StringListType` | `org.eclipse.smarthome.core.library.types.StringListType` |
| `RawType` | `org.eclipse.smarthome.core.library.types.RawType` |
| `items` | Instance of `java.util.Map&lt;String, State&gt;` |
| `itemRegistry` | Instance of `org.eclipse.smarthome.core.items.ItemRegistry` |
| `SIUnits` | `org.eclipse.smarthome.core.library.unit.SIUnits` |
| `ImperialUnits` | `org.eclipse.smarthome.core.library.unit.SmartHomeUnits` |
| `MetricPrefix` | `org.eclipse.smarthome.core.library.unit.SmartHomeUnits` |
| `SmartHomeUnits` | `org.eclipse.smarthome.core.library.unit.SmartHomeUnits` |
| `BinaryPrefix` | `org.eclipse.smarthome.core.library.unit.SmartHomeUnits` |
| `items` | Instance of `java.util.Map&lt;String, State&gt;` |
| `ir` | Alias for `itemRegistry` |
| `itemRegistry` | Instance of `org.eclipse.smarthome.core.items.ItemRegistry` |
| `things` | Instance of `org.eclipse.smarthome.core.thing.ThingRegistry` |
| `rules` | Instance of `org.openhab.core.automation.RuleRegistry` |
| `events` | (internal) Used to send events, post commands, etc. [Details](#event_operations) below] |
| `actions` | Instance of `org.eclipse.smarthome.core.thing.binding.ThingActions` |
| `scriptExtension` | (internal) For loading script presets. |
| `se` | Alias for `scriptExtension` |
| `events` | (internal) Used to send events, post commands, etc. [Details](#event_operations) below] |
<a name="#event_operations"></a>
@ -232,7 +241,7 @@ The Default preset is preloaded, so it does not require importing.
#### RuleSimple Preset
These variables are loaded using:
These variables and classes are loaded using:
```python
scriptExtension.importPreset("RuleSimple")
@ -242,22 +251,22 @@ The primary usage of this preset is for defining rule (`SimpleRule`) subclasses.
See language-specific documentation for examples.
| Variable | Description |
|----------|------|-------|
| SimpleRule | Base class for Jython Rules |
| SimpleActionHandler | `org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleActionHandler` |
| SimpleConditionHandler | `org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleConditionHandler` |
| SimpleTriggerHandler | `org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleTriggerHandler` |
| TriggerType | `org.openhab.core.automation.type.TriggerType` |
|----------|-------------|
| ActionType | `org.openhab.core.automation.type.ActionType` |
| ConfigDescriptionParameter | `org.eclipse.smarthome.config.core.ConfigDescriptionParameter` |
| ModuleType | `org.openhab.core.automation.type.ModuleType` |
| ActionType | `org.openhab.core.automation.type.ActionType` |
| SimpleActionHandler | `org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleActionHandler` |
| SimpleConditionHandler | `org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleConditionHandler` |
| SimpleRule | Base class for Jython Rules `org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleRule` |
| SimpleTriggerHandler | `org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleTriggerHandler` |
| TriggerType | `org.openhab.core.automation.type.TriggerType` |
| Visibility | `org.openhab.core.automation.Visibility` enum |
<a name="rulesupport_presets"></a>
#### `RuleSupport` Preset
These variables are loaded using:
These variables and classes are loaded using:
```python
scriptExtension.importPreset("RuleSupport")
@ -265,12 +274,17 @@ scriptExtension.importPreset("RuleSupport")
| Variable | Description |
|----------|-------------|
| automationManager | Instance for managing rules and other openHAB module instances. (e.g., `addRule`) |
| Configuration | `org.eclipse.smarthome.config.core.Configuration` |
| Action | `org.openhab.core.automation.Action` |
| Condition | `org.openhab.core.automation.Condition` |
| Action | `org.openhab.core.automation.Action` |
| ActionBuilder | `org.openhab.core.automation.ActionBuilder` |
| Condition | `org.openhab.core.automation.Condition` |
| ConditionBuilder | `org.openhab.core.automation.ConditionBuilder` |
| Configuration | `org.eclipse.smarthome.config.core.Configuration` |
| ModuleBuilder | `org.openhab.core.automation.ModuleBuilder` |
| Rule | `org.openhab.core.automation.Rule` (use `SimpleRule` for defining rules) |
| Trigger | `org.openhab.core.automation.Trigger` |
| Rule | `org.openhab.core.automation.Rule` (use `SimpleRule` for defining rules) |
| TriggerBuilder | `org.openhab.core.automation.TriggerBuilder` |
| automationManager | Instance for managing rules and other openHAB module instances. (e.g., `addRule`) |
| ruleRegistry | `org.openhab.core.automation.Rule` |
<a name="rulefactories_presets"></a>
@ -287,12 +301,6 @@ scriptExtension.importPreset("RuleFactories")
| `ActionHandlerFactory` | `org.openhab.core.automation.module.script.rulesupport.shared.factories.ScriptedActionHandlerFactory` |
| `ConditionHandlerFactory` | `org.openhab.core.automation.module.script.rulesupport.shared.factories.ScriptedConditionHandlerFactory` |
| `TriggerHandlerFactory` | `org.openhab.core.automation.module.script.rulesupport.shared.factories.ScriptedTriggerHandlerFactory` |
| `TriggerType` | `org.openhab.core.automation.type.TriggerType` |
| `ConfigDescriptionParameter` | `org.eclipse.smarthome.config.core.ConfigDescriptionParameter` |
| `ModuleType` | `org.openhab.core.automation.type.ModuleType` |
| `ActionType` | `org.openhab.core.automation.type.ActionType` |
| `Visibility` | `org.openhab.core.automation.Visibility` enum |
<a name="trigger_types"></a>

8
configuration/multimedia.md
View File

@ -9,7 +9,7 @@ title: Multimedia
## Volume
The framework supports some base [functions](https://www.eclipse.org/smarthome/documentation/javadoc/org/eclipse/smarthome/model/script/actions/Audio.html#getMasterVolume--) to control the audio sinks' volume.
The framework supports some base [functions](https://www.openhab.org/javadoc/v2.5/org/eclipse/smarthome/model/script/actions/audio#method.summary) to control the audio sinks' volume.
### Actions
@ -58,7 +58,7 @@ openhab> smarthome:audio stream example.com
### Actions
Alternatively the [`playSound()`](https://www.eclipse.org/smarthome/documentation/javadoc/org/eclipse/smarthome/model/script/actions/Audio.html#playSound-java.lang.String-) or [`playStream()`](https://www.eclipse.org/smarthome/documentation/javadoc/org/eclipse/smarthome/model/script/actions/Audio.html#playStream-java.lang.String-) functions can be used in DSL rules:
Alternatively the [`playSound()`](https://www.openhab.org/javadoc/v2.5/org/eclipse/smarthome/model/script/actions/audio#playSound(java.lang.String)) or [`playStream()`](https://www.openhab.org/javadoc/v2.5/org/eclipse/smarthome/model/script/actions/audio#playStream(java.lang.String)) functions can be used in DSL rules:
- `playSound(String filename)` : plays a sound from the sounds folder to the default sink
- `playSound(String filename, PercentType volume)` : plays a sound with the given volume from the sounds folder to the default sink
@ -109,7 +109,7 @@ openhab> smarthome:voice say Hello world!
### Actions
Alternatively you can execute such commands within DSL rules by using the [`say()`](https://www.eclipse.org/smarthome/documentation/javadoc/org/eclipse/smarthome/core/voice/VoiceManager.html#say-java.lang.String-) function:
Alternatively you can execute such commands within DSL rules by using the [`say()`](https://www.openhab.org/javadoc/v2.5/org/eclipse/smarthome/core/voice/voicemanager#say(java.lang.String)) function:
```java
say("Hello world!")
@ -151,7 +151,7 @@ openhab> smarthome:voice interpret turn on the light
The default human language interpreter will be used.
In case of interpretation error, the error message will be said using the default voice and default audio sink.
Again, such a command can also be entered within DSL rules (using the [`interpret()`](https://www.eclipse.org/smarthome/documentation/javadoc/org/eclipse/smarthome/core/voice/VoiceManager.html#interpret-java.lang.String-) function)
Again, such a command can also be entered within DSL rules (using the [`interpret()`](https://www.openhab.org/javadoc/v2.5/org/eclipse/smarthome/core/voice/voicemanager#interpret(java.lang.String)) function)
```java
interpret("turn on the light")

3
configuration/packages.md
View File

@ -61,7 +61,8 @@ These are:
**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 an demonstrator what there is to come.
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)

28
configuration/persistence.md
View File

@ -67,7 +67,7 @@ The following strategies are defined internally and may be used in place of `str
- `restoreOnStartup`: load and initialize the last persisted state of the Item on openHAB startup (if the Item state is undefined (`UNDEF`)).
#### Cron Persistence Triggers
openHAB uses [Quartz](http://www.quartz-scheduler.org/documentation/quartz-2.1.x/quick-start.html) for time-related cron events.
openHAB uses [Quartz](https://www.quartz-scheduler.org/documentation) for time-related cron events.
See the [Rules article]({{base}}/configuration/rules-dsl.html#time-based-triggers) for more information.
### Items
@ -175,12 +175,12 @@ Here is the full list of available persistence extensions:
|-----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `<item>.persist` | Persists the current State of the Item |
| `<item>.lastUpdate` | Queries for the last update timestamp of a given Item |
| `<item>.historicState(AbstractInstant)` | Retrieves the State of an Item at a certain point in time (returns HistoricItem) |
| `<item>.historicState(AbstractInstant)` | Retrieves the State of an Item at a certain point in time (returns HistoricItem) |
| `<item>.changedSince(AbstractInstant)` | Checks if the State of the Item has (ever) changed since a certain point in time |
| `<item>.updatedSince(AbstractInstant)` | Checks if the state of the Item has been updated since a certain point in time |
| `<item>.maximumSince(AbstractInstant)` | Gets the maximum value of the State of a persisted Item since a certain point in time |
| `<item>.minimumSince(AbstractInstant)` | Gets the minimum value of the State of a persisted Item since a certain point in time |
| `<item>.averageSince(AbstractInstant)` | Gets the average value of the State of a persisted Item since a certain point in time |
| `<item>.maximumSince(AbstractInstant)` | Gets the maximum value of the State of a persisted Item since a certain point in time (returns HistoricItem) |
| `<item>.minimumSince(AbstractInstant)` | Gets the minimum value of the State of a persisted Item since a certain point in time (returns HistoricItem) |
| `<item>.averageSince(AbstractInstant)` | Gets the average value of the State of a persisted Item since a certain point in time. This method uses a time-weighted average calculation (see example below) |
| `<item>.deltaSince(AbstractInstant)` | Gets the difference in value of the State of a given Item since a certain point in time |
| `<item>.previousState()` | Gets the previous State of a persisted Item (returns HistoricItem) |
| `<item>.previousState(true)` | Gets the previous State of a persisted Item, skips Items with equal State values and searches the first Item with State not equal the current State (returns HistoricItem) |
@ -190,12 +190,28 @@ These extensions use the default persistence service.
(Refer to 'Default Persistence Service' above to configure this.)
You may specify a different persistence service by appending a String as an optional additional parameter at the end of the extension.
**Example**
#### Examples
To persist an Item called `Lights` in an rrd4j database, you would enter the following:
`Lights.persist("rrd4j")`
To get the average temperature over the last 5 minutes from the Item called `Temperature` in the influxdb persistence service, you would use:
`Temperature.averageSince(now.minusMinutes(5), "influxdb")`
The most useful methods of the HistoricItem object returned by some queries, are `.state` and `.getTimestamp`
#### Time-weighted averages
Time-weighted averages take into consideration not only the numerical levels of a particular variable, but also the amount of time spent on it.
For instance, if you are measuring the temperature in a room - acknowledging the differences in the amounts of time until it changes.
A brief example:
18 °C for 13 hours a day, 21 °C for 7 hours a day, and 16.5 °C for 4 hours a day, you would obtain 18 °C x 13 h, 21 °C x 7 h and 16.5 °C x 4 h (234, 147, and 66, respectively).
Sum the values that you obtained.
In this case, 447 °C hours.
Add together the time weights to get the total weight.
In our example, the total weight is 13 h + 7 h + 4 h = 24 h.
Divide the value in Step 2 by the total weights in Step 3, to get an average of 447 °C hours / 24 h = 18.625 °C.
### Date and Time Extensions
A number of date and time calculations have been made available in openHAB through incorporation of [Jodatime](http://joda-time.sourceforge.net/).

20
configuration/rules-dsl.md
View File

@ -22,7 +22,7 @@ On this page you will learn how to leverage its functionality to do *real* home
### File Location
Rules are placed in the folder `$OPENHAB_CONF/rules`.
The [demo setup]({{base}}/tutorials/demo.html) already comes with a demo file called `demo.rules`, which has a couple of examples that can be a good starting point.
The [demo setup](http://demo.openhab.org:8080/) already comes with a demo file called [`demo.rules`](https://github.com/openhab/openhab-distro/blob/master/features/distro-resources/src/main/resources/rules/demo.rules), which has a couple of examples that can be a good starting point.
A rule file can contain multiple rules.
All rules of a file share a common execution context, i.e. they can access and exchange variables with each other.
@ -380,7 +380,7 @@ There are two ways to discover these methods:
- Use the [openHAB VS Code Extension](/docs/configuration/editors.html#editors.html#openhab-vs-code-extension) and the `<ctrl><space>` key combo to list all the available methods
- Look at the JavaDocs for the given type.
For example, the [JavaDoc for HSBType](http://www.eclipse.org/smarthome/documentation/javadoc/index.html?org/eclipse/smarthome/core/library/types/HSBType.html) shows getRed, getBlue, and getGreen methods.
For example, the [JavaDoc for HSBType](https://www.openhab.org/javadoc/v2.5/org/eclipse/smarthome/core/library/types/hsbtype) shows getRed, getBlue, and getGreen methods.
These methods can be called in Rules-DSL without the "get" part in name as in `(MyColorItem.state as HSBType).red)`.
They retrieve the state of MyColorItem and then casts it as HSBType to be able to use the methods associated with the HSBType.
@ -553,16 +553,16 @@ Here some other commonly needed conversions:
* For DecimalType states:
```java
//convert integer_number to string containing hex_code
var String hex_code = Long.toHexString(integer_number);
// convert integer_number to string containing hex_code
var String hex_code = Long.toHexString(integer_number)
//convert hex_code to Number type
var MyNumber = Integer.parseInt(hex_code, 16) as Number
//use the following for large_hex_code
var MyNumber = Long.parseLong(hex, 16) as Number
// convert hex_code to Number type
var myNumber = Integer.parseInt(hex_code, 16) as Number
// use the following for large_hex_code
var myNumber = Long.parseLong(hex, 16) as Number
// coverting hex_code into DecimalType
var DecimalType parsedResult = DecimalType.valueOf(Long.parseLong(hex_code, 16).toString);
// convert hex_code to DecimalType
var DecimalType parsedResult = new DecimalType(Long.parseLong(hex_code, 16))
```
* For QuantityType states:

14
configuration/sitemaps.md
View File

@ -247,7 +247,7 @@ Switch item=<itemname> [label="<labelname>"] [icon="<iconname>"] [mappings="<map
```
Switches are one of the more common elements of a typical Sitemap.
A Switch will present a discrete state Item and allow changing of it's value.
A Switch will present a discrete state Item and allow changing of its value.
Note that Switch elements can be rendered differently on the user interface, based on the Item type and the `mappings` parameter.
- `mappings` comes as an array of value-to-string translations, [documented further down](#mappings).
@ -288,8 +288,8 @@ Selection item=LR_TV_Channel label="TV Channel" mappings=[0="DasErste", 1="BBC O
Setpoint item=<itemname> [label="<labelname>"] [icon="<iconname>"] minValue=<min value> maxValue=<max value> step=<step value>
```
- `minValue` and `maxValue` limit the possible range of the value (both included in the range).
- `step` defines how much the value will change when the button is pressed one time.
- `minValue` (defaults to 0) and `maxValue` (defaults to 100) limit the possible range of the value (both included in the range).
- `step` (defaults to 1) defines how much the value will change when the button is pressed one time.
**Example:**
@ -467,7 +467,7 @@ See this [Tutorial](https://community.openhab.org/t/13761/1) for more details.
- When using rrd4j persistence, the strategy `everyMinute` (60 seconds) has to be used. Otherwise no data will be persisted (stored) and the chart will not be drawn properly (see [rrd4j Persistence](/addons/persistence/rrd4j)).
- The visibility of multiple Chart objects may be toggled to simulate changing the Chart period; non-visible Chart widgets are NOT generated behind the scenes until they become visible.
- When charting a group of item, make sure that every label is unique. If the label contains spaces, the first word of the label must be unique. Identical labels result in an empty chart.
- When charting a group of item, make sure that every label is unique.
## Mappings
@ -536,9 +536,9 @@ The Item will be visible if any one of the comparisons is evaluated as `true`, o
**Examples:**
```perl
visibility=[Battery_Level<30]
visibility=[TV_Power==ON]
visibility=[Day_Time=="Morning", Day_Time=="Afternoon", Temperature>19]
Text item=BatteryWarning visibility=[Battery_Level<30]
Switch item=CinemaLight "Cinema light" visibility=[TV_Power==ON]
Switch item=LawnSprinkler visibility=[Day_Time=="Morning", Day_Time=="Afternoon", Temperature>19]
```
In the third example above, a control for a lawn sprinkler will be visible if it is Morning, *OR* if it is Afternoon, *OR* if the temperature is above 19 °C.

8
configuration/things.md
View File

@ -76,12 +76,12 @@ Thing <binding_id>:<type_id>:<thing_id> "Label" @ "Location" [ <parameters> ]
The first keyword defines whether the entry is a bridge or a thing.
The next statement defines the UID of the thing which contains of the following three segments: `binding id`, `thing type id`, `thing id`.
So the first two segments must match to a thing type supported by a binding (e.g. `network:device` or `astro:moon`), whereas the thing id can be freely defined.
The first two segments must match to a thing type supported by a binding (e.g. `network:device` or `astro:moon`), whereas the thing id can be freely defined.
Optionally, you may provide a label in order to recognize it easily, otherwise the default label from the thing type will be displayed.
To help organizing your things, you also may define a location (`Location` in the example above).
Inside the squared brackets configuration parameters of the thing are defined.
Inside the square brackets configuration parameters of the thing are defined.
The type of the configuration parameter is determined by the binding and must be specified accordingly in the DSL.
@ -106,7 +106,7 @@ Please check each individual binding's [documentation](/addons/#binding) for det
### Defining Bridges Using Files
Bridges can be defined together with contained things. The following configuration shows the definition of a hue bridge with two hue lamps:
Bridges can be defined together with contained things. The following configuration shows the definition of a Hue bridge with two Hue lamps:
```xtend
Bridge hue:bridge:mybridge [ ipAddress="192.168.3.123" ] {
@ -123,7 +123,7 @@ The resulting UID of the thing is `hue:0210:mybridge:bulb1`.
Bridges that are defined somewhere else can also be referenced in the DSL:
```xtend
Thing hue:0210:mybridge:bulb (hue:bridge:mybridge) [lightId="3"]
Thing hue:0210:mybridge:bulb "Label" (hue:bridge:mybridge) @ "Location" [lightId="3"]
```
The referenced bridge is specified in the parentheses.

68
developers/bindings/index.md
View File

@ -660,9 +660,9 @@ The following table gives an overview about the main parts of a `DiscoveryResult
| `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.
| `label` | The human readable representation of the discovery result. Do not put IP/MAC addresses or similar into the label but use the special `representationProperty` instead. |
| `representationProperty` | The name of one of the properties which discriminates the discovery result best against other results of the same type. Typically this is a serial number, IP or MAC address. The representationProperty often matches a configuration parameter and is also explicitly given in the thing-type definition. |
| `representationProperty` | The name of one of the properties or configuration parameters, which best discriminates the result from other results of the same type. See chapter [Representation Property](#representation-property) below. |
To simplify the implementation of own discovery services, an abstract base class `AbstractDiscoveryService` implements the `DiscoveryService`, that must only be extended.
To simplify the implementation of custom discovery services, an abstract base class `AbstractDiscoveryService` implements the `DiscoveryService` and just needs to be extended.
Subclasses of `AbstractDiscoveryService` do not need to handle the `DiscoveryListeners` themselves, they can use the methods `thingDiscovered` and `thingRemoved` to notify the registered listeners.
Most of the descriptions in this chapter refer to the `AbstractDiscoveryService`.
@ -692,6 +692,57 @@ It uses the `DiscoveryResultBuilder` to create the discovery result.
The discovery service needs to provide the list of supported thing types, that can be found by the discovery service.
This list will be given to the constructor of `AbstractDiscoveryService` and can be requested by using `DiscoveryService#getSupportedThingTypes` method.
### Representation Property
The name of one of the properties or configuration parameters, which best discriminates the discovery result from other results of the same type.
Typically this is a serial number, or an IP or MAC address.
The representation property is used to auto-ignore discovery results of Things that already exist in the system.
This can happen, a) if a Thing has been created manually, or b) if the Thing has been discovered separately by two mechanisms e.g. by mDNS, and by NetBios, or UPnP.
If a new Thing goes online, the auto-ignore service of the inbox checks if the inbox already contains a discovery result of the same type where the existing representation property is identical to the representation property of the newly discovered Thing.
If this is the case, the Thing in the inbox is automatically ignored.
The representation property must be declared in the [thing-types.xml](thing-xml.md#representation-property)
When comparing representation properties, the framework checks for matches between the representation property of the newly discovered Thing, and both the `properties` and the `configuration parameters` of existing Things.
If defining a representation property for a bridge, the representation property does not need to be **globally** unique, but only unique within the context of the bridge, so long as the discovery service calls `.withBridge(bridgeUID)` when building the DiscoveryResult. e.g. if bridge A. has child Things with representation properties of 1, 2, and 3, and bridge B. also has child Things with representation properties of 1, 2, and 3, they will not conflict.
```java
DiscoveryResult result = DiscoveryResultBuilder.create(thingUID)
.withProperty("uniqueId", nonUniquePropertyValue)
.withBridge(bridgeUID) // bridgeUID plus nonUniquePropertyValue are unique
.withRepresentationProperty("uniqueId")
.build();
```
Furthermore, if a Thing has two configuration parameters where each individually is not globally unique, but the combination of the two is unique, one can define an extra property that combines the two:
```java
String cfgParamValA = "value-of-non-unique-config-param-A";
String cfgParamValB = "value-of-non-unique-config-param-B";
String uniquePropVal = String.format("%s-%s", cfgParamValA, cfgParamValB);
...
DiscoveryResult hub = DiscoveryResultBuilder.create(thingUID)
.withProperty("uniqueId", uniquePropVal)
.withRepresentationProperty("uniqueId")
.build();
```
If Things are created manually, the property or configuration parameter that will match the auto discovery representation property must be set.
In the case that a `property` will be used to match the representation property its value must be set in the Thing handler's `initialize()` method:
```java
updateProperty("uniqueId", uniquePropVal);
```
Alternatively in the case that a `configuration parameter` will be used to match the auto discovery representation property, the parameter must be declared in either, a) the `thing-types.xml` file, or b) the `config-description` [XML file](config-xml.md).
And it must also be declared in the Thing handler's `Configuration` class:
```java
public class MyThingConfiguration {
public String uniqueId;
}
```
### Registering as an OSGi service
The `Discovery` class of a binding which implements `AbstractDiscoveryService` should be annotated with
@ -725,7 +776,7 @@ The following example shows the implementation of the above mentioned methods in
@Override
protected void stopBackgroundDiscovery() {
logger.debug("Stop WeMo device background discovery");
if (wemoDiscoveryJob != null && !wemoDiscoveryJob.isCancelled()) {
if (wemoDiscoveryJob != null) {
wemoDiscoveryJob.cancel(true);
wemoDiscoveryJob = null;
}
@ -761,6 +812,17 @@ The `getThingUID` method of the discovery service should create a consistent UID
This way existing discovery results and existing things with this UID will be updated with the properties from the current scan.
With this, dynamic discoveries (like UPnP or mDNS) can re-discover existing things and update communication properties like host names or TCP ports.
### Ending an Active Scan
As described above an active scan is initiated via `startScan`.
There is no explicit end to an active scan and discovery results can be provided even after `startScan` completes (e.g. from a separate thread).
If you would like assistance with enforcing a scan end pass a timeout to the `AbstractDiscoveryService` constructor.
`stopScan` will then be called on your discovery service upon timeout expiration allowing you to stop your scan however needed.
If a timeout is specified the scan will be considered active until the timeout expires even if `startScan` completed beforehand.
In particular UIs such as the Paper UI will show the scan as in progress throughout the timeout.
If you override `stopScan` don't forget to call `super.stopScan` as `AbstractDiscoveryService` performs some cleanup in its version.
If the timeout is set to 0 `stopScan` will not be called.
### Remove older results
Normally, older discovery results already in the inbox are left untouched by a newly triggered scan.

47
developers/bindings/thing-xml.md
View File

@ -78,6 +78,8 @@ The granularity of channel types should be on its semantic level, i.e. very fine
If a Thing measures two temperature values, one for indoor and one for outdoor, this should be modelled as two different channel types.
Overriding labels of a channel type must only be done if the very same functionality is offered multiple times, e.g. having an actuator with 5 relays, which each is a simple "switch", but you want to individually name the channels (1-5).
### State Channel Types
The following XML snippet shows a thing type definition with 2 channels and one referenced channel type:
```xml
@ -152,6 +154,8 @@ Especially for complex devices with a lot of channels, only a small set of chann
Whether a channel should be declared as `advanced` depends on the device and can be decided by the binding developer.
If a functionality is rarely used it should be better marked as `advanced`.
### Trigger Channel Types
The following XML snippet shows a trigger channel:
```xml
@ -192,7 +196,7 @@ There exist system-wide trigger channel types that are available by default:
| rawrocker | system.rawrocker | Can trigger `DIR1_PRESSED`, `DIR1_RELEASED`, `DIR2_PRESSED` and `DIR2_RELEASED` |
In the following sections the declaration and semantics of tags, state descriptions and channel categories will be explained in more detail.
For a complete sample of the thing types XML file and a full list of possible configuration options please see the [XML Configuration Guide](xml-reference.html).
For a complete sample of the thing types XML file and a full list of possible configuration options please see the [XML Configuration Guide](config-xml.html).
### Default Tags
@ -484,7 +488,7 @@ In contrast to the properties defined in the 'ThingType' definitions the thing h
### Representation Property
A thing type can contain a so-called `representation property`.
This optional property contains the _name_ of a property whose value can be used to uniquely identify a device.
This optional property contains the **name** of a property whose value can be used to uniquely identify a device.
The `thingUID` cannot be used for this purpose because there can be more than one thing for the same device.
Each physical device normally has some kind of a technical identifier which is unique.
@ -492,7 +496,7 @@ This could be a MAC address (e.g. Hue bridge, camera, all IP-based devices), a u
This property is normally part of a discovery result for that specific thing type.
Having this property identified per binding it could be used as the `representation property` for this thing.
The `representation property` will be defined in the thing type XML:
The `representation property` shall be defined in the thing type XML:
```xml
<thing-type id="thingTypeId">
@ -500,22 +504,41 @@ The `representation property` will be defined in the thing type XML:
<properties>
<property name="vendor">Philips</property>
</properties>
<representation-property>serialNumber</representation-property>
<representation-property>uniqueId</representation-property>
...
</thing-type>
```
Note that the `representation property` is normally not listed in the `properties` part of the thing type, as this part contains static properties, that are the same for each thing of this thing type.
The name of the `representation property` identifies a property that is added to the thing in the thing handler upon successful initialization.
Note that the `representation property` is normally not listed in the `properties` part of the Thing type XML, as this part contains static properties, that are the same for all instances of this Thing type.
The name of the `representation property` identifies a property or configuration parameter that is added to the Thing in the Thing handler upon successful initialization.
### Representation Property and Discovery
The representation property is being used to auto-ignore discovery results of devices that already have a corresponding thing.
This happens if a device is being added manually.
If the new thing is going online, the auto-ignore service of the inbox checks if the inbox already contains a discovery result of the same type where the value of its `representation property` is identical to the value of the `representation property` of the newly added thing.
If this is the case, the result in the inbox is automatically set to ignored.
Note that this result is automatically removed when the manual added thing is eventually removed.
A new discovery would then automatically find this device again and add it to the inbox properly.
The representation property is used to auto-ignore discovery results of Things that already exist in the system.
This can happen if, a) a Thing has been created manually, or b) the Thing has been discovered separately by two mechanisms e.g. by mDNS, and by NetBios, or UPnP.
If this is the case, the Thing in the inbox is automatically ignored.
Note that this Thing is automatically removed when the manually added Thing is removed.
A new discovery would then automatically find this Thing again and add it to the inbox properly.
See also [Implementing a Discovery Service](index.md#representation-property)
When comparing representation properties, the auto-ignore service checks for matches between the representation property of the newly discovered Thing, and both the properties and the configuration parameters of existing Things.
If a configuration parameter will be used, then its respective `parameter` shall be declared in the XML `config-description` section or the `config-description` [XML file](config-xml.md):
```xml
<thing-type id="thingTypeId">
...
<representation-property>uniqueId</representation-property>
...
<config-description>
<parameter name="uniqueId" type="text">
<label>Unique Id</label>
<description>The Unique Id for Representation Property</description>
</parameter>
</config-description>
...
</thing-type>
```
## Formatting Labels and Descriptions

21
developers/buildsystem.md
View File

@ -19,8 +19,10 @@ This section talks about some common buildsystem related topics and also some qu
## Adding Dependencies
Generally all dependencies should be available on JCenter.
In most cases they should be referenced in the project POM with scope `compile`:
Generally all dependencies should be OSGi-bundles and available on JCenter.
### External dependency
In most cases they should be referenced in the project POM with scope `provided`:
```
<dependencies>
@ -47,8 +49,19 @@ To ensure that they are available at runtime they also need to be added to the `
<bundle dependency="true">mvn:org.openhab.addons.bundles/org.openhab.binding.bluetooth/2.5.0-SNAPSHOT</bundle>
```
Bundles that are used in more than one binding should use the same version that is already present.
You need to exclude those bundles from embedding by adding an exclusion to the `pom.xml`:
### Internal dependency
In two cases libraries can be added to the `/lib` directory:
1. The bundle is not available for download
2. The bundle is not an OSGi bundle but needs to be used for integration tests.
Unlike Karaf, BND is not able to wrap bundles on its own.
In this case the binding works as wrapper.
You need add the library and export all needed packages manually.
The build system automatically picks up all JAR files in `/lib` and embeds them in the new bundle.
In this case they must not be added to the feature.
If the bundles manifest is not properly exporting all needed packages, you can import them manually by adding
```
<properties>

19
developers/contributing.md
View File

@ -103,6 +103,7 @@ or `Fixes #XXX`, which will automatically close the issue when merged.
openHAB maintainers use the [GitHub review feature](https://help.github.com/articles/about-pull-request-reviews/) to indicate acceptance.
<a id="sign-your-work"></a>
### Sign your Work
The sign-off is a simple line at the end of the explanation for the
@ -184,6 +185,24 @@ Don't forget: being a maintainer is a time investment.
Make sure you will have time to make yourself available.
You don't have to be a maintainer to make a difference on the project!
### Contributing to the Documentation
Sharing your knowledge through documentation contributions is incredibly valuable for the community allowing everybody to benefit from your lessons learned.
If you are not yet ready to contribute code don't let that stop you from contributing to the documentation.
Documentation change requests are very easy.
No need to file an issue.
You don't even need to know Git.
* Create a GitHub account and configure your full name in your profile.
* Go to the documentation page that you want to update and click on "Edit this page on GitHub" at the bottom.
* GitHub will bring up a web editor where you can enter your desired changes.
* You can preview your changes under the "Preview changes" tab.
* Add a title and optional description for your proposed change at the bottom of the editor.
* The [sign off rules](#sign-your-work) described above do apply to documentation contributions as well.
Simply add an empty line and the sign off statement "Signed-off-by: Joe Smith \<joe.smith@email.com\>" at the end of your change description at the bottom of the editor.
Note that as per the rules you have to provide your full name in the sign off and that full name has to match the name you configured in your GitHub profile for the DCO check to succeed.
* Click the "Propose file change" button at the bottom of the editor, then click "Create pull request" on the next page, and then on the summary page click "Create pull request" one more time.
If you prefer to use Git you can of course use the code contribution process for documentation contributions as well.
## Community Guidelines
We want to keep the openHAB community awesome, growing and collaborative. We

6
developers/guidelines.md
View File

@ -26,6 +26,7 @@ If you are just keen on binding development, you may skip this document first an
The structure of a binding follows the structure of a typical OSGi bundle project.
```
|- doc Images and other assets used in the Readme.md
|- src/main
|---- feature
|-------- feature.xml Your OSGI feature file
@ -350,8 +351,3 @@ For Web Socket Operations
::: tip Note
WebSocketClient instances should be obtained by the handler factory through the WebSocketClientFactory service and unless there are specific configuration requirements, the shared instance should be used.
:::
Additionally these libraries are allowed
* Apache Commons IO
* Apache Commons Lang

102
developers/ide/eclipse.md
View File

@ -7,7 +7,11 @@ title: Eclipse IDE
Eclipse is the development environment used since the inception of openHAB.
To make development easier an out-of-the-box setup is available that completely configures Eclipse to easily develop for the openHAB projects.
This guide describes the steps to setup Eclipse and how to debug an add-on in Eclipse.
This guide describes the steps to setup Eclipse and how to run and debug an add-on in Eclipse.
::: tip Existing Eclipse Installations
If you already have Eclipse installed it is recommended to perform a separate Eclipse install for OpenHAB to avoid overriding your existing Eclipse configuration.
:::
## Eclipse IDE Setup
@ -47,7 +51,7 @@ This guide describes the steps to setup Eclipse and how to debug an add-on in Ec
::: warning Attention
Select `2.5.x` if you want to develop for 2.5.x.
The Core Framework only has a master branch (3.0 development).
The Core Framework only has a master branch (3.0 development), which means you can no longer make Core Framework changes for a 2.5.x system.
:::
1. Click `Next>`, verify/modify Root and install folder name. Click on `Show all variables` to open the window shown below.
@ -80,29 +84,19 @@ This guide describes the steps to setup Eclipse and how to debug an add-on in Ec
1. After all tasks are finished you are ready to start developing.
::: tip
The Maven build system is configured to download the SNAPSHOT version daily.
As a result when you restart Eclipse the other day.
It may take some time as it updates all SNAPSHOT versions of openHAB.
:::
1. If you have selected `openHAB Add-ons` the installer will clone the [openHAB Add-ons](https://github.com/openhab/openhab-addons/) repository.
To get an existing binding project into Eclipse import it as a Maven project.
Goto `File` -> `Import...` -> `Maven` -> `Existing Maven projects` and follow the wizard to select the directory of the binding or bindings to import.
1. If you want to develop a new binding. Read about the [Skeleton Script](../#develop-a-new-binding) to generate the base for your binding, creating all required files.
1. If you need additional libraries see the [Build System](../buildsystem.html) documentation.
For other libraries supported out-of-the-box check the [Default Libraries](../guidelines.html#default-libraries) on the guidelines page.
## Debugging an Add-on
## Working with Add-ons
To test your binding you can build the add-on on the command line with Maven and drop the jar file in an `addons/` folder of an existing installation.
But to easily debug an add-on the `openHAB Development` setup installs and imports a demo project that contains a complete openHAB environment to run and debug an add-on.
To easily run, modify and debug an add-on the `openHAB Development` setup installs and imports a demo project that contains a complete openHAB environment to run and debug an add-on.
This mechanism replaces the add-on installation process via the PaperUI that you would use outside the IDE.
### Running Add-ons
Under `Infrastructure` you will find the project `org.openhab.demo.app`.
This project contains the full configuration to start a debug sessions.
The following files are of interest for the debug environment:
This project contains the full configuration to run OpenHAB.
The following files are of interest for the execution environment:
```
|- org.openhab.demo.app
@ -110,17 +104,10 @@ The following files are of interest for the debug environment:
|------- conf Here you configure the manual text files
|------- userdata Here is the openHAB user data
|------- logback.xml XML file for logging options
|--- app.bndrun The file to start a debug session
|--- app.bndrun The file to start OpenHAB
|--- pom.xml The pom file with all dependencies for the demo project
```
1. Import the add-on in Eclipse.
Either it is an existing add-on or a new binding created with the skeleton script.
Import the add-on project via `File > Import... > General > Existing Projects into Workspace`.
Importing an add-on is necessary if you want to modify or debug the add-on.
It is also possible to run existing add-ons part of the SNAPSHOT release in the demo project without having it imported in Eclipse.
Simply follow the next step to add the add-on.
1. To let the demo project know about the add-on, the add-on must be added to the demo project `pom.xml`.
Here is an example for the `astro` binding:
@ -133,17 +120,12 @@ Here is an example for the `astro` binding:
</dependency>
```
::: tip
To only run a binding in the demo you don't need to import the binding in Eclipse.
Add the binding to the pom.xml and follow the steps below and you will be able to use that binding in the demo.
:::
1. To debug the add-on with the `app.bndrun` run configuration.
1. To run the add-on with the `app.bndrun` run configuration.
Double click to open `app.bndrun` file (takes a few seconds):
![Bndtools](images/ide_debug_eclipse_1_bndtools.png)
1. Under `Browse Repos` search for the binding you want to run/debug (`astro` in our case) and add it to the `Run Requirements` list using drag&drop from the `Browse Repos` list:
1. Under `Browse Repos` search for the add-on you want to run (`astro` in our case) and add it to the `Run Requirements` list using drag&drop from the `Browse Repos` list:
::: tip
If you cannot find the binding you want run/debug in the Browse Repos list, or the list is empty,
@ -156,17 +138,61 @@ Here is an example for the `astro` binding:
1. Save and click "Resolve": a window with the list of resolved bundles will be shown.
Click `Finish` and save the file.
::: tip
Watch out - it's easy to miss saving the `app.bndrun` file.
If you see the little asterisk next to `app` in the `app` tab you haven't yet saved.
:::
Now the IDE is ready to start openHAB with a minimum set of the openHAB core bindings, UIs and the selected binding you want to run/debug.
Now the IDE is ready to start openHAB with a minimum set of the openHAB core bindings, UIs and the add-ons you configured.
1. Start openHAB from the IDE clicking "Run OSGi" or "Debug OSGi" (upper right of the `app.bndrun` window)
1. Start openHAB from the IDE by clicking "Run OSGi" (upper right of the `app.bndrun` window).
1. You can check openHAB is running going with your browser to: http://localhost:8080/paperui/ (the last `/` is important!)
1. You can check that openHAB is running with your browser by going to: http://localhost:8080/paperui/ (the last `/` is important!)
1. You can check log output in the `Console` tab at the bottom.
1. Check the chosen binding is active in `Paper UI > Configuration > Bindings`
### From start to debug in a single animation
View all the above steps in a single animation:
![Debug Animation](images/ide_eclipse_debug_animation.gif)
### Modifying and Debugging Add-ons
If you don't just want to run an add-on, but also want to modify and debug it you need to install sources for the add-on and build them locally.
1. Install Sources
Sources are installed by cloning the [openHAB Add-ons](https://github.com/openhab/openhab-addons/) repository.
If you select `openHAB Add-ons` during installation the installer automatically clones the [openHAB Add-ons](https://github.com/openhab/openhab-addons/) repository into `git\openhab-addons` under your installation folder.
If you didn't install `openHAB Add-ons` you can manually clone the [openHAB Add-ons](https://github.com/openhab/openhab-addons/) repository by executing `git clone https://github.com/openhab/openhab-addons.git` in the `git` folder under your installation folder.
You can now modify add-on sources as needed.
1. Build Sources
Add the add-on as an Eclipse project so that Eclipse will build it automatically.
Import the add-on project via `File > Import... > General > Existing Projects into Workspace`.
Specify your add-on's source root folder (e.g. `git\openhab-addons\bundles\org.openhab.binding.astro` under the installation folder) as the root folder in the wizard.
1. Start a Debug Session
Simply start your debug session by clicking "Debug OSGi" (upper right of the `app.bndrun` window).
You can now use breakpoints and all other Eclipse debug tools.
::: tip Where do add-on jar files come from?
If you just run an add-on following the above steps then the required add-on jar files are retrieved through your Maven repository folder `.m2/repository` (e.g. `.m2\repository\org\openhab\addons\bundles\org.openhab.binding.astro`).
If you imported your add-on as a project then the jar file is no longer retrieved from the Maven repository, but instead from the project build (e.g. `git\openhab-addons\bundles\org.openhab.binding.astro\target` under the installation folder).
:::
### Using New Bindings
If you want to develop a new binding read about the [Skeleton Script](../#develop-a-new-binding) to generate the base for your binding and create all required files.
Then follow the above steps to build your sources and to configure the demo app to run your binding.
## Updating OpenHAB
You can update the OpenHAB version you are running in the IDE at any time simply by updating your git repos under your install folder.
For example to update to the latest version run `git checkout` in each repo folder under your `git` folder in the installation folder.

2
developers/ide/vscode.md
View File

@ -83,7 +83,7 @@ You can now make changes, set breakpoints, etc.
1. May take openHAB a few seconds to realize there is a new bundle and to reinitilize it after it's been copied. Be a little bit patient.
2. You must run the `mvn Compile (Online)` task atleast once to allow the offline compile to occur. You should use the `mvn Compile (Offline)` task for most of your development as it's quicker since it uses the cache files. When you are ready to commit (or release a test bundle) - you should run the `mvn Compile (Release)` task to include code checks (and resolve them).
3. Win10+ allows forward slashes as part of it's path. If you use backward slashes instead - you will need to double up on them since tasks.json uses a backward slash as a delimiter. Example: `c:\\\\openhab`
3. Win10+ allows forward slashes as part of its path. If you use backward slashes instead - you will need to double up on them since tasks.json uses a backward slash as a delimiter. Example: `c:\\\\openhab`
## Tasks

4
developers/index.md
View File

@ -32,14 +32,14 @@ openHAB allows you to build up on the following concepts:
Extend where audio can be played on or implement audio sources.
* and many more (not covered yet).
Sometimes though its just not worth writing a binding and you are better off
Sometimes though it's just not worth writing a binding and you are better off
just using an http action in a rule or script to retrieve some values.
Therefore: First think what you want to achieve! Check our [community forum](https://community.openhab.org)
and discuss your concept.
Find the right abstraction and the corresponding link on the left navigation panel.
General [coding guidelines](development/guidelines.html) apply to all types of addon development.
General [coding guidelines](docs/developer/guidelines.html) apply to all types of addon development.
## Setup the Development Environment

2
developers/legacy/compatibilitylayer.md
View File

@ -38,4 +38,4 @@ Here is what you need to do:
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](https://www.eclipse.org/smarthome/documentation/development/bindings/xml-reference.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.
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.

2
developers/osgi/osgi.md
View File

@ -87,7 +87,7 @@ The table below shows the possible states of an OSGi bundle with a short explana
| Status | Description |
|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| INSTALLED | The bundle has been installed into the OSGi container, but some of it's dependencies are still not resolved. The bundle requires packages that have not been exported by any other bundle. |
| INSTALLED | The bundle has been installed into the OSGi container, but some of its dependencies are still not resolved. The bundle requires packages that have not been exported by any other bundle. |
| RESOLVED | The bundle is installed and the all the dependencies at a class level are resolved and wired. The bundle can export the packages, that it provides. |
| STARTING | A temporary state that the bundle goes through while the bundle is starting, after all dependencies have been resolved. The bundle is permitted to register services. |
| ACTIVE | The bundle is running |

BIN
images/addons/bluetooth.airthings.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.3 KiB

BIN
images/addons/bluetooth.am43.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

BIN
images/addons/ecobee.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 14 KiB

After

Width:  |  Height:  |  Size: 15 KiB

BIN
images/addons/fmiweather.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.9 KiB

BIN
images/addons/insteon.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 32 KiB

15
installation/docker.md
View File

@ -97,7 +97,7 @@ docker run \
-e USER_ID=<uid> \
-e GROUP_ID=<gid> \
--restart=always \
openhab/openhab:<version>-<architecture>-<distribution>
openhab/openhab:<version>-<distribution>
```
Where
@ -105,7 +105,6 @@ Where
- `<uid>` is the user ID number for the `openhab` user which you can obtain using the command `id openhab`,
- `<gid>` is the group ID number for the `openhab` user,
- `<version>` is the version of openHAB,
- `<architecture>` is the architecture of your system and
- `<distribution>` is the base system (debian or alpine).
It is important that the ID number is passed in.
@ -149,14 +148,14 @@ ExecStart=/usr/bin/docker run --name=%n --net=host \
--device=/dev/ttyUSB0 \
-e USER_ID=<uid_of_openhab> \
-e GROUP_ID=<gid_of_openhab> \
openhab/openhab:<version>-<architecture>-<distribution>
openhab/openhab:<version>-<distribution>
ExecStop=/usr/bin/docker stop -t 2 %n ; /usr/bin/docker rm -f %n
[Install]
WantedBy=multi-user.target
```
Where `<uid>` is the user ID number for the `openhab` user which you can obtain using the command `id openhab`, `<version>` is the version of openHAB, `<architecture>` is the architecture of your system and `<distribution>` is the base system (debian or alpine).
Where `<uid>` is the user ID number for the `openhab` user which you can obtain using the command `id openhab`, `<version>` is the version of openHAB and `<distribution>` is the base system (debian or alpine).
It is important that the ID number is passed in.
The ID for the `openhab` user inside the container will not match the ID of the user on your host system and file permissions may be a bit odd (e.g. why does www-data own my openHAB config files?).
@ -180,8 +179,8 @@ Note, always review the README on [Docker Hub](https://hub.docker.com/r/openhab/
- `-v /opt/openhab/.java:/openhab/.java` : needed by the Nest 1.x binding (and others?), location of the security token
- `--device=/dev/ttyUSB0` : location of my zwave controller, change and/or add more --device tags to pass all your devices needed by openHAB to the container
- `--restart=always` : if the container crashes or the system reboots the container is restarted
- `openhab/openhab:<version>-<architecture>-<distribution>` : name of the Docker Image
- `start_debug.sh` : You can start the container with the command ``docker run -it openhab/openhab:<version>-<architecture>-<distribution> ./start_debug.sh`` to get into the debug shell. You might need to mount additional volumes and parameters as described above.
- `openhab/openhab:<version>-<distribution>` : name of the Docker Image
- `start_debug.sh` : You can start the container with the command ``docker run -it openhab/openhab:<version>-<distribution> ./start_debug.sh`` to get into the debug shell. You might need to mount additional volumes and parameters as described above.
## Environment Variables
@ -212,10 +211,10 @@ Delete the container:
Pull down the latest image:
```bash
docker pull openhab/openhab:<version>-<architecture>-<distribution>
docker pull openhab/openhab:<version>-<distribution>
```
where `<version>` is the version of openHAB, `<architecture>` is your architecture and `<distribution>` is the base system (debian or alpine).
where `<version>` is the version of openHAB and `<distribution>` is the base system (debian or alpine).
Restart the container using the full command above.

13
installation/index.md
View File

@ -45,20 +45,19 @@ OpenJDK may also be used, but it has some [known limitations](https://community.
| Java Platform | Advantages | Disadvantages |
|---------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Zulu](https://zulu.org/download/?show=all) | Completely open source, fully certified Java SE compliant build of OpenJDK, embedded version optimized for ARM devices [available here](http://www.azul.com/downloads/zulu-embedded/) | |
| [Azul Zulu](https://www.azul.com/downloads/) | Completely open source, fully certified Java SE compliant build of OpenJDK, embedded version optimized for ARM devices [available here](https://www.azul.com/downloads/zulu-embedded/) | |
| [Oracle Java](https://java.com/en/) | Full openHAB support on all platforms | [Licensing restrictions](https://blog.takipi.com/running-java-on-docker-youre-breaking-the-law/), manual installation required on many Linux systems: [Ubuntu](https://help.ubuntu.com/community/Java), [Mint](https://community.linuxmint.com/tutorial/view/1091), and [Debian](https://wiki.debian.org/Java/Sun) are some examples |
| [OpenJDK](http://openjdk.java.net) | Supported by many Linux distributions, packages [typically available](http://openjdk.java.net/install/index.html) | [Performance issues](https://github.com/openhab/openhab-distro/issues/10#issuecomment-223786506) on ARM platforms, [compatibility issues](https://community.openhab.org/t/openhab-is-offline-message-fixed/17441/8) with certain bindings and certificates |
| [AdoptOpenJDK](https://adoptopenjdk.net) | Open Source JDK backed by many large companies | |
Please download and install the **Java 8** version of the JVM.
openHAB does not work well with newer Java versions such as Java 9 or Java 11.
openHAB 3 will use Java 11 and you *can* go for it with 2.X, too, but be aware that although developers are working hard to make this work, there might be problems with the oldest parts of openHAB such as some of the v1 bindings due to non-backward compatible changes in Java 11.
The **64-bit version** of the JVM is recommended on platforms using a 64-bit OS and an Intel or AMD processor.
The **32-bit version** of the JVM is recommended on ARM platforms such as the Raspberry Pi.
The 32-bit JVM performs better on the ARM platform and some add-ons use libraries that do not work with a 64-bit JVM on the ARM platform.
The 32-bit JVM performs better on the ARM platform. Some add-ons use libraries that do not work with a 64-bit JVM on ARM.
For best compatibility, namely with the openHAB Cloud service [myopenhab.org](http://www.myopenhab.org) and the [Eclipse IoT Marketplace]({{base}}/configuration/eclipseiotmarket.html), the minimum recommended Java 8 revision is "161".
Attention: Most package managers serve an **older revision**.
For best compatibility, namely with the openHAB Cloud service [myopenhab.org](https://www.myopenhab.org) and the [Eclipse IoT Marketplace]({{base}}/configuration/eclipseiotmarket.html), the minimum recommended Java 8 revision is "161".
Check your current Java version by opening a command line console and typing `java -version`:
```text
@ -73,7 +72,7 @@ Before you can start, two decisions have to be made:
1. openHAB 2 is available as a platform independent archive file or through a package repository:
- **Manual setup:** Download and extract a platform independent zip archive: [macOS](macos.html), [Windows](windows.html), [Linux](linux.html#manual-installation)
- **Package setup:** Install though a package repository, including automatic updates.
- **Package setup:** Install through a package repository, including automatic updates.
This option is only available for Debian or Ubuntu derivatives and the recommended choice: [Linux (apt/deb)](linux.html#package-repository-installation)
2. Stable release or cutting edge:

6
installation/linux.md
View File

@ -49,7 +49,7 @@ openHAB 2 can be installed through
The installation through the **openHABian project** and the use of the provided openHABian configuration tool is recommended for end users.
Installing using the provided **package repository** (using `apt`, `apt-get`, `yum` or `dnf`) is easier, but requires more manualconfiguration later on due to the missing openHABian configuration tool.
Installing using the provided **package repository** (using `apt`, `apt-get`, `yum` or `dnf`) is easier, but requires more manual configuration later on due to the missing openHABian configuration tool.
The manual installation through a platform independent archive file is suited for users who know what they are doing.
@ -679,7 +679,7 @@ Please contact the community forum for more detailed information regarding indiv
### Java Network Permissions
The Java Virtual Machine hosting openHAB is restricted in it's permissions to interact on network level for security reasons.
The Java Virtual Machine hosting openHAB is restricted in its permissions to interact on network level for security reasons.
Some openHAB add-ons, like the Network or AmazonDash bindings, need elevated permissions to work.
If needed, grand these permissions by executing the following command:
@ -697,7 +697,7 @@ The [openHAB VS Code Extension]({{base}}/configuration/editors.html#openhab-vs-c
We will now guide you through the Samba network shares setup process.
Start by installing Samba.
Afterwards open it's configuration file in your favorite editor:
Afterwards open its configuration file in your favorite editor:
```shell
sudo apt-get install samba samba-common-bin

23
installation/pine.md
View File

@ -1,23 +0,0 @@
---
layout: documentation
title: PINE A64
---
{% include base.html %}
# Pine A64
The [PINE A64](https://www.pine64.org/?page_id=1194) is a young but promising single-board computer (SBC) on the market.
The project started off as a [Kickstarter campaign](https://www.kickstarter.com/projects/pine64/pine-a64-first-15-64-bit-single-board-super-comput) back in December 2015.
The Pine A64 is powered by Quad-Core ARM Cortex A53 64-Bit Processor.
![Pine A64](images/pine64.png)
Please visit the [official homepage](https://www.pine64.org) and [wiki](http://wiki.pine64.org/index.php/Main_Page) for more information and details.
## Recommended Setup
We are proud to provide a system image for the Pine A64, including the latest version of openHAB 2 and many recommended settings and useful software additions.
The image is based on the official [Ubuntu Base Image by longsleep](http://wiki.pine64.org/index.php/Pine_A64_Software_Release) and developed and maintained by the openHABian project.
Check out more details about [openHABian, the hassle-free openHAB setup](openhabian.html).

168
installation/security.md
View File

@ -29,7 +29,7 @@ In an apt installation, you would best do this in the file `/etc/default/openhab
### SSL Certificates
On the very first start, openHAB generates a personal (self-signed, 256-bit ECC) SSL certificate and stores it in the Jetty keystore (in `${USER_DATA}etc/keystore`).
On the very first start, openHAB generates a personal (self-signed, 256-bit ECC) SSL certificate and stores it in the Jetty keystore (in `$OPENHAB_USERDATA/etc/keystore`).
This process makes sure that every installation has an individual certificate, so that nobody else can falsely mimic your server.
Note that on slow hardware, this certificate generation can take up to several minutes, so be patient on a first start - it is all for your own security.
@ -101,6 +101,7 @@ The good news is that [openHABian](openhabian) already offers the possibility to
- [Redirecting HTTP Traffic to HTTPS](#nginx-httpredirect)
- [Putting it All Together](#nginx-summary)
- [Additional HTTPS Security](#nginx-https-security)
- [Configuration on Synology DiskStation](#synology-remote-config)
- [Further Reading](#nginx-further-reading)
{: #nginx-setup}
@ -234,12 +235,12 @@ These lines are placed in the `location{}` block. For example, by adding the lin
```nginx
satisfy any;
allow 192.168.0.1/24;
allow 192.168.0.0/24;
allow 127.0.0.1;
deny all;
```
NGINX will allow anyone within the 192.168.0.1/24 range **and** the localhost to connect without a password.
NGINX will allow anyone within the 192.168.0.0/24 range **and** the localhost to connect without a password.
If you have setup a password following the previous section, then the rest will be prompted for a password for access.
{: #nginx-domain}
@ -251,7 +252,7 @@ To generate a trusted certificate, you need to own a domain. To acquire your own
|:-------------------------------- |:------------- |:---- |
| Purchasing a domain name | [GoDaddy](http://www.godaddy.com), [Namecheap](http://www.namecheap.com), [Enom](http://www.enom.com), [Register](http://www.register.com) | You should have an IP adress that doesn't change (i.e. fixed), or changes rarely, and then update the DNS *A record* so that your domain/subdomain to point towards your IP. |
| Obtaining a free domain | [FreeNom](http://www.freenom.com) | Setup is the same as above. |
| Using a "Dynamic DNS" sevice | [No-IP](http://www.noip.com), [Dyn](http://www.dyn.com/dns) | Uses a client to automatically update your IP to a domain of you choice, some Dynamic DNS services offer a free domain too. |
| Using a "Dynamic DNS" sevice | [No-IP](http://www.noip.com), [Dyn](http://www.dyn.com/dns), [FreeDNS](http://freedns.afraid.org) | Uses a client to automatically update your IP to a domain of you choice, some Dynamic DNS services (like FreeDNS) offer a free domain too. |
{: #nginx-https}
#### Enabling HTTPS
@ -417,7 +418,7 @@ server {
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
satisfy any;
allow 192.168.0.1/24;
allow 192.168.0.0/24;
allow 127.0.0.1;
deny all;
auth_basic "Username and Password Required";
@ -430,6 +431,163 @@ server {
}
}
```
{: #synology-remote-config}
#### Configuration on Synology DiskStation
Synology DSM (as of 6.2) has the ability to automatically acquire certificates from Let's Encrypt and renew them every 90 days as required.
The majority of the configuration mentioned above can be completed through the DSM GUI, but SSH access is required to implement authentication (**authentication is essential for remote access to your openHAB instance**).
Before you continue, make sure you have the below conditions:
- A working installation of openHAB on your DiskStation (see the [Synology Installation Guide](https://www.openhab.org/docs/installation/synology.html/))
- Your own domain you can configure the CAA record for (see [Setting up a Domain](#nginx-domain))
- Access to your DiskStation by SSH ([How to login to DSM with root permission via SSH/Telnet](https://www.synology.com/en-global/knowledgebase/DSM/tutorial/General_Setup/How_to_login_to_DSM_with_root_permission_via_SSH_Telnet/))
- Ports 80 and 443 forwarded from your router to your DiskStation (make sure you reconfigure the router web UI to a different port first, so you don't lose access!)
Log into the GUI of your DiskStation as administrator, and open the package center.
Install Apache HTTP Server.
This is needed to generate the password files.
Go to Control Panel > Application Portal > Reverse Proxy. We will set up two reverse proxies, one for HTTP and one for HTTPS.
The HTTP one can be disabled later if desired (not at all essential if you will only use the app remotely, and never a browser).
Create two reverse proxies as follows:
| Parameter | Value |
|:------------------------- |:--------------- |
|Description: |openHAB HTTPS |
|Source Protocol: |HTTPS |
|Source Hostname: |your-hostname.com|
|Source Port: |443 |
|Enable HSTS |Unchecked |
|Enable HTTP/2 |Unchecked |
|Enable access control |Unchecked |
|Destination Protocol: |HTTPS |
|Destination Hostname: |localhost |
|Destination Port: |8443 (or whichever HTTPS port your openHAB instance is on)|
| Parameter | Value |
|:------------------------- |:--------------- |
|Description: |openHAB HTTP |
|Source Protocol: |HTTP |
|Source Hostname: |your-hostname.com|
|Source Port: |80 |
|Enable HSTS |Unchecked |
|Enable HTTP/2 |Unchecked |
|Enable access control |Unchecked |
|Destination Protocol: |HTTP |
|Destination Hostname: |localhost |
|Destination Port: |8080 (or whichever HTTP port your openHAB instance is on)|
Verify that the reverse proxy is working as expected - try http://your-hostname.com and https://your-hostname.com - you should end up at the openHAB landing page in both cases, but will get a security warning for the https site.
Next, acquire certificates from Let's Encrypt using the GUI in DSM.
Go to Control Panel > Security > Certificate, and click on 'Add'.
Select the option to 'Add a new Certificate'.
Put in a description, something like 'openHAB SSL Cert' (it doesn't matter).
Select 'Get a certificate from Let's Encrypt' and check the box to set it as default.
Click next.
Put in your domain name and email address.
Add a 'Subject Alternative Name' if you want a different topic in the subject line when Let's Encrypt email you about that certificate (not essential).
Click Apply, and wait a few minutes - your certificate is done!
::: tip Note
Sometimes you may receive an error at the end of the certificate wizard - the first time this happens, click on 'cancel and see if you have a certificate anyway.
If the certifcate has been generated, you are good to go.
:::
Select the certificate that has just been created, and click on 'Configure'.
Ensure that the new certificate is listed next to your-hostname.com in the table - something like the below.
If it's not selected, update it.
| Services | Certificate |
|:------------------------- |:--------------- |
|your-hostname.com |your-hostname.com|
|FTPS |synology.com |
|Cloud Station Server |synology.com |
|etc etc |synology.com |
Once this is done, update the CAA record for your-hostname.com with your registrar (exact process will vary by registrar).
Within an hour or so, you should not receive the security warning for https://your-hostname.com.
Next, you must add authentication to the reverse proxy.
There's no GUI way to do this, so we need to create another small NGINX virtual host on the DiskStation.
Log into your DiskStation by SSH.
Use the admin username and password.
Create a .htpasswd file in your openHAB userdata folder (your userdata location may vary, update accordingly):
```shell
htpasswd -c /volume1/SmartHome/openHAB/userdata/.htpasswd username
```
Next, add a very simple NGINX configuration similar to that created above, but without the SSL parameters.
DSM comes with vi installed by default, but you may wish to [install nano](https://anto.online/other/how-to-install-nano-on-your-synology-nas/)
```shell
sudo nano /usr/local/etc/nginx/sites-enabled/openHAB-auth
```
```nginx
# OpenHab NGINX config
server {
listen 2020; #This is simply an unused port, it can be any number
server_name dow-family-adsl.ddns.net;
return 301 https://$server_name$request_uri;
}
server {
listen 7443 ssl; #This is simply an unused port, it can be any number
server_name dow-family-adsl.ddns.net;
location / {
proxy_pass https://localhost:8443/; #Update the port number if needed
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-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
satisfy any;
allow 192.168.1.0/24;
allow 127.0.0.1;
deny all;
auth_basic "Username and Password Required";
auth_basic_user_file /volume1/SmartHome/openHAB/userdata/.htpasswd; #Update with your userdata folder if different
}
}
```
Once you are done, save the file, restart and test NGINX:
```shell
sudo nginx -s reload && sudo nginx -t
```
As above, the first part of the file redirects any HTTP queries to HTTPS directly.
If you don't get any errors, update the reverse proxy settings in the DSM GUI to point to these new endpoints.
Back in the GUI, go to Control Panel > Application Portal > Reverse Proxy, make the updates below:
| Parameter | Value |
|:------------------------- |:--------------- |
|Destination Port: |7443 (or whatever you set it to in the openHAB-auth file)|
| Parameter | Value |
|:------------------------- |:--------------- |
|Destination Port: |2020 (or whatever you set it to in the openHAB-auth file)|
::: tip Note
We do this 'double' redirect to take advantage of the GUI certificate handling in DSM - this is the equivalent of CertBot for a linux installation.
:::
Give it a try again - you should now get redirected to https://your-hostname.com from http://your-hostname.com, and should receive a username and password prompt before you see the openHAB landing page.
If you need to troubleshoot the nginx server, SSH into your DiskStation, and check the NGINX error log:
```shell
sudo tail -f /var/log/nginx/error.log
```
This log will update in real-time, so do whatever it was that you were having issues with again, and you'll see the error.
{: #nginx-https-security}
#### Additional HTTPS Security

1
installation/windows.md
View File

@ -156,6 +156,7 @@ By installing the openHAB process as a service in Windows, you can:
wrapper.java.additional.17=-Dorg.osgi.service.http.port.secure=8443
wrapper.java.additional.18=-Djava.util.logging.config.file="%KARAF_ETC%\java.util.logging.properties"
wrapper.java.additional.19=-Dkaraf.logs="%OPENHAB_LOGDIR%"
wrapper.java.additional.20=-Dfile.encoding=UTF-8
wrapper.java.maxmemory=512
# Wrapper Logging Properties

40
introduction.md
View File

@ -46,12 +46,12 @@ Here are some key considerations especially for new users. To be successful, you
Remember, openHAB is just a computer program.
The computer will only do what *you* tell it to do.
openHAB can provide many default solutions that are easy to setup.
On the flip side, the more you insist that everything should look and work exactly as you want it, the more work you will have to do.
On the flip side, the more you insist that everything should look and work exactly the way you want it, the more work you will have to invest.
openHAB is fully customizable, but doing so will require substantial effort on your part.
After you have read the documentation for openHAB, you will have:
* Identified on which computer you will run openHAB
* Identified a computer on which to run openHAB
* Learned how to install openHAB, as well as all other software that is needed to run openHAB (e.g., JAVA)
* Learned how your smart devices communicate with openHAB; how to make openHAB give commands to your smart devices; and how you can interact with openHAB
@ -65,7 +65,7 @@ But this may not be a problem as you are reading the documentation of software t
Lastly, be prepared to start a new hobby: home automation.
Basic functions can be achieved in openHAB rather quickly, e.g., switch lights on at a certain time.
Others will require much more efforts and thoughts, e.g., how do I determine that someone is home, including guests, but not counting pets?
Others will require much more effort and thought, e.g., how do I determine that someone is home, including guests, but not counting pets?
The openHAB forum is a great place to learn and discuss.
## A Quick Overview
@ -89,7 +89,7 @@ All the above [Concepts]({{base}}/concepts/index.html) are explained in more dep
### Channels
Channels are for the logical link of a [Thing]({{base}}/concepts/things.html) to an [Item]({{base}}/concepts/items.html).
Channels are the logical link between a [Thing]({{base}}/concepts/things.html) and an [Item]({{base}}/concepts/items.html).
Channels originate from [Things]({{base}}/concepts/things.html) definition and define how your [Thing]({{base}}/concepts/things.html) can communicate with [Item]({{base}}/concepts/items.html) (and vice versa).
You will create channels when defining your [Thing]({{base}}/concepts/things.html).
@ -102,7 +102,7 @@ Bindings are software packages that are installed by the user in openHAB.
The main purpose of Bindings is to establish the connection between your device and your [Thing]({{base}}/concepts/things.html).
Bindings communicate with your device and translate all commands to and from openHAB between your device and your [Thing]({{base}}/concepts/things.html).
Bindings are provided at the [Add-on section](https://www.openhab.org/addons/) of this website.
Bindings are provided in the [Add-on section](https://www.openhab.org/addons/) of this website.
Here you will find a searchable list of several hundred bindings to support as many devices as possible.
New bindings are regularly added as developers integrate more devices into openHAB.
@ -121,19 +121,21 @@ If you have a strong preference towards a particular platform, then that platfor
You can install openHAB on your desktop computer for evaluation purposes if you already have any of these systems available for use, but we recommend using a dedicated system in the long run.
If you feel serious about home automation it may be better to start with a dedicated system right away.
For anyone undecided: many people find that the simplest way to experiment with openHAB is to get a [Raspberry Pi (Version 4 with 2 or 4 GB for the best experience, but a RPi 2 or 3 is fine, too)](https://raspberrypi.org) and install [openHABian]({{base}}/installation/openhabian.html); a "hassle-free openHAB setup".
If you have no strong preference, get a [Raspberry Pi 4](https://www.raspberrypi.org/products/raspberry-pi-4-model-b/) with 2 GB and a 16 GB SD card and install [openHABian]({{base}}/installation/openhabian.html) for the best experience.
A RPi 2 or 3 is fine, too, but a RPi4/8GB is overkill, as are larger SD cards.
While openHABian offers a streamlined and simplified way to get up and running quickly, it is a complete openHAB home automation system easily capable of automating your entire home.
However, it is worth noting two potential limitations of Raspberry Pis:
RPi 3 and older are limited in RAM (1 GB of memory or less) and may not perform well when additional memory hungry applications such as databases and data visualization programs are installed.
It is worth noting two potential limitations of Raspberry Pis, however:
RPi 3 and older are limited in RAM (1 GB of memory or less) and may not perform well when additional memory hungry applications such as databases and data visualization programs are being used.
Two or more GB should be fine.
Running Raspberries off the internal SD card only may result in system instabilities as these memory cards can degrade quickly under openHAB's use conditions.
If you choose to deploy openHABian, there's the ZRAM feature available to mitigate.
Running Raspberries off the internal SD card only may result in system instabilities as these memory cards can degrade quickly under openHAB's use conditions (infamous 'wearout').
When you choose to deploy openHABian, there's the ZRAM feature available to mitigate.
Once you have openHAB up and running, the [Configuration]({{base}}/configuration/index.html) article contains everything you need to know to get your openHAB installation talking to different devices around your home.
You will quickly discover that you may want to learn more about Things, Channels, Items, and more.
To do so, we highly recommend that you read the next chapter titled [Concepts]({{base}}/concepts/index.html).
It provides a more in-depth descriptions of Things, Items, Bindings, etc. that will help you as you dive deeper into openHAB.
It provides more in-depth descriptions of Things, Items, Bindings, etc. that will help you as you dive deeper into openHAB.
The amount of information provided here can be overwhelming, so please come back to these sections often as you develop your home automation system.
@ -149,15 +151,15 @@ It is an active and responsive community of experienced users who generally resp
Remember that openHAB is an open-source development, driven exclusively by volunteers.
Please be kind and courteous, it will be most appreciated by those that will try to help you.
In many occasions, you will notice that your problem has already been raised by others; and discussed and resolved by the community before.
You can search previous conversations and issues to see if your question has already been answered.
It is best practice and generally considered to be good etiquette to check fairly thoroughly before posting your own question.
In many occasions, you will notice that your problem has already been raised, discussed and resolved by the community before.
You can search previous conversations and issues to see if your questions have already been answered.
It is best practice and generally considered to be good etiquette to check fairly thoroughly before posting an own question.
If it is your first time posting a question, please read [How to help us helping you](https://community.openhab.org/t/how-to-ask-a-good-question-help-us-help-you/58396) for information on what information you will need to provide.
If it is your first time posting a question, please read [How to help us help you](https://community.openhab.org/t/how-to-ask-a-good-question-help-us-help-you/58396) to see what information you will need to provide with your post.
## Putting it into Practice
Once you are getting a first overview, it is time to practice.
Once you have got a first overview, it is time to practice.
Here a short list of the steps that you will need to consider to get openHAB up and running as your home automation system:
1. Install openHAB
@ -175,10 +177,10 @@ But remember, there is always more than one way to achieve your goal in openHAB.
A final word for the DIY enthusiasts. openHAB is very flexible and can support many DIY devices.
However, you will quickly realize that DIY often literally means that you _"do it yourself"_.
Working with DIY solutions often requires a deeper level of understanding, as well as more patience and perseverance than the integration of ready-to-use devices from commercial providers.
The choice is yours of course, but you will need to be prepared spending either money or time (and sometimes both) to make your home automation goals a reality.
The choice is yours of course, but you will need to be prepared to spend either money or time (and sometimes both) to make your home automation goals a reality.
And quite often, the investment will be significant.
Don’t give up, openHAB is very powerful and flexible and most likely can help you achieve your home automation goals, whichever they are.
Don’t give up, openHAB is very powerful and flexible and will help you achieve your home automation goals, whatever they are.
But it comes with a rather steep learning curve.
## A Deeper Dive: openHAB Structure for Advanced Users
@ -189,6 +191,6 @@ openHAB 2 is developed in [Java](https://www.java.com/) and uses [OSGi](https://
openHAB is highly modular software that can be extended through "Add-ons".
Add-ons give openHAB a wide array of capabilities, from User Interfaces, to the ability to interact with a large and growing number of physical Things.
Add-ons may come from the openHAB 2 distribution, the legacy openHAB 1 distribution or from any other external source.
Add-ons may come from the openHAB 2 distribution, the legacy openHAB 1 distribution or from other external sources.
If you are new to openHAB, we suggest you continue to the [Concepts]({{base}}/concepts/index.html) chapter where we introduce many fundamental ideas that are used throughout openHAB.

2
tutorials/beginner/1sttimesetup.md
View File

@ -7,7 +7,7 @@ layout: tutorial-beginner
# First-time setup of openHAB
When you start openHAB for the first time, it only starts the dashboard.
So let's have a look at it: open a browser and browse to you openHAB dashboard:
So let's have a look at it: open a browser and browse to your openHAB dashboard:
<http://IP-of-your-machine:8080>

231
tutorials/beginner/configuration.md
View File

@ -7,162 +7,183 @@ layout: tutorial-beginner
# Configuration of openHAB
We left at the [start page]({{base}}/tutorials/beginner/1sttimesetup.html) before showing you the differences of the UIs.
Now click on the "PAPER UI" link and you will be taken to the "Inbox".
The inbox is the place where you can discover/add new "things" (i.e. Zwave devices, Hue lamps, network devices and so on).
Now click on the "PAPER UI" link and you will be taken to the ```Inbox```.
![](images/picture_04.jpg)
In order to be able to add new things, at first you must install the corresponding binding for that type of thing.
I.e. if you want to control your Zwave devices, you have to install the Zwave binding.
The ```Inbox``` is the place where you can discover/add new "things" such as Z-Wave devices, Hue lamps, network devices and many more.
![](images/inbox.png)
## Install bindings
In order to be able to add new things, at first you must install the corresponding binding for that type of thing.
If you want to control your Z-Wave devices, you have to install the Z-Wave binding.
If you want to control your Hue lamps, you have to install the Hue binding etc.
The installation is done on the "Add-ons" page in the left menu.
The installation is done on the ```Add-ons``` page in the navigation menu on the left.
![](images/picture_05.jpg)
![](images/addons.png)
You can scroll down and have a look at lots of bindings available for openHAB!
There are different sections within the __Add-ons__ page.
- ```ACTIONS``` contains add-ons that enable you perform actions such as sending a telegram message or a twitter message.
- ```BINDINGS``` contains add-ons that integrate physical hardware, external systems and web services in openHAB.
- ```MISC``` contains add-ons that "link" openHAB to other services. Like the openHAB cloud connector or the HUE emulation
- ```PERSISTENCE``` contains add-ons for data persistence. With this openHAB stores data over time which then can be retrieved later or you can display those data in a chart
- ```TRANSFORMATIONS``` contains add-ons that enable you to transform incoming or outgoing data from an item. e.g. if your sensor sends "1" when the door is open and "0" when the door is closed, you can use a transformation service to translate this so that "1" becomes "OPEN" and "0" becomes "CLOSED"
- ```USER INTERFACES``` contains add-ons for different user interfaces.
- ```VOICE``` contains add-ons for TTS (text-to-speech) services
Let's start with the "Network Binding", as this binding can be used in every setup from the start and will show you the basic configuration possibilities.
For now we continue with the section ```BINDINGS```.\
You will see that this list offers a wide variety of different bindings.
Let's continue with the __Network Binding__, as this binding can be used in every setup from the start and will show you the basic configuration possibilities.
With the network binding, you can define some of your network devices as things in order to use them in a rule for example, or just to see if they are online or offline and for how long.
Scroll down or use the "Search" field to find the "Network Binding".
Click on install, the binding will be downloaded and installed automatically.
![](images/picture_06.jpg)
Scroll down or use the __search field__ to find the __Network Binding__.<br/>
Click on __install__, and the binding will be downloaded and installed automatically.
![](images/picture_07.jpg)
![](images/install_binding_1.png)
Now that the binding is installed, switch back to the "Inbox".
If you click the "+"-button, you now are able to choose the binding which you want to use for discovering new things.
![](images/install_binding_2.png)
## Add things
Now that the binding is installed, switch back to the ```Inbox```.
If you click the "+" button, you now are able to choose the binding which you want to use for discovering new things.
Because we only installed the network binding so far, it's the only binding to choose.
![](images/picture_08.jpg)
![](images/add_thing_1.png)
As soon as you click on "Network Binding", the binding will start an automatic discovery of all (reachable) network devices in the same subnet as your openHAB installation resides in via ICMP (ping).
As soon as you click on "Network Binding", the binding will start an automatic discovery of all reachable network devices which are in the same subnet as the system running openHAB.
![](images/picture_09.jpg)
![](images/add_thing_2.png)
The discovered "things" are now displayed in the inbox, and you can decide what to do next:
- Add the device as a thing by clicking the check icon.
- Ignore the device by clicking the crossed-out-eye icon.
- Delete the device by clicking the trashcan icon.
| Icon | Meaning
| ------------- | ------------- |
| ![](images/check.png) | add the device as a thing |
| ![](images/ignore.png) | Ignore the device. The device will not be shown in the inbox anymore. By clicking on __SHOW IGNORED__ all ignored devices will be shown again |
| ![](images/delete.png) | Delete the device. The device will appear on the inbox with the next scan |
The difference between ignoring and deleting discovered things is as follows:
- If you ignore a thing, it disappears from the visible inbox.
If you decide to add it at a later time, you can do so by scrolling to the bottom of the inbox and click the "SHOW IGNORED" button.
- If you delete the thing, it won't be visible in the inbox any more.
But if you start a new discovery process later, the thing will reappear.
In this example, we only have one item with the IP ```192.168.139.130``` available. Click on the blue check icon to add the device.
In this example, we click on the check icon of the thing with the IP address 192.168.1.103.
Let's assume this is John's mobile phone which we want to use for presence detection.
We change the (automatically added during the discovery) name of the thing on the next page to "John's Mobile" and click on the "ADD AS THING" button.
We change the name of the thing - which was automatically added during the discovery - on the next page to "John's Mobile" and click on the ```ADD AS THING ``` button.
::: tip Note
If your network devices use a DHCP server to obtain ther IP addresses automatically, please make sure to define a DHCP reservation for a device which you want to use in openHAB.
Otherwise it's IP address may change in the future and your thing definiton won't work any more.
If your network devices use a DHCP server to obtain the IP addresses automatically, please make sure to define a DHCP reservation for a device which you want to use in openHAB.
Otherwise its IP address may change in the future and your thing definition won't work any more.
*Information about how to define a DHCP reservation can be normally be found in the manual of your network router.*
:::
![](images/picture_10.jpg)
![](images/add_thing_3.png)
Before we proceed, let's change one of the default system settings of openHAB to ease up the following processes.
You will see why in a moment.
Go to "Configuration -> System" via the menu on the left.
Here you can find the basic system properties of your openHAB installation.
Scroll down to "Item linking", activate the "Simple Mode" slider and click the "SAVE" button which appears afterwards.
You will notice afterwards that the "Items" menu item will be gone.
## Create items in simple mode
After creating the thing, you can access it via the ```Configuration --> Things``` page
There you will find all created things
![](images/picture_11.jpg)
![](images/create_item_simple_1.png)
Now back to your recently added thing.
Go to the "Configuration -> Things" page.
There you will find your network device thing, including the name "John's Mobile" which we defined above.
![](images/picture_12.jpg)
You can already see the status, "ONLINE", of the thing, so it's currently reachable by openHAB.
You can already see the status, "__ONLINE__", of the thing, so it's currently reachable by openHAB.
If you click on the name, you'll get to the next page showing the available channels of the thing.
Channels represent the different functions the items provide.
In this case you can see two channels: "Online" and "Time", the description below it says it all :)
Channels represent the different functions provided by the things and can be linked to items.
Those items then can be used to interact with the thing or read data from the things.
In our case you see
![](images/picture_13.jpg)
![](images/create_item_simple_2.png)
What is very important: The channels are not "linked" after the thing discovery.
Linking means to create an openHAB "item" which represents the state of a channel of a thing.
Because we activated the "Simple Mode" before, this can be done automatically by clicking the corresponding radio button left to the channel.
Otherwise you have to define the name of the item yourself.
On a fresh installation, __simple mode__ is enabled by default.
That means all available channels of the thing get automatically linked to items.
You can see that by the icon of each channel:
So we'll link both channels of the "John's Mobile" thing now by clicking the radio buttons.
| Icon | Meaning
| ------------- | ------------- |
| ![](images/linked.png) | this channel has already at least one item linked |
| ![](images/unlinked.png) | this channel has currently no linked item|
![](images/picture_14.jpg)
Since on our system, the simple mode is enabled, al our channels directly get linked to newly created items and thus you're' finished creating your thing.
Navigate to the ```CONTROL``` section and you should see the following:
For most of the bindings each thing can be configured further by clicking the pen-icon.
There you can edit the name again, chose a location (this is important for the "Control" menu item later) and, of course, change binding related options.
With the network binding for example, you can also change the IP address, the timeout, the refresh interval etc.
![](images/control_1.png)
![](images/picture_15.jpg)
::: tip Note
PaperUI is purely for administration purposes.
You see all things in the control section and can interact with them, but there's no customization possibility.
To create your own beautiful UIs you need to switch to the chapter [Creating a sitemap]({{base}}/tutorials/beginner/sitemap.html)
:::
You can save changed values by clicking the check icon at the top.
## Creating items manually
If you want to have more control over your items like
- item name
- item type (switch / contact /...)
Now that we linked the two channels in the previous step, we can have a look at the "Control" menu item at the top left.
On the "Control" page you can see all your linked items.
So far we added only one thing ("John's Mobile") and linked it's two channels, so that's all we see:
you need to disable __simple mode__ first.
To do this, navigate to ```Configuration --> System``` (1) and scroll down to the __Item Linking__ section.
Disable simple mode (2) and click on __SAVE__ (3) to apply the changes.
You also see that the navigation bar shows a new element called ```ITEMS``` (4)
![](images/picture_16.jpg)
![](images/disable_simple_mode.png)
With that, we can create now the items on our things manually.
To do that, go back to "John's Mobile".
You see that the previous items - which were created manually - remain untouched by disabling simple mode.
If you now click on the blue button before the channel name the you will see all items that are linked to this channel.
The highlighted item is the automatically created item when simple mode was switched on.
![](images/create_item_1.png)
You can also change this item by using the icons next to it:
| Icon | Description
| ------------- | ------------- |
| ![](images/pen.png) | edit item profile |
| ![](images/trash.png) | delete the item|
To add a new item click on the blue (+) icon next to the text __Linked items__.
![](images/create_item_2.png)
The popup asks you for a profile (leave it to __Default__) and by clicking on the empty line after *Please select the item to link*, you will have the possibility to create a new item by clicking on __"+ Create new item"__
![](images/create_item_3.png)
Fill out all the necessary data:
| Field | Description
| ------------- | ------------- |
| Name | The name of the new item. This name must be __UNIQUE__ |
| Label | This is the text label for the item. It will be used to display the item on the UIs.|
| Category | This can be chosen freely and will change the icon. e.g. if you select __faucet__ you will see a faucet instead of the power icon. See [Classic icons](https://www.openhab.org/docs/configuration/iconsets/classic/) in order see which icons you can use by default|
| Type | On some channels you can select different types. In this case you only __Switch__ is available. For more information see [Items]({{base}}/configuration/items.html)
After clicking ```LINK```, your item will be created and you will see it immediately on the control tab:
![](images/create_item_4.png)
Items which are linked to channels of the same thing are displayed together, represented by the thing's name.
Here you can see the state of the "Online" and the "Time" channel.
John's mobile is online, and the ping time is 10ms.
As you can see in the screenshot with the configuration parameters of the thing above, the refresh interval is set to 60000ms by default.
This means that openHAB pings the device every 60 seconds.
If you want to set a lower value there, feel free.
John's mobile is online, and the ping latency is 10ms.
**These are the basics to configure openHAB via Paper UI, meaning that the process is pretty much the same with other bindings.**
To demonstrate that, we'll proceed and install the Zwave binding in order to add Zwave things to openHAB.
## Changing parameters of the thing
**If you do not own a Zwave controller you won't be able to follow the next steps.
However, this is a demonstration about how to install and configure add-ons.
As mentioned before, the pure procedure to install and configure add-ons is mostly the same with other addons.**
For most of the bindings each thing can be configured further by clicking the pen-icon.
There you can edit the name again, choose a location (this is only for the "Control" menu item later) and, of course, change binding-related options.
With the network binding for example, you can change the IP address, the timeout, the refresh interval etc.
**More information about the Zwave binding and the other available bindings can be found [on the bindings page of the user manual](/addons/#bindings)!**
![](images/change_thing_parameters.png)
The installation is just like the example with the network binding above.
Use the "Add-ons" menu item, search for the "Zwave" binding, click "INSTALL" and go directly to the "Inbox" afterwards.
There, we click the "+" icon again and can now choose between the "Network Binding" and the "Zwave Binding".
You can save changed values by clicking the check icon at the top.
![](images/picture_17.jpg)
## Conclusion
Congratulations! In this chapter you have learned
- how to install a binding
- how to create a thing
- how to create items to interact with the thing
- the difference between items in simple mode and in manual mode
The difference to the network binding is, that we have to configure the Zwave controller first.
So we are taken directly to the Zwave controller config page after clicking on the "Zwave Binding" link.
Here we configure the port and basic settings and click the check icon afterwards.
![](images/picture_18.jpg)
openHAB immediately starts discovering Zwave things via the Zwave controller and shows them in the inbox.
This only happens if they already have been included.
If this is a completely new Zwave controller, you'll have to include your Zwave things first.
To set the controller into incusion mode, press the "+" icon again.
Please refer to the manual of your Zwave device in order to find out how the inclusion works there (most of the time it's pressing the tamper button thrice).
Let's assume we bought a new wallplug and included it, it's "Node 30".
For a simple sitemap and rule example on the next page, we'll configure this thing now:
![](images/picture_19.jpg)
![](images/picture_20.jpg)
![](images/picture_21.jpg)
Basically we gave the thing a name ("Wallplug TV") and linked the "Switch" channel.
Now we can see the wallplug (and the Zwave controller) on the "Control" page, too.
Its switch is currently turned off:
![](images/picture_22.jpg)
If you activate the slider of the wallplug, it will start routing power :)
**Your first action with openHAB!**
[On the next page]({{base}}/tutorials/beginner/sitemap.html), we will define a sitemap to create your own view of things and items.

BIN
tutorials/beginner/images/add_thing_1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 27 KiB

BIN
tutorials/beginner/images/add_thing_2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

BIN
tutorials/beginner/images/add_thing_3.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 45 KiB

BIN
tutorials/beginner/images/addons.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 55 KiB

BIN
tutorials/beginner/images/change_thing_parameters.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 44 KiB

BIN
tutorials/beginner/images/check.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.1 KiB

BIN
tutorials/beginner/images/control_1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 25 KiB

BIN
tutorials/beginner/images/create_item.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 48 KiB

BIN
tutorials/beginner/images/create_item_1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 48 KiB

BIN
tutorials/beginner/images/create_item_2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 51 KiB

BIN
tutorials/beginner/images/create_item_3.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 50 KiB

BIN
tutorials/beginner/images/create_item_4.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 29 KiB

BIN
tutorials/beginner/images/create_item_simple_1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

BIN
tutorials/beginner/images/create_item_simple_2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 58 KiB

BIN
tutorials/beginner/images/delete.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 271 B

BIN
tutorials/beginner/images/disable_simple_mode.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 47 KiB

BIN
tutorials/beginner/images/ignore.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 800 B

BIN
tutorials/beginner/images/inbox.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 23 KiB

BIN
tutorials/beginner/images/install_binding_1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 33 KiB

BIN
tutorials/beginner/images/install_binding_2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 33 KiB

BIN
tutorials/beginner/images/linked.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.2 KiB

BIN
tutorials/beginner/images/pen.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 357 B

BIN
tutorials/beginner/images/picture_04.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 28 KiB

BIN
tutorials/beginner/images/picture_05.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 56 KiB

BIN
tutorials/beginner/images/picture_06.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 37 KiB

BIN
tutorials/beginner/images/picture_07.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 36 KiB

BIN
tutorials/beginner/images/picture_08.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 28 KiB

BIN
tutorials/beginner/images/picture_09.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 44 KiB

BIN
tutorials/beginner/images/picture_10.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 56 KiB

BIN
tutorials/beginner/images/picture_11.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 43 KiB

BIN
tutorials/beginner/images/picture_12.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 59 KiB

BIN
tutorials/beginner/images/picture_13.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 83 KiB

BIN
tutorials/beginner/images/picture_14.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 84 KiB

BIN
tutorials/beginner/images/picture_15.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 104 KiB

BIN
tutorials/beginner/images/picture_16.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 41 KiB

BIN
tutorials/beginner/images/picture_17.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 69 KiB

BIN
tutorials/beginner/images/picture_18.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 46 KiB

BIN
tutorials/beginner/images/picture_19.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 35 KiB

BIN
tutorials/beginner/images/picture_20.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 52 KiB

BIN
tutorials/beginner/images/picture_21.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 112 KiB

BIN
tutorials/beginner/images/picture_22.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 84 KiB

BIN
tutorials/beginner/images/trash.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 360 B

BIN
tutorials/beginner/images/unlinked.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.1 KiB

2
tutorials/beginner/index.md
View File

@ -11,7 +11,7 @@ This part covers all the basics to use openHAB after you installed it: how to pe
The goal of this tutorial is to cover the first steps for new users.
After performing the first-time setup, you will learn how to install a very simple "binding", the "Network Binding".
A binding is an additional package for openHAB to be able to interact with all kinds of devices or situations.
To show you the use and configuration of a more complex binding, we'll guide you through the installation of the "Zwave Binding", a binding to control devices in a Zwave network.
To show you the use and configuration of a more complex binding, we'll guide you through the installation of the "Z-Wave Binding", a binding to control devices in a Z-Wave network.
At the end of this tutorial, you will be able to create a local sitemap and your first simple rules.
**This tutorial assumes that you already installed openHAB on your preferred system.

10
tutorials/beginner/logs.md
View File

@ -8,12 +8,12 @@ layout: tutorial-beginner
While using openHAB, you may need to look at the logs generated by the software to see if there are any issues that need your attention.
Two log files are going to interest us which are openhab.log and events.log
The events.log file contains what is happening on the Openhab event bus like sensors changing states, very handy for writting rules as you can see things changing in realtime.
The other file openhab.log shows the output of all bindings and addons and allows you to fault find issues with a binding.
Two log files which are going to interest us are openhab.log and events.log
The events.log file contains what is happening on the openHAB event bus like sensors changing states, very handy for writing rules as you can see things changing in realtime.
The other file, openhab.log, shows the output of all bindings and addons and allows you to fault find issues with a binding.
Before asking for help on the forum, it is worth checking openhab.log for clues as to what is causing any issues as this will result in getting help much faster.
To watch the logs in realtime with a openhabian based setup use the below linux command which can be done via SSH with a program called putty from a windows or mac machine.
To watch the logs in realtime with a openHABian-based setup use the below Linux command which can be done via SSH with a program called putty from a Windows or Mac machine.
CTRL+C will close the stream.
You can also use SAMBA/network shares to open or copy the file directly.
@ -23,7 +23,7 @@ tail -f /var/log/openhab2/openhab.log -f /var/log/openhab2/events.log
Bindings can have the level of detail increased or decreased on a per binding basis and this is done with the Karaf console.
To find them if you are not using Openhabian:
To find them if you are not using openHABian:
- open the finder,
- navigate to your home folder,

4
tutorials/beginner/rules.md
View File

@ -6,7 +6,7 @@ layout: tutorial-beginner
# Working with rules and scripts
Now that we have the two items - "Presence_Mobile_John" aka "Johns mobile" and "Wallplug_FF_LR_TV" aka "TV wallplug LR" - we can create a simple rule.
Now that we have the two items - "Presence_Mobile_John" aka "John's mobile" and "Wallplug_FF_LR_TV" aka "TV wallplug LR" - we can create a simple rule.
Let's assume we want to turn on the wallplug (and give some juice to the connected TV) as soon as John's mobile comes online, turn it off again when the mobile goes offline (this would be a very basic "presence" rule).
Rules are defined in the `$OPENHAB_CONF/rules` directory.
@ -59,7 +59,7 @@ The trigger conditions can be one of the following:
- Item triggers - just like in the example above. If the state of an item changes, do something
- Time triggers - do something at a specified time
- System triggers - do something after a system event happened, i.e. openHAB was started or is shut down
- System triggers - do something after a system event happened, e.g. openHAB was started or is shut down
**More information on rules can be found [in the rules section of the user manual!]({{base}}/configuration/rules-dsl.html)**

16
tutorials/beginner/sitemap.md
View File

@ -7,12 +7,12 @@ layout: tutorial-beginner
# Creating a sitemap
Controlling your things via Paper UI is nice, but currently you can sort them only by editing the "Location" in the thing configuration.
If you want to create your own view you can use a so called "sitemap" which can be displayed in the Basic UI (you remember, it was automatically installed at the beginning).
If you want to create your own view you can use a so-called "sitemap" which can be displayed in the Basic UI (you remember, it was automatically installed at the beginning).
But before that, you have to create an items file.
Both the items and the sitemap files are edited in your editor of choice.
The files' location is in the `$OPENHAB_CONF` directory, which is different on different operating systems.
See the linux installation instructions for the [file locations]({{base}}/installation/linux.html#file-locations) specific to linux, or the Windows [file locations]({{base}}/installation/windows.html#file-locations) specific to Windows.
See the Linux installation instructions for the [file locations]({{base}}/installation/linux.html#file-locations) specific to Linux, or the Windows [file locations]({{base}}/installation/windows.html#file-locations) specific to Windows.
macOS files are located in the same place as Linux files.
```bash
@ -23,7 +23,7 @@ $OPENHAB_CONF/sitemaps <-- *.sitemap files
After a fresh installation these directories are empty (except for the readme files), so you have to create a file there. We'll use "default.items" as the items file and "default.sitemap" as the sitemap file in this tutorial.
**In fact, you can have multiple .items files to sort your items logically, for example lamps.items, contacts.items, network.items etc.**
**As long as the file extension is .items, it's definitions will be loaded in openHAB. The same applies to .sitemap and .rules files as well**
**As long as the file extension is .items, its definitions will be loaded in openHAB. The same applies to .sitemap and .rules files as well**.
So we create the files:
@ -37,7 +37,7 @@ Let's start small.
Open the default.items file and define your first item:
```java
Switch Presence_Mobile_John "Johns Mobile" <network> { channel="network:device:192_168_1_103:online" }
Switch Presence_Mobile_John "John's Mobile" <network> { channel="network:device:192_168_1_103:online" }
```
::: tip Note
@ -55,7 +55,7 @@ The syntax is as follows:
ItemType ItemName "ItemDescription" <ItemIcon> { ItemToThingChannelLink }
```
You can find a detailled overview of the different item types [here]({{base}}/configuration/items.html)
You can find a detailed overview of the different item types [here]({{base}}/configuration/items.html)
In this example we use "Switch" as the item's type. This results in a slider which is either turned on or turned off.
@ -107,10 +107,12 @@ Next comes the block with the actual items you want to show on your sitemap. Her
The syntax is again pretty straight:
```bash
ItemType item=ItemName label="Description of the item shown on the webpage"
ElementType item=ItemName label="Description of the item shown on the webpage"
```
where ItemType and ItemName must be the same as defined in default.items
where ItemName must be the same as defined in default.items
You can find a detailed overview of the different element types [here]({{base}}/configuration/sitemaps.html#element-types)
One last thing to do is setting the default sitemap for the "Basic UI" via "Paper UI".
Browse to "Configuration -> Services" in Paper UI and click the "Configure" button of Basic UI

10
tutorials/beginner/uis.md
View File

@ -10,19 +10,19 @@ openHAB offers different UIs in its standard configuration: the *Paper UI*, the
## The Paper UI
The Paper UI is an interface that helps setting up and configuring your openHAB instance.
The Paper UI is an interface that helps set up and configure your openHAB instance.
It does not (yet) cover all aspects, so you still need to resort to textual configuration files, but it already offers the following:
- Add-on management: Easily install or uninstall openHAB add-ons
![](images/picture_05.jpg)
![](/images/addons.jpg)
- Thing discovery: See devices and services found on your network and add them to your setup.
![](images//picture_09.jpg)
![](/images/add_thing_2.jpg)
- Linking items to channels: Instead of adding a binding configuration to your item file, you can directly link Thing channels to your items.
![](images//picture_21.jpg)
![](/images/linked.jpg)
Note that you still need to define your items, sitemaps, persistence configurations and rules in the according configuration files (as done in openHAB 1).
Note that you still need to define your items, sitemaps, persistence configurations and rules in the relevant configuration files (as done in openHAB 1).
Such functionality will be added bit by bit to the Paper UI only.
All these aspects are explained in the rest of this tutorial.