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

Resolve merge conflicts / Fix CI builds (#1472) 

* Apply bulk automated corrections. 🔧(#1433)

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

* Added sidebar links. (#1434)

* Added sidebar links.
* Introduce openhabian placeholder page.
* Remove local version of openhabian doc page.

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

* Fix linter errors 🔧(#1435)

* Fix errros for the addon folder.
* Fix errros for the administration folder.
* Fix errros for the concepts folder.
* Fix errros for the configuration folder.
* Improved and synced markdown linting rules.

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

* Revert #1428 (#1436)

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

* Fix linter errors. 🔧(#1437)

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

* Bulk edit linter errors. (#1438)

* Bulk edit linter errors.

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

* Fix linter style

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

* Fix linter errors (#1439)

* Some leftover linting error fixes.
* Adapt rules and enble markdownlint for pull requests.

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

* Fix markdownlint workflow

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

* Fixes for linter errors and markdown configuration. (#1440)

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

* Update guidelines.md (#1441)

Only a maintainer told me how to tackle a DTO properly as a class. As I did not see this anywhere, I decide to make this change.

* Add fixes from markdownlint-cli (#1442)

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

* Switch to markdown cli action (#1443)

* Fix left markdownlint errors.

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

* Change to markdownlint-cli action.

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

* Update markdownlint.yml

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

* Move trigger order

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

* Make pr check available for markdownlint 📝 (#1446)

* Make pr check available for markdownlint (hopefully).
Signed-off-by: Jerome Luckenbach <github@luckenba.ch>

* Add link check action. (#1449)

* Add link check action.

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

* Add blank line.

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

* Replace local urls with inline code. Change one occurence to openhabian. (#1450)

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

* remove uncessary instructions f. contribution guide (#1454)

* Update items.md (#1455)

Example with item Switch Kitchen_Light in the example is not correct for current binding version.

* Created API token docs (#1453)

* Created API token docs

Signed-off-by: Gerwin Lammers <gerwinlammers@gmail.com>

* Update after review session

Signed-off-by: Gerwin Lammers <gerwinlammers@gmail.com>

* Add new page to sidebar navigation.

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

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

* Update rules-dsl.md (#1456)

* Update rules-dsl.md

Corrected the "system started" section to reflect that the trigger will no longer execute on loading the rules file in OH v.3.

* Adapt inline codeblock design.

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

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

* Remove paper ui references. (#1457)

* Remove paper uii references.

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

* Fix Markdown errors.

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

* Remove target param from markdownlint pr trigger.

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

* Update items.md (#1458)

There is one comma too much in the sample for profile hysteresis. The profile must be related to the channel. The comma will lead also to an error message in log.
Switch Low_Battery { channel="serialbutton:button:mybutton:battery-level" [profile="hysteresis", lower=15, inverted=true] }

* Remove cronmaker since it doesn't support HTTPS (#1459)

1. When trying to reach https://www.cronmaker.com/ the website refuses the connection. You can only reach it using HTTP (without HTTPS). 
You could leave cronmaker in there but I think leading users to web pages that aren't using HTTPS might be not be best idea.

2. Fix Typo in url for quartz-scheduler.org

* Update links to target "main" branches (#1460)

* Update links to target "main" branches

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

* Update process_file.rb

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

* Update for all other repos too

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

* Add hint that /etc/default/openhab2 is not considered by the upgrade (#1461)

* Add hint that /etc/default/openhab2 is not considered by the upgrade 

When you use a raspberry you may have used the file /etc/default/openhab2 to changed JAVA options.
After upgrade to openHAB 3.0 this file is no longer used. Instead the file /etc/default/openhab must be used.

* Small modifications to original pull request.

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

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

* Fix typo in restdocs (#1463)

* Update rules-dsl.md (#1465)

Updated the rule example "Start wake up light on sunrise" to use the new formatting of the receivedEvent implicit variable

* Update list of system default channel types (#1467)

Related to https://github.com/openhab/openhab-core/pull/2069
Related to https://github.com/openhab/openhab-core/pull/2157

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

* Delete habpanel.md (#1471)

* Delete habpanel.md

This file is gathered from its code repository for a long time already.
Signed-off-by: Jerome Luckenbach <github@luckenba.ch>

* Add habpanel placeholder for preview

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

Co-authored-by: coop-git <65073745+coop-git@users.noreply.github.com>
Co-authored-by: J-N-K <J-N-K@users.noreply.github.com>
Co-authored-by: sancho-sumy <59047465+sancho-sumy@users.noreply.github.com>
Co-authored-by: Gerwin Lammers <59145105+lampy2@users.noreply.github.com>
Co-authored-by: dathbe <github@beffa.us>
Co-authored-by: thefechner <76476432+thefechner@users.noreply.github.com>
Co-authored-by: Felix Schneider <45742226+Trysupe@users.noreply.github.com>
Co-authored-by: Wouter Born <github@maindrain.net>
Co-authored-by: BertramVielsack <53342169+BertramVielsack@users.noreply.github.com>
Co-authored-by: mueller-ma <mueller-ma@users.noreply.github.com>
Co-authored-by: lukiep111 <lukiep@outlook.com>
Co-authored-by: Christoph Weitkamp <github@christophweitkamp.de>
pull/1569/head
Jerome Luckenbach 2021-01-29 16:25:42 +01:00 committed by GitHub
parent 2002490012
commit a7ef0879be
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
88 changed files with 1070 additions and 1993 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
.github/markdownStyle.rb vendored
View File

@ -1,19 +0,0 @@
all
# Expect dash usage for unorderd lists
rule 'MD004', :style => :dash
# Allow trailing spaces
exclude_rule 'MD009'
# Allow long line lengths
exclude_rule 'MD013'
# Allow Multiple top level headers in the same document
exclude_rule 'MD025'
# Allow inline HTML
exclude_rule 'MD033'
# Allow Frontmatter and exclude top level header on first line rule
exclude_rule 'MD041'

18
.github/workflows/brokenLinkCheck.yml vendored Normal file
View File

@ -0,0 +1,18 @@
name: Check for broken links
# https://github.blog/2020-08-03-github-actions-improvements-for-fork-and-pull-request-workflows/
on:
push:
branches:
- main
jobs:
markdown-link-check:
name: Check for broken links
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@master
- uses: gaurav-nelson/github-action-markdown-link-check@v1

27
.github/workflows/markdownlint.yml vendored
View File

@ -1,16 +1,22 @@
name: Linting
name: Checking Markdown For Errors
# https://github.blog/2020-08-03-github-actions-improvements-for-fork-and-pull-request-workflows/
on:
push:
branches:
- 'main'
- '2.5.x'
- main
- 2.5.x
tags-ignore:
- '**'
# pull_request:
# branches:
# - main
# types: [open,synchronize,reopen]
pull_request:
branches:
- main
types:
- open
- synchronize
- reopen
jobs:
markdownlint:
@ -20,7 +26,8 @@ jobs:
- name: Check out code
uses: actions/checkout@v2
- name: Run markdownlint (mdl)
uses: bewuethr/mdl-action@v1.0.12
- name: Run markdownlint-cli
uses: Confectrician/github-action-markdown-cli@v2.0.0
with:
style-file: .github/markdownStyle.rb
files: .
config_file: ".markdownlint.yaml"

7
.markdownlint.json
View File

@ -1,7 +0,0 @@
{
"default": true,
"MD004": { "style": "dash" },
"MD013": false,
"MD025": false,
"MD029": { "style": "one" }
}

27
.markdownlint.yaml Normal file
View File

@ -0,0 +1,27 @@
default: true
# Expect dash usage for unorderd lists
MD004:
style: dash
# Allow long line lengths
MD013: false
# Allow duplicate headers for different nesting
MD024:
allow_different_nesting: true
# Allow Multiple top level headers in the same document
MD025: false
# Allow trailing punctuation in headers
MD026: false
MD029:
style: one
# Allow inline HTML
MD033: false
# Code block style
MD046:
style: fenced

8
.vuepress/add_placeholders.rb
View File

@ -3,19 +3,21 @@
def add_placeholder_pages()
puts ">>> Adding placeholder pages for preview"
[
"addons/integrations/homekit",
"docs/apps/android.md",
"docs/configuration/iconsets/classic",
"docs/configuration/ui/habmin",
"docs/configuration/ui/habot",
"docs/configuration/ui/habpanel",
"docs/configuration/ui/basic",
"docs/configuration/ui/classic",
"docs/ecosystem/alexa",
"docs/ecosystem/google-assistant",
"docs/ecosystem/ifttt",
"docs/ecosystem/mycroft",
"addons/integrations/homekit",
"docs/installation/openhabian.md",
"link/homekit",
"link/openhabcloud",
"docs/apps/android.md"
"link/openhabcloud"
].each { |path|
puts " -> #{path}"
page = path

4
.vuepress/docs-sidebar.js
View File

@ -84,14 +84,16 @@ module.exports = [
'configuration/habpanel',
['configuration/ui/basic/', 'Basic UI'],
['configuration/restdocs', 'REST API'],
['configuration/apitokens', 'API Token Generation'],
['apps/android', 'Android App'],
'apps/ios',
'apps/windows',
['ecosystem/alexa/', 'Amazon Alexa'],
['ecosystem/google-assistant/', 'Google Assistant'], // from v2.3 onwards
['../addons/integrations/homekit/', 'Apple HomeKit'],
['../link/homekit/', 'Apple HomeKit'],
// ['ecosystem/ifttt/', 'IFTTT'], // Temporary remove until service gets reactivated
['ecosystem/mycroft/', 'Mycroft.AI'],
['../link/openhabcloud/', 'openHAB Cloud'],
]
},
{

16
.vuepress/process_file.rb
View File

@ -57,24 +57,18 @@ def process_file(indir, file, outdir, source)
addon_type = outdir_parts[1]
addon = file.split('/')[0]
source = ""
if addon == "habmin" then
puts " (add-on is habmin)"
source = "https://github.com/openhab/org.openhab.ui.habmin/blob/master/README.md"
elsif addon == "habpanel" then
if addon == "habpanel" then
puts " (add-on is habpanel)"
source = "https://github.com/openhab/org.openhab.ui.habpanel/blob/master/README.md"
source = "https://github.com/openhab/openhab-webui/blob/main/bundles/org.openhab.ui.habpanel/README.md"
elsif addon == "zigbee" then
puts " (add-on is zigbee)"
source = "https://github.com/openhab/org.openhab.binding.zigbee/blob/master/org.openhab.binding.zigbee/README.md"
source = "https://github.com/openhab/org.openhab.binding.zigbee/blob/main/org.openhab.binding.zigbee/README.md"
elsif addon == "zwave" && !(file =~ /things/) then
puts " (add-on is zwave)"
source = "https://github.com/openhab/org.openhab.binding.zwave/blob/master/README.md"
elsif $esh_features.include?("esh-#{addon_type}-#{addon.gsub('.', '-')}") then
puts " (add-on is from ESH)"
source = "https://github.com/eclipse/smarthome/blob/master/extensions/#{addon_type}/org.eclipse.smarthome.#{addon_type}.#{addon}/README.md"
source = "https://github.com/openhab/org.openhab.binding.zwave/blob/main/README.md"
elsif !(file =~ /things/) then
puts " (add-on is from openhab-addons)"
source = "https://github.com/openhab/openhab-addons/blob/master/addons/#{addon_type}/org.openhab.#{addon_type}.#{addon}/README.md"
source = "https://github.com/openhab/openhab-addons/blob/main/addons/#{addon_type}/org.openhab.#{addon_type}.#{addon}/README.md"
end
out.puts "source: #{source}" if source != ""

2
.vuepress/process_main_docs.rb
View File

@ -3,7 +3,7 @@ require_relative "./process_file.rb"
def process_main_docs(docs_source_dir)
puts ">>> Migrating the introduction article"
process_file(".", "introduction.md", "docs", "https://github.com/openhab/openhab-docs/blob/master/introduction.md")
process_file(".", "introduction.md", "docs", "https://github.com/openhab/openhab-docs/blob/main/introduction.md")
FileUtils.mv("docs/introduction.md", "docs/readme.md")

25
CONTRIBUTING.md
View File

@ -1,12 +1,12 @@
# Contribution Guidelines
### Pull requests are always welcome
## Pull requests are always welcome
We are always thrilled to receive pull requests, and do our best to
process them as fast as possible. Not sure if that typo is worth a pull
request? Do it! We will appreciate it.
### Conventions
## Conventions
Fork the repo and make changes on your fork in a feature branch.
@ -28,7 +28,7 @@ comment.
Commits that fix or close an issue should include a reference like `Closes #XXX`
or `Fixes #XXX`, which will automatically close the issue when merged.
### Sign your work
## Sign your work
The sign-off is a simple line at the end of the explanation for the
patch, which certifies that you wrote it or otherwise have the right to
@ -36,7 +36,7 @@ pass it on as an open-source patch. The rules are pretty simple: if you
can certify the below (from
[developercertificate.org](https://developercertificate.org/)):
```
```text
Developer Certificate of Origin
Version 1.1
@ -77,19 +77,19 @@ By making a contribution to this project, I certify that:
then you just add a line to every git commit message:
Signed-off-by: Joe Smith <joe.smith@email.com>
`Signed-off-by: Joe Smith <joe.smith@email.com>`
using your real name (sorry, no pseudonyms or anonymous contributions.) and an
e-mail address under which you can be reached (sorry, no github noreply e-mail
addresses (such as username@users.noreply.github.com) or other non-reachable
addresses are allowed).
#### Small patch exception
### Small patch exception
There are several exceptions to the signing requirement. Currently these are:
* Your patch fixes spelling or grammar errors.
* Your patch is a single line change to documentation.
- Your patch fixes spelling or grammar errors.
- Your patch is a single line change to documentation.
## Community Guidelines
@ -97,22 +97,21 @@ We want to keep the openHAB community awesome, growing and collaborative. We
need your help to keep it that way. To help with this we've come up with some
general guidelines for the community as a whole:
* Be nice: Be courteous, respectful and polite to fellow community members: no
- Be nice: Be courteous, respectful and polite to fellow community members: no
regional, racial, gender, or other abuse will be tolerated. We like nice people
way better than mean ones!
* Encourage diversity and participation: Make everyone in our community
- Encourage diversity and participation: Make everyone in our community
feel welcome, regardless of their background and the extent of their
contributions, and do everything possible to encourage participation in
our community.
* Keep it legal: Basically, don't get us in trouble. Share only content that
- Keep it legal: Basically, don't get us in trouble. Share only content that
you own, do not share private or sensitive information, and don't break the
law.
* Stay on topic: Make sure that you are posting to the correct channel
- Stay on topic: Make sure that you are posting to the correct channel
and avoid off-topic discussions. Remember when you update an issue or
respond to an email you are potentially sending to a large number of
people. Please consider this before you update. Also remember that
nobody likes spam.

4
README.md
View File

@ -18,7 +18,7 @@ We will read about them later.
Correct, this is done in the original repository of the add-on.
You may want to know how to find the right file in all of those repos?
This is fairly easy:
on most of the documentation pages on https://openhab.org/,
on most of the documentation pages on <https://openhab.org/>,
you will find the following link at the bottom, which will point you directly to the file you want to improve.
![Contribution link to a specific page](./images/contribution_link.png)
@ -96,4 +96,4 @@ In short, the following has to be considered:
- Versions like "2.1.0" are marked by git tags.
- Based on tags branches like "2.1-patch" are created, to include later discovered changes (like fixed links).
When a version is tagged (or updated), a static version of the website has to be generated and copied into the correct sub-folder, this is currently a manual operation described succinctly here: https://github.com/openhab/website/issues/72
When a version is tagged (or updated), a static version of the website has to be generated and copied into the correct sub-folder, this is currently a manual operation described succinctly here: <https://github.com/openhab/website/issues/72>

26
addons/actions.md
View File

@ -59,11 +59,11 @@ One can configure whether specific log entries are logged out and where they get
You have different options to execute a command through an action.
- `executeCommandLine(String commandLine)`: Executes a command on the command line without waiting for the command to complete
For example you could run `executeCommandLine("path/to/my/script.sh")` which then would be executed and the rule would continue processing.
- `executeCommandLine(String commandLine)`: Executes a command on the command line without waiting for the command to complete.
For example you could run `executeCommandLine("path/to/my/script.sh")` which then would be executed and the rule would continue processing.
- `executeCommandLine(Duration.ofSeconds(timeout), String commandLine)`: Executes a command on the command and waits `timeout` seconds for the command to complete, returning the output from the command as a String
For example you could run `var ScriptResponse = executeCommandLine(Duration.ofSeconds(60), "path/to/my/script.sh");` would get executed and wait 1 minute for the output to be responded back and write it into the `ScriptResponse` variable.
- `executeCommandLine(Duration.ofSeconds(timeout), String commandLine)`: Executes a command on the command and waits `timeout` seconds for the command to complete, returning the output from the command as a String.
For example you could run `var ScriptResponse = executeCommandLine(Duration.ofSeconds(60), "path/to/my/script.sh");` would get executed and wait 1 minute for the output to be responded back and write it into the `ScriptResponse` variable.
Other Durations than `ofSeconds` units are possible too.
Check out the [Java Documentation](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/Duration.html?is-external=true) for possible units.
@ -106,6 +106,7 @@ All HTTP Actions can have a last `timeout` parameter added in ms. eg. `sendHttpP
:::
For example:
```javascript
val headers = newHashMap("Cache-control" -> "no-cache")
val output = sendHttpGetRequest("https://example.com/?id=1", headers, 1000)
@ -158,6 +159,7 @@ if ((thingStatusInfo !== null) && (thingStatusInfo.getStatus().toString() == "ON
```
### openHAB Subsystem Actions
openHAB has several subsystems that can be accessed from Rules. These include persistence, see [Persistence Extensions in Scripts and Rules]({{base}}/configuration/persistence.html#persistence-extensions-in-scripts-and-rules), transformations, scripts.
- `callScript(String scriptName)`: Calls a script which must be located in the `$OPENHAB_CONF/scripts` folder.
@ -182,6 +184,7 @@ Three different actions are available:
- `sendLogNotification(message)`: Sends a log notification to the `notifications` list at your openHAB Cloud instance. Notifications are NOT sent to any registered devices
For each of the three actions, there's another variant accepting an icon name and a severity:
- `sendNotification(emailAddress, message, icon, severity)`
- `sendBroadcastNotification(message, icon, severity)`
- `sendLogNotification(message, icon, severity)`
@ -189,12 +192,13 @@ For each of the three actions, there's another variant accepting an icon name an
Icon and severity can potentially be used by cloud instance clients (such as the openHAB apps for Android or iOS) to be displayed in the list of notifications.
The parameters for these actions have the following meaning:
- `emailAddress`: String containing the email address the target user is registered with in the cloud instance
- `message`: String containing the notification message text
- `icon`: String containing the icon name (as described in [Items]({{base}}/configuration/items.html#icons))
- `severity`: String containing a description of the severity of the incident
**Example**
### Example
```javascript
rule "Front Door Notification"
@ -205,7 +209,7 @@ then
end
```
For information on making use of the [openHAB Cloud service](https://github.com/openhab/openhab-cloud/blob/master/README.md) hosted by the [openHAB Foundation e.V.](https://www.openhabfoundation.org/), visit the [myopenhab.org website](https://www.myopenhab.org).
For information on making use of the [openHAB Cloud service](https://github.com/openhab/openhab-cloud/blob/main/README.md) hosted by the [openHAB Foundation e.V.](https://www.openhabfoundation.org/), visit the [myopenhab.org website](https://www.myopenhab.org).
## Ephemeris
@ -213,7 +217,7 @@ Ephemeris is a way to determine what type of day today or a number of days befor
For example, a way to determine if today is a weekend, a bank holiday, someone’s birthday, trash day, etc.
The default bank holidays and configuration syntax is defined by the [Jollyday library](https://github.com/svendiedrichsen/jollyday).
### Actions
### Actions Examples
#### Rules DSL
@ -294,6 +298,7 @@ dayset-workday=[MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY]
dayset-weekend=[SATURDAY,SUNDAY]
dayset-trash=[MONDAY]
```
#### Custom Bank Holidays
In addition to the ability to define custom daysets, one can define a custom list of holidays or other important days.
@ -314,6 +319,7 @@ The following is an example listing a few custom days.
</tns:Holidays>
</tns:Configuration>
```
For further examples and to find the list of elements to reference holidays that require more complicated calculations (e.g. holidays based on a lunar calendar, Easter, etc.) see the [XSD that defines the structures of the XML](https://github.com/svendiedrichsen/jollyday/blob/b78fa20e75d48bdf14e3fa8107befe44e3bacf3a/src/main/xsd/Holiday.xsd) or the XML file for your country or others.
You can place these XML files anywhere on your file system that openHAB has permission to read.
@ -335,9 +341,9 @@ 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.
- 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

2
addons/bindings.md
View File

@ -36,7 +36,7 @@ Bindings connect your smart home's devices and technologies to openHAB.
<td>
<p>
Most bindings developed for openHAB 1 can also be used in openHAB 2.
These bindings are connected directly to <a href="{{base}}/concepts/items.html">items</a> by editing text files.
These bindings are connected directly to <a href="{{base}}/concepts/items.html">items</a> by editing text files.
</p>
</td>
</tr>

116
addons/index.md
View File

@ -1,115 +1,7 @@
---
layout: documentation
layout: redirected
sitemap: false
redirect_to: /configuration/addons.html
---
{% include base.html %}
# Add-ons
All add-ons for openHAB 2 are part of the distribution.
This includes all 2.x Bindings as well as all 1.x add-ons that were reported to be compatible.
There are several ways you can install an add-on.
These are described under *Installation of Add-ons* below
| Add-on Type | Description |
|-----------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| [Bindings](/addons/#bindings) | Bindings integrate physical hardware, external systems and web services in openHAB |
| [User Interfaces]({{base}}/configuration/#versatility) | User interfaces are either native smartphone apps or web applications that access the openHAB server through the REST API |
| [Persistence](/addons/#persistence) | Persistence services allow openHAB to store time series data for history-based actions or statistics |
| [Actions](/addons/#actions) | Actions are predefined methods for openHAB rules and scripts |
| [Transformations](/addons/#transform) | Transformations are used to translate between technical and human-readable values for Items |
| [Voice Services](/addons/#voice) | Services that provide voice enabling features, such as text-to-speech, speech-to-text etc. |
| [3rd Party System Integration](/addons/#ios) | Expose openHAB to external systems |
## Installation of 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
Navigate to the add-ons section.
Search for the desired add-on in the categories and press install.
![installing Add-ons through Paper UI](images/index_installation_paperui.gif)
### Through Configuration Files
For this installation option you need to know the `id` of the desired add-on, e.g., network or mqtt1.
You can find it out with the following command within [openHAB console]({{base}}/administration/console.html):
```sh
feature:list | grep ^openhab
```
A list of all available add-ons starting with "openhab" will be returned.
It could look similar to this example:
```text
...
openhab-transformation-xslt | 0.9.0.SNAPSHOT | | Uninstalled | openhab-aggregate-xml | XSLT Transformation
openhab-voice-mactts | 0.9.0.SNAPSHOT | | Uninstalled | openhab-aggregate-xml | macOS Text-to-Speech
openhab-binding-amazondashbutton | 2.0.0.SNAPSHOT | | Uninstalled | openhab-aggregate-xml | Amazon Dash Button Binding
openhab-binding-astro | 2.0.0.SNAPSHOT | | Uninstalled | openhab-aggregate-xml | Astro Binding
openhab-binding-autelis | 2.0.0.SNAPSHOT | | Uninstalled | openhab-aggregate-xml | Autelis Binding
openhab-binding-avmfritz | 2.0.0.SNAPSHOT | | Uninstalled | openhab-aggregate-xml | AVM Fritz!Box Binding
...
openhab-binding-network │ 2.2.0 │ │ Uninstalled │ openhab-addons-2.2.0 │ Network Binding
...
```
According to the [naming convention for bundles]({{base}}/administration/bundles.html#naming-convention-for-bundles) the *id* for the shown example is *network*.
Another way to find the correct `id` is to look at the URL of the add-on documentation page.
For example the url for the [mqtt Binding documentation]({{base}}/addons/bindings/mqtt1/readme.html) is
```text
https://docs.openhab.org/addons/bindings/mqtt1/readme.html
```
In this case, the `id` would be "mqtt1".
Did you notice the trailing *1* in this id?
This is because the mqtt Binding is a 1.x add-on.
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.
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 chosen package and already installed add-ons):
```text
package = standard
ui = basic,paper,habpanel
action = pushover
binding = astro,mqtt1
transformation = jsonpath
persistence = influxdb
misc = restdocs
```
To install the network Binding like we want in this example, we just need to add the id *network* to the Binding section.
```text
binding = astro,mqtt1,network
```
After saving the file, the add-on will be installed.
### Through manually provided add-ons
> Attention:
> This option is adressed to advanced users.
> Installing add-os with a `.jar`file can lead to problems, because add-on dependencies may not be installed.
> Please make sure to use this option only in special cases (like add-on testing for an upcoming version) or when you know what you are doing.
For this installation option you need a bundles `.jar` file.
One way of retrieving those files is mentiones 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.
Place the .jar file in the folder Additional add-on files as described in File Locations ([Linux]({{base}}/installation/linux.html#file-locations), [Windows]({{base}}/installation/windows.html#file-locations) or [macOS]({{base}}/installation/macos.html#file-locations)).
<!-- Note to authors: This file was created in January 2021. Feel free to remove it after a few months... -->

2
addons/io.md
View File

@ -9,7 +9,7 @@ title: System Integrations
openHAB supports services that enable integration with various technologies that don't fall into other add-on categories.
Most of the systems mentioned below are integrated via a *Misc* add-on, installed e.g. through Paper UI.
Most of the systems mentioned below are integrated via a *Misc* add-on, installed e.g. through UI.
Detailed instructions and requirements may be found in the corresponding documentation pages.
<!-- selection not needed for now table id="ios-select" class="striped">

2
addons/persistence.md
View File

@ -21,7 +21,7 @@ Persistence services enable the storage of item states over time.
<td>
<p>
Some openHAB 1 persistence services have not yet completed validation for inclusion in the distribution; however, they may indeed work properly under openHAB 2.
All openHAB 1 add-ons can be downloaded in a <a href="https://bintray.com/openhab/mvn/download_file?file_path=org%2Fopenhab%2Fdistro%2Fopenhab%2F1.9.0%2Fopenhab-1.9.0-addons.zip">zip file</a>.
All openHAB 1 add-ons can be downloaded in a <a href="https://bintray.com/openhab/mvn/download_file?file_path=org%2Fopenhab%2Fdistro%2Fopenhab%2F1.9.0%2Fopenhab-1.9.0-addons.zip">zip file</a>.
We need your help testing them so that they may be easily installed in a future distribution.
Please see the <a href="{{base}}/developers/development/compatibilitylayer.html#how-to-use-openhab-1x-add-ons-that-are-not-part-of-the-distribution">compatibility layer documentation</a> and
also search the <a href="https://community.openhab.org">openHAB community forum</a> for the latest information and steps for manual installation.

2
addons/transformations.md
View File

@ -23,7 +23,7 @@ The relevant transformation service needs to be installed via the paperUI before
Be aware, that some Transformation services rely on transformation files, while others work by directly providing the transformation logic.
Transformation files need to be placed in the directory `$OPENHAB_CONF/transform`.
1. Item and Sitemap Labels
1. Item and Sitemap Labels
Transformations used in the [state/value part]({{base}}/configuration/items.html#state-transformations) of labels are applied **on the fly**.
While the **transformed value** will (for example) be visible on a Sitemap, the **original value** is stored in the Item.

38
addons/uis.md
View File

@ -1,37 +1,7 @@
---
layout: documentation
title: User Interfaces
layout: redirected
sitemap: false
redirect_to: /configuration/editors.html
---
{% include base.html %}
# User Interfaces
openHAB offers a variety of frontends for user interaction, from administrative web frontends to dedicated smartphone apps.
| Web Application | Description |
|-------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
| [Basic UI]({{base}}/addons/uis/basic/readme.html) | The Basic UI is an HTML5 web application in Material Design, designed for operating openHAB. |
| [Classic UI]({{base}}/addons/uis/classic/readme.html) | The Classic UI is the original openHAB 1.x webui, designed for operating openHAB. |
| [HABmin]({{base}}/addons/uis/habmin/readme.html) | HABmin is a modern, professional and portable user interface for openHAB, providing both user and administrative functions. |
| [HABPanel]({{base}}/addons/uis/habpanel/readme.html) | HABPanel is a lightweight dashboard interface for openHAB. |
| [Paper UI]({{base}}/addons/uis/paper/readme.html) | The Paper UI is an AngularJS-based HTML5 web application in Material Design, designed for setup and administration purposes. |
| App | Description |
|---------------------------------------------------------|--------------------------------------------------------|
| [Android App]({{base}}/addons/uis/apps/android.html) | The native Android app to access openHAB on the go. |
| [iOS App]({{base}}/addons/uis/apps/ios.html) | The native iOS app to access openHAB on the go. |
| [Windows 10 App]({{base}}/addons/uis/apps/windows.html) | The native Windows 10 app to access openHAB on the go. |
## Iconsets
Basic UI, Classic UI and all openHAB apps present a graphical user interface as defined in [Sitemaps]({{base}}/configuration/sitemaps.html), with the help of [Items]({{base}}/configuration/items.html).
Each Item as well as each Sitemap element may be associated with an icon visible next to it.
Currently only the Classic Icon Set is provided.
Addition of personal icons and customization of the existing ones is supported and encouraged.
See the instructions about [Custom Icons and Custom Dynamic Icons]({{base}}/configuration/items.html#icons) for more details.
| Iconset | Description |
|-----------------------------------------------------------|---------------------------------------------------------------------|
| [Classic Icons]({{base}}/configuration/iconsets/classic/) | This is a modernized version of the original icon set of openHAB 1. |
<!-- Note to authors: This file was created in January 2021. Feel free to remove it after a few months... -->

2
administration/bundles.md
View File

@ -64,7 +64,7 @@ Bundles are named according to the following convention:
where
- **prefix** is the first element to categorize the bundle.
For addons this is `org.openhab`.
For addons this is `org.openhab`.
- **type** is the add-on type, e.g. "binding", "persistence", or "ui"
- **id** is the identifier for this bundle

21
administration/console.md
View File

@ -9,17 +9,17 @@ title: The Console
The console offers the ability to:
* Monitor the [log](logging.html#karaf-console) in realtime
* Manage [bundles](bundles.html)
* Execute [runtime commands](runtime.html)
- Monitor the [log](logging.html#karaf-console) in realtime
- Manage [bundles](bundles.html)
- Execute [runtime commands](runtime.html)
## Accessing the Console
The method used to access the console depends on how openHAB was started.
* When started in interactive mode using the provided command line scripts (e.g. `start.sh` or `start.bat`), openHAB naturally transitions directly to the console prompt.
* When started as a service (i.e. when openHAB is running as a background process), access to the console is given by running the `$OPENHAB_RUNTIME/bin/client` (`client.bat` for Windows) script or by [connecting via SSH](#connecting-via-ssh).
Linux package based installations can also use the command `openhab-cli console`.
- When started in interactive mode using the provided command line scripts (e.g. `start.sh` or `start.bat`), openHAB naturally transitions directly to the console prompt.
- When started as a service (i.e. when openHAB is running as a background process), access to the console is given by running the `$OPENHAB_RUNTIME/bin/client` (`client.bat` for Windows) script or by [connecting via SSH](#connecting-via-ssh).
Linux package based installations can also use the command `openhab-cli console`.
The default username/password is **openhab:habopen**, so enter `habopen` at the password prompt.
@ -148,7 +148,7 @@ To add custom parameters or overwrite the default values, you can change the con
### Changing the Password
The password is stored in the file `users.properties`, located in the `etc` directory as [mentioned above](#console-settings-files-and-directories).
By default, the line with the password contains the text `openhab = `, followed by the current password (e.g. `habopen`) or a password hash (e.g. `{CRYPT}4AE1A0FD...{CRYPT}`).
By default, the line with the password contains the text `openhab =`, followed by the current password (e.g. `habopen`) or a password hash (e.g. `{CRYPT}4AE1A0FD...{CRYPT}`).
To change the authentication password edit the file manually, replacing the password or password hash (including `{CRYPT}`) with your new password in clear text.
Alternately, run the following Linux shell command, which will perform the replacement for you.
@ -180,7 +180,6 @@ To enable binding to all interfaces, uncomment the line
in `services/runtime.cfg`.
### Change the Port Number
The SSH port configuration is done through the file `org.apache.karaf.shell.cfg`, located in the `etc` directory as [mentioned above](#console-settings-files-and-directories).
@ -191,10 +190,8 @@ Alternately, run the following Linux shell command, which will perform the repla
Substitute `1234` with your desired port number.
Depending on your system, you may have to substitute [the directory](#console-settings-files-and-directories) at the end of the command.
```shell
sudo sed -i -e "s/sshPort = .*/sshPort = 1234/g" /var/lib/openhab/etc/org.apache.karaf.shell.cfg
```
```sudo sed -i -e "s/sshPort = .*/sshPort = 1234/g" /var/lib/openhab/etc/org.apache.karaf.shell.cfg```
----
## More Information
Please check the [Apache Karaf reference](https://karaf.apache.org/manual/latest/) for more details.

5
administration/jsondb.md
View File

@ -40,7 +40,7 @@ Most data stored in the database is written in a way that should be understandab
As stated above, the files are only read during system startup - therefore if you change a file you will need to stop openHAB, make your changes and restart the system for the changes to take effect.
----
---
openHAB stores configuration information in JSON (JavaScript Object Notation) formatted (structured) text files located in the `OPENHAB_USERDATA/jsondb/` directory.
@ -69,7 +69,7 @@ The system employs two write mechanisms to improve performance where there are m
The parameters for the two mechanisms may be modified in UI :arrow_right: Settings :arrow_right: Json Storage
1. _Write delay_ (defaults to 500 ms): Sets the time to wait before writing changes to disk.
This can reduce the number of writes when many changes are being introduced within a short period, and
This can reduce the number of writes when many changes are being introduced within a short period, and
1. _Maximum write delay_ (defaults to 30000 ms): Sets the maximum period the service will wait to write data in cases where changes are happening continually.
The service keeps up to five backups of each table.
@ -194,6 +194,7 @@ Step 3. Using UI :arrow_right: Settings :arrow_right: Things, edit the new `ISP_
- Location (from unset to `MyHome`)
- Retry (from 1 to 3)
- Timeout (from 5000 to 10000)
and save:
![Edit_Thing_UI](./images/ui_edit_thing.png)

9
administration/runtime.md
View File

@ -11,33 +11,32 @@ It is possible to query and even change the state of entities like items or thin
{::options toc_levels="3..4"/}
* TOC
- TOC
{:toc}
::: tip Note
Some of the described commands are executed on the internal database and could break your installation. Please use this functionality only if you know what you are doing!
:::
## Examples
Query an item's state:
```
```shell
openhab> openhab:status Heating_GF_Corridor
OFF
```
Changing an item's state:
```
```shell
openhab> openhab:send Heating_GF_Corridor ON
Command has been sent successfully.
```
Get help for a command:
```
```shell
openhab> help openhab:send
Usage: openhab:send <item> <command> - sends a command for an item
```

10
administration/serial.md
View File

@ -23,18 +23,18 @@ openHABian comes with a menu option to configure the serial ports automatically.
If you can see issues related to opening the serial port with Linux, and you are using **non standard serial ports** (e.g. `/dev/ttyAMA0`) you might have to configure openHAB to detect and access the port correctly:
* Adapt Java command line arguments to include `-Dgnu.io.rxtx.SerialPorts=/dev/ttyAMA0` (where `/dev/ttyAMA0` is the serial port). If you have multiple serial ports to configure, separate them with colon (`:`). Depending on openHAB installation method, you should modify `start.sh`, `start_debug.sh`, `start.bat`, or `start_debug.bat` (standalone/manual installation) or `EXTRA_JAVA_OPTS` in `/etc/default/openhab` (Debian installation)
* Depending on Linux distribution, you might need to add the user running openHAB to `dialout` user group.With Debian openHAB installation: `sudo usermod -a -G dialout openhab`. The user will need to logout from all login instances and log back in to see their new group added. If the user added to this group still cannot get permission, rebooting the box to ensure the new group permission is attached to the user is suggested.
* When using more than one USB-Serial converters, it may happen that the `/dev/ttyUSB0` device is named `/dev/ttyUSB1` after a reboot. To prevent this problem, alias names can be assigned to serial devices by adding them to `/etc/udev/rules.d/99-com.rules`. Example:
- Adapt Java command line arguments to include `-Dgnu.io.rxtx.SerialPorts=/dev/ttyAMA0` (where `/dev/ttyAMA0` is the serial port). If you have multiple serial ports to configure, separate them with colon (`:`). Depending on openHAB installation method, you should modify `start.sh`, `start_debug.sh`, `start.bat`, or `start_debug.bat` (standalone/manual installation) or `EXTRA_JAVA_OPTS` in `/etc/default/openhab` (Debian installation)
- Depending on Linux distribution, you might need to add the user running openHAB to `dialout` user group.With Debian openHAB installation: `sudo usermod -a -G dialout openhab`. The user will need to logout from all login instances and log back in to see their new group added. If the user added to this group still cannot get permission, rebooting the box to ensure the new group permission is attached to the user is suggested.
- When using more than one USB-Serial converters, it may happen that the `/dev/ttyUSB0` device is named `/dev/ttyUSB1` after a reboot. To prevent this problem, alias names can be assigned to serial devices by adding them to `/etc/udev/rules.d/99-com.rules`. Example:
```bash
```shell
SUBSYSTEM=="tty", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", ATTRS{serial}=="AE01F0PD", SYMLINK+="ttyMySensors"
SUBSYSTEM=="tty", ATTRS{idVendor}=="10c4", ATTRS{idProduct}=="ea60", ATTRS{serial}=="0001", SYMLINK+="ttyCulStick"
```
You need to find relevant pieces of information using e.g. `udevadm` command line utility:
```
```shell
udevadm info -a -p $(udevadm info -q path -n /dev/ttyACM0)
```

8
appendix/contributing.md
View File

@ -36,20 +36,20 @@ We want to keep the openHAB community awesome, growing and collaborative.
We need your help to keep it that way.
To help with this we've come up with some general guidelines for the community as a whole:
* **Be nice:** Be courteous, respectful and polite to fellow community members: no
- **Be nice:** Be courteous, respectful and polite to fellow community members: no
regional, racial, gender, or other abuse will be tolerated. We like nice people
way better than mean ones!
* **Encourage diversity and participation:** Make everyone in our community
- **Encourage diversity and participation:** Make everyone in our community
feel welcome, regardless of their background and the extent of their
contributions, and do everything possible to encourage participation in
our community.
* **Keep it legal:** Basically, don't get us in trouble. Share only content that
- **Keep it legal:** Basically, don't get us in trouble. Share only content that
you own, do not share private or sensitive information, and don't break the
law.
* **Stay on topic:** Make sure that you are posting to the correct channel
- **Stay on topic:** Make sure that you are posting to the correct channel
and avoid off-topic discussions. Remember when you update an issue or
respond to an email you are potentially sending to a large number of
people. Please consider this before you update. Also remember that

5
appendix/help.md
View File

@ -10,14 +10,13 @@ title: Finding Help and FAQs
openHAB is surrounding by an amazing community helping new users, discussing problems and providing tutorials and examples.
Join today and find answers for all details of openHAB:
* [community.openhab.org](https://community.openhab.org)
- [community.openhab.org](https://community.openhab.org)
# FAQs - Frequently Asked Questions
In the community forum you'll also find a list of recurring questions with short answers, commonly known as FAQs.
Check there before posting your own questions and feel free to add questions and answers:
* [openHAB 2 FAQs at community.openhab.org](https://community.openhab.org/t/frequently-asked-questions/17727)
- [openHAB 2 FAQs at community.openhab.org](https://community.openhab.org/t/frequently-asked-questions/17727)
{% include contribution-wanted.html %}

40
concepts/audio.md
View File

@ -10,33 +10,33 @@ 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 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*.
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](images/audio.png)
- *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.
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.
Typical audio source services are microphones. Typically, a continuous stream is expected from them.
- *Audio Sinks* are services that accept audio streams of certain formats.
Typically, these are expected to play the audio stream, i.e. they are some kind of speaker or media device.
- *Text-to-Speech* (TTS) services are similar to audio sources with respect to the ability to create audio streams.
The difference is that they take a string as an input and will synthesize this string to a spoken text using a given voice.
TTS services can provide information about the voices that they support and the locale that those voices are associated with.
Each voice supports exactly one locale.
- *Speech-to-Text* (STT) services are similar to audio sinks, but they do not simply play back the stream, but convert it to a plain string.
They provide information about supported formats and locales.
- *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.
Typical audio source services are microphones. Typically, a continuous stream is expected from them.
- *Audio Sinks* are services that accept audio streams of certain formats.
Typically, these are expected to play the audio stream, i.e. they are some kind of speaker or media device.
- *Text-to-Speech* (TTS) services are similar to audio sources with respect to the ability to create audio streams.
The difference is that they take a string as an input and will synthesize this string to a spoken text using a given voice.
TTS services can provide information about the voices that they support and the locale that those voices are associated with.
Each voice supports exactly one locale.
- *Speech-to-Text* (STT) services are similar to audio sinks, but they do not simply play back the stream, but convert it to a plain string.
They provide information about supported formats and locales.
As plain text from an STT service is often not very useful, there is additionally the concept of a *human language interpreter*:
![](images/hli.png)
![hli](images/hli.png)
A *Human Language Interpreter* takes a string as an input.
It then derives actions from it (like sending commands to devices) and/or replies with a string, which opens the possibility to realize conversations.
As such an interpreter is not directly linked to audio streams, but operates on strings only, this can be the basis for any kind of assistant, e.g. for chat bots using the console, XMPP, Twitter or other messaging services.
A *Human Language Interpreter* takes a string as an input.
It then derives actions from it (like sending commands to devices) and/or replies with a string, which opens the possibility to realize conversations.
As such an interpreter is not directly linked to audio streams, but operates on strings only, this can be the basis for any kind of assistant, e.g. for chat bots using the console, XMPP, Twitter or other messaging services.
Applications can dynamically choose which services to use, so that different sinks can be used for different use cases.
Applications can dynamically choose which services to use, so that different sinks can be used for different use cases.
Defaults can be set as a configuration for all those services in case an application does not ask for any specific service.

126
concepts/categories.md
View File

@ -23,34 +23,34 @@ The list of all predefined categories can be found in our categories overview:
| Category | Description | Icon Example |
|------------------|------------------------------------------------------------------------------------------------------|-----------------|
| Battery | Batteries, Energy Storages | ![](/iconsets/classic/battery.png) |
| Blinds | Roller shutters, window blinds, etc. | ![](/iconsets/classic/blinds.png) |
| Camera | All kinds of cameras | ![](/iconsets/classic/camera.png) |
| Battery | Batteries, Energy Storages | ![battery](/iconsets/classic/battery.png) |
| Blinds | Roller shutters, window blinds, etc. | ![blinds](/iconsets/classic/blinds.png) |
| Camera | All kinds of cameras | ![camera](/iconsets/classic/camera.png) |
| Car | Smart Cars | |
| CleaningRobot | Vacuum robots, mopping robots, etc. | |
| Door | Door | ![](/iconsets/classic/door.png) |
| FrontDoor | Front Door | ![](/iconsets/classic/frontdoor.png) |
| GarageDoor | Garage Door | ![](/iconsets/classic/garagedoor.png) |
| Door | Door | ![door](/iconsets/classic/door.png) |
| FrontDoor | Front Door | ![frontdoor](/iconsets/classic/frontdoor.png) |
| GarageDoor | Garage Door | ![garagedoor](/iconsets/classic/garagedoor.png) |
| HVAC | Air condition devices, Fans | |
| Inverter | Power inverter, such as solar inverters etc. | |
| LawnMower | Lawn mowing robots, etc. | ![](/iconsets/classic/lawnmower.png) |
| Lightbulb | Devices that illuminate something, such as bulbs, etc. | ![](/iconsets/classic/lightbulb.png) |
| Lock | Devices whose primary pupose is locking something | ![](/iconsets/classic/lock.png) |
| LawnMower | Lawn mowing robots, etc. | ![lawnmower](/iconsets/classic/lawnmower.png) |
| Lightbulb | Devices that illuminate something, such as bulbs, etc. | ![lightbulb](/iconsets/classic/lightbulb.png) |
| Lock | Devices whose primary pupose is locking something | ![lock](/iconsets/classic/lock.png) |
| MotionDetector | Motion sensors/detectors | |
| NetworkAppliance | Bridges/Gateway need to access other devices like used by Philips Hue for example, Routers, Switches | |
| PowerOutlet | Small devices to be plugged into a power socket in a wall which stick there | ![](/iconsets/classic/poweroutlet.png) |
| Projector | Devices that project a picture somewhere | ![](/iconsets/classic/projector.png) |
| PowerOutlet | Small devices to be plugged into a power socket in a wall which stick there | ![poweroutlet](/iconsets/classic/poweroutlet.png) |
| Projector | Devices that project a picture somewhere | ![projector](/iconsets/classic/projector.png) |
| RadiatorControl | Controls on radiators used to heat up rooms | |
| Receiver | Audio/Video receivers, i.e. radio receivers, satelite or cable receivers, recorders, etc. | ![](/iconsets/classic/receiver.png) |
| Screen | Devices that are able to show a picture | ![](/iconsets/classic/screen.png) |
| Receiver | Audio/Video receivers, i.e. radio receivers, satelite or cable receivers, recorders, etc. | ![receiver](/iconsets/classic/receiver.png) |
| Screen | Devices that are able to show a picture | ![screen](/iconsets/classic/screen.png) |
| Sensor | Device used to measure something | |
| Siren | Siren used by Alarm systems | ![](/iconsets/classic/siren.png) |
| Siren | Siren used by Alarm systems | ![siren](/iconsets/classic/siren.png) |
| SmokeDetector | Smoke detectors | |
| Speaker | Devices that are able to play sounds | |
| WallSwitch | Any device attached to the wall that controls a binary status of something, for ex. a light switch | ![](/iconsets/classic/wallswitch.png) |
| WallSwitch | Any device attached to the wall that controls a binary status of something, for ex. a light switch | ![wallswitch](/iconsets/classic/wallswitch.png) |
| WebService | Account with credentials for a website | |
| Window | Window | ![](/iconsets/classic/window.png) |
| WhiteGood | Devices that look like Waschingmachines, Dishwashers, Dryers, Fridges, Ovens, etc. | ![](/iconsets/classic/whitegood.png) |
| Window | Window | ![window](/iconsets/classic/window.png) |
| WhiteGood | Devices that look like Waschingmachines, Dishwashers, Dryers, Fridges, Ovens, etc. | ![whitegood](/iconsets/classic/whitegood.png) |
### Channel Group Categories
@ -62,72 +62,72 @@ The Channel type definition allows to specify a category.
A Binding should classify each Channel into one of the existing categories or leave the category blank, if there is no good match.
There are different types of categories for Channels, which are listed below.
#### Widgets
### Widgets
| Category | Icon Example |
|---------------|------------------------------------------|
| Colorpicker | ![](/iconsets/classic/colorpicker.png) |
| Number | ![](/iconsets/classic/number.png) |
| Rollershutter | ![](/iconsets/classic/rollershutter.png) |
| Slider | ![](/iconsets/classic/slider.png) |
| Switch | ![](/iconsets/classic/switch.png) |
| Text | ![](/iconsets/classic/text.png) |
| Group | ![](/iconsets/classic/group.png) |
| Colorpicker | ![colorpicker](/iconsets/classic/colorpicker.png) |
| Number | ![number](/iconsets/classic/number.png) |
| Rollershutter | ![rollershutter](/iconsets/classic/rollershutter.png) |
| Slider | ![slider](/iconsets/classic/slider.png) |
| Switch | ![switch](/iconsets/classic/switch.png) |
| Text | ![text](/iconsets/classic/text.png) |
| Group | ![group](/iconsets/classic/group.png) |
#### Weather
| Category | Icon Example |
|-------------|----------------------------------------|
| Sun | ![](/iconsets/classic/sun.png) |
| Moon | ![](/iconsets/classic/moon.png) |
| Clouds | ![](/iconsets/classic/clouds.png) |
| Sun_Clouds | ![](/iconsets/classic/sun_clouds.png) |
| Rain | ![](/iconsets/classic/rain.png) |
| Snow | ![](/iconsets/classic/snow.png) |
| Wind | ![](/iconsets/classic/wind.png) |
| Humidity | ![](/iconsets/classic/humidity.png) |
| Temperature | ![](/iconsets/classic/temperature.png) |
| Sun | ![sun](/iconsets/classic/sun.png) |
| Moon | ![moon](/iconsets/classic/moon.png) |
| Clouds | ![clouds](/iconsets/classic/clouds.png) |
| Sun_Clouds | ![sun_clouds](/iconsets/classic/sun_clouds.png) |
| Rain | ![rain](/iconsets/classic/rain.png) |
| Snow | ![snow](/iconsets/classic/snow.png) |
| Wind | ![wind](/iconsets/classic/wind.png) |
| Humidity | ![humidity](/iconsets/classic/humidity.png) |
| Temperature | ![temperature](/iconsets/classic/temperature.png) |
#### Properties
| Category | Icon Example |
|------------------|---------------------------------------------|
| BatteryLevel | ![](/iconsets/classic/batterylevel.png) |
| LowBattery | ![](/iconsets/classic/lowbattery.png) |
| CarbonDioxide | ![](/iconsets/classic/carbondioxide.png) |
| Energy | ![](/iconsets/classic/energy.png) |
| Gas | ![](/iconsets/classic/gas.png) |
| Oil | ![](/iconsets/classic/oil.png) |
| Water | ![](/iconsets/classic/water.png) |
| Light | ![](/iconsets/classic/light.png) |
| ColorLight | ![](/iconsets/classic/colorlight.png) |
| Temperature | ![](/iconsets/classic/temperature.png) |
| Smoke | ![](/iconsets/classic/smoke.png) |
| SoundVolume | ![](/iconsets/classic/soundvolume.png) |
| Pressure | ![](/iconsets/classic/pressure.png) |
| Fire | ![](/iconsets/classic/fire.png) |
| Motion | ![](/iconsets/classic/motion.png) |
| QualityOfService | ![](/iconsets/classic/qualityofservice.png) |
| Moisture | ![](/iconsets/classic/moisture.png) |
| Noise | ![](/iconsets/classic/noise.png) |
| Flow | ![](/iconsets/classic/flow.png) |
| Price | ![](/iconsets/classic/price.png) |
| Time | ![](/iconsets/classic/time.png) |
| BatteryLevel | ![batterylevel](/iconsets/classic/batterylevel.png) |
| LowBattery | ![lowbattery](/iconsets/classic/lowbattery.png) |
| CarbonDioxide | ![carbondioxide](/iconsets/classic/carbondioxide.png) |
| Energy | ![energy](/iconsets/classic/energy.png) |
| Gas | ![gas](/iconsets/classic/gas.png) |
| Oil | ![oil](/iconsets/classic/oil.png) |
| Water | ![water](/iconsets/classic/water.png) |
| Light | ![light](/iconsets/classic/light.png) |
| ColorLight | ![colorlight](/iconsets/classic/colorlight.png) |
| Temperature | ![temperature](/iconsets/classic/temperature.png) |
| Smoke | ![smoke](/iconsets/classic/smoke.png) |
| SoundVolume | ![soundvolume](/iconsets/classic/soundvolume.png) |
| Pressure | ![pressure](/iconsets/classic/pressure.png) |
| Fire | ![fire](/iconsets/classic/fire.png) |
| Motion | ![motion](/iconsets/classic/motion.png) |
| QualityOfService | ![qualityofservice](/iconsets/classic/qualityofservice.png) |
| Moisture | ![moisture](/iconsets/classic/moisture.png) |
| Noise | ![noise](/iconsets/classic/noise.png) |
| Flow | ![flow](/iconsets/classic/flow.png) |
| Price | ![price](/iconsets/classic/price.png) |
| Time | ![time](/iconsets/classic/time.png) |
#### Control
| Category | Icon Example |
|--------------|-----------------------------------------|
| Heating | ![](/iconsets/classic/heating.png) |
| MediaControl | ![](/iconsets/classic/mediacontrol.png) |
| MoveControl | ![](/iconsets/classic/movecontrol.png) |
| Zoom | ![](/iconsets/classic/zoom.png) |
| Heating | ![heating](/iconsets/classic/heating.png) |
| MediaControl | ![mediacontrol](/iconsets/classic/mediacontrol.png) |
| MoveControl | ![movecontrol](/iconsets/classic/movecontrol.png) |
| Zoom | ![zoom](/iconsets/classic/zoom.png) |
#### Purpose
| Category | Icon Example |
|----------|-------------------------------------|
| Alarm | ![](/iconsets/classic/alarm.png) |
| Presence | ![](/iconsets/classic/presence.png) |
| Vacation | ![](/iconsets/classic/vacation.png) |
| Party | ![](/iconsets/classic/party.png) |
| Alarm | ![alarm](/iconsets/classic/alarm.png) |
| Presence | ![presence](/iconsets/classic/presence.png) |
| Vacation | ![vacation](/iconsets/classic/vacation.png) |
| Party | ![party](/iconsets/classic/party.png) |

2
concepts/discovery.md
View File

@ -11,7 +11,7 @@ Many devices, technologies and systems can be automatically discovered on the ne
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
## Background Discovery
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.

2
concepts/index.md
View File

@ -44,7 +44,7 @@ Channels may be linked to multiple Items and Items may be linked to multiple Cha
To illustrate these concepts, consider the example below of a two-channel actuator that controls two lights:
![](images/thing-devices-1.png)
![thing-devices-1](images/thing-devices-1.png)
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).

26
concepts/profiles.md
View File

@ -5,30 +5,30 @@ title: Profiles
# Profiles
The communication between the framework and the Thing handlers is managed by the "Communication Manager", which in turn uses "Profiles" to determined what exactly needs to be done.
The communication between the framework and the Thing handlers is managed by the "Communication Manager", which in turn uses "Profiles" to determined what exactly needs to be done.
This provides some flexibility to influence these communication paths.
By their nature, profiles are correlated to links between Items and Channels (i.e. `ItemChannelLinks`). So if one Channel is linked to several Items it also will have several profile instances, each handling the communication to exactly one of these Items.
The same applies for the situation where one Item is linked to multiple Channels.
By their nature, profiles are correlated to links between Items and Channels (i.e. `ItemChannelLinks`). So if one Channel is linked to several Items it also will have several profile instances, each handling the communication to exactly one of these Items.
The same applies for the situation where one Item is linked to multiple Channels.
Profiles are created by ProfileFactories and are retained for the lifetime of their link.
This means that they are allowed to retain a transient state, like e.g. the timestamp of the the last event or the last state.
Profiles are created by ProfileFactories and are retained for the lifetime of their link.
This means that they are allowed to retain a transient state, like e.g. the timestamp of the the last event or the last state.
With this, it is possible to take into account the temporal dimension when calculating the appropriate action in any situation.
There exist two different kinds of profiles: state and trigger profiles.
### State Profiles
## State Profiles
State profiles are responsible for communication between Items and their corresponding state Channels (`ChannelKind.STATE`).
State profiles are responsible for communication between Items and their corresponding state Channels (`ChannelKind.STATE`).
Their purpose is to forward state updates and commands to and from the Thing handlers.
### Trigger Profiles
## Trigger Profiles
Trigger Channels (`ChannelKind.TRIGGER`) by themselves do not maintain a state (as by their nature they only fire events).
With the help of trigger profiles they can be linked to Items anyway.
Hence the main purpose of a trigger profile is to calculate a state based on the fired events.
This state then is forwarded to the linked Item by sending `ItemStateEvents`.
Trigger Channels (`ChannelKind.TRIGGER`) by themselves do not maintain a state (as by their nature they only fire events).
With the help of trigger profiles they can be linked to Items anyway.
Hence the main purpose of a trigger profile is to calculate a state based on the fired events.
This state then is forwarded to the linked Item by sending `ItemStateEvents`.
Trigger profiles are powerful means to implement some immediate, straight-forward logic without the need to write any rules.
Trigger profiles are powerful means to implement some immediate, straight-forward logic without the need to write any rules.
Apart from that, they do not pass any commands or state updates to and from the Thing handler as by their nature trigger Channels are not capable of handling these.

8
concepts/things.md
View File

@ -12,7 +12,7 @@ From a user perspective, they are relevant for the setup and configuration proce
Things can have configuration properties, which can be optional or mandatory.
Such properties can be basic information like an IP address, an access token for a web service or a device specific configuration that alters its behavior.
### Channels
## Channels
Things provide "Channels", which represent the different functions the Thing provides.
Where the Thing is the physical entity or source of information, the Channel is a concrete function from this Thing.
@ -23,17 +23,16 @@ Channels are linked to Items, where such links are the glue between the virtual
Once such a link is established, a Thing reacts to events sent for an item that is linked to one of its Channels.
Likewise, it actively sends out events for Items linked to its Channels.
### Bridges
## Bridges
A special type of Thing is a "bridge".
Bridges are Things that need to be added to the system in order to gain access to other Things.
A typical example of a bridge is an IP gateway for some non-IP based home automation system or a web service configuration with authentication information which every Thing from this web service might need.
### Discovery
## Discovery
As many Things can be automatically discovered, there are special mechanisms available that deal with the handling of [automatically discovered Things](discovery.html).
## Thing Status
Each Thing has a status object, which helps to identify possible problems with the device or service.
@ -93,4 +92,3 @@ The following table lists the different status details for each status:
<tr valign="top"><td>REMOVING</td> <td>NONE</td><td>No further status details available.</td></tr>
<tr valign="top"><td>REMOVED</td> <td>NONE</td><td>No further status details available.</td></tr>
</table>

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

@ -41,29 +41,30 @@ The unit given in the state description is parsed and then used for conversion (
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.
Number:Temperature temperature "Outside [%.2f °F]" { channel="...:current#temperature" }
`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:
"Outside [%.2f %unit%]"
`"Outside [%.2f %unit%]"`
The special placeholder `%unit%` will then be replaced by the actual unit symbol.
The placeholder `%unit%` can be placed anywhere in the state description.
#### Defining ChannelTypes
### Defining ChannelTypes
In order to match `NumberItems` and Channels and define a default state description with unit placeholder the Channel also has to provide an Item type which includes the dimension information:
<channel-type id="temperature">
<item-type>Number:Temperature</item-type>
<label>Temperature</label>
<description>Current temperature</description>
<state readOnly="true" pattern="%.1f %unit%" />
</channel-type>
```xml
<channel-type id="temperature">
<item-type>Number:Temperature</item-type>
<label>Temperature</label>
<description>Current temperature</description>
<state readOnly="true" pattern="%.1f %unit%" />
</channel-type>
```
The state description pattern "%.1f %unit%" describes the value format as floating point with one decimal place and also the special placeholder for the unit.
@ -80,7 +81,6 @@ The `org.openhab.core.library.dimension` and `javax.measure.quantity` packages p
All units which are currently supported by default are listed in the tables below.
Imperial (base unit symbols):
| Type | Unit | Symbol |
@ -213,7 +213,8 @@ Binary Prefixes:
| Yobi | Yi | 2⁸⁰ |
To use the prefixes simply add the prefix to the unit symbol - for example:
* milliAmpere - `mA`
* centiMetre - `cm`
* kiloWatt - `kW`
* KibiByte - `KiB`
- milliAmpere - `mA`
- centiMetre - `cm`
- kiloWatt - `kW`
- KibiByte - `KiB`

5
configuration/addons.md
View File

@ -2,8 +2,6 @@
layout: documentation
---
{% include base.html %}
# Installation of Add-ons
Add-ons can be installed in different ways, described below.
@ -14,7 +12,7 @@ Log into your admin account (if not already done).
Navigate to `Settings` and have a look for the add-ons section.
Search for the desired add-on in the categories and press install.
![installing Add-ons through Paper UI](./images/InstallAddonsThroughUi.gif)
![installing Add-ons through UI](./images/InstallAddonsThroughUi.gif)
## Through Configuration Files
@ -72,7 +70,6 @@ binding = astro,network
After saving the file, the add-on will be installed.
## Through manually provided add-ons
::: warning Attention

39
configuration/apitokens.md Normal file
View File

@ -0,0 +1,39 @@
---
layout: documentation
title: openHAB API tokens
---
# openHAB API tokens
API tokens are an authentication method, like an username and password.
Usually you would use an API token to authenticate an external service or script.
## Generate an API token
Sign in to openHAB with your administrator username and password, by clicking on the sign-in button (bottem left).
After signing in, click again on the profile button to access your profile page.
Click on Create new API token.
![apitoken login](images/apitoken_login.png)
Use your admin username and password and fill in the token name (e.g. the service you want to gain access for) and a Token Scope.
![Create token](images/apitoken_create_token.png)
Now the token is created.
Copy the complete token.
![Token](images/apitoken_token.png)
This token is in the used service your username, leave the password empty.
As example, below in NodeRed configuration the generated token is used as username.
![Example](images/apitoken_example.png)
## Overview of generated tokens
In your profile overview page you can find an overview of generated tokens.
Additionally, they can be deleted here.
![Overview](images/apitoken_overview_tokens.png)

13
configuration/editors.md
View File

@ -15,7 +15,7 @@ This documentation page can give you some guidance in choosing the right one for
- TOC
{:toc}
### Network Preparations
## Network Preparations
Any editors used to configure openHAB need to be able to access the configuration files on the remote openHAB host.
@ -27,6 +27,7 @@ If you are using [openHABian]({{base}}/installation/openhabian.html), the networ
*Attention Windows users:* Directly accessing network shares (UNC paths) is often not supported. Please be sure to mount the network share to a drive letter.
{: #openhab-vscode}
## openHAB VS Code Extension
openHAB VS Code is an extension for the [Visual Studio Code](https://code.visualstudio.com) editor.
@ -37,10 +38,11 @@ You can find it in the [Microsoft Visual Studio Marketplace](https://marketplace
### Installation
1. Install [Visual Studio Code](https://code.visualstudio.com/Download) on your desktop computer (not on the openHAB host)
2. Open the extension sidebar. <br> ![openHAB VS Code Extension alternative installation](images/vscode_extensiontab_icon.png)
3. Search for openHAB and install the extension.
1. Open the extension sidebar.
![openHAB VS Code Extension alternative installation](images/vscode_extensiontab_icon.png)
1. Search for openHAB and install the extension.
[Visit the Extensions GitHub Page for further Informations](https://github.com/openhab/openhab-vscode/blob/master/README.md "GitHub Repo for the VS Code Extension")
[Visit the Extensions GitHub Page for further Informations](https://github.com/openhab/openhab-vscode/blob/main/README.md "GitHub Repo for the VS Code Extension")
### Rule Validation
@ -50,6 +52,7 @@ The validation needs a running openHAB installation in your environment and can
You can find all important information in the extensions [readme file](https://github.com/openhab/openhab-vscode#validating-the-rules).
{: #others}
## Other Editor Integrations
The here summarized projects provide syntax highlighting for different text editors, but have no _on top_ functionality.
@ -60,6 +63,7 @@ mcedit is an editor which comes with mc (Midnight Commander).
You can find the syntax files and installation instructions on [openhab-mcedit](https://github.com/CWempe/openhab-mcedit).
{: #notepadpp}
### Notepad++
Notepad++ is a free source code editor for Windows.
@ -85,4 +89,3 @@ You can find the syntax file and installation instructions on [openhab-syntax-te
BBEdit is a text and code editor for macOS and the offical successor of TextWrangler.
You can find the syntax file and installation instructions on [BBEdit-openHAB-language](https://github.com/mjmeijer/BBEdit-openHAB-language).

284
configuration/habpanel.md
View File

@ -1,284 +0,0 @@
---
layout: documentation
title: HABPanel
source: https://github.com/openhab/org.openhab.ui.habpanel/blob/master/doc/habpanel.md
---
{% include base.html %}
<!-- Attention authors: Do not edit directly. Please add your changes to the appropriate source repository -->
# Designing dashboard interfaces with HABPanel
The [HABPanel]({{base}}/addons/ui/habpanel/readme.html) user interface is installed by default when choosing any initial setup package, and allows the creation of user-friendly dashboards, particularly suited for (e.g. wall-mounted) tablets. These dashboards can be designed interactively in the embedded designer, rather than using configuration files.
Despite being similar, HABPanel's dashboards and [sitemaps]({{base}}/configuration/sitemaps.html) are separate concepts, and can be designed independently as they aren't related to each other; however, they rely and act on [items]({{base}}/concepts/items.html) which must therefore be [defined]({{base}}/configuration/items.html) first. The [demo setup package]({{base}}/configuration/packages.html#demo-package-sample-setup), available for installation when starting openHAB for the first time, defines a series of sample items and configures HABPanel with a comprehensive set of dashboards to showcase a possible end result. It's the same as the one installed on the [openHAB Demo Server](https://demo.openhab.org/){:target="_blank"}, and it may be modified without risk of breaking anything: it's the best playground to discover HABPanel's features.
## Concepts
HABPanel has its own terminology of entities presented below:
![HABPanel concepts](images/habpanel_concepts.png)
- The **Panel Registry** is the central storage used by HABPanel on a given openHAB instance, it contains several **Panel Configurations**;
- A **Panel Configuration** is a container holding a **Panel** along with its **Settings** and the definition of **Custom Widgets**. Each device HABPanel runs on (desktop browser, tablet...) has an active panel configuration and displays the panel associated with it;
- A **Panel** is a set of **Dashboards** (or pages) which can be presented to end users, who can also easily switch between them using the menu.
- A **Dashboard** is comprised of discrete **Widgets** positioned on the dashboard's surface at design time. There are several types of built-in *standard widgets*, configured separately, and the administrator can also develop (or import) *custom widgets*.
## About data persistence
By default, when running HABPanel on a new browser or device, a tutorial will be displayed allowing the user to start from scratch, or switch to an previously defined panel configuration. **Until a panel configuration is created (or chosen), HABPanel will run in "local storage" mode for this device: the settings will be retained in the browser's local storage only and nothing will be persisted on the server.** By contrast, when an active panel configuration is set, each change performed on the device will update the panel configuration on the server. This allows the sharing of panel configuration among devices, because other browsers and devices using this panel configuration will pick up the changes with a page refresh - this is useful for instance to design a panel comfortably on a computer, then use it on a tablet.
To switch from the local storage to a server-hosted panel configuration, go to the Settings page from the main menu or the side drawer (see below). A list of panel configurations will be presented in the _Current storage configuration_ section; if only the _"Local storage"_ option is available, click on the **Save the current configuration to a new panel configuration** link, give it a name to identify it (avoid spaces or special characters), and it should be added to the list. The radio button is also automatically checked, meaning it is now the active panel configuration.
Even when there is an active panel configuration, HABPanel uses the browser's storage to sync a locally-managed copy. With the **Edit the local panel configuration (experts only)** link under the _"Local storage"_ storage configuration option in the settings screen, the raw structure of the panel configuration can be inspected, modified, and exported or imported from/to a .json file. It is also an alternative way to backup, restore and share the configuration.
HABPanel uses service configuration variables to store its data on the openHAB server. They can be accessed using Paper UI (_Configuration > Services > UI > HABPanel > Configure_) or in the openHAB Karaf console:
```
openhab> config:edit org.openhab.habpanel
openhab> config:property-get <property>
```
The following properties are defined:
- `panelsRegistry`: contains the entire registry serialized in JSON, it is maintained by the application and shouldn't be modified directly (editing it by hand, while possible, is strongly discouraged);
- `lockEditing`: when enabled, all HABPanel instances will hide their editing features (a page refresh is necessary). When panels are complete and stable, it is advisable to turn on this setting so they cannot be easily modified by end users;
- `initialPanelConfig`: if this option is unset and no prior local configuration is detected, the tutorial will be displayed until some dashboards are added or a panel configuration is selected. This setting allows to bypass the tutorial and switch directly to the existing panel configuration with the given name.
## Major interface elements and features
### The main menu
The main menu is HABPanel's home page. It contains tiles linking to the panel's dashboards, and an icon to switch between the run mode and the edit mode (if available).
![Main menu - run mode](images/habpanel_main-menu-run.png)
Use the gears icon in the top-right corner to switch between the two modes.
![Main menu - edit mode](images/habpanel_main-menu-edit.png)
When in edit mode, several features are available:
* Add a new empty dashboard with the **Add new dashboard** link;
* Go to the settings screen (for instance, to switch from local storage to a server-managed panel configuration) by clicking on the **Advanced settings** link;
* Adjust the number of columns for the grid of main menu tiles with the slider, from 1 (the default) to 6;
* Drag the arrow icons in the top-left corner of each tile to move it;
* Resize tiles with the chevron (triangle) in the bottom-right corner of each tile;
* Configure the tiles and the dashboards themselves with the gears icons in the top-right corner of each tile;
* Enter the dashboard designer by clicking inside a tile.
The configuration dialog when clicking on a tile's gear icon contains the following settings:
| Setting | Description
|---------|-------------|
| Name | The name of the dashboard, also displayed on the tile
| Background URL | The URL of a background image *for the main menu tile*
| Backdrop Icon | Iconset and icon displayed on the tile as a Backdrop
| Center backdrop horizontally | When unchecked, the backdrop is aligned to the right of the tile; when checked, it is centered
| Icon | Icon associated with the dashboard, currently only used in the side drawer
| Size (icon) | _(currently unused)_
| Title Text Color | Color for the name of the dashboard on the tile
| Advanced tab | Contains settings currently unstable or unsupported, for advanced users only
| Custom widgets tab | This [experimental feature](https://community.openhab.org/t/new-display-options-incl-experimental-custom-widgets-everywhere/34140/1) allows certain parts of a dashboard to be replaced by a custom widget (see _Custom Widgets_ below): the main menu tile, the drawer menu and the dashboard item - use with caution
It also contains a **Delete** button which will delete the entire dashboard and its contents - this happens immediately and cannot be undone!
### The side drawer
![Side drawer](images/habpanel_side-drawer.png)
The side drawer can be accessed from any screen by a swipe or drag to the right (on most elements where there isn't a conflict with this gesture), or with the "hamburger icon" ☰ in the top-left corner.
It is comprised of three parts:
1. A **header** - clicking on it returns to the main menu. Note: if defined, the title of the panel is displayed instead of the default "HABPanel" label, it is configured in the settings (see below);
2. A **list of dashboards** for quick switching between dashboards without going back to the main menu - they are presented in the order of the menu (sorted by row, then by column);
3. A **footer** displaying the current date & time and featuring a link to the settings screen (if available).
### The dashboard designer
![Dashboard designer](images/habpanel_dashboard-designer.png)
The dashboard designer is where widgets can be added, positioned, resized and configured. Placeholders are displayed where actual widgets would be on the running dashboard.
To add a widget, use the **Add widget** button and choose among the list of standard widgets, or eventual custom widgets in the panel configuration.
See below for a description of the standard widgets.
![Add widget menu](images/habpanel_add-widget.png)
Use the header of a widget placeholder (with the four-arrow icon and the widget type) to move the widget. Moving a widget over other widgets do not push them away to make room (contrary to the main menu tiles), so ensure there is sufficient room for your widget before moving it.
![Widget placeholder features](images/habpanel_dashboard-designer-placeholder-menu.png)
When hovering over a placeholder (or tapping inside it if on a touch interface), a chevron appears in the bottom-right corner allowing to resize it.
Use the ellipsis icon **⁝** to bring up the widget's contextual menu, offering the following options:
- **Edit...:** Displays the configuration dialog for the widget. The options available in the dialog depend on the type of the widget and are detailed in the Widgets section;
- **Copy/move to...**: Displays a dialog allowing to clone the widget with its configuration, to the current dashboard or another, or move it to another dashboard (the target widget will retain its size of the source widget but it will be placed where there is available room, use the target dashboard's designer to find it and reposition it);
- **Delete**: Deletes the widget.
Modifications to the dashboard are not saved automatically, use the **Save** button in the header to commit the changes to the panel configuration (or local storage). The **Run** button also saves, then runs the dashboard.
### Running dashboards
![A running dashboard](images/habpanel_running-dashboard.png)
When a dashboard is running, widgets can be interacted with, and server-sent events are received when items' states are updated, so widgets update automatically in HABPanel.
The icons in the top-right corner perform the following:
- the **speech balloon** activates the speech recognition feature and send the results as text to openHAB's default human language interpreter. This implies [some configuration on the server]({{base}}/configuration/multimedia.html#human-language-interpreter), and this icon might not be displayed if the browser doesn't support voice recognition ([mainly only in Chrome and other webkit variants currently](http://caniuse.com/#feat=speech-recognition){:target="_blank"}). It can also be configured in the panel configuration to appear on the bottom of the screen;
- the **refresh** button forces HABPanel to retrieve the current state of all items;
- the **fullscreen** button tells the browser to go fullscreen, if supported.
Tip: while running a dasboard, append `?kiosk=on` to the URL in the web browser to switch to "kiosk mode"; in this mode, the header, hamburger menu and toolbar will be hidden and the side drawer will be disabled - therefore there will be no easy way for an end user to switch to another screen (except with button widgets configured for that purpose). This mode is useful to display a full-screen, bare-bones UI for a fixed tablet.
## Additional features and settings
Apart from the storage configuration discussed above, the settings screen contains several settings kept as part of the panel configuration (meaning they are set separately):
| Setting | Description
|---------|-------------|
| Panel name | An user-friendly name for the panel. It will be displayed in the header of the side drawer.
| Theme | HABPanel comes with a number of built-in themes, with this setting a different theme may applied to the panel. Themes are not user-modifiable.
| Background image | Sets the specified URL as background image for the whole panel. *Tip: the background image works best with the 'translucent' theme!*
| Additional stylesheet | Reference the relative URL of an additional CSS file which will be included and can be used to override the styles defined by the theme. For additional information on how you can customize HABPanel's styles, go to: [HABPanel Development & Advanced Features: Start Here!](https://community.openhab.org/t/habpanel-development-advanced-features-start-here/30755/1)
| Drawer heading image | Reference the URL of an image (expected width: 265 pixels) which will replace the header in the side drawer
| Hide the drawer's footer | Check to remove the bottom black part of the side drawer containing the date & time
| Hide toolbar buttons (speak/refresh/fullscreen) | Check those boxes to hide the corresponding button in the default dashboard header top-right corner
| Show a clock in the header | If checked, a clock will be displayed in the main menu and the dashboards
| Header clock format (shown if "Show a clock in the header" is checked) | Use an [AngularJS' date filter format string](https://docs.angularjs.org/api/ng/filter/date) to customize the clock format in the header. The default is `HH:mm`
| Prevent scrolling (when not editing) | When enabled, it is impossible to scroll the dashboard on a tablet (and it prevents the "elastic" bouncing effect on iOS/Safari)
| Manage > (custom widgets) | Goes to the list of custom widget definitions for the active panel configuration
| Voice | Selects a voice from the detected list for text-to-speech*
| Speak the new value of the following item when it changes | When the selected String item change to a new text, HABPanel will use the browser's text-to-speech engine and the selected voice to read it aloud*
| Display a floating speech button at the bottom of the screen | Use an alternative style for the Speak (voice input) button in dashboards
| When this item changes to a dashboard's name, switch to it | This allows controlling the currently displayed dashboard by an openHAB item (useful with rules and as a side-effect to commands)
*Note: the text-to-speech functionality featured in HABPanel is unrelated to the [TTS services]({{base}}/configuration/multimedia.html#text-to-speech) defined on the openHAB server, and they are not compatible (this is why a String item is required and the `say()` function cannot be used). However, HABPanel will play audio streamed through the ['webaudio' sink]({{base}}/configuration/multimedia.html#audio), including spoken text.
## Widgets
### Standard widgets
The following built-in widgets are available:
#### Dummy (dummy)
![Dummy widget](images/habpanel_widget-dummy.png)
The so-called dummy widget (whose name is explained by historical reasons - it evolved from the first developed widget) displays the current state of an item without any interactivity, along with a label and an optional icon.
#### Switch (switch)
![Switch widget](images/habpanel_widget-switch.png)
The switch widget is a simple widget to control a Switch item as defined in openHAB - it reports its state and is able to toggle it between ON and OFF.
#### Label (label)
![Label widget](images/habpanel_widget-label.png)
The label widget is straightforward: it simply displays a fixed text and has a few appeareance options (color, font). It can for example be used as a header for a group of widgets below it.
#### Button (button)
![Button widget](images/habpanel_widget-button.png)
The button widget can be clicked (or tapped) and will perform an action, like sending commands to an item or navigating to another dashboard. It can also adjust its colors depending on the state of the underlying item.
Multiple buttons are often used together to present different options for an item.
#### Slider (slider)
![Slider widget](images/habpanel_widget-slider.png)
The slider widget can reflect the state of, and update, numerical items within a range of values. Several options are available to alter its appearance and behavior.
#### Knob (knob)
![Knob widget](images/habpanel_widget-knob.png)
The knob widget is similar in essence to the slider, but in a rotary fashion. It also offers extensive configurability over its appearance and behavior.
#### Selection (selection)
![Selection widget](images/habpanel_widget-selection.png)
The selection widget displays the current state of an item, much like a dummy widget, except it opens a menu or a grid of automatically or manually configured choices for sending commands to this item. Various display options are available.
#### Color picker (colorpicker)
![Color picker widget](images/habpanel_widget-colorpicker.png)
The color picker widget offers several ways of displaying and updating the state of an openHAB Color item (or group).
#### Image (image)
![Image widget](images/habpanel_widget-image.png)
The image widget can display an image, directly or via an openHAB String item, and can refresh it at regular intervals.
#### Frame (frame)
![Frame widget](images/habpanel_widget-frame.png)
The frame widget displays an external web page in a HTML `<iframe>`.
#### Clock (clock)
![Clock widget](images/habpanel_widget-clock.png)
The clock widget displays an analog or digital clock. It can also be used to display the current date.
#### Chart (chart)
![Chart widget](images/habpanel_widget-chart.png)
The chart widget can leverage openHAB persistence services to plot numerical series over a time period. It can also display server-generated chart images (default or rrd4j variants).
#### Timeline (timeline)
![Timeline widget](images/habpanel_widget-timeline.png)
The timeline widget is the chart widget's counterpart for non-numerical items. It can display multiple "swimlanes" of items with color-coded slices representing their state changes during the selected period. Hovering or tapping inside a color slice displays details on the state of the item at the time.
#### Template (template)
The template widget allows an user-configured AngularJS HTML template to be rendered and hosted inside the widget boundaries; it exposes several helper functions and other facilities to retrieve and update openHAB's items from the template's markup.
With only a few web development skills required, you can easily start developing your own widgets and share them to community. It is nonetheless rather complex, so the best information has been compiled in this community wiki topic: [HABPanel Development & Advanced Features: Start Here!](https://community.openhab.org/t/habpanel-development-advanced-features-start-here/30755). You can also [learn by example in the forum's HABPanel category](https://community.openhab.org/c/apps-services/habpanel) or seek the help of the community.
Templates are defined inline, for each particular instance, and thus are not optimized for sharing and re-use. For those cases, developing a _custom widget_ is more appropriate.
### Custom widgets
Custom widgets are similar to (and based on) the template widget but are designed to be reused, shared, and configured. A custom widget is an AngularJS template with an associated set of configuration settings. It can be added to dashboards and configured individually, like a built-in widget. Definitions of custom widgets are stored in the registry at the panel configuration level; this means they are specific to a panel configuration and each panel configuration has its own custom widgets (see the _Concepts_ section above).
For more information, please read the [community thread about this feature](https://community.openhab.org/t/custom-widgets-feature-walkthrough/16670/1).
#### Managing custom widgets
The list of custom widgets either via the dashboard designer (click/tap the gears icon in the _Add Widget_ dropdown menu), or with the _Manage_ button in the settings screen.
From the list, custom widgets can be created from scratch, or imported from a previously exported .json file or a GitHub repository. Members of the openHAB community also present their custom widgets on the forum: the _Get widgets from the openHAB community_ link brings up a filtered lists of custom widgets from the community.
Widgets can also come from [an openHAB addon or OSGi bundle](https://community.openhab.org/t/new-feature-globally-provisioned-widgets-i-e-with-osgi-bundles/26994): those are "globally-provisioned widgets". They cannot be modified or deleted (but can be cloned and then modified), and are available to all panel configurations.
The context menu **⁝** can be used to perform operations on the widget: globally-provisioned widgets can only be cloned, and manually defined or imported widgets can be exported or deleted. Widgets imported from GitHub can also be updated and include a link to repository's Readme file.
#### The widget designer
Upon clicking on a custom widget definition, the widget designer opens. It contains three tabs:
- **Code:** This tab is an editor for the template's code. You can use the Ctrl-S (or Cmd-S) keyboard shortcut to save the widget while editing the code;
- **Settings:** This tab hosts the widget's general settings and configuration settings structure to be defined.
Click on the **Add setting** to add a new configuration setting. Each configuration setting must have a type, a technical ID, and other optional attributes. Each type of setting determines the UI element presented in the dashboard designer when configuring instances of the custom widget.
Use the arrow buttons to move configuration settings up or down, and the trash bin icon to remove them.
When instantiated, the value of configuration settings are set in the template's scope as `config.<setting_id>` (except those of type Icon which define an additional value, the iconset name, as `config.<setting_id>_iconset`);
- **Preview:** Upon switching to this tab, a test instance of the widget is rendered in an otherwise blank testbed dashboard. Use the sliders to resize the widget in order to preview it at different sizes. If it defines configuration settings, they must likely be set for this preview using the gears icon: this will bring up the widget instance's configuration dialog as it would appear in the dashboard designer.
Don't forget to save the changes with the **Save** button.

BIN
configuration/images/apitoken_create_token.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 KiB

BIN
configuration/images/apitoken_example.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

BIN
configuration/images/apitoken_login.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 44 KiB

BIN
configuration/images/apitoken_overview_tokens.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.6 KiB

BIN
configuration/images/apitoken_token.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

13
configuration/index.md
View File

@ -86,7 +86,7 @@ _Note there is an option in Main UI to bulk create Items where you can copy'n'pa
<td>✔️</td>
<td>❌</td>
<td>❌</td>
<td>transform/*.map *.js files</td>
<td>transform/*.map*.js files</td>
</tr>
<tr>
<td>Define Persistence</td>
@ -157,15 +157,14 @@ All text files must be created with UTF-8 encoding. When using Visual Studio Cod
Here are some hints to avoid some common pitfalls when starting out.
* Start by modelling your house using a Semantic Model in Main UI.
- Start by modelling your house using a Semantic Model in Main UI.
Use it to create groups for rooms and apply proper semantic tags right away.
This will ultimately save a lot of setup work, as it will allow for group functions such as "switch off lights in _kitchen_" or _ground floor_ or _house_" and
also enable voice assistants to properly execute your instructions.
Be careful to apply a consistent naming scheme right in the beginning.
* Use Main UI to manage Things. Remember that once initially configured, their configuration will not change much over time.
* Run autodiscovery for _Things_ wherever offered so that you don't have to enter all of them manually
* Also use Main UI to manage Items.
- Use Main UI to manage Things. Remember that once initially configured, their configuration will not change much over time.
- Run autodiscovery for _Things_ wherever offered so that you don't have to enter all of them manually
- Also use Main UI to manage Items.
You can use the import function to import `.items` files or snippets taken from other sources like the openHAB community forum.
* Use VS code extensions to [edit rules, items and sitemap files](editors.html).
- Use VS code extensions to [edit rules, items and sitemap files](editors.html).
You can also use any text editor or cloud based tool, but VS code extensions will work locally and help you by highlighting and cross-checking the file syntax.

95
configuration/items.md
View File

@ -32,9 +32,9 @@ For example, an Item bound to a sensor receives updated sensor readings and an I
There are two methods for defining Items:
1. Through UI
1. Through UI
2. Through text `.items` files located in the `$OPENHAB_CONF/items` folder.
1. Through text `.items` files located in the `$OPENHAB_CONF/items` folder.
Files here must have the extension `.items`; you may create as many `.items` files as needed.
However, each Item must be unique across all `.items` files.
Refer to the [installation docs]({{base}}/installation/index.html) to determine your specific installation's folder structure.
@ -51,6 +51,7 @@ It's recommended to edit `.items` files using one of the [openHAB supporting edi
Doing so will provide you with full IDE support including features such as syntax checking, and context assistance.
{: #syntax}
## Item Definition and Syntax
Items are defined using the following syntax:
@ -68,7 +69,7 @@ itemtype itemname "labeltext [stateformat]" <iconname> (group1, group2, ...) ["t
**Examples:**
```java
Switch Kitchen_Light "Kitchen Light" {mqtt="<[...], >[...]" }
Switch Kitchen_Light "Kitchen Light" {channel="mqtt:topic:..." }
String Bedroom_Sonos_CurrentTitle "Title [%s]" (gBedRoom) {channel="sonos:..."}
Number Bathroom_WashingMachine_Power "Power [%.0f W]" <energy> (gPower) {channel="homematic:..."}
@ -89,6 +90,7 @@ The last example above defines an Item with the following fields:
The remainder of this article provides additional information regarding Item definition fields.
{: #type}
### Type
The Item type defines what kind of state can be stored in that Item and which commands the Item will accept.
@ -145,6 +147,7 @@ In the example above, if you move the Slider widget to 60%, move the Switch to O
-->
{: #name}
### Name
The Item name is used to uniquely identify an Item.
@ -164,14 +167,14 @@ An Item naming scheme with a physical or logical top-down will ensure you can ea
The following naming style guide is recommended:
- Words build a physical or logical hierarchy
- Words build a physical or logical hierarchy
- Every word of the Item name starts with an uppercase letter
- Every word of the Item name starts with an uppercase letter
- Words should be separated by an underscore character, except for words that logically belong together
- Words should be separated by an underscore character, except for words that logically belong together
- Names that reoccur frequently, such as the names of rooms or appliances, may be abbreviated to reduce overall name length.
(Example: Bathroom = BR)
- Names that reoccur frequently, such as the names of rooms or appliances, may be abbreviated to reduce overall name length.
(Example: Bathroom = BR)
Examples:
@ -187,9 +190,9 @@ Examples:
Users are encouraged to apply the style guide above to group names as well as Item names.
Two naming schemes are established in the community for Group names:
1. Use a plural word form (e.g. Batteries) where possible.
1. Use a plural word form (e.g. Batteries) where possible.
Otherwise the word "Group" may be appended for clarity.
2. Prepend a lowercase "g" to the name (e.g. gBattery)
1. Prepend a lowercase "g" to the name (e.g. gBattery)
| Group Name | Interpretation |
|-------------------------------------------|-----------------------------------------------------------------------|
@ -199,6 +202,7 @@ Two naming schemes are established in the community for Group names:
| "`Livingroom`" or "`gLR`" | Group for *all* Items (including lights) belonging to the living room |
{: #label}
### Label
Label text is used to describe an Item in a human-readable way.
@ -215,28 +219,31 @@ Number Livingroom_Temperature "Temperature [%.1f °C]"
Channel labels can be overwritten by Item definitions and Item labels can be overwritten in [Sitemaps]({{base}}/configuration/sitemaps.html#element-types).
{: #state}
### State
The state of an Item depends on the Item type, the Channel bound to the Item, and internal or external events.
A analogy can be drawn between the state of an Item and the value of a variable in a computer program.
{: #item-state}
#### Item State
This section provides information about what a user can expect regarding the behavior of the state of an Item.
- Items are created with a state of `NULL`
- Items are created with a state of `NULL`
- Operations in openHAB such as a user interacting with the Item using the Basic UI, or a Binding updating the state of an Item will change the state of the Item
- Operations in openHAB such as a user interacting with the Item using the Basic UI, or a Binding updating the state of an Item will change the state of the Item
- An Item's state may also be set through a Binding which may be reacting to changes in the real world
- An Item's state may also be set through a Binding which may be reacting to changes in the real world
- A Binding may set the state of an Item to `UNDEF` if it looses communications with a Thing (for example, a Z-wave doorbell with a dead battery).
The Binding may also set the state to `UNDEF` if an error exists in the binding configuration, or under other conditions
- A Binding may set the state of an Item to `UNDEF` if it looses communications with a Thing (for example, a Z-wave doorbell with a dead battery).
The Binding may also set the state to `UNDEF` if an error exists in the binding configuration, or under other conditions
*N.B.* Many openHAB users find that it can be very useful to use [Persistence](/addons/#persistence) and [System started]({{base}}/configuration/rules-dsl.html#system-based-triggers) rules so that their systems behaves in a predictable way after an openHAB restart.
{: #command-vs-status}
#### Command vs. Status
Users should bear in mind the difference between an Item used to send a command to a Thing, and an Item that reflects the status of a real-world Thing in the UI.
@ -258,6 +265,7 @@ Then you add the light-level Item to your UI.
Now when you send the Switch Item command, and you see a corresponding increase in light level in the room, you know for sure that your command has been received and acted upon, because you have a return status Item in your UI.
{: #state-presentation}
#### State Presentation
The Item definition determines the Item's textual state presentation, e.g., regarding formatting, decimal places, unit display and more.
@ -286,6 +294,7 @@ Location My_Location "My Location [%2$s°N %3$s°E %1$sm]" // e.g.
```
{: #state-transformation}
#### State Transformation
Transformations can be used in the state part of an Item, to translate the raw state of an Item into another language, or to convert technical values into human readable information.
@ -299,6 +308,7 @@ Contact Livingroom_Window "Ventana del salón [MAP(window_esp.map):%s]"
Please refer to the article on [Transformations](/docs/configuration/transformations.html) for more usage details and a list of available transformation services.
{: #icons}
### Icons
The icon name is used by openHAB to select the image to display next to an Item name when using one of openHAB's UIs, e.g. Basic UI.
@ -332,6 +342,7 @@ Note that image files with the wrong file ending will be ignored.
Users may substitute their own icon for an icon from the default icon set by placing a file in the `$OPENHAB_CONF/icons/classic/` folder with the same filename as the name of the icon being substituted.
{: #icons-dynamic}
#### Dynamic Icons
Some icons are dynamically selected by openHAB depending on the Item's state.
@ -353,15 +364,15 @@ Dynamic icon filenames follow the pattern below:
Dynamic icon sets may consist of as many state-specific icon files as needed.
Each set must meet the following criteria:
- A default icon is mandatory.
- A default icon is mandatory.
The default icon filename is the name of the icon without a hyphen or state (e.g. `switch.svg`)
- Icon filenames must follow the naming restrictions given for [icons](#icons) above
- Icon filenames must follow the naming restrictions given for [icons](#icons) above
- The state name must reflect the Item's raw state.
- The state name must reflect the Item's raw state.
[Transformations](#state-transformation) applied in the state presentation definition of the Item have no influence on icon selection.
- The state portion of the icon name must be in lowercase letters
- The state portion of the icon name must be in lowercase letters
**Example:**
@ -403,6 +414,7 @@ For a dimmable light (0-100%), you might provide icons as in the example:
Just as with regular icons, user-defined dynamic icon sets may be configured via the custom icons folder `$OPENHAB_CONF/icons/classic/`.
{: #groups}
### Groups
The Group is a special Item type that can be used to define a category or collection into which you can combine other Items or Groups.
@ -416,12 +428,12 @@ Group groupname ["labeltext"] [<iconname>] [(group1, group2, ...)]
The Group item is commonly used to define hierarchies of Items from different perspectives.
For example:
- Location-oriented or physical perspective:
- Floors in your house → Rooms on that floor → An appliance in that room...
- Location-oriented or physical perspective:
- Floors in your house → Rooms on that floor → An appliance in that room...
- Functional or logical perspective:
- Maintenance Group → All battery states → Individual battery states in percentage
- Further examples: all lights, all room temperatures, combined power consumption
- Functional or logical perspective:
- Maintenance Group → All battery states → Individual battery states in percentage
- Further examples: all lights, all room temperatures, combined power consumption
These relationships can be exploited in [Sitemaps]({{base}}/configuration/sitemaps.html) or in [automation rules]({{base}}/configuration/rules-dsl.html) to navigate through the hierarchically organized Items or to perform computations and updates on subsets of similar Items.
@ -455,6 +467,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}
### Derive Group State from Member Items
As you are now aware, an Item can have a state (e.g. "ON", "OFF").
@ -492,13 +505,13 @@ Incompatible Item types within a Group may result in the invalid aggregation res
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: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"
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 three examples above compute the number of active lights and store them as group state.
@ -518,6 +531,7 @@ The `EARLIEST` function returns `now().minusDays(10)`, the `LATEST` function ret
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 its basic Item type.
@ -538,6 +552,7 @@ Tags will be ignored if no Items in the openHAB installation support it.
See the [Hue Emulation Service](/addons/integrations/hueemulation/) or [HomeKit Add-on](/addons/integrations/homekit/) documentation for more details.
{: #binding}
### Binding Configuration
One of the greatest strengths of an openHAB automation system is the sheer number of devices you can interact with.
@ -558,11 +573,11 @@ Each Thing has one or more Channels, and Items are linked to one or more Channel
There are two different kinds of channels:
- State Channels will, as soon as linked to the Item, update the state of it and/or listen for Commands you send to it.
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`)
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 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.
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 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 UI.
Once accepted, the new Thing will appear under Settings > Things.
@ -609,8 +624,8 @@ Switch Office_PC {channel="lgwebos:WebOSTV:01dd3ac4-62f4-7505-208b-12345679", ch
The first example shows a symbiosis of the LG webOS Binding and the Wake-on-LAN Binding to interact with a TV.
{: #autoupdate}
#### Parameter `autoupdate`
When left as default, openHAB's `autoupdate` function attempts to predict the outcome of a *command* on the Item *state*.
@ -626,6 +641,7 @@ Switch Garage_Gate {channel="xxx", autoupdate="false"}
```
{: #expire}
#### Parameter `expire`
This parameter allows to post an update or command to an item after a period of time has passed.
@ -635,7 +651,7 @@ Any future expiring update or command is cancelled, if the item receives an upda
The parameter accepts a duration of time that can be a combination of hours, minutes and seconds in the format
```
```shell
expire="1h 30m 45s"
expire="1h05s"
expire="55h 59m 12s"
@ -647,7 +663,7 @@ Whitespaces are allowed between the sections.
This duration can optionally be followed by a comma and the state or command to post, when the timer expires.
If this optional section is not present, it defaults to the Undefined (`UnDefType.UNDEF`) state.
```
```shell
Player MyPlayer { expire="1h,command=STOP" } // send STOP command after one hour
Number MyChannel { expire="5m,state=0" } // update state to 0 after five minutes
String MyMessage { expire="3m12s,Hello" } // update state to Hello after three minutes and 12 seconds
@ -702,6 +718,7 @@ You have an Item called `Bedroom_Light` that is connected to a Hue lamp
```java
Color Bedroom_Light { channel="hue:0210:1:bulb1:color" }
```
and a [Rule]({{base}}/configuration/rules-dsl.html) to toggle this light with a serial button:
```java
@ -735,5 +752,5 @@ Switch Outdoor_Temperature_Low_Alert { channel="openweathermap:weather-and-forec
// Indicates a battery low alarm if battery level drops below 15
Number Battery_Level { channel="serialbutton:button:mybutton:battery-level" }
Switch Low_Battery { channel="serialbutton:button:mybutton:battery-level", [profile="hysteresis", lower=15, inverted=true] }
Switch Low_Battery { channel="serialbutton:button:mybutton:battery-level" [profile="hysteresis", lower=15, inverted=true] }
```

62
configuration/jsr223.md
View File

@ -30,6 +30,7 @@ New APIs are planned to be implemented in the future, which will provide standar
:::: tabs
::: tab JavaScript
```js
'use strict';
@ -54,10 +55,11 @@ sRule.setTriggers([
automationManager.addRule(sRule);
```
:::
::: tab Jython
```python
scriptExtension.importPreset("RuleSupport")
scriptExtension.importPreset("RuleSimple")
@ -79,9 +81,11 @@ sRule.setTriggers([
automationManager.addRule(sRule)
```
:::
::: tab Groovy
```groovy
import org.openhab.core.automation.*
import org.openhab.core.automation.module.script.rulesupport.shared.simple.*
@ -105,6 +109,7 @@ sRule.setTriggers([
automationManager.addRule(sRule)
```
:::
::::
@ -133,8 +138,6 @@ For example, with the following scripts and directory structure...
... the load order will be: `/001_script.py`, `/dir1/001_script.py`, `/dir2/002_script.py`, `/script.py`, `/dir1/script.py`, `/dir2/script.py`.
<a name="presets"></a>
### `ScriptExtension` Objects (all JSR223 languages)
To faciliate JSR223 scripting, several openHAB-related variables are automatically predefined within `ScriptExtension` presets.
@ -146,8 +149,6 @@ The `default` preset is preloaded, so it does not require importing.
- [`RuleSupport`](#rulesupport_presets)
- [`RuleFactories`](#rulefactories_presets)
<a name="default_presets"></a>
#### Default Preset (`importPreset` not required)
| Variable | Description |
@ -212,8 +213,6 @@ The `default` preset is preloaded, so it does not require importing.
| `scriptExtension` | (internal) For loading script presets. |
| `se` | Alias for `scriptExtension` |
<a name="#event_operations"></a>
##### `events` operations
- `events.postUpdate(String, String)`
@ -227,8 +226,6 @@ The `default` preset is preloaded, so it does not require importing.
- `events.storeStates(Item...)`
- `events.restoreStates(Map<Item, State>)`
<a name="rulesimple_presets"></a>
#### RuleSimple Preset
These variables and classes are loaded using:
@ -252,8 +249,6 @@ See language-specific documentation for examples.
| TriggerType | `org.openhab.core.automation.type.TriggerType` |
| Visibility | `org.openhab.core.automation.Visibility` enum |
<a name="rulesupport_presets"></a>
#### `RuleSupport` Preset
These variables and classes are loaded using:
@ -276,8 +271,6 @@ scriptExtension.importPreset("RuleSupport")
| automationManager | Instance for managing rules and other openHAB module instances. (e.g., `addRule`) |
| ruleRegistry | `org.openhab.core.automation.Rule` |
<a name="rulefactories_presets"></a>
#### `RuleFactories` Preset
>Note: Advanced usage
@ -292,73 +285,58 @@ scriptExtension.importPreset("RuleFactories")
| `ConditionHandlerFactory` | `org.openhab.core.automation.module.script.rulesupport.shared.factories.ScriptedConditionHandlerFactory` |
| `TriggerHandlerFactory` | `org.openhab.core.automation.module.script.rulesupport.shared.factories.ScriptedTriggerHandlerFactory` |
<a name="trigger_types"></a>
### `TriggerType` Objects (all JSR223 languages)
The following trigger types are defined by openHAB (custom triggers can also be defined) and take the specified configuration parameters.
All parameters are Strings.
Read the JSR223 language specific documentation for examples of using these `TriggerType` objects.
<details>
<summary>timer.GenericCronTrigger</summary>
::: details timer.GenericCronTrigger
| Parameter | Description |
|-----------|-------------|
| `cronExpression` | The cron expression |
</details>
<details>
<summary>timer.TimeOfDayTrigger</summary>
:::
::: details timer.TimeOfDayTrigger
| Parameter | Description |
|-----------|-------------|
| `time` | The time in "hh:mm" format |
</details>
<details>
<summary>core.ItemCommandTrigger</summary>
:::
::: details core.ItemCommandTrigger
| Parameter | Description |
|-----------|-------------|
| `itemName` | The name of the `Item` |
| `command` | The `Command` (optional) |
</details>
<details>
<summary>core.ItemStateUpdateTrigger</summary>
:::
::: details core.ItemStateUpdateTrigger
| Parameter | Description |
|-----------|-------------|
| `itemName` | The name of the `Item` |
| `state` | The `State` (optional) |
</details>
<details>
<summary>core.ItemStateChangeTrigger</summary>
:::
::: details core.ItemStateChangeTrigger
| Parameter | Description |
|-----------|-------------|
| `itemName` | The name of the `Item` |
| `previousState` | The previous `State` (optional) |
| `state` | The `State` (optional) |
</details>
<details>
<summary>core.ChannelEventTrigger</summary>
:::
::: details core.ChannelEventTrigger
| Parameter | Description |
|-----------|-------------|
| `channelUID` | The `ChannelUID` of the `Channel` |
| `event` | The `Channel` trigger `Event` (optional) |
</details>
<details>
<summary>core.GenericEventTrigger</summary>
:::
::: details core.GenericEventTrigger
| Parameter | Description |
|-----------|-------------|
| `eventTopic` | Default: "openhab/\*"<br><br>Events can also be filtered, e.g.<br>Item events: "openhab/items/\*/"<br>Channel events: "openhab/channels/\*/triggered"<br>Thing events: "openhab/things/\*/" |
| `eventSource` | `Item` name, `ChannelUID`, `ThingUID`, etc. |
| `eventTypes` | `ItemCommandEvent`, `ItemStateEvent`, `ItemStateChangedEvent`, `GroupItemStateChangedEvent`, `ItemAddedEvent`, `ItemRemovedEvent`, `ThingAddedEvent`, `ThingRemovedEvent`, `ThingStatusInfoChangedEvent`, `ThingStatusInfoEvent`, `ThingUpdatedEvent`, etc. |
</details>
:::

54
configuration/migration/index.md
View File

@ -9,9 +9,9 @@ description: Description of Beaking Changes and needed steps for a proper Migrat
There are different approaches to get your openHAB 2 Environment upgraded to openHAB 3.
You could start with a fresh install and migrate your environment step-by-step or you can upgrade your running environment and change your configuration where needed.
Since this is a major version release you have to pay attention to some `Breaking Changes` that may affect your environment too.
You can find a general note on the `Breaking Changes` here:
https://github.com/openhab/openhab-distro/wiki/Breaking-Changes-in-openHAB-3
Since this is a major version release you have to pay attention to some **Breaking Changes** that may affect your environment too.
You can find a general note on the **Breaking Changes** here:
<https://github.com/openhab/openhab-distro/wiki/Breaking-Changes-in-openHAB-3>
Please read them carefully and check if you are affected by some of the changes, like the changes to some rules namespaces and the handling of time functions.
@ -25,18 +25,23 @@ Please be aware of possible changes needed for your specific environment in case
If you are working with an [openHABian](https://www.openhab.org/docs/installation/openhabian.html) setup, the upgrade is quite easy. Regardless of if you are currently using the openHAB 2.5 stable release or one of the latest 3.0.0 SNAPSHOT or milestone builds, switching to openHAB 3.0.0 stable is done in just a few steps:
1. Connect to the SSH command line and execute: `sudo openhabian-config`
2. When being asked, answer that you want to update.
3. Select the menu entry"03 - Install openHAB" option.
1. When being asked, answer that you want to update.
1. Select the menu entry"03 - Install openHAB" option.
### Package-based Installations
Since the openHAB 2 Linux `openhab2*` packages used folder names like `/etc/openhab2` we used this opportunity to remove the version out of anything the packages provides, including the name of the package itself. Some files such as `openhab-cli` didn't use any version in the naming at all, and therefore haven't moved anywhere.
Since the openHAB 2 Linux `openhab2*` packages used folder names like `/etc/openhab2` we used this opportunity to remove the version out of anything the packages provides, including the name of the package itself.
Some files such as `openhab-cli` didn't use any version in the naming at all, and therefore haven't moved anywhere.
Unfortunately, it means that in terms of openHAB 2 and openHAB 3, you cannot install both at the same time and openHAB 2 will not automatically update to openHAB 3, but if you use the commands to install openHAB 3 whilst openHAB 2 is installed, then the configs will copy across automatically.
Please be aware that system configuration done for openHAB 2 is not copied across automatically.
E.g. if you have changed /etc/default/openhab2, similar changes in /etc/default/openhab might be required.
#### Backup first
If you've got an existing openHAB 2 installation, back it up before you do anything. `openhab-cli backup [filepath]/[filename].zip` will create a zip file which can be used to restore the same version of openHAB later using `openhab-cli restore [filepath]/[filename].zip`. Put the file somewhere not related to openHAB, such as your own home directory (e.g. `/home/pi/`). You should probably do your usual OS backup too to make sure you can get back to where you left off.
If you've got an existing openHAB 2 installation, back it up before you do anything. `openhab-cli backup [filepath]/[filename].zip` will create a zip file which can be used to restore the same version of openHAB later using `openhab-cli restore [filepath]/[filename].zip`.
Put the file somewhere not related to openHAB, such as your own home directory (e.g. `/home/pi/`).
You should probably do your usual OS backup too to make sure you can get back to where you left off.
#### Prerequisites
@ -46,13 +51,13 @@ You must also be on the relevant repository for openHAB, this hasn't changed for
For DEB based installers (apt), your `.list` file should contain the line:
```
```shell
deb https://dl.bintray.com/openhab/apt-repo2 stable main
```
For RPM based installers (yum), your `.repo` file should contain:
```
```shell
[openHAB-Stable]
name=openHAB Stable
baseurl=https://dl.bintray.com/openhab/rpm-repo2/stable
@ -71,7 +76,7 @@ With `openhab2` still installed:
##### APT (Debian / Ubuntu and derivatives)
```
```shell
sudo apt update
sudo apt install openhab
```
@ -80,14 +85,14 @@ The system will ask you if you want to remove `openhab2` as part of this, and yo
You can get rid of openHAB2 leftover configuration files by using the `sudo apt purge openhab2` command, but this also gets rid of the `openhab` user, to fix this issue you should follow this with:
```
```shell
sudo apt install --reinstall openhab
sudo openhab-cli reset-ownership
```
##### DNF (RedHat, CentOS, Fedora, etc.)
```
```shell
sudo dnf --allowerasing install openhab
```
@ -96,7 +101,8 @@ DNF does not replace configuration files for you by default, have a look at the
##### YUM (Older RedHat, CentOS, Fedora, etc.)
The equivalent command should be:
```
```shell
sudo yum swap openhab2 openhab
```
@ -114,7 +120,7 @@ After a successful install, you can use commands like `sudo systemctl start open
##### APT (Debian / Ubuntu and derivatives)
```sh
```shell
sudo apt purge openhab2
sudo apt update
sudo apt install openhab
@ -122,12 +128,12 @@ sudo apt install openhab
##### YUM or DNF (RedHat, CentOS, Fedora, etc)
```sh
```shell
sudo dnf remove openhab2
sudo dnf install openhab
```
Replace "dnf" with "yum" for older Red Hat based OSes.
<a name="manual-installations">
### Manual Installations
@ -138,20 +144,20 @@ Official update scripts are available that let you update your 2.x installation
#### Linux/MacOS
1. Change to your openHAB root directory (e.g. `cd /opt/openhab`)
2. Create a backup by calling `sudo ./runtime/bin/backup`.
2. Run the update command:
1. Create a backup by calling `sudo ./runtime/bin/backup`.
1. Run the update command:
```
```shell
sudo ./runtime/bin/update 3.0.0
```
#### Windows
1. Make a backup of your openHAB installation folder.
2. Run PowerShell as an administrator and change to your openHAB root directory (e.g. `cd C:\openHAB`)
3. Run the update command:
1. Run PowerShell as an administrator and change to your openHAB root directory (e.g. `cd C:\openHAB`)
1. Run the update command:
```
. .\runtime\bin\update.ps1
Update-openHAB -OHVersion 3.0.0
```shell
. .\runtime\bin\update.ps1
Update-openHAB -OHVersion 3.0.0
```

20
configuration/multimedia.md
View File

@ -31,7 +31,7 @@ The distribution comes with these options built-in:
|---------------------|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `javasound` | System Speaker | This uses the JRE sound drivers to play audio to the local sound interface. |
| `enhancedjavasound` | System Speaker (with mp3 support) | This uses the JRE sound drivers plus an additional 3rd party library, which adds support for mp3 files. |
| `webaudio` | Web Audio | Convenient, if sounds should not be played on the server, but on the client: This sink sends the audio stream through HTTP to web clients, which then cause it to be played back by the browser. Obviously, the browser needs to be opened and have a compatible openHAB UI running. Currently, this feature is supported by Paper UI and HABPanel. |
| `webaudio` | Web Audio | Convenient, if sounds should not be played on the server, but on the client: This sink sends the audio stream through HTTP to web clients, which then cause it to be played back by the browser. Obviously, the browser needs to be opened and have a compatible openHAB UI running. Currently, this feature is supported by UI and HABPanel. |
Additionally, certain bindings register their supported devices as audio sinks, e.g. Sonos speakers.
@ -46,7 +46,7 @@ javasound
webaudio
```
You can define the default audio sink either by textual configuration in `$OPENHAB_CONF/services/runtime.cfg` or in the Paper UI in `Configuration->System->Audio`.
You can define the default audio sink either by textual configuration in `$OPENHAB_CONF/services/runtime.cfg` or in the UI in `Settings->Audio`.
In order to play a sound, you can use the following command on the console:
@ -60,13 +60,13 @@ openhab> openhab:audio stream example.com
Alternatively the [`playSound()`](https://openhab.org/javadoc/latest/org/openhab/core/model/script/actions/audio#playSound(java.lang.String)) or [`playStream()`](https://openhab.org/javadoc/latest/org/openhab/core/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
- `playSound(String sink, String filename)` : plays a sound from the sounds folder to the given sink(s)
- `playSound(String sink, String filename, PercentType volume)` : plays a sound with the given volume from the sounds folder to the given sink(s)
- `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
- `playSound(String sink, String filename)` : plays a sound from the sounds folder to the given sink(s)
- `playSound(String sink, String filename, PercentType volume)` : plays a sound with the given volume from the sounds folder to the given sink(s)
- `playStream(String url)` : plays an audio stream from an url to the default sink (set url to `null` if streaming should be stopped)
- `playStream(String sink, String url)` : plays an audio stream from an url to the given sink(s) (set url to `null` if streaming should be stopped)
- `playStream(String url)` : plays an audio stream from an url to the default sink (set url to `null` if streaming should be stopped)
- `playStream(String sink, String url)` : plays an audio stream from an url to the given sink(s) (set url to `null` if streaming should be stopped)
#### Examples
@ -99,7 +99,7 @@ mactts:Ioana Ioana (ro_RO)
mactts:Kanya Kanya (th_TH)
```
You can define a default TTS service and a default voice to use either by textual configuration in `$OPENHAB_CONF/services/runtime.cfg` or in the Paper UI in `Configuration->System->Voice`.
You can define a default TTS service and a default voice to use either by textual configuration in `$OPENHAB_CONF/services/runtime.cfg` or in the UI in `Settings->Voice`.
In order to say a text, you can enter such a command on the console (The default voice and default audio sink will be used):
@ -140,7 +140,7 @@ There are two implementations available by default:
| Interpreter | Type | Description |
|-------------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `rulehli` | Rule-based Interpreter | This mimics the behavior of the Android app - it sends the string as a command to a (configurable, default is "VoiceCommand") item and expects a rule to pick it up and further process it. |
| `system` | Built-in Interpreter | This is a simple implementation that understands basic home automation commands like "turn on the light" or "stop the music". It currently supports only English, German and French and the vocabulary is still very limited. The exact syntax still needs to be documented, for the moment you need to refer to the [source code](https://github.com/openhab/openhab-core/blob/master/bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/internal/text/StandardInterpreter.java#L48). |
| `system` | Built-in Interpreter | This is a simple implementation that understands basic home automation commands like "turn on the light" or "stop the music". It currently supports only English, German and French and the vocabulary is still very limited. The exact syntax still needs to be documented, for the moment you need to refer to the [source code](https://github.com/openhab/openhab-core/blob/main/bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/internal/text/StandardInterpreter.java#L48). |
To test the interpreter, you can enter such a command on the console (assuming you have an item with label 'light'):

31
configuration/paperui.md
View File

@ -1,31 +0,0 @@
---
layout: documentation
title: Configuration though Paper UI
---
{% include base.html %}
# Configuration though Paper UI
The Paper UI is a new interface that helps setting up and configuring 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
![extensions](images/paperui1.png)
- Thing discovery:
See devices and services found on your network and add them to your setup.
![discovery](images/paperui2.png)
- Linking items to channels:
Instead of adding a binding configuration to your item file, you can directly link Thing channels to your items.
![links](images/paperui3.png)
Note that you still need to define your items, sitemaps, persistence configurations and rules in the according config files (as done in openHAB 1). Such functionality will be added bit by bit to the Paper UI only.
Here you can find a small screencast about the Paper UI:
[![Paper UI](https://img.youtube.com/vi/MV2a5qwtmRE/0.jpg)](https://www.youtube.com/watch?v=MV2a5qwtmRE)
{% include contribution-wanted.html %}

14
configuration/persistence.md
View File

@ -22,8 +22,8 @@ Please refer to the [available persistence service add-on](/addons/#persistence)
It is important to select a default persistence service.
You should do this even if you have only one persistence add-on installed.
To select a default persistence service, in paper UI, select Configuration and then System from the side menu.
Scroll down to "Persistence", and select your default service from the drop-down list.
To select a default persistence service, in UI, select `Settings->Persistence`.
Select your default service from the drop-down list.
Note that you must first install a persistence add-on before you make this selection.
Be sure to save your choice once you have selected your default service.
@ -67,6 +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](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.
@ -88,8 +89,9 @@ where `<itemlist>` is a comma-separated list consisting of one or more of the fo
- `*` - this line should apply to all items in the system
- `<itemName>` a single Item identified by its name. This Item can be a group Item. But note that only the group value will be persisted. The value of the individual group members will not be persisted using this option.
- `<groupName>*` - all members of this group will be persisted, but not the group itself. If no strategies are provided, the default strategies that are declared in the first section are applied. Optionally, an alias may be provided if the persistence service requires special names (e.g. a table to be used in a database, a feed id for an IoT service, etc.)
Note that * is NOT a wildcard match character in this context.
- `<groupName>*` - all members of this group will be persisted, but not the group itself. If no strategies are provided, the default strategies that are declared in the first section are applied.
Optionally, an alias may be provided if the persistence service requires special names (e.g. a table to be used in a database, a feed id for an IoT service, etc.)
Note that `*` is NOT a wildcard match character in this context.
The example `Items` section below takes advantage of a `default` entry in the `Strategies` section.
Assume the `Strategies` section contains the line:
@ -151,8 +153,8 @@ Items {
item1, item2 : strategy = everyChange, restoreOnStartup
}
```
It is usually not necessary to restore all Items since there is a good chance that they are no longer accurate (switches may have been toggled, sensor values are likely to have changed), and the restoration may result in unwanted rule actions.
It is usually not necessary to restore all Items since there is a good chance that they are no longer accurate (switches may have been toggled, sensor values are likely to have changed), and the restoration may result in unwanted rule actions.
## Persistence Extensions in Scripts and Rules
@ -193,7 +195,7 @@ 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.
#### Examples
### Examples
To persist an Item called `Lights` in an rrd4j database, you would enter the following:
`Lights.persist("rrd4j")`

16
configuration/restdocs.md
View File

@ -11,7 +11,7 @@ Through the openHAB [REST API](https://en.wikipedia.org/wiki/REST_API) most aspe
This includes for example, the access to all data related to Items, Things and Bindings as well as the capabilities to invoke actions that can change the state of Items or influence the behavior of other elements of openHAB.
Interactions with the REST API are based on the http protocol.
Access over the Internet to the REST API is possible, but this represents a significant security risk.
Users are encouraged to [ensure safe and secure connections](http://docs.openhab.org/installation/security.html).
Users are encouraged to [ensure safe and secure connections](/docs/installation/security.html).
Be aware that the documentation of the REST API may not be automatically installed, but once installed it is accessible through the openHAB dashboard.
## REST API Examples
@ -83,22 +83,10 @@ You can also do this in a single, non-interactive command, in this case **add `-
### With an API token
This method is often recommended in order to keep your passwords safe and avoid to store them without encryption in any public places.
To authenticate with an API token, **apaddpend `-u '{API_TOKEN}:'` to the commandline.**
To authenticate with an API token, **add `-u '{API_TOKEN}:'` to the commandline.**
You can manage all access tokens in your profile settings in the Main UI.
### Disable authentication
It is possible to disable authentication.
Stop openhab and add this part to ```$OPENHAB_USERDATA/etc/org.apache.karaf.features.xml``` before ```</featuresProcessing>```:
```
<blacklistedFeatures>
<feature>openhab-*-auth</feature>
</blacklistedFeatures>
```
Once openhab is restarted authentication will be disabled.
## Additional Considerations
The REST API also supports server-push supporting subscriptions on change notification for certain resources.

66
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](https://demo.openhab.org) 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.
The [demo setup](https://demo.openhab.org) already comes with a demo file called [`demo.rules`](https://github.com/openhab/openhab-distro/blob/main/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.
@ -120,6 +120,7 @@ end
- `<SCRIPT_BLOCK>` - Contains the logic that should be executed when a trigger condition is met, see the [script](#scripts) section for details on its syntax.
{: #rule-triggers}
### Rule Triggers
Before a rule starts working, it has to be triggered.
@ -135,6 +136,7 @@ There are different categories of rule triggers:
Here are the details for each category:
{: #event-based-triggers}
### Event-based Triggers
You can listen to commands for a specific item, on status updates or on status changes (an update might leave the status unchanged).
@ -153,6 +155,7 @@ When using the `received command` trigger, the Rule might trigger **before** the
Therefore, if the Rule needs to know what the command was, use the [implicit variable]({{base}}/configuration/rules-dsl.html#implicit-variables-inside-the-execution-block) `receivedCommand` instead of `<ItemName>.state`.
{: #member-of-triggers}
### Member of Triggers
As with Item based event-based triggers discussed above, you can listen for commands, status updates, or status changes on the members of a given Group.
@ -172,9 +175,10 @@ Also, as with Item event-based triggers, when using `received command`, the Rule
So in Rules where the Rule needs to know what the command was, use the `receivedCommand` implicit variable instead of `triggeringItem.state`.
{: #time-based-triggers}
### Time-based Triggers
You can either use some pre-defined expressions for timers or use a [cron expression](https:////www.quartz-scheduler.org/documentation/quartz-2.2.2/tutorials/tutorial-lesson-06.html) instead:
You can either use some pre-defined expressions for timers or use a [cron expression](https://www.quartz-scheduler.org/documentation/quartz-2.2.2/tutorials/tutorial-lesson-06.html) instead:
```java
Time is midnight
@ -185,23 +189,24 @@ Time cron "<cron expression>"
A cron expression takes the form of six or optionally seven fields:
1. Seconds
2. Minutes
3. Hours
4. Day-of-Month
5. Month
6. Day-of-Week
7. Year (optional field)
1. Minutes
1. Hours
1. Day-of-Month
1. Month
1. Day-of-Week
1. Year (optional field)
You may use [CronMaker](https://www.cronmaker.com/) or the generator at [FreeFormatter.com](https://www.freeformatter.com/cron-expression-generator-quartz.html) to generate cron expressions.
You may use the generator at [FreeFormatter.com](https://www.freeformatter.com/cron-expression-generator-quartz.html) to generate your cron expressions.
{: #system-based-triggers}
### System-based Triggers
Two system-based triggers are provided as described in the table below:
One system-based trigger is provided as described in the table below:
| Trigger | Description |
|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| System started | System started is triggered upon openHAB startup, after the rule file containing the System started trigger is modified, or after item(s) are modified in a .items file. |
| System started | `System started` is triggered upon openHAB startup. In openHAB version 2, `System started` is also triggered after the rule file containing the System started trigger is modified, or after item(s) are modified in a .items file. |
You may wish to use the 'System started' trigger to initialize values at startup if they are not already set.
@ -219,6 +224,7 @@ end
```
{: #thing-based-triggers}
### Thing-based Triggers
Your rules can take actions based upon status updates or status changes generated by Things.
@ -235,7 +241,7 @@ You can find all the possible values for status from [Thing Status](/docs/concep
And refer to [Thing Status Action](/docs/configuration/actions.html#thing-status-action) to find how to get thing status in the script.
The `thingUID` is the identifier assigned to the Thing, manually in your configuration or automatically during auto discovery.
You can find it from PaperUI or from Karaf remote console.
You can find it from UI or from Karaf remote console.
For example, one z-wave device can be "zwave:device:c5155aa4:node14".
::: tip Note
@ -243,6 +249,7 @@ You need to use quotes around `thingUID` if it contains special characters such
:::
{: #channel-based-triggers}
### Channel-based Triggers
Some add-ons provide trigger channels.
@ -279,6 +286,7 @@ end
```
{: #scripts}
## Scripts
The expression language used within scripts is the same that is used in the Xtend language - see the [documentation of expressions](https://www.eclipse.org/xtend/documentation/203_xtend_expressions.html) on the Xtend homepage.
@ -302,6 +310,7 @@ if (Temperature.state < 20) {
```
{: #manipulating-item-states}
### Manipulating Item States
Rules are often used to manipulate the state of an Item, for example switching lights on and off under certain conditions.
@ -321,12 +330,14 @@ The following table summarizes the impact of the two manipulator commands on the
**Beware:**
In most cases, a rule with a trigger of `received update` will fire following the command `sendCommand` as:
- openHAB auto-updates the status of Items for which the item definition does not contain `autoupdate="false"`
- the Thing sends a status update to the Item.
Besides the specific manipulator command methods `MyItem.sendCommand(<new_state>)` and `MyItem.postUpdate(<new_state>)`, generic manipulators in the form of `sendCommand(MyItem, <new_state>)` and `postUpdate(MyItem, <new_state>)` are available. The specific versions is normally recommended.
{: #sendcommand-method-vs-action}
#### MyItem.sendCommand("new state") versus sendCommand(MyItem, "new state")
Using the methods `MyItem.sendCommand(<new_state>)` and `MyItem.postUpdate(<new_state>)` is often preferable.
@ -345,8 +356,9 @@ Using `Myitem.sendCommand(new_state)` or `Myitem.postUpdate(new_state)` will, in
The Action `sendCommand(MyItem, new_state)` does not provide the same flexibilty.
For example, if `new_state` is typed as a primitive (e.g., `var int new_state = 3`) and myItem is of the Object type Dimmer:
* the following command ***will fail***: ~~sendCommand(MyItem, new_state)~~.
* However, the following command **will work**: `MyItem.sendCommand(new_state)`.
- the following command ***will fail***: ~~sendCommand(MyItem, new_state)~~.
- However, the following command **will work**: `MyItem.sendCommand(new_state)`.
Using `MyItem.postUpdate(new_state)` or `MyItem.sendCommand(new_state)` will create the most stable code.
It provides by far the best option for avoiding most problems.
@ -362,6 +374,7 @@ sendCommand("My_Lamp_" + index, ON)
```
{: #using-state-of-items-in-rules}
### Using the States of Items in Rules
Often it is desired to calculate other values from Item states or to compare Item states against other values
@ -376,6 +389,7 @@ This section differentiates between command type and state type.
For ease of reading, it is possible to simply add “type” to the end of a command type thereby obtaining the state type.
For example, a Color Item can receive an OnOffType, IncreaseDecreaseType, PercentType, or HSBType.
Therefore the following are all valid commands one can send to a Color Item:
- `MyColorItem.sendCommand(ON)`
- `MyColorItem.sendCommand(INCREASE)`
- `MyColorItem.sendCommand(new PercentType(50))`
@ -395,11 +409,12 @@ 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](https://openhab.org/javadoc/latest/org/openhab/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.
For example, the [JavaDoc for HSBType](https://openhab.org/javadoc/latest/org/openhab/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.
{: #conversions}
#### Working with Item States: Conversions
*Reminder: For a complete and up-to-date list of what item types are currently allowed in openHAB and the command types each item can accept refer to the section on [items in the openHAB documentation]({{base}}/concepts/items.html).*
@ -554,7 +569,7 @@ DecimalType and QuantityType are also java.lang.Number so all the conversions li
Here some other commonly needed conversions:
* For DecimalType states:
- For DecimalType states:
```java
// convert integer_number to string containing hex_code
@ -569,7 +584,7 @@ var myNumber = Long.parseLong(hex, 16) as Number
var DecimalType parsedResult = new DecimalType(Long.parseLong(hex_code, 16))
```
* For QuantityType states:
- For QuantityType states:
```java
// define a QuantityType variable
@ -634,7 +649,7 @@ val stateAsString = MyStringItem.state.toString
In case an item returns a string containing a value as a hexadecimal number, it can be converted to an integer by using
```
```shell
//Loading hexvalue from string
val itemvalue = new java.math.BigDecimal(Integer::parseInt(myHexValue, 16))
```
@ -649,7 +664,6 @@ One can convert from ON and OFF to 1 and 0 with code similar to:
val SwitchNum = if (MySwitchItem.state == ON) 1 else 0
```
#### Deeper Dive
While interacting with Item states, care must be taken to understand the difference between Objects and primitives.
@ -688,6 +702,7 @@ Each of these separate methods is individually written to handle all of these di
MyItem will automatically apply the method that corresponds to the argument type.
{: #implicit-variables}
### Implicit Variables inside the Execution Block
Besides the implicitly available variables for items and commands/states, rules can have additional pre-defined variables, depending on their triggers:
@ -700,13 +715,14 @@ Besides the implicitly available variables for items and commands/states, rules
- `receivedEvent` - implicitly available in every rule that has a channel-based trigger.
{: #return}
### Early returns
It is possible to return early from a rule, not executing the rest of the statements like this:
```java
if (Temperature.state > 20) {
return;
return;
}
Heating.sendCommand(ON)
```
@ -714,6 +730,7 @@ Heating.sendCommand(ON)
Caveat: Please note the semicolon after the return statement which terminates the command without an additional argument.
{: #concurrency-guard}
### Concurrency Guard
If a rule triggers on UI events it may be necessary to guard against concurrency.
@ -737,6 +754,7 @@ end
```
{: #transformations}
### Transformations
openHAB [Transformation services](/addons/#transform) can be used in rules to transform/translate/convert data.
@ -782,8 +800,8 @@ finally {
For all available Transformation services please refer to the list of [Transformation Add-ons](/addons/#transform).
{: #logging}
### Logging
You can emit log messages from your rules to aid debugging.
@ -863,7 +881,7 @@ rule "Start wake up light on sunrise"
when
Channel "astro:sun:home:rise#event" triggered
then
switch(receivedEvent.getEvent()) {
switch(receivedEvent) {
case "START": {
Light.sendCommand(ON)
}

499
configuration/rules-ng.md
View File

@ -11,7 +11,6 @@ title: Next-Gen Rules
Since openHAB 2.4 another Rule Engine has been added. It works fundamentally different than what you find with our current [Rules](https://www.openhab.org/docs/configuration/rules-dsl.html). It allows Rules to be edited in a graphical fashion and to interact with [JSR223 Scripts (Javascript, Jypthon, etc)](https://www.openhab.org/docs/configuration/jsr223.html).
## Installation
Install the rule engine from Add-ons → Misc → Rule Engine (Experimental).
@ -27,7 +26,7 @@ When you now refresh your browser, you will see a `Rules` menu appearing in the
In general this rule engine aims to support rules defined with syntax similar to:
```text
ON item_id state changed IF item_id.state == desired_value THEN item_id2.state = desired_value2
ON item_id state changed IF item_id.state == desired_value THEN item_id2.state = desired_value2
```
A rule consists of basic information like name, tags and a description. The main building blocks of rules are modules however, and each rule consists of one or more instances of each of the following modules:
@ -54,43 +53,50 @@ Those use predefined configurations and/or modified module input/output objects.
A given **Module type** has the following elements:
uid - unique id
label - localizable text
description - localizable text
configDescriptions - list of meta data for the configuration properties
input variables - list of meta data for the supported input objects
output variables - list of meta data for the supported output objects
```text
uid - unique id
label - localizable text
description - localizable text
configDescriptions - list of meta data for the configuration properties
input variables - list of meta data for the supported input objects
output variables - list of meta data for the supported output objects
```
**configDescriptions** has the following metadata defined for each property:
name
type - one of the following "text", "integer", "decimal", "boolean"
label - localizable text
description - localizable text
required - boolean flag indicating if this configuration property can be optional and thus it can be ommited in the rule, by default required is false
defaultValue - default value for the configuration property when not specified in the rule
```text
name
type - one of the following "text", "integer", "decimal", "boolean"
label - localizable text
description - localizable text
required - boolean flag indicating if this configuration property can be optional and thus it can be ommited in the rule, by default required is false
defaultValue - default value for the configuration property when not specified in the rule
```
**Input property** has the following metadata:
name
type - fully qualified name of Java class ("java.lang.Integer")
label - localizable text
description - localizable text
defaultValue - default value for the configuration property when not specified in the rule
tags - shows how to be considered a given value. For example, as a Temperature
```text
name
type - fully qualified name of Java class ("java.lang.Integer")
label - localizable text
description - localizable text
defaultValue - default value for the configuration property when not specified in the rule
tags - shows how to be considered a given value. For example, as a Temperature
```
**Output property** has the following metadata:
name
type - fully qualified name of Java class ("java.lang.Integer")
label - localizable text
description - localizable text
defaultValue - default value for the configuration property when not specified in the rule
reference - which means the property value can be specified as a reference to configuration parameter or input parameter
tags - shows how a given value should be considered (e.g. as a Temperature)
```text
name
type - fully qualified name of Java class ("java.lang.Integer")
label - localizable text
description - localizable text
defaultValue - default value for the configuration property when not specified in the rule
reference - which means the property value can be specified as a reference to configuration parameter or input parameter
tags - shows how a given value should be considered (e.g. as a Temperature)
```
**Supported Types**
### Supported Types
The types supported in the **input/output** objects can be any string and the following validation is performed:
@ -109,15 +115,15 @@ The types in the **Configuration** object are restricted to the following:
**JSON schemas for:**
* [module types](../../schemas/ModuleTypes_schema.json)
* [rule templates](../../schemas/Templates_schema.json)
* [rule instances](../../schemas/Rules_schema.json)
- [module types](../../schemas/ModuleTypes_schema.json)
- [rule templates](../../schemas/Templates_schema.json)
- [rule instances](../../schemas/Rules_schema.json)
### Sample Rules
* **Sample rule instance referencing module types:**
- **Sample rule instance referencing module types:**
```
```json
{
"uid":"sample.rule1",
"name":"SampleRule",
@ -157,16 +163,16 @@ The types in the **Configuration** object are restricted to the following:
}
```
* **Sample module types:**
- **Sample module types:**
```
"triggers":[
{
```json
"triggers":[
{
"uid":"SampleTrigger",
"label":"SampleTrigger label",
"description":"Sample Trigger description.",
"outputs":[
{
"outputs":[
{
"name":"triggerOutput",
"type":"java.lang.String",
"label":"TriggerOutput label",
@ -176,12 +182,12 @@ The types in the **Configuration** object are restricted to the following:
}
]
},
{
{
"uid":"CompositeSampleTrigger",
"label":"CompositeTrigger label",
"description":"Composite Trigger description.",
"outputs":[
{
"outputs":[
{
"name":"compositeTriggerOutput",
"type":"java.lang.String",
"label":"compositeTriggerOutput label",
@ -189,8 +195,8 @@ The types in the **Configuration** object are restricted to the following:
"reference":"compositeChildTrigger1.triggerOutput"
}
],
"children":[
{
"children":[
{
"id":"compositeChildTrigger1",
"type":"SampleTrigger"
}
@ -199,28 +205,28 @@ The types in the **Configuration** object are restricted to the following:
]
```
```
"conditions":[
{
```json
"conditions":[
{
"uid":"SampleCondition",
"label":"SampleCondition label",
"description":"Sample Condition description",
"configDescriptions":[
{
"configDescriptions":[
{
"name":"operator",
"type":"TEXT",
"description":"Valid operators are =,>,<,!=",
"required":true
},
{
{
"name":"constraint",
"type":"TEXT",
"description":"Right operand which is compared with the input.",
"required":true
}
],
"inputs":[
{
"inputs":[
{
"name":"conditionInput",
"type":"java.lang.String",
"label":"ConditionInput label",
@ -232,14 +238,14 @@ The types in the **Configuration** object are restricted to the following:
]
```
```
"actions":[
{
```json
"actions":[
{
"uid":"SampleAction",
"label":"SampleAction label",
"description":"Sample Action description.",
"configDescriptions":[
{
"configDescriptions":[
{
"name":"message",
"type":"TEXT",
"label":"message label",
@ -249,12 +255,12 @@ The types in the **Configuration** object are restricted to the following:
}
]
},
{
{
"uid":"CompositeSampleAction",
"label":"CompositeAction label",
"description":"Composite Action description.",
"configDescriptions":[
{
"configDescriptions":[
{
"name":"compositeMessage",
"type":"TEXT",
"label":"custom message label",
@ -263,8 +269,8 @@ The types in the **Configuration** object are restricted to the following:
"required":false
}
],
"inputs":[
{
"inputs":[
{
"name":"compositeActionInput",
"type":"java.lang.String",
"label":"ActionInput label",
@ -272,18 +278,18 @@ The types in the **Configuration** object are restricted to the following:
"required":true
}
],
"children":[
{
"children":[
{
"id":"SampleAction1",
"type":"SampleAction",
"configuration":{
"configuration":{
"message":"$compositeMessage"
}
},
{
{
"id":"SampleAction2",
"type":"SampleAction",
"configuration":{
"configuration":{
"message":"$compositeActionInput"
}
}
@ -296,46 +302,46 @@ The types in the **Configuration** object are restricted to the following:
There are several ways to add new rules:
* using **JAVA API** from package: **org.openhab.automation.api**;
* using **text console commands: openhab:automation**;
* using **resource bundles** that provide moduletypes, rules and rule templates stored in **.json** files;
* using **REST API** - see the next chapter bellow.
- using **JAVA API** from package: **org.openhab.automation.api**;
- using **text console commands: openhab:automation**;
- using **resource bundles** that provide moduletypes, rules and rule templates stored in **.json** files;
- using **REST API** - see the next chapter bellow.
## REST API
* http://<host:port>/rest/module-types - lists module types.
* http://<host:port>/rest/templates" - lists rule templates.
* http://<host:port>/rest/rules - lists rule instances.
- `http://<host:port>/rest/module-types` - lists module types.
- `http://<host:port>/rest/templates` - lists rule templates.
- `http://<host:port>/rest/rules` - lists rule instances.
#### /rest/templates
### /rest/templates
- GET /rest/templates - returns all registered rule templates.
- GET /rest/templates/{templateUID} - returned response includes only the content of the specified template.
- GET /rest/templates - returns all registered rule templates.
- GET /rest/templates/{templateUID} - returned response includes only the content of the specified template.
#### /rest/module-types
### /rest/module-types
- GET /rest/module-types - returns all registered module types.
- optional parameter 'type' with possible values: 'trigger', 'condition' or 'action' - filters the response to include only module definitions of specified type.
- optional parameter 'tags' - filters the response to include only module types which have specified tags.
- GET /rest/module-types/{moduleTypeUID} - returned response includes only the content of the specified module type.
#### /rest/rules
- GET /rest/module-types - returns all registered module types.
- optional parameter 'type' with possible values: 'trigger', 'condition' or 'action' - filters the response to include only module definitions of specified type.
- optional parameter 'tags' - filters the response to include only module types which have specified tags.
- GET /rest/module-types/{moduleTypeUID} - returned response includes only the content of the specified module type.
- GET /rest/rules - returns all registered rule instances.
- POST /rest/rules - adds new rule instance to the rule registry.
- DELETE /rest/rules/{ruleUID} - deletes the specified rule instance.
- PUT /rest/rules/{ruleUID} - updates the specified rule instance.
- PUT /rest/rules/{ruleUID}/enable - enable/disable specified rule instance.
- PUT /rest/rules/{ruleUID}/runnow - executes actions of specified rule instance.
- GET /rest/rules/{ruleUID}/config - returns the configuration of the specified rule instance.
- PUT /rest/rules/{ruleUID}/config - updates the configuration of the specified rule instance.
- GET /rest/rules/{ruleUID}/triggers - returns the triggers defined for the specified rule instance.
- GET /rest/rules/{ruleUID}/conditions - returns the conditions defined for the specified rule instance.
- GET /rest/rules/{ruleUID}/actions - returns the actions defined for the specified rule instance.
- GET /rest/rules/{ruleUID}/{moduleCategory}/{id} - returns module instance with specified id and category {triggers/conditions/actions} of the specified rule.
- GET /rest/rules/{ruleUID}/{moduleCategory}/{id}/config - returns the configuration of the specified module instance.
- GET /rest/rules/{ruleUID}/{moduleCategory}/{id}/config/{param} - returns the value of specified module configuration parameter (media type is text/plain).
- PUT /rest/rules/{ruleUID}/{moduleCategory}/{id}/config/{param} - updates the value of specified module configuration parameter (media type is text/plain).
### /rest/rules
- GET /rest/rules - returns all registered rule instances.
- POST /rest/rules - adds new rule instance to the rule registry.
- DELETE /rest/rules/{ruleUID} - deletes the specified rule instance.
- PUT /rest/rules/{ruleUID} - updates the specified rule instance.
- PUT /rest/rules/{ruleUID}/enable - enable/disable specified rule instance.
- PUT /rest/rules/{ruleUID}/runnow - executes actions of specified rule instance.
- GET /rest/rules/{ruleUID}/config - returns the configuration of the specified rule instance.
- PUT /rest/rules/{ruleUID}/config - updates the configuration of the specified rule instance.
- GET /rest/rules/{ruleUID}/triggers - returns the triggers defined for the specified rule instance.
- GET /rest/rules/{ruleUID}/conditions - returns the conditions defined for the specified rule instance.
- GET /rest/rules/{ruleUID}/actions - returns the actions defined for the specified rule instance.
- GET /rest/rules/{ruleUID}/{moduleCategory}/{id} - returns module instance with specified id and category {triggers/conditions/actions} of the specified rule.
- GET /rest/rules/{ruleUID}/{moduleCategory}/{id}/config - returns the configuration of the specified module instance.
- GET /rest/rules/{ruleUID}/{moduleCategory}/{id}/config/{param} - returns the value of specified module configuration parameter (media type is text/plain).
- PUT /rest/rules/{ruleUID}/{moduleCategory}/{id}/config/{param} - updates the value of specified module configuration parameter (media type is text/plain).
## JAVA API
@ -346,36 +352,35 @@ There are several ways to add new rules:
`org.openhab.automation.template.TemplateRegistry` - provides functionality to get templates from the Rule Engine.
## Text console commands
`automation listModuleTypes [-st] <filter> ` - lists all Module Types. If filter is present, lists only matching Module Types.
`automation listModuleTypes [-st] <filter>` - lists all Module Types. If filter is present, lists only matching Module Types.
`automation listTemplates [-st] <filter> ` - lists all Templates. If filter is present, lists only matching Templates.
`automation listTemplates [-st] <filter>` - lists all Templates. If filter is present, lists only matching Templates.
`automation listRules [-st] <filter> `- lists all Rules. If filter is present, lists only matching Rules.
`automation listRules [-st] <filter>`- lists all Rules. If filter is present, lists only matching Rules.
`automation removeModuleTypes [-st] <url> ` - Removes the Module Types, loaded from the given url.
`automation removeModuleTypes [-st] <url>` - Removes the Module Types, loaded from the given url.
`automation removeTemplates [-st] <url ` - Removes the Templates, loaded from the given url.
`automation removeTemplates [-st] <url` - Removes the Templates, loaded from the given url.
`automation removeRule [-st] <uid> ` - Removes the rule, specified by given UID.
`automation removeRule [-st] <uid>` - Removes the rule, specified by given UID.
`automation removeRules [-st] <filter> `- Removes the rules. If filter is present, removes only matching Rules.
`automation removeRules [-st] <filter>`- Removes the rules. If filter is present, removes only matching Rules.
`automation importModuleTypes [-p] <parserType> [-st] <url> ` - Imports Module Types from given url. If parser type missing, "json" parser will be set as default.
`automation importModuleTypes [-p] <parserType> [-st] <url>` - Imports Module Types from given url. If parser type missing, "json" parser will be set as default.
`automation importTemplates [-p] <parserType> [-st] <url> ` - Imports Templates from given url. If parser type missing, "json" parser will be set as default.
`automation importTemplates [-p] <parserType> [-st] <url>` - Imports Templates from given url. If parser type missing, "json" parser will be set as default.
`automation importRules [-p] <parserType> [-st] <url> ` - Imports Rules from given url. If parser type missing, "json" parser will be set as default.
`automation importRules [-p] <parserType> [-st] <url>` - Imports Rules from given url. If parser type missing, "json" parser will be set as default.
`automation exportModuleTypes [-p] <parserType> [-st] <file> ` - Exports Module Types in a file. If parser type missing, "json" parser will be set as default.
`automation exportModuleTypes [-p] <parserType> [-st] <file>` - Exports Module Types in a file. If parser type missing, "json" parser will be set as default.
`automation exportTemplates [-p] <parserType> [-st] <file> ` - Exports Templates in a file. If parser type missing, "json" parser will be set as default.
`automation exportTemplates [-p] <parserType> [-st] <file>` - Exports Templates in a file. If parser type missing, "json" parser will be set as default.
`automation exportRules [-p] <parserType> [-st] <file> ` - Exports Rules in a file. If parser type missing, "json" parser will be set as default.
`automation exportRules [-p] <parserType> [-st] <file>` - Exports Rules in a file. If parser type missing, "json" parser will be set as default.
`automation enableRule [-st] <uid> <enable> ` - Enables the Rule, specified by given UID.
`automation enableRule [-st] <uid> <enable>` - Enables the Rule, specified by given UID.
The use of the 'enable' argument is optional, and will accept a boolean value.
If used, the command will enable (true) or disable (false) the Rule.
If it is not used, the command will return the current status of the Rule.
@ -397,51 +402,51 @@ The rule template is used only once when the rule is imported in the Rule Engine
After that the reference from the rule instance to the rule template is removed and a given rule may exist even if the rule template is removed or modified.
This will not have any impact on the already imported rules.
* **Sample rule instance referencing rule template:**
- **Sample rule instance referencing rule template:**
```
{
```json
{
"uid": "sample.rulebytemplate",
"name": "RuleByTemplate",
"templateUID": "SampleRuleTemplate",
"tags": [
"tags": [
"rule",
"template"
],
"configuration": {
"configuration": {
"condition_operator": "!=",
"condition_constraint": "template"
}
}
```
* **Sample rule template:**
- **Sample rule template:**
```
{
```json
{
"uid":"SampleRuleTemplate",
"description":"Sample Rule Template",
"tags":[
"tags":[
"sample",
"rule",
"template"
],
"configDescriptions":[
"configDescriptions":[
{
"name":"condition_operator",
"name":"condition_operator",
"type": "TEXT",
"description": "Valid operators are =,>,<,!=",
"required": true
},
{
"name":"condition_constraint",
"name":"condition_constraint",
"type": "TEXT",
"description": "Right operand which is compared with the input.",
"required": true
}
],
"triggers": [
{
"triggers": [
{
"id": "CompositeSampleTriggerTemplateID",
"type": "CompositeSampleTrigger",
"label": "Sample Trigger",
@ -464,7 +469,7 @@ This will not have any impact on the already imported rules.
}
],
"actions": [
{
{
"id": "CompositeActionTemplateID",
"type": "CompositeSampleAction",
"label": "Sample Action",
@ -472,7 +477,7 @@ This will not have any impact on the already imported rules.
"configuration": {
"compositeMessage": "Hello World!!!"
},
"inputs": {
"inputs": {
"compositeActionInput": "CompositeSampleTriggerTemplateID.compositeTriggerOutput"
}
}
@ -487,98 +492,101 @@ The above example uses two rule configuration properties:
### GenericEventTrigger
GenericEventTrigger has 3 configuration paramters: `eventTopic`,` eventSource` and `eventTypes` and one output: 'event'.
GenericEventTrigger has 3 configuration paramters: `eventTopic`,`eventSource` and `eventTypes` and one output: 'event'.
```json
{
"uid":"GenericEventTrigger",
"label":"Basic Event Trigger",
"description":"Triggers Rules on Events",
"configDescriptions":[
{
"uid":"GenericEventTrigger",
"label":"Basic Event Trigger",
"description":"Triggers Rules on Events",
"configDescriptions":[
{
"name":"eventTopic",
"type":"TEXT",
"label":"Topic",
"description":"This is the topic, the trigger will listen to: >>openhab/*<<",
"required":true,
"defaultValue":"openhab/*"
},
{
"name":"eventSource",
"type":"TEXT",
"label":"Source",
"description":"This is the source of the event (eg. item name)",
"required":true,
"defaultValue":""
},
{
"name":"eventTypes",
"type":"TEXT",
"label":"Event Type",
"description":"the event type, the trigger should listen to. Multiple types can be specified comma-separated",
"required":true,
"defaultValue":""
}
],
"outputs":[
{
"name":"event",
"type":"org.openhab.core.events.Event",
"label":"Event",
"description":"The events which was sent.",
"reference":"event"
}
]
"name":"eventTopic",
"type":"TEXT",
"label":"Topic",
"description":"This is the topic, the trigger will listen to: >>openhab/*<<",
"required":true,
"defaultValue":"openhab/*"
},
{
"name":"eventSource",
"type":"TEXT",
"label":"Source",
"description":"This is the source of the event (eg. item name)",
"required":true,
"defaultValue":""
},
{
"name":"eventTypes",
"type":"TEXT",
"label":"Event Type",
"description":"the event type, the trigger should listen to. Multiple types can be specified comma-separated",
"required":true,
"defaultValue":""
}
],
"outputs":[
{
"name":"event",
"type":"org.openhab.core.events.Event",
"label":"Event",
"description":"The events which was sent.",
"reference":"event"
}
]
}
```
### GenericCompareCondition
This module type is used to compare a value against a configuration property using an operator like `<, >, =`.
The value to be compared can be specified either as an input or as a configuration property.
{
"uid":"GenericCompareCondition",
"label":"CompareCondition",
"description":"configurable compare condition",
"configDescriptions":[
{
"name":"inputproperty",
"label":"Input property",
"type":"TEXT",
"description":"property of the input to be compared",
"required":false
},
{
"name":"right",
"type":"TEXT",
"label":"compare with",
"description":"the value to be compared with the input",
"required":true
},
{
"name":"operator",
"type":"TEXT",
"description":"the compare operator, allowed are <, >, =",
"required":true,
"defaultValue":"="
}
],
"inputs": [
{
"name":"input",
"type": "java.lang.Object",
"label": "input",
"description": "The input which will be compared.",
"required":true
}
]
}
```json
{
"uid":"GenericCompareCondition",
"label":"CompareCondition",
"description":"configurable compare condition",
"configDescriptions":[
{
"name":"inputproperty",
"label":"Input property",
"type":"TEXT",
"description":"property of the input to be compared",
"required":false
},
{
"name":"right",
"type":"TEXT",
"label":"compare with",
"description":"the value to be compared with the input",
"required":true
},
{
"name":"operator",
"type":"TEXT",
"description":"the compare operator, allowed are <, >, =",
"required":true,
"defaultValue":"="
}
],
"inputs": [
{
"name":"input",
"type": "java.lang.Object",
"label": "input",
"description": "The input which will be compared.",
"required":true
}
]
}
```
## Providing new Module Types
The rule engine is pluggable - any OSGi bundle can provide implementation for triggers, actions and condition module types and their corresponding metatype definition in JSON format.
The rule engine is pluggable - any OSGi bundle can provide implementation for triggers, actions and condition module types and their corresponding metatype definition in JSON format.
The extension bundle should register the service ModuleHandlerFactory (`org.openhab.automation.handler.ModuleHandlerFactory`)
The extension bundle should register the service ModuleHandlerFactory (`org.openhab.automation.handler.ModuleHandlerFactory`)
and implement the necessary methods for creation of instances of the supported module handlers:
- `org.openhab.automation.handler.TriggerHandler`
@ -590,44 +598,45 @@ and implement the necessary methods for creation of instances of the supported m
Another way to extend the supported module types is by defining composite module types as an extension of the system module types.
The composite module type wraps one or more instances of a system module type and defines new configuration parameters, inputs and outputs.
```json
{
"uid":"ItemStateChangeTrigger",
"label":"Item State Trigger",
"description":"This triggers a rule if an items state changed",
"configDescriptions":[
{
"uid":"ItemStateChangeTrigger",
"label":"Item State Trigger",
"description":"This triggers a rule if an items state changed",
"configDescriptions":[
{
"name":"itemName",
"type":"TEXT",
"context":"item",
"label":"item name",
"description":"the name of the item which's state change should be observed",
"required":true
}
],
"children":[
{
"id":"itemStateChangeTriggerID",
"type":"GenericEventTrigger",
"configuration":{
"eventSource":"$itemName",
"eventTopic":"openhab/items/*",
"eventTypes":"ItemStateEvent"
}
}
],
"outputs":[
{
"name":"event",
"type":"org.openhab.core.events.Event",
"description":"the event of the item state change",
"label":"event",
"reference":"itemStateChangeTriggerID.event"
}
]
"name":"itemName",
"type":"TEXT",
"context":"item",
"label":"item name",
"description":"the name of the item which's state change should be observed",
"required":true
}
],
"children":[
{
"id":"itemStateChangeTriggerID",
"type":"GenericEventTrigger",
"configuration":{
"eventSource":"$itemName",
"eventTopic":"openhab/items/*",
"eventTypes":"ItemStateEvent"
}
}
],
"outputs":[
{
"name":"event",
"type":"org.openhab.core.events.Event",
"description":"the event of the item state change",
"label":"event",
"reference":"itemStateChangeTriggerID.event"
}
]
}
```
This example demonstrates a new module type *ItemStateChangeTrigger* which wraps the system module type *GenericEventTrigger*.
It defines the new configuration property `itemName` which is used as the `eventSource` property of the *GenericEventTrigger*.
The other config parameters `eventTopic` and `eventTypes` are staticly defined.
The composite module type can also have inputs and outputs and can use a reference to map them to inputs and outputs of the nested system module type(s).
The composite module type can also have inputs and outputs and can use a reference to map them to inputs and outputs of the nested system module type(s).

158
configuration/sitemaps.md
View File

@ -23,7 +23,7 @@ Sitemaps follow the syntax described in this article.
For easy editing of sitemap definition files, we suggest to use one of the [openHAB supporting editors]({{base}}/configuration/editors.html).
These provide full IDE support for sitemap files, including syntax checking and auto-completion.
The openHAB runtime distribution comes with a demo configuration package containing a sitemap file named [`demo.sitemap`](https://github.com/openhab/openhab-distro/blob/master/features/distro-resources/src/main/resources/sitemaps/demo.sitemap).
The openHAB runtime distribution comes with a demo configuration package containing a sitemap file named [`demo.sitemap`](https://github.com/openhab/openhab-distro/blob/main/features/distro-resources/src/main/resources/sitemaps/demo.sitemap).
You may find it useful to use this file as a starting point in creating a sitemap that fits your personal home setup.
The following example illustrates what a typical Sitemap definition might look like:
@ -85,7 +85,7 @@ openHAB supports these dependencies by providing parameters for dynamic behavior
Be sure to check out the [Dynamic Sitemaps](#dynamic-sitemaps) chapter.
For the technically interested: The Sitemap definition language is an
Xtext Domain Specific Language and the sitemap file model can be found [here](https://github.com/openhab/openhab-core/blob/master/bundles/org.openhab.core.model.sitemap/src/org/openhab/core/model/sitemap/Sitemap.xtext).
Xtext Domain Specific Language and the sitemap file model can be found [here](https://github.com/openhab/openhab-core/blob/main/bundles/org.openhab.core.model.sitemap/src/org/openhab/core/model/sitemap/Sitemap.xtext).
### Special Element 'sitemap'
@ -133,18 +133,18 @@ This provides the flexibility to present Items in the way desired in your home a
**General remarks on parameters:**
- In the following definitions, parameters in `[square brackets]` are optional.
- In the following definitions, parameters in `[square brackets]` are optional.
- Parameters must be supplied in the order shown.
- Parameters must be supplied in the order shown.
- Common parameters, also known from [items definition](items.html#item-syntax):
- `item` defines the name of the Item you want to present (e.g. `Temperature`), [more details](items.html#item-name).
- `label` sets the textual description displayed next to the preprocessed Item data (e.g. "`Now [%s °C]`"), [more details](items.html#item-label).
- `icon` chooses the name of the icon file to show next to the element, [more details](items.html#icons).
- Common parameters, also known from [items definition](items.html#item-syntax):
- `item` defines the name of the Item you want to present (e.g. `Temperature`), [more details](items.html#item-name).
- `label` sets the textual description displayed next to the preprocessed Item data (e.g. "`Now [%s °C]`"), [more details](items.html#item-label).
- `icon` chooses the name of the icon file to show next to the element, [more details](items.html#icons).
- When an [Item]({{base}}/configuration/items.html) is defined, you have the opportunity to assign a label and/or an icon at that point.
If no label or icon are specified in the Sitemap, then the label and/or icon you assigned to the Item will be displayed.
Setting a value for `label` or `icon` of a Sitemap element will override the values defined for the linked Item.
- When an [Item]({{base}}/configuration/items.html) is defined, you have the opportunity to assign a label and/or an icon at that point.
If no label or icon are specified in the Sitemap, then the label and/or icon you assigned to the Item will be displayed.
Setting a value for `label` or `icon` of a Sitemap element will override the values defined for the linked Item.
It has to be considered that if the label defined in a Channel or an Item contains text and state, these representations have to be overwritten separately in the Sitemap.
In the following example a Item which has a label and state defined is overwritten.
@ -163,9 +163,10 @@ sitemap demo label="My home automation" {
}
}
```
UoM = [Units of Measurment]({{base}}/concepts/units-of-measurement.html)
- Additional parameters such as `mappings` and `valuecolor` are described below.
- Additional parameters such as `mappings` and `valuecolor` are described below.
### Element Type 'Frame'
@ -197,7 +198,6 @@ Default item=<itemname> [label="<labelname>"] [icon="<iconname>"]
Presents an Item using the default UI representation specified by the type of the given Item.
E.g., a `Dimmer` Item will be represented as a [Slider](#element-type-slider) element while a `Player` Item will be rendered with player button controls (Previous/Pause/Play/Next).
### Element Type 'Text'
```perl
@ -307,16 +307,16 @@ Slider item=<itemname> [label="<labelname>"] [icon="<iconname>"] [sendFrequency=
This type presents a value as a user-adjustable control which slides from left (0) to right (100).
- `sendFrequency` is used to distinguish between long and short button presses in the classic (web) frontend.
- `sendFrequency` is used to distinguish between long and short button presses in the classic (web) frontend.
This parameter defines the interval in milliseconds for sending increase/decrease requests.
- `switchSupport` is a parameter without an assignment.
- Classic UI: If specified, a short press on the "up" or "down" button switches the item "on" or "off" (0 or 100) respectively.
- Android app: If specified, a short press on the item row (except the slider itself) switches the item "on" or "off".
- This parameter has no effect in other UIs.
- `switchSupport` is a parameter without an assignment.
- Classic UI: If specified, a short press on the "up" or "down" button switches the item "on" or "off" (0 or 100) respectively.
- Android app: If specified, a short press on the item row (except the slider itself) switches the item "on" or "off".
- This parameter has no effect in other UIs.
- `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 the distance between two possible/selectable datapoints on the slider.
- `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 the distance between two possible/selectable datapoints on the slider.
**Example:**
@ -336,7 +336,6 @@ This element is a combined control for something like a rgb or rgbw light where
The down-button decreases brightness to zero and switches the light off. The up-button sets brightness to full but keeps the previous color (hue).
The middle button opens an overlay to finetune your color. A color wheel let you pick the hue and a slider allows to set the brightness.
- `sendFrequency` is used to distinguish between long and short button presses in the classic (web) frontend.
This parameter defines the interval in milliseconds for sending increase/decrease requests.
@ -393,7 +392,7 @@ Image [item=<itemname>] [icon="<iconname>"] url="<url of image>" [label="<labeln
This element type is able to present an image.
The image must be available on a reachable website or webserver without password or access token.
Alternatively, the image file (e.g. YourImageFile.png) may be stored locally in the $OPENHAB_CONF/html folder, and will be accessible through the static route, https://<my.openHAB.device>:8080/static/YourImageFile.png.
Alternatively, the image file (e.g. YourImageFile.png) may be stored locally in the $OPENHAB_CONF/html folder, and will be accessible through the static route, `https://<my.openHAB.device>:8080/static/YourImageFile.png`.
- `item` can refer to either an Image Item whose state is the raw data of the image, or a String Item whose state is an URL that points to an image. Some clients may not (yet) consider `item`.
- `url` is the default URL from which to retrieve the image, if there is no associated Item or if the associated item's state is not a URL.
@ -444,18 +443,18 @@ Chart [item=<itemname>] [icon="<iconname>"] [label="<labelname>"] [refresh=xxxx]
Adds a time-series chart object for the display of logged data.
- `refresh` defines the refresh period of the Image (in milliseconds).
- `refresh` defines the refresh period of the Image (in milliseconds).
- `service` sets the persistence service to use.
If no service is specified, openHAB will use the first queryable persistence service it finds.
Therefore, for an installation with only a single persistence service, this is not required.
- `service` sets the persistence service to use.
If no service is specified, openHAB will use the first queryable persistence service it finds.
Therefore, for an installation with only a single persistence service, this is not required.
- `period` is the scale of the time axis. Valid values are `h, 4h, 8h, 12h, D, 2D, 3D, W, 2W, M, 2M, 4M or Y`.
- `period` is the scale of the time axis. Valid values are `h, 4h, 8h, 12h, D, 2D, 3D, W, 2W, M, 2M, 4M or Y`.
- `begin` / `end` sets the beginning and end of the time axis.
Valid values are in the format: "yyyyMMddHHmm" (yyyy = year, MM = month, dd = day, HH = hour (0-23), mm = minutes).
- `begin` / `end` sets the beginning and end of the time axis.
Valid values are in the format: `yyyyMMddHHmm` (`yyyy` = year, `MM` = month, `dd` = day, `HH` = hour (0-23), `mm` = minutes).
- `legend` is used to show or to hide the chart legend.
- `legend` is used to show or to hide the chart legend.
Valid values are `true` (always show the legend) and `false` (never show the legend).
If this parameter is not set, the legend is hidden if there is only one chart series.
@ -499,7 +498,6 @@ Its power state is represented by a binary Switch Item.
Its channel number is a discrete number Item that may only be set to one of three states.
By using a Switch or Selection element with a mappings array, you can replace these meaningless values with user-friendly descriptions for display on the user interface.
This mapping changes the displayed power state of the TV from "ON" and "OFF" to the more accurate terms, "on" and "standby".
Similarly, mapping above changes the numbers "1", "2", and "3" to "DasErste", "BBC One", and "Cartoon Network" respectively.
@ -654,105 +652,31 @@ sitemap demo label="My home automation" {
Explanation:
- The Sitemap "demo" with the shown title "My home automation" is defined.
- The Sitemap "demo" with the shown title "My home automation" is defined.
- One first Frame with a date stamp is shown.
- One first Frame with a date stamp is shown.
- Another Frame with a visual label "Demo" is presented, containing:
- Another Frame with a visual label "Demo" is presented, containing:
- A Switch for the Item "Lights"
- A Switch for the Item "Lights"
- A Text element showing a temperature in a given format
- A Text element showing a temperature in a given format
- A Group element. Upon clicking the element, a new view containing all "Heating" Items will be shown.
- A Group element. Upon clicking the element, a new view containing all "Heating" Items will be shown.
- Another Text element showing a "Multimedia" summary, e.g. "Currently playing".
- Another Text element showing a "Multimedia" summary, e.g. "Currently playing".
The element is additionally the host for a nested block.
By clicking in the element, a new view with two elements is presented:
- A Selection presenting four options in a modal dialog prompt
- A Slider to set the volume (e.g. 0-100%)
- A Selection presenting four options in a modal dialog prompt
- A Slider to set the volume (e.g. 0-100%)
<!-- Note to author: If you update this example, remember to copy it to the beginning of this article as well! -->
## Further notes and comparison details
- String comparisons are case sensitive, so `==ON` is not the same as `==on`.
- String comparisons are case sensitive, so `==ON` is not the same as `==on`.
- DateTime comparisons are relative to the current time and specified in seconds.
- DateTime comparisons are relative to the current time and specified in seconds.
So the expression `Lights_On_Time > 300` will return true if the DateTime Item is set to a value that's newer than the past 5 minutes (300 seconds).
- Further examples for defining Sitemaps can be found in our [openHAB-Samples](https://github.com/openhab/openhab/wiki/Samples-Sitemap-Definitions) section.
<!-- Note to author:
- The screenshot were created with chrome mobile developer tools on a page width of 529px
-The screenshots were created in BasicUI with the following items and Sitemap file content:
Group:Number:AVG Temperatures <heating>
Number Demo_LivingroomTemperature "Livingroom [21.0 °C]" <temperature> (Temperatures)
Number Demo_BedroomTemperature "Bedroom [19.5 °C]" <temperature> (Temperatures)
Number Demo_KitchenTemperature "Kitchen [20.5 °C]" <temperature> (Temperatures)
Location Demo_Location "Location [48.858377,2.294486,66.0]"
Number Demo_TV_Channel
Color Demo_Color
sitemap demo label="My home automation" {
Frame label="Date" {
Text item=Date label="Today [Monday, 01. Aug. 2016]"
}
Frame label="Demo" {
Switch item=Lights icon="light" mappings=[OFF="All Off"]
Text item=Temperature label="Livingroom [21.3 °C]" icon="temperature" valuecolor=[>25="orange",>15="green",<=15="blue"]
Group item=Heating
Text item=Multimedia_Summary label="Multimedia" icon="video" {
Selection item=TV_Channel mappings=[0="off", 1="DasErste", 2="BBC One", 3="Cartoon Network"]
Slider item=Volume
}
}
Text label="The following elements are for screenshots. The screen was at this width:"
Text label="---------------------------------------------------------------------------------------"
Frame {
Text item=Temperature label="Livingroom [21.3 °C]" icon="temperature"
}
Frame {
Switch item=Livingroom_Light_OnOff label="Ceiling Light" icon="light"
}
Frame {
Switch item=Demo_TV_Channel label="TV Channel" icon="television" mappings=[0="DasErste", 1="BBC One", 2="Cartoon Network"]
}
Frame {
Selection item=Demo_TV_Channel label="TV Channel" icon="television" mappings=[0="DasErste", 1="BBC One", 2="Cartoon Network"]
}
Frame {
Setpoint item=Demo_KitchenTemperature
}
Frame {
Slider item=Demo_KitchenTemperature switchSupport
}
Frame {
Colorpicker item=Demo_Color label="LED Light Color" icon="colorwheel"
}
//Frame {
// Chart item=Demo_KitchenTemperature label="Test" period=h refresh=600
//}
Frame {
Group item=gHeatAct label="Room Temperatures [%.1f °C]"
}
Frame {
Image url="https://raw.githubusercontent.com/wiki/openhab/openhab/images/features.png"
}
Frame {
Video url="https://demo.openhab.org/Hue.m4v"
}
Frame {
Webview url="https://www.openhab.org" height=5
}
Frame {
Text item=Temperature label="Livingroom [22.0 °C]" icon="temperature" labelcolor=[!=1="blue"] valuecolor=[!=1="green"]
}
Frame {
Mapview item=Demo_Location height=5
}
}
-->
- Further examples for defining Sitemaps can be found in our [openHAB-Samples](https://github.com/openhab/openhab/wiki/Samples-Sitemap-Definitions) section.

47
configuration/things.md
View File

@ -33,11 +33,11 @@ From then on, everything else is configured at the application layer for that en
From start to finish, the process for fully configuring a physical entity represented by a Thing looks like this:
1. Identify the binding required for the Thing
2. Install the binding if it has not already been installed
3. Define and configure the Thing
4. Identify the Channels provided by the Thing
5. [Add Items]({{base}}/configuration/items.html) and link them to the Thing's Channels
6. At this point Items can be used to control the Thing or consume its information in e.g. [Sitemaps]({{base}}/configuration/sitemaps.html) or [Rules]({{base}}/configuration/rules-dsl.html)
1. Install the binding if it has not already been installed
1. Define and configure the Thing
1. Identify the Channels provided by the Thing
1. [Add Items]({{base}}/configuration/items.html) and link them to the Thing's Channels
1. At this point Items can be used to control the Thing or consume its information in e.g. [Sitemaps]({{base}}/configuration/sitemaps.html) or [Rules]({{base}}/configuration/rules-dsl.html)
There are two methods for defining Things provided by the various bindings:
through [discovery]({{base}}/concepts/discovery.html) or by manual definition in configuration text files.
@ -84,7 +84,6 @@ To help organizing your things, you also may define a location (`Location` in th
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.
**Examples:**
```xtend
@ -110,8 +109,8 @@ Bridges can be defined together with contained things. The following configurati
```xtend
Bridge hue:bridge:mybridge [ ipAddress="192.168.3.123" ] {
Thing 0210 bulb1 [ lightId="1" ]
Thing 0210 bulb2 [ lightId="2" ]
Thing 0210 bulb1 [ lightId="1" ]
Thing 0210 bulb2 [ lightId="2" ]
}
```
@ -160,11 +159,11 @@ It is also possible to add additional channels to existing things and for bindin
```xtend
Thing yahooweather:weather:losangeles [ location=2442047, unit="us", refresh=120 ] {
Channels:
State String : customChannel1 "My Custom Channel" [
configParameter="Value"
]
State Number : customChannel2 []
Channels:
State String : customChannel1 "My Custom Channel" [
configParameter="Value"
]
State Number : customChannel2 []
}
```
@ -176,11 +175,11 @@ As state channels are the default channels, you can omit the `State` keyword, th
```xtend
Thing yahooweather:weather:losangeles [ location=2442047, unit="us", refresh=120 ] {
Channels:
String : customChannel1 "My Custom Channel" [
configParameter="Value"
]
Number : customChannel2 []
Channels:
String : customChannel1 "My Custom Channel" [
configParameter="Value"
]
Number : customChannel2 []
}
```
@ -190,10 +189,10 @@ You may optionally give the channel a proper label (like “My Custom Channel”
```xtend
Thing yahooweather:weather:losangeles [ location=2442047, unit="us", refresh=120 ] {
Channels:
Trigger String : customChannel1 [
configParameter="Value"
]
Channels:
Trigger String : customChannel1 [
configParameter="Value"
]
}
```
@ -235,11 +234,11 @@ If you decide not to, then the label from the referenced channel type definition
### Linking Items
Items can be linked to Channels of discovered or manually defined Things inside Paper UI or inside configuration files.
Items can be linked to Channels of discovered or manually defined Things inside UI or inside configuration files.
For more details about Item definition and usage, please refer to the [Items configuration article]({{base}}/configuration/items.html).
It is important to note, that Channels of discovered Things can also be linked to Items defined in `.items` files.
In order to link a Thing to an Item in an `.items` file, open the Thing in Paper UI under *Configuration → Things*.
In order to link a Thing to an Item in an `.items` file, open the Thing in UI under `Settings → Things`.
In the list of Thing Channels, look for the Channel you wish to link to an Item and copy the Channel's ID.
For instance, a Z-Wave switch might have a Switch Channel that has an ID like this:

2
developers/audio/index.md
View File

@ -24,7 +24,7 @@ The distribution comes with these built-in audio sinks options:
|-------------------|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| javasound | System Speaker | This uses the JRE sound drivers to play audio to the local sound interface. |
| enhancedjavasound | System Speaker (with mp3 support) | This uses the JRE sound drivers plus an additional 3rd party library, which adds support for mp3 files. |
| webaudio | Web Audio | If sounds should not be played on the server but on the client: This sink sends the audio stream through HTTP to web clients, which then cause it to be played back by the browser. The browser needs to be opened and have a compatible UI running. Currently this feature is supported by Paper UI and HABPanel. |
| webaudio | Web Audio | If sounds should not be played on the server but on the client: This sink sends the audio stream through HTTP to web clients, which then cause it to be played back by the browser. The browser needs to be opened and have a compatible UI running. Currently this feature is supported by UI and HABPanel. |
The framework is able to play sound either from the file system, from URLs (e.g. Internet radio streams) or generated by text-to-speech engines (which are available as optional Voice add-ons).

8
developers/bindings/binding-xml.md
View File

@ -3,7 +3,7 @@ layout: developersguide
title: Binding Descriptions
---
## Binding Definitions
# Binding Definitions
Every binding has to provide meta information such as binding id or name.
@ -16,7 +16,7 @@ The full Java API for binding definitions can be found in the Java package `org.
For the declarative way, you add your binding information in form of a `binding.xml` file to the bundle's folder `/src/main/resources/OH-INF/binding/binding.xml`.
### XML Structure for Binding Definitions
## XML Structure for Binding Definitions
```xml
<?xml version="1.0" encoding="UTF-8"?>
@ -57,9 +57,9 @@ The full XML schema for binding definitions is specified in the [Binding XSD](ht
- The attribute `uri` in the section `config-description` is optional, it *should not* be specified in binding definition files because it's an embedded configuration. If the `uri` is *not* specified, the configuration description is registered as `binding:bindingID`, otherwise the given `uri` is used.
- If a configuration description is already specified somewhere else and the binding wants to (re-)use it, a `config-description-ref` should be used instead.
- Normally the service id must not be defined, because it is implicitly set to "binding.&lt;binding.id&gt;".
A binding can register an OSGi service which implements the ManagedService interface and define the service.pid as e.g."binding.hue" to receive the configuration.
A binding can register an OSGi service which implements the ManagedService interface and define the service.pid as e.g."binding.hue" to receive the configuration.
### Example
## Example
The following code gives an example for a binding definition.

7
developers/bindings/config-xml.md
View File

@ -31,9 +31,10 @@ The description can include limited HTML to enhance the display of this informat
The following HTML tags are allowed -: ```<b>, <br>, <em>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <i>, <p>, <small>, <strong>, <sub>, <sup>, <ul>, <ol>, <li>```.
These must be inside the XML escape sequence - eg.
```<description><![CDATA[ HTML marked up text here ]]></description>```.
`<description><![CDATA[ HTML marked up text here ]]></description>`.
## XML Structure for Configuration Descriptions
```xml
<?xml version="1.0" encoding="UTF-8"?>
<config-description:config-descriptions
@ -149,7 +150,6 @@ The above filter is evaluated as follows:
```text
(type=Switch OR type=Dimmer) AND (tag=Light OR tag=Heating)
```
Similarly, the <strong>Channel</strong> context can contain criteria to filter channels based on <strong>kind</strong> field.
@ -164,6 +164,7 @@ For example:
Groups allow parameters to be grouped together into logical blocks so that the user can find the parameters they are looking for.
A parameter can be placed into a group so that the UI knows how to display the information.
<table>
<tr><td><b>Property</b></td><td><b>Description</b></td></tr>
<tr><td>group.name</td><td>The group name - this is used to link the parameters into the group, along with the groupName option in the parameter (mandatory).</td></tr>
@ -178,7 +179,7 @@ The full XML schema for configuration descriptions is specified in the [openHAB
**Hints:**
- Although the attribute `uri` is optional, it *must* be specified in configuration description files.
Only for embedded configuration descriptions in documents for binding definitions and `Thing` type descriptions, the attribute is optional.
Only for embedded configuration descriptions in documents for binding definitions and `Thing` type descriptions, the attribute is optional.
## Example

17
developers/bindings/faq.md
View File

@ -12,13 +12,12 @@ If you do not find an answer to your question, do not hesitate to ask it on the
## Structuring Things and Thing Types
1. _I am implementing a binding for system X.
Shall I design this as one Thing or as a Bridge with multiple Things for the different functionalities?_
1. _I am implementing a binding for system X. Shall I design this as one Thing or as a Bridge with multiple Things for the different functionalities?_
In general, both options are valid:
1. You have one Thing which has channels for all your actors, sensors and other functions
2. You have one Bridge and an additional Thing for every actor and sensor and they would hold the channels
1. You have one Bridge and an additional Thing for every actor and sensor and they would hold the channels
The preferred architecture is the latter, if this is feasible.
This means that the physical devices should be represented by a Thing each.
@ -27,29 +26,27 @@ Shall I design this as one Thing or as a Bridge with multiple Things for the dif
If your system does not provide you any possibility to get hold of such information, but rather only shows you a "logical" view of it, then 1) is also a valid option to pursue.
2. _Do I have to create XML files in `OH-INF/thing` for all devices or is there any other option?_
1. _Do I have to create XML files in `OH-INF/thing` for all devices or is there any other option?_
No, the XML files are only one way to describe your devices.
Alternatively, you can implement your own [ThingTypeProvider](https://github.com/openhab/openhab-core/blob/master/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/ThingTypeProvider.java), through which you can provide thing descriptions in a programmatic way.
Alternatively, you can implement your own [ThingTypeProvider](https://github.com/openhab/openhab-core/blob/main/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/ThingTypeProvider.java), through which you can provide thing descriptions in a programmatic way.
Nonetheless, the static XML descriptions of thing types can be picked up for documentation generation and other purposes.
So whenever possible, static XML descriptions should be provided.
3. _For my system XY, there are so many different variants of devices.
Do I really need to define a thing type for every single one of them?_
1. _For my system XY, there are so many different variants of devices. Do I really need to define a thing type for every single one of them?_
Thing types are important if you have no chance to request any structural information about the devices from your system and if you need users to manually chose a thing to add or configure (i.e. there is also no automatic discovery).
The thing types that you provide will be the list the user can choose from.
If your system supports auto-discovery and you can also dynamically construct things (and their channels) from structural information that you can access during runtime, there is in theory no need to provide any thing type description at all.
Nonetheless, static descriptions of thing types have the advantage that the user knows which kind of devices are supported, no matter if he has a device at home or not - so you should at least have static XML descriptions for the devices that are known to you at implementation time.
4. _I have a device that can have different firmware versions with slightly different functionality.
Should I create one or two thing types for it?_
1. _I have a device that can have different firmware versions with slightly different functionality. Should I create one or two thing types for it?_
If the firmware version makes a huge difference for the device (and can be seen as a different model of it), then it is ok to have different things defined.
If the list of channels can be determined by knowing the firmware revision, this is good.
If you can only determine the existing channels by querying the device itself, it might be the better option to have only one thing type and construct its channels upon first access.
5. _When creating a Thing through my ThingHanderFactory, does it exactly have to have the channels that are defined in the thing type description?_
1. _When creating a Thing through my ThingHanderFactory, does it exactly have to have the channels that are defined in the thing type description?_
It must at least have the channels that are defined in its thing type (and they are already automatically added by the super() implementation).
Nonetheless, you are free to add any number of additional channels to the thing.

52
developers/bindings/index.md
View File

@ -6,6 +6,7 @@ title: Bindings
{% include base.html %}
# Developing a Binding
{:.no_toc}
A binding is an extension to openHAB that integrates an external system like a software service or a hardware device.
@ -19,6 +20,7 @@ It makes sense to briefly read over all sections to make you familiar with what
During development you might come back with specific questions.
{::options toc_levels="2,3"/}
- TOC
{:toc}
@ -117,16 +119,16 @@ For an example, our exemplary Weather binding starts and stops a scheduled job t
The startup of a handler is divided in two essential steps:
1. Handler is registered: `ThingHandler` instance is created by a `ThingHandlerFactory` and tracked by the framework.
In addition, the handler can be registered as a service if required, e.g. as `FirmwareUpdateHandler` or `ConfigStatusProvider`.
In addition, the handler can be registered as a service if required, e.g. as `FirmwareUpdateHandler` or `ConfigStatusProvider`.
2. Handler is initialized: `ThingHandler.initialize()` is called by the framework in order to initialize the handler.
This method is only called if all 'required' configuration parameters of the Thing are present.
The handler is ready to work (methods like `handleCommand`, `handleUpdate` or `thingUpdated` can be called).
1. Handler is initialized: `ThingHandler.initialize()` is called by the framework in order to initialize the handler.
This method is only called if all 'required' configuration parameters of the Thing are present.
The handler is ready to work (methods like `handleCommand`, `handleUpdate` or `thingUpdated` can be called).
The diagram below illustrates the startup of a handler in more detail.
The life cycle is controlled by the `ThingManager`.
The diagram below illustrates the startup of a handler in more detail.
The life cycle is controlled by the `ThingManager`.
![thing_life_cycle_startup](images/thing_life_cycle_startup.png)
![thing_life_cycle_startup](images/thing_life_cycle_startup.png)
The `ThingManager` mediates the communication between a `Thing` and a `ThingHandler` from the binding.
The `ThingManager` creates for each Thing a `ThingHandler` instance using a `ThingHandlerFactory`.
@ -153,11 +155,11 @@ After the handler is initialized, the handler must be ready to handle methods ca
The shutdown of a handler is also divided in two essential steps:
1. Handler is unregistered: `ThingHandler` instance is no longer tracked by the framework.
The `ThingHandlerFactory` can unregister handler services (e.g. `FirmwareUpdateHandler` or `ConfigStatusProvider`) if registered, or release resources.
The `ThingHandlerFactory` can unregister handler services (e.g. `FirmwareUpdateHandler` or `ConfigStatusProvider`) if registered, or release resources.
2. Handler is disposed: `ThingHandler.disposed()` method is called.
The framework expects `dispose()` to be non-blocking and to return quickly.
For longer running disposals, the implementation has to take care of scheduling a separate job.
1. Handler is disposed: `ThingHandler.disposed()` method is called.
The framework expects `dispose()` to be non-blocking and to return quickly.
For longer running disposals, the implementation has to take care of scheduling a separate job.
![thing_life_cycle_shutdown](images/thing_life_cycle_shutdown.png)
@ -538,7 +540,7 @@ Currently the framework provides two base thing handler implementations for the
Sub-classes of these handlers must only override the operation `getConfigStatus` to provide the configuration status in form of a collection of `org.openhab.core.config.core.status.ConfigStatusMessage`s.
#### Internationalization
#### Internationalization of Config Status Messages
The framework will take care of internationalizing messages.
@ -816,7 +818,7 @@ There is no explicit end to an active scan and discovery results can be provided
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.
In particular UIs the scan will be shown 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.
@ -833,7 +835,7 @@ If this behavior is not appropriate for the implemented discovery service, one c
}
```
### Internationalization
### Internationalization of Discovery result labels
The framework will take care of internationalizing labels of discovery results if you extend the `AbstractDiscoveryService`.
See [i18n](../utils/i18n.html#discovery) for more information.
@ -858,12 +860,12 @@ To facilitate the development, binding developers only need to implement a `Upnp
Here the developer only needs to implement three simple methods:
- `getSupportedThingTypeUIDs` - Returns the list of thing type UIDs that this participant supports.
The discovery service uses this method of all registered discovery participants to return the list of currently supported thing type UIDs.
The discovery service uses this method of all registered discovery participants to return the list of currently supported thing type UIDs.
- `getThingUID` - Creates a thing UID out of the UPnP result or returns `null` if this is not possible.
This method is called from the discovery service during result creation to provide a unique thing UID for the result.
This method is called from the discovery service during result creation to provide a unique thing UID for the result.
- `createResult` - Creates the `DiscoveryResult` out of the UPnP result.
This method is called from the discovery service to create the actual discovery result.
It uses the `getThingUID` method to create the thing UID of the result.
This method is called from the discovery service to create the actual discovery result.
It uses the `getThingUID` method to create the thing UID of the result.
The following example shows the implementation of the UPnP discovery participant for the Hue binding, the `HueBridgeDiscoveryParticipant`.
@ -918,12 +920,12 @@ Here the developer only needs to implement four simple methods:
- `getServiceType` - Defines the [mDNS service type](https://www.dns-sd.org/ServiceTypes.html).
- `getSupportedThingTypeUIDs` - Returns the list of thing type UIDs that this participant supports.
The discovery service uses this method of all registered discovery participants to return the list of currently supported thing type UIDs.
The discovery service uses this method of all registered discovery participants to return the list of currently supported thing type UIDs.
- `getThingUID` - Creates a thing UID out of the mDNS service info or returns `null` if this is not possible.
This method is called from the discovery service during result creation to provide a unique thing UID for the result.
This method is called from the discovery service during result creation to provide a unique thing UID for the result.
- `createResult` - Creates the `DiscoveryResult` out of the mDNS result.
This method is called from the discovery service to create the actual discovery result.
It uses the `getThingUID` method to create the thing UID of the result.
This method is called from the discovery service to create the actual discovery result.
It uses the `getThingUID` method to create the thing UID of the result.
### Discovery that is bound to a Thing
@ -937,11 +939,11 @@ Various binding related questions are answered in our [Binding development FAQ](
Once you are happy with your implementation, you need to integrate it in the Maven build and add it to the official distro.
- Add a new line in the [bundle pom.xml](https://github.com/openhab/openhab-addons/blob/master/bundles/pom.xml).
- Add a new line in the [binding pom.xml](https://github.com/openhab/openhab-addons/blob/master/bom/openhab-addons/pom.xml).
- Add a new line in the [bundle pom.xml](https://github.com/openhab/openhab-addons/blob/main/bundles/pom.xml).
- Add a new line in the [binding pom.xml](https://github.com/openhab/openhab-addons/blob/main/bom/openhab-addons/pom.xml).
- If you have a dependency on a transport bundle (e.g. upnp, mdns or serial) or an external library,
make sure to add a line for this dependency in the `/src/main/feature/feature.xml` file in your binding folder. See the other bindings as an example.
- Add your binding to the [CODEOWNERS](https://github.com/openhab/openhab-addons/blob/master/CODEOWNERS) file so that you get notified by Github when someone adds a pull request towards your binding.
- Add your binding to the [CODEOWNERS](https://github.com/openhab/openhab-addons/blob/main/CODEOWNERS) file so that you get notified by Github when someone adds a pull request towards your binding.
> Please make sure you add the above entries at their alphabetically correct position!

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

@ -6,6 +6,7 @@ title: Thing Descriptions
{% include base.html %}
# Binding Definitions
{:.no_toc}
In order to work with *Things* and *Channels*, some meta information about them is needed.
@ -14,6 +15,7 @@ These are provided through 'ThingType' and 'ChannelType' definitions,
which describe details about their functionality and configuration options.
{::options toc_levels="2,3"/}
- TOC
{:toc}
@ -123,27 +125,28 @@ The following XML snippet shows a system channel type definition and thing type
There exist system-wide channel types that are available by default:
| Channel Type ID | Reference typeId | Item Type | Category | Description |
|----------------------|-----------------------------|----------------------|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| signal-strength | system.signal-strength | Number | QualityOfService | Represents signal strength of a device as a Number with values 0, 1, 2, 3 or 4; 0 being worst strength and 4 being best strength. |
| low-battery | system.low-battery | Switch | Battery | Represents a low battery warning with possible values on (low battery) and off (battery ok). |
| battery-level | system.battery-level | Number | Battery | Represents the battery level as a percentage (0-100%). Bindings for things supporting battery level in a different format (e.g. 4 levels) should convert to a percentage to provide a consistent battery level reading. |
| power | system.power | Switch | - | Turn a device on/off. |
| brightness | system.brightness | Dimmer | Light | Brightness of a bulb (0-100%). |
| color | system.color | Color | ColorLight | Color of a bulb. |
| color-temperature | system.color-temperature | Dimmer | ColorLight | Color temperature of a bulb (0-100%). 0% should be the coldest setting (highest Kelvin value). |
| location | system.location | Location | - | Location in lat.,lon.,height coordinates. |
| motion | system.motion | Switch | Motion | Motion detected by the device (ON if motion is detected). |
| mute | system.mute | Switch | SoundVolume | Turn on/off the volume of a device. |
| volume | system.volume | Dimmer | SoundVolume | Change the sound volume of a device (0-100%). |
| media-control | system.media-control | Player | MediaControl | Control for a media player. |
| media-title | system.media-title | String | - | Title of a (played) media file. |
| media-artist | system.media-artist | String | - | Artist of a (played) media file. |
| outdoor-temperature | system.outdoor-temperature | Number:Temperature | Temperature | Current outdoor temperature. |
| wind-direction | system.wind-direction | Number:Angle | Wind | Wind direction in degrees (0-360°). |
| wind-speed | system.wind-speed | Number:Speed | Wind | Wind speed |
| atmospheric-humidity | system.atmospheric-humidity | Number:Dimensionless | Humidity | Atmospheric humidity in percent. |
| barometric-pressure | system.barometric-pressure | Number:Pressure | Pressure | Barometric pressure |
| Channel Type ID | Reference typeId | Item Type | Category | Description |
|-----------------------|------------------------------|----------------------|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| signal-strength | system.signal-strength | Number | QualityOfService | Represents signal strength of a device as a Number with values 0, 1, 2, 3 or 4; 0 being worst strength and 4 being best strength. |
| low-battery | system.low-battery | Switch | LowBattery | Represents a low battery warning with possible values on (low battery) and off (battery ok). |
| battery-level | system.battery-level | Number | Battery | Represents the battery level as a percentage (0-100%). Bindings for things supporting battery level in a different format (e.g. 4 levels) should convert to a percentage to provide a consistent battery level reading. |
| power | system.power | Switch | Switch | Turn a device on/off. |
| brightness | system.brightness | Dimmer | Light | Brightness of a bulb (0-100%). |
| color | system.color | Color | ColorLight | Color of a bulb. |
| color-temperature | system.color-temperature | Dimmer | ColorLight | Color temperature of a bulb (0-100%). 0% should be the coldest setting (highest Kelvin value), 100 the warmest. |
| color-temperature-abs | system.color-temperature-abs | Number | ColorLight | Color temperature of a bulb in Kelvin (1000K-10000K). |
| location | system.location | Location | - | Location in lat.,lon.,height coordinates. |
| motion | system.motion | Switch | Motion | Motion detected by the device (ON if motion is detected). |
| mute | system.mute | Switch | SoundVolume | Turn on/off the volume of a device. |
| volume | system.volume | Dimmer | SoundVolume | Change the sound volume of a device (0-100%). |
| media-control | system.media-control | Player | MediaControl | Control for a media player. |
| media-title | system.media-title | String | - | Title of a (played) media file. |
| media-artist | system.media-artist | String | - | Artist of a (played) media file. |
| outdoor-temperature | system.outdoor-temperature | Number:Temperature | Temperature | Current outdoor temperature. |
| wind-direction | system.wind-direction | Number:Angle | Wind | Wind direction in degrees (0-360°). |
| wind-speed | system.wind-speed | Number:Speed | Wind | Wind speed |
| atmospheric-humidity | system.atmospheric-humidity | Number:Dimensionless | Humidity | Atmospheric humidity in percent. |
| barometric-pressure | system.barometric-pressure | Number:Pressure | Pressure | Barometric pressure |
For further information about categories see the [categories page](../../concepts/categories.html).
@ -286,6 +289,7 @@ The following XML snippet defines a list of commands:
```
The user interface can use these values to render
- a drop down and also represent the current state or
- as push buttons to simply send a command to the ThingHandler.
@ -548,6 +552,7 @@ The label and descriptions for things, channels and config descriptions should f
The label should be short so that for most UIs it does not spread across multiple lines.
Guideline is 2-3 words with up to 25 chars.
Labels should be capitalized using the following rules:
- Always capitalize the first and the last word.
- Lowercase articles, coordinating conjunctions, and prepositions (`a, an, the, and, as, but, by, for, from, in, into, like, near, nor, of, onto, or, out, over, past, so, till, to, up, upon, with, yet`).
- Capitalize all other words.
@ -850,5 +855,5 @@ The full XML schema for Thing type descriptions is specified in the [https://ope
- Any identifiers of the types are automatically mapped to unique identifiers: `bindingID:id`.
- The attribute `uri` in the section `config-description` is optional, it *should not* be specified in bridge/*Thing*/channel type definition files because it's an embedded configuration.
If the `uri` is *not* specified, the configuration description is registered as `thing-type:bindingID:id` or `channel-type:bindingID:id` otherwise the given `uri` is used.s
If the `uri` is *not* specified, the configuration description is registered as `thing-type:bindingID:id` or `channel-type:bindingID:id` otherwise the given `uri` is used.s
- If a configuration description is already specified somewhere else and the bridge/*Thing*/channel type wants to (re-)use it, a `config-description-ref` should be used instead.

14
developers/buildsystem.md
View File

@ -40,8 +40,8 @@ These dependencies are embedded in the resulting bundle automatically.
There are two exceptions:
1) Dependencies to other openHAB bundles (e.g. `org.openhab.addons.bundles/org.openhab.binding.bluetooth/2.5.0-SNAPSHOT` or `org.openhab.addons.bundles/org.openhab.transform.map/2.5.0-SNAPSHOT`).
2) Bundles that are used by more than one binding (e.g. Netty-bundles like `io.netty/netty-common/4.1.34.Final`).
1. Dependencies to other openHAB bundles (e.g. `org.openhab.addons.bundles/org.openhab.binding.bluetooth/2.5.0-SNAPSHOT` or `org.openhab.addons.bundles/org.openhab.transform.map/2.5.0-SNAPSHOT`).
1. Bundles that are used by more than one binding (e.g. Netty-bundles like `io.netty/netty-common/4.1.34.Final`).
Dependencies on other openHAB bundles should have the scope `provided`.
To ensure that they are available at runtime they also need to be added to the `feature.xml`:
@ -55,10 +55,10 @@ To ensure that they are available at runtime they also need to be added to the `
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.
1. 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.
@ -104,7 +104,7 @@ The need to be added to the feature to make them available at runtime.
Two cases need to be treated differently:
1. Bundles that have a core feature are referenced by the feature (e.g. `<feature>openhab-runtime-jna</feature>` or `<feature>openhab-transport-upnp</feature>`).
2. Bundles that do not have a core feature are added directly (e.g. `<bundle dependency="true">mvn:commons-codec/commons-codec/1.10</bundle>`).
1. Bundles that do not have a core feature are added directly (e.g. `<bundle dependency="true">mvn:commons-codec/commons-codec/1.10</bundle>`).
### Multi-Bundle Features / Sub-Bundles

21
developers/contributing.md
View File

@ -89,11 +89,6 @@ sure to post a comment after pushing. The new commits will show up in the pull
request automatically, but the reviewers will not be notified unless you
comment.
Before the pull request is merged, make sure that you squash your commits into
logical units of work using `git rebase -i` and `git push -f`. After every
commit the test suite should be passing. Include documentation changes in the
same commit so that a revert would remove all traces of the feature or fix.
Commits that fix or close an issue should include a reference like `Closes #XXX`
or `Fixes #XXX`, which will automatically close the issue when merged.
@ -150,7 +145,9 @@ By making a contribution to this project, I certify that:
then you just add a line to every git commit message:
Signed-off-by: Joe Smith <joe.smith@email.com>
```text
Signed-off-by: Joe Smith <joe.smith@email.com>
```
using your real name (sorry, no pseudonyms or anonymous contributions.) and an
e-mail address under which you can be reached (sorry, no github noreply e-mail
@ -161,9 +158,11 @@ Additionally can also sign off commits automatically by adding the `-s` or `--si
If your commit contains code from others as well, please ensure that they certify the DCO as well and add them with an "Also-By" line to your commit message:
Also-by: Ted Nerd <ted.nerd@email.com>
Also-by: Sue Walker <sue.walker@email.com>
Signed-off-by: Joe Smith <joe.smith@email.com>
```text
Also-by: Ted Nerd <ted.nerd@email.com>
Also-by: Sue Walker <sue.walker@email.com>
Signed-off-by: Joe Smith <joe.smith@email.com>
```
#### Small Patch Exception
@ -196,8 +195,8 @@ You don't even need to know Git.
- 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.
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.

32
developers/guidelines.md
View File

@ -66,7 +66,7 @@ Rules are enforced as part of the build process using [Spotless Maven Plugin](ht
To check if your code is following the code style run `mvn spotless:check`. If Maven prints `[INFO] Spotless check skipped` then run `mvn spotless:check -Dspotless.check.skip=false` instead as the check isn't mandatory yet.
To reformat you code run `mvn spotless:apply`
Code styles files are located in here: <https://github.com/openhab/static-code-analysis/tree/master/codestyle/src/main/resources>
Code styles files are located in here: <https://github.com/openhab/static-code-analysis/tree/main/codestyle/src/main/resources>
#### Java Code
@ -74,7 +74,7 @@ The rules are defined using the Eclipse Java Formatter definitions. There are pl
- Official [openHAB Eclipse IDE setup](ide/eclipse.html) is preconfigured
- Eclipse standalone installation
- You can manually import [openhab_codestyle.xml](https://raw.githubusercontent.com/openhab/static-code-analysis/master/codestyle/src/main/resources/openhab_codestyle.xml) via `Eclipse Preferences -> Java -> Code Style -> Formatter` and [openhab.importorder](https://raw.githubusercontent.com/openhab/static-code-analysis/master/codestyle/src/main/resources/openhab.importorder) via `Eclipse Preferences -> Java -> Code Style -> Organize Imports`
- You can manually import [openhab_codestyle.xml](https://raw.githubusercontent.com/openhab/static-code-analysis/main/codestyle/src/main/resources/openhab_codestyle.xml) via `Eclipse Preferences -> Java -> Code Style -> Formatter` and [openhab.importorder](https://raw.githubusercontent.com/openhab/static-code-analysis/main/codestyle/src/main/resources/openhab.importorder) via `Eclipse Preferences -> Java -> Code Style -> Organize Imports`
- IntelliJ using plugin <https://plugins.jetbrains.com/plugin/6546-eclipse-code-formatter>
- Same files as for the Eclipse standalone installation. Be sure to follow *all- the plugin configuration steps.
@ -84,7 +84,7 @@ The rules are defined using the Eclipse Java Formatter definitions. There are pl
- Other `xml` files shall have 1 tab indentation
- Line length shall be 120 characters
The rules are defined at <https://github.com/openhab/static-code-analysis/tree/master/codestyle/src/main/resources> for the Eclipse WTP formatter, but will have to be manually entered into your IDE.
The rules are defined at <https://github.com/openhab/static-code-analysis/tree/main/codestyle/src/main/resources> for the Eclipse WTP formatter, but will have to be manually entered into your IDE.
### Java Coding Style
@ -149,15 +149,15 @@ See [Default libraries](#default-libraries) for more details.
## E. Runtime Behavior
1. Overridden methods from abstract classes or interfaces are expected to return fast unless otherwise stated in their JavaDoc.
Expensive operations should therefore rather be scheduled as a job.
2. Creation of threads must be avoided.
Instead, resort into using existing schedulers which use pre-configured thread pools.
If there is no suitable scheduler available, start a discussion in the forum about it rather than creating a thread by yourself.
For periodically executed jobs that do not require a fixed rate [scheduleWithFixedDelay](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/ScheduledExecutorService.html#scheduleWithFixedDelay(java.lang.Runnable,long,long,java.util.concurrent.TimeUnit)) should be preferred over [scheduleAtFixedRate](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/ScheduledExecutorService.html#scheduleAtFixedRate(java.lang.Runnable,long,long,java.util.concurrent.TimeUnit)).
3. Bundles need to cleanly start and stop without throwing exceptions or malfunctioning.
This can be tested by manually starting and stopping the bundle from the console (```stop <bundle-id>``` resp. ```start <bundle-id>```).
4. Bundles must not require any substantial CPU time.
Test this e.g. using "top" or VisualVM and compare CPU utilization with your bundle stopped vs. started.
Expensive operations should therefore rather be scheduled as a job.
1. Creation of threads must be avoided.
Instead, resort into using existing schedulers which use pre-configured thread pools.
If there is no suitable scheduler available, start a discussion in the forum about it rather than creating a thread by yourself.
For periodically executed jobs that do not require a fixed rate [scheduleWithFixedDelay](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/ScheduledExecutorService.html#scheduleWithFixedDelay(java.lang.Runnable,long,long,java.util.concurrent.TimeUnit)) should be preferred over [scheduleAtFixedRate](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/ScheduledExecutorService.html#scheduleAtFixedRate(java.lang.Runnable,long,long,java.util.concurrent.TimeUnit)).
1. Bundles need to cleanly start and stop without throwing exceptions or malfunctioning.
This can be tested by manually starting and stopping the bundle from the console (```stop <bundle-id>``` resp. ```start <bundle-id>```).
1. Bundles must not require any substantial CPU time.
Test this e.g. using "top" or VisualVM and compare CPU utilization with your bundle stopped vs. started.
## F. Logging
@ -185,8 +185,8 @@ void myFun() {
```
- Exceptions with stacktraces in the log are considered to be bugs in your binding that should be reported and fixed.
If you add an exception as a last parameter to the logging, the stack trace will be printed.
Configuration errors by users should only print log messages about what's wrong. In that case you would use `e.getMessage()`.
If you add an exception as a last parameter to the logging, the stack trace will be printed.
Configuration errors by users should only print log messages about what's wrong. In that case you would use `e.getMessage()`.
```java
void myFun() {
@ -264,7 +264,7 @@ This sections provides some background and more detailed information about parts
### Static Code Analysis
The openHAB Maven build includes [tooling for static code analysis](https://github.com/openhab/static-code-analysis) that will validate your code against the Coding Guidelines and some additional best practices.
Information about the checks can be found [here](https://github.com/openhab/static-code-analysis/blob/master/docs/included-checks.md).
Information about the checks can be found [here](https://github.com/openhab/static-code-analysis/blob/main/docs/included-checks.md).
The tool will generate an individual report for each bundle that you can find in `path/to/bundle/target/code-analysis/report.html` file and a report for the whole build that contains links to the individual reports in the `target/summary_report.html`.
The tool categorizes the found issues by priority: 1(error),2(warning) or 3(info).
@ -288,6 +288,8 @@ public class MyClass(){}
This forces you to think about every field in your class if it can be null at any point, or should rather be default initialized.
If you have fields that are neither marked as nullable, nor are initialized, the code will not compile.
When using data transfer objects (DTO), you can move this into a package called dto or append DTO to the class name to get rid of the checkstyle warning about missing NonNullByDefault annotation.
Fields that can be null are to be annotated like this:
```java

10
developers/ide/eclipse.md
View File

@ -83,12 +83,12 @@ If you already have Eclipse installed it is recommended to perform a separate Ec
1. After all tasks are finished you are ready to start developing.
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.
For other libraries supported out-of-the-box check the [Default Libraries](../guidelines.html#default-libraries) on the guidelines page.
## Working with Add-ons
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.
This mechanism replaces the add-on installation process via the UI that you would use outside the IDE.
### Running Add-ons
@ -107,7 +107,7 @@ The following files are of interest for the execution environment:
```
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:
Here is an example for the `astro` binding:
```xml
<dependency>
@ -146,11 +146,11 @@ Here is an example for the `astro` binding:
1. Start openHAB from the IDE by clicking "Run OSGi" (upper right of the `app.bndrun` window).
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 that openHAB is running with your browser by going to: `http://localhost:8080/` (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`
1. Check the chosen binding is active in `UI > Settings > Bindings`
View all the above steps in a single animation:

4
developers/ide/examples/vscode/settings.json
View File

@ -7,7 +7,7 @@
"java.saveActions.organizeImports": true,
"java.configuration.checkProjectSettingsExclusions": false,
"java.codeGeneration.generateComments": true,
"java.format.settings.url": "https://raw.githubusercontent.com/openhab/static-code-analysis/master/codestyle/src/main/resources/openhab_codestyle.xml",
"java.format.settings.url": "https://raw.githubusercontent.com/openhab/static-code-analysis/main/codestyle/src/main/resources/openhab_codestyle.xml",
"java.format.settings.profile": "openHAB",
"[java]": {
"editor.defaultFormatter": "redhat.java",
@ -17,4 +17,4 @@
"[xml]": {
"editor.defaultFormatter": "redhat.vscode-xml"
}
}
}

15
developers/ide/intellij.md
View File

@ -18,11 +18,14 @@ This article refers to the directory where you installed the distribution as `<D
## Build the addons repostory
1. fork and clone the [openhab addons repository](https://www.github.com/openhab/openhab-addons) into a new directory (Reference `<ADDON_DIR>` from now on for this arcticle)
- `git clone https://github.com/<yourgitusername>/openhab-addons` (replace git user name accordingly)
1. fork and clone the [openhab addons repository](https://www.github.com/openhab/openhab-addons) into a new directory (Reference `<ADDON_DIR>` from now on for this arcticle) with `git clone https://github.com/<yourgitusername>/openhab-addons` (replace git user name accordingly)
1. open IntelliJ and create a new Project from existing sources (File | New | Project from existing sources) and pick `<ADDON_DIR>`/pom.xml
- IntelliJ will start importing, indexing and building, it will take while, wait until finished (see status bar)
IntelliJ will start importing, indexing and building, it will take while, wait until finished (see status bar)
1. Use Maven to clean & install the addons project
- mvn clean install in the root of `<ADDON_DIR>` using commandline Maven (or IntelliJ Maven view)
- some of the addons might fail to build - if it's not the one, you're interested in that should not bother you
- when the Maven project finished, you should find the freshly built addon JAR in the target directory
@ -30,16 +33,22 @@ This article refers to the directory where you installed the distribution as `<D
## Debug your addon
1. copy the addon JAR to Openhab distribution created before
- `cp target/<ADDON_NAME>.jar <DISTRO_DIR>/addons`
1. The running instance of the openhab distribution should pick up your new addon & start it
- you can type `log:tail` in the openhab console to stream the openhab logs
1. create a Remote Debug runtime configuration in IntelliJ:
- Open menu Run | Edit configurations
- click the + sign to add a "Remote" configuration
- adapt the module setting to the root (org.openhab.addons.reactor)
- click OK
- start the debug configuration
- the IntelliJ console should log: `Connected to the target VM, address: 'localhost:5005', transport: 'socket'`
![Remote Debug Run Configuration](images/ide_setup_intellij_debug_configuration.png)
You can now add breakpoints to your project now and your test distro should stop there.

12
developers/ide/vscode.md
View File

@ -29,13 +29,14 @@ The following steps will only need to be done once to setup both VSCode and your
Either globally define the formatting options via ```Files->Preferences->Settings->Extendions->Java configuration``` (or in the global ```settings.json```). You can also define them local to a specific bundle by putting those lines in the ```.vscode/settings.json``` file in the bundle (similar to ```tasks.json```/```launch.json``` below).
Download [settings.json](https://raw.githubusercontent.com/openhab/openhab-docs/master/developers/ide/examples/vscode/settings.json) for the recommended settings (or simply wish to copy the URLs in the above image).
Download [settings.json](https://raw.githubusercontent.com/openhab/openhab-docs/main/developers/ide/examples/vscode/settings.json) for the recommended settings (or simply wish to copy the URLs in the above image).
## Steps for each Bundle
The following steps will show you how to setup a specific bundle for development with VSCode. These steps will show how to setup the Russound bundle but are generic to any bundle in the system.
1. Ensure the bundle builds correctly (natively with maven)
1. Open console to the bundle location (example: `%BASE%\openhab-addons\bundles\org.openhab.binding.russound`)
1. `mvn clean install -DskipChecks` in the console to build the bundle
1. Should produce a jar file in the 'target' directory of the bundle(example: `%BASE%\openhab-addons\bundles\org.openhab.binding.russound\target\org.openhab.binding.russound-2.5.0-SNAPSHOT.jar`)
@ -46,7 +47,7 @@ The following steps will show you how to setup a specific bundle for development
![define .vscode](images/ide_setup_vscode_folder.png)
1. Download [tasks.json](https://raw.githubusercontent.com/openhab/openhab-docs/master/developers/ide/examples/vscode/tasks.json) to the .vscode directory (example: `%BASE%\openhab-addons\bundles\org.openhab.binding.russound\.vscode\tasks.json`)
1. Download [tasks.json](https://raw.githubusercontent.com/openhab/openhab-docs/main/developers/ide/examples/vscode/tasks.json) to the .vscode directory (example: `%BASE%\openhab-addons\bundles\org.openhab.binding.russound\.vscode\tasks.json`)
![define tasks.json](./images/ide_setup_vscode_folder_tasks.png)
@ -63,13 +64,11 @@ The following steps will show you how to setup a specific bundle for development
1. Start the openHAB instance with the debug option - `start.bat debug` from a console in the openHAB home directory. You should see the following line printed somewhere in the karaf console:
`Listening for transport dt_socket at address: xxxx` (where xxxx should be 5005)
1. Download [launch.json](https://raw.githubusercontent.com/openhab/openhab-docs/master/developers/ide/examples/vscode/launch.json) to the .vscode directory (example: `%BASE%\openhab-addons\bundles\org.openhab.binding.russound\.vscode\launch.json`)
1. Download [launch.json](https://raw.githubusercontent.com/openhab/openhab-docs/main/developers/ide/examples/vscode/launch.json) to the .vscode directory (example: `%BASE%\openhab-addons\bundles\org.openhab.binding.russound\.vscode\launch.json`)
![define launch.json](./images/ide_setup_vscode_folder_launch.png)
1. Edit launch.json and ...
![launch.json changes](./images/ide_setup_vscode_launch.png)
1. Edit launch.json and ...<br>![launch.json changes](./images/ide_setup_vscode_launch.png)
1. Set the `port` to xxxx (from step 7). This can be skipped if xxxx was 5005 from step 7.
1. Set the `hostName` to the hostname running openHAB. This can be skipped if running locally (localhost)
@ -80,7 +79,6 @@ The following steps will show you how to setup a specific bundle for development
1. Shutdown any instances of openHAB
1. Press `CTRL-SHIFT-P -> Tasks: Run Task -> Start openHAB (Debug)` to start an openHAB instance in debug mode. You should see openHAB startup in a new VSCode terminal.
1. Press F5 (or bring up debug in VSCode and choose the "Debug (Attach) - openHAB" configuration) and the following should occur in the VSCode terminal
1. The maven compile occuring (successfully)
1. The resulting JAR is copied to the openHAB addons directory (`openhab_addons`)
1. Connecting to the openHAB instance (the debug call stack should show a bunch of openHAB type threads running)

22
developers/osgi/equinox.md
View File

@ -6,6 +6,7 @@ title: Equinox
{% include base.html %}
# Equinox
{:.no_toc}
[Equinox][Equinox] is considered to be a reference implementation of the [OSGi Core Release 7][OSGi-core].
@ -16,24 +17,25 @@ The openHAB bundles are deployed on an Equinox runtime.
Knowledge about how to start the runtime and execute basic commands will help you to speedup the development process.
{::options toc_levels="2,3"/}
- TOC
{:toc}
## Start Equinox Runtime from Eclipse
1. Go to "Run" -> "Run Configurations".
2. From the list in the left panel choose "OSGi Framework". Right click on it and choose "New".
3. After you've been created a new configuration, select the bundles that you need from the workspace.
4. Then make sure that the following bundles from the target platform are selected, otherwise the OSGi console will not be available:
1. From the list in the left panel choose "OSGi Framework". Right click on it and choose "New".
1. After you've been created a new configuration, select the bundles that you need from the workspace.
1. Then make sure that the following bundles from the target platform are selected, otherwise the OSGi console will not be available:
org.apache.felix.gogo.runtime
org.apache.felix.gogo.shell
org.apache.felix.gogo.command
org.eclipse.equinox.console
5. Click on "Add Required Bundles". Eclipse will resolve all dependencies of the bundles listed above and include new bundles to the configuration.
6. Click on "Validate Bundles" and make sure that "No problems were detected" is displayed.
7. You can start Equinox with the "Run" button.
1. Click on "Add Required Bundles". Eclipse will resolve all dependencies of the bundles listed above and include new bundles to the configuration.
1. Click on "Validate Bundles" and make sure that "No problems were detected" is displayed.
1. You can start Equinox with the "Run" button.
![Run Configurations dialog window](images/runconfiguration.png)
@ -45,9 +47,9 @@ If you have compiled openHAB once either via command line (`mvn install`) or the
Find it in your maven cache directory (linux `~/.m2/repository/org/eclipse/platform/org.eclipse.osgi/3.15.0/org.eclipse.osgi-3.15.0.jar`
and windows `C:\Users\your.name\.m2\..`).
1. Create `configuration` folder in that directory.
1. Inside the `configuration` folder create a file `config.ini`.
1. Save the following content in the `config.ini` file:
1. Create `configuration` folder in that directory.
1. Inside the `configuration` folder create a file `config.ini`.
1. Save the following content in the `config.ini` file:
```ini
osgi.bundles=\
@ -67,7 +69,7 @@ and windows `C:\Users\your.name\.m2\..`).
eclipse.consoleLog=true
```
1. Use the following command line to run Equinox:
1. Use the following command line to run Equinox:
```shell
java -jar org.eclipse.osgi-3.x.x.jar -console -configuration configuration

1
developers/osgi/osgi.md
View File

@ -13,6 +13,7 @@ openHAB is being based on [OSGi][OSGi] and understanding of OSGi modular archite
This page is aimed to help developers, that are going to use OSGi for the first time and contains a basic overview of the OSGi technology.
{::options toc_levels="2,3"/}
- TOC
{:toc}

2
developers/osgi/osgids.md
View File

@ -24,7 +24,7 @@ In order to simplify the usage of services the [OSGi Alliance](https://www.osgi.
In order to understand this model, we will have to first explain a few terms, used below:
- **Declarative Services Container** (we will use the shorthand **DS**) - a module that is managing the [lifecycle](#vii-component-lifecycle) of a *service component- dynamically.
It activates and deactivates different components, basing its decisions on the information contained in the *component description*;
It activates and deactivates different components, basing its decisions on the information contained in the _component description_;
- **Service Component** (or also **component**) - an object whose lifecycle is managed,
usually by a component framework such as Declarative Services (DS).
A component may publish itself as an OSGi service or consume OSGi services.

32
developers/utils/events.md
View File

@ -6,6 +6,7 @@ title: Event Bus
{% include base.html %}
# Event Bus
{:.no_toc}
The openHAB framework provides an event bus for inter-component communication.
@ -16,6 +17,7 @@ This section introduces the event API and illustrates how to receive such events
Furthermore, the sending of events and the implementation of new event types will be described.
{::options toc_levels="2,3"/}
- TOC
{:toc}
@ -171,19 +173,19 @@ Each event subscriber must be registered via OSGi Declarative Services (DS) unde
The listing below summarizes some best practices in order to implement event subscribers:
- To subscribe to only one event type openHAB provides the `org.openhab.core.events.AbstractTypedEventSubscriber` implementation.
To receive an already cast event the `receiveTypedEvent(T)` method must be implemented.
To provide an event filter the method `getEventFilter()` can be overridden.
To receive an already cast event the `receiveTypedEvent(T)` method must be implemented.
To provide an event filter the method `getEventFilter()` can be overridden.
- openHAB provides an `AbstractItemEventSubscriber` class in order to receive `ItemStateEvents` and `ItemCommandEvents` (more information can be obtained in the next chapter).
- To filter events based on a topic the `org.openhab.core.events.TopicEventFilter` implementation from the openHAB core bundle can be used.
The filtering is based on [Java regular expression](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/regex/Pattern.html).
The filtering is based on [Java regular expression](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/regex/Pattern.html).
- The subscribed event types and the filter should be stored as class members (see example above) due to performance reasons.
- If the subscribed event types are sufficient in order to receive all interested events, do not return any filter (in that case the method getFilter() returns null) due to performance reasons.
- Avoid the creation of too many event subscribers.
Similar event types can be received in one event subscriber.
Similar event types can be received in one event subscriber.
- Handle exceptions in event subscriber implementation and throw only serious exceptions.
Thrown exceptions will be handled in the framework by logging an error message with the cause.
Thrown exceptions will be handled in the framework by logging an error message with the cause.
- The receive method should terminate quickly, since it blocks other event subscribers.
Create a thread for long running operations.
Create a thread for long running operations.
### Receive ItemStateEvents and ItemCommandEvents
@ -280,7 +282,7 @@ public class SunriseEvent extends AbstractEvent {
The listing below summarizes some coding guidelines as illustrated in the example above:
- Events should only be created by event factories.
Constructors do not have any access specifier in order to make the class package private.
Constructors do not have any access specifier in order to make the class package private.
- The serialization of the payload into a data transfer object (e.g. `SunriseDTO`) should be part of the event factory and will be assigned to a class member via the constructor.
- A public member `TYPE` represents the event type as string representation and is usually the name of the class.
- The `toString()` method should deliver a meaningful string since it is used for event logging.
@ -328,14 +330,14 @@ public class SunEventFactory extends AbstractEventFactory {
The listing below summarizes some guidelines as illustrated in the example above:
- Provide the supported event types (`SunriseEvent.TYPE`) via an `AbstractEventFactory` constructor call.
The supported event types will be returned by the `AbstractEventFactory.getSupportedEventTypes()` method.
The supported event types will be returned by the `AbstractEventFactory.getSupportedEventTypes()` method.
- The event factory defines the topic (`SUNRISE_EVENT_TOPIC`) of the supported event types.
Please ensure that the topic format follows the topic structure of the openHAB core events, similar to a REST URI (`{namespace}/{entityType}/{entity}/{sub-entity-1}/.../{sub-entity-n}/{action}`).
The namespace must be `openhab`.
Please ensure that the topic format follows the topic structure of the openHAB core events, similar to a REST URI (`{namespace}/{entityType}/{entity}/{sub-entity-1}/.../{sub-entity-n}/{action}`).
The namespace must be `openhab`.
- Implement the method `createEventByType(String eventType, String topic, String payload, String source)` to create a new event based on the topic and the payload, determined by the event type.
This method will be called by the framework in order to dispatch received events to the corresponding event subscribers.
If the payload is serialized with JSON, the method `deserializePayload(String payload, Class<T> classOfPayload)` can be used to deserialize the payload into a data transfer object.
This method will be called by the framework in order to dispatch received events to the corresponding event subscribers.
If the payload is serialized with JSON, the method `deserializePayload(String payload, Class<T> classOfPayload)` can be used to deserialize the payload into a data transfer object.
- Provide a static method to create event instances based on a domain object (Item, Thing, or in the example above `Sunrise`).
This method can be used by components in order to create events based on domain objects which should be sent by the EventPublisher.
If the data transfer object should be serialized into a JSON payload, the method `serializePayload(Object payloadObject)` can be used.
Custom event factories must be registered as an OSGi Service (eg. by using the @Component annotation) in order to receive the custom events.
This method can be used by components in order to create events based on domain objects which should be sent by the EventPublisher.
If the data transfer object should be serialized into a JSON payload, the method `serializePayload(Object payloadObject)` can be used.
Custom event factories must be registered as an OSGi Service (eg. by using the @Component annotation) in order to receive the custom events.

2
developers/utils/i18n.md
View File

@ -6,11 +6,13 @@ title: Internationalization
{% include base.html %}
# Internationalization
{:.no_toc}
In this chapter the openHAB support for internationalization is described.
{::options toc_levels="2,3"/}
- TOC
{:toc}

2
developers/utils/tools.md
View File

@ -23,7 +23,7 @@ The id is provided through a static method and can be retrieved through
The `NetworkAddressService` is an OSGi service that can be used like any other OSGi service by adding a service reference to it.
Its OSGi service name is `org.openhab.core.network`.
A user can configure his default network address via Paper UI under `Configuration -> System -> Network Settings`.
A user can configure his default network address via UI under `Settings -> Network Settings`.
One can obtain the configured address via the `getPrimaryIpv4HostAddress()` method on the service.
This service is useful for example in the `ThingHandlerFactory` or an `AudioSink` where one needs a specific IP address of the host system to provide something like a `callback` URL.

2
installation/docker.md
View File

@ -173,7 +173,7 @@ Note, always review the README on [Docker Hub](https://hub.docker.com/r/openhab/
- `-v /etc/timezone:/etc/timezone:ro` : ties the timezone of the container to the host's time zone, read only so the container cannot change the host's time zone
- `-v /opt/openhab/conf:/openhab/conf` : location of the conf folder for openHAB configurations (*Note:* you must create these folders on the host before running the container)
- `-v /opt/openhab/userdata:/openhab/userdata` : location for logs, cache, persistence databases, etc.
- `-v /opt/openhab/addons:/openhab/addons` : only needed if installing addons unavailable via PaperUI or the Karaf Console
- `-v /opt/openhab/addons:/openhab/addons` : only needed if installing addons unavailable via UI or the Karaf Console
- `-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

2
installation/linux.md
View File

@ -597,7 +597,7 @@ Your personal configuration will be retained on upgrades, but you should **stop
```bash
cd /opt/openhab
sudo sh -c "$(curl -fsSL https://raw.githubusercontent.com/openhab/openhab-distro/master/distributions/openhab/src/main/resources/bin/update)" -- 2.1.0
sudo sh -c "$(curl -fsSL https://raw.githubusercontent.com/openhab/openhab-distro/main/distributions/openhab/src/main/resources/bin/update)" -- 2.1.0
```
#### Uninstall

4
installation/macos.md
View File

@ -94,7 +94,7 @@ To exit, use '<ctrl-d>' or 'logout'.
openhab>
```
Without closing the terminal, open your favorite web browser and type the following URL: [http://localhost:8080](http://localhost:8080), you should see the openHAB welcome screen, and you're all set to [using openHAB]({{base}}/tutorial/first_steps.html).
Without closing the terminal, open your favorite web browser and type the following URL: `http://localhost:8080`, you should see the openHAB welcome screen, and you're all set to [using openHAB]({{base}}/tutorial/first_steps.html).
If you installed openHAB on a different device, replace localhost with the IP address of the device.
## Updating openHAB
@ -133,7 +133,7 @@ Assuming the openHAB directory is in `~/openhab` simply run the following comman
```shell
cd ~/openhab
sudo sh -c "$(curl -fsSL https://raw.githubusercontent.com/openhab/openhab-distro/master/distributions/openhab/src/main/resources/bin/update)" -- 2.1.0
sudo sh -c "$(curl -fsSL https://raw.githubusercontent.com/openhab/openhab-distro/main/distributions/openhab/src/main/resources/bin/update)" -- 2.1.0
```
## Backup and Restore

515
installation/openhabian.md
View File

@ -1,515 +0,0 @@
---
layout: documentation
title: openHABian
source: https://github.com/openhab/openhabian/blob/master/docs/openhabian.md
---
{% include base.html %}
<!-- Attention authors: Do not edit directly. Please add your changes to the source repository -->
::: tip TL;DR
Jump to [install instructions](#raspberry-pi-prepackaged-sd-card-image). But read the full docs before you ask for help !
:::
# openHABian - Hassle-free openHAB Setup
The Raspberry Pi and other small single-board computers are quite famous platforms for openHAB.
However, setting up a fully working Linux system with all recommended packages and openHAB recommendations is a **boring task**, takes a lot of time and **Linux newcomers** shouldn't need to worry about technical details like these.
<p style="text-align: center; font-size: 1.2em; font-style: italic;"><q>A home automation enthusiast doesn't have to be a Linux enthusiast!</q></p>
openHABian aims to provide a **self-configuring** Linux system setup specific to the needs of every openHAB user.
It provides:
* complete **SD-card images pre-configured with openHAB** for the Raspberry Pi line of SBCs
* The openHABian configuration tool to set up and configure openHAB and many related things on any Debian based system
#### Table of Contents
{::options toc_levels="2..3"/}
- TOC
{:toc}
## Features
Out of the box, the openHABian image provides
- Hassle-free setup without a display or keyboard, connected via Ethernet or [WiFi](#wifi-based-setup-notes)
- the latest stable version of openHAB
- Zulu Embedded OpenJDK Java 8, 11 or AdoptOpenJDK
- [openHABian Configuration Tool](#openhabian-configuration-tool) including updater functionality
- web based openHAB Log Viewer (based on [frontail](https://github.com/mthenw/frontail))
- Samba file sharing [pre-configured to use shares](https://www.openhab.org/docs/installation/linux.html#mounting-locally)
- Useful Linux packages pre-installed, including `vim, mc, screen, htop, ...`
- Login information screen, powered by [FireMotD](https://github.com/OutsideIT/FireMotD)
- Customized Bash shell experience, settings and openHAB syntax highlighting for [vim](https://github.com/cyberkov/openhab-vim) and [nano](https://github.com/airix1/openhabnano)
- [Mosquitto](https://mosquitto.org) MQTT broker
- the [InfluxDB](https://www.influxdata.com/) database to store home automation data and [Grafana](https://grafana.com/) to visualize it
- FIND, the [Framework for Internal Navigation and Discovery](https://www.internalpositioning.com/)
- [Tailscale](https://tailscale.com/blog/how-tailscale-works/) VPN and [WireGuard](https://www.wireguard.com/) for remote VPN access
The included **openHABian Configuration Tool** [`openhabian-config`](#openhabian-configuration-tool) provides the following optional settings and components:
![openHABian-config menu](images/openHABian-config.png)
- Switch openHAB versions 2 vs 3 and select the latest *Release*, *Milestone* or *Snapshot* [*unstable/SNAPSHOT* build](https://www.openhab.org/docs/installation/linux.html#changing-versions) version
- Install and Setup a [reverse proxy](security.html##running-openhab-behind-a-reverse-proxy) with password authentication and/or HTTPS access (incl. [Let's Encrypt](https://letsencrypt.org) certificate) for self-controlled remote access
- manually set up a WiFi connection
- Setup [Backup](#availability-and-backup) for your system
- Easily install and preconfigure [Optional Components](#optional-components) of your choice
- configure Raspberry Pi specific functions
- Prepare the serial port for the use with extension boards like RaZberry, Enocean Pi, ...
- Use ZRAM to mitigate SD card wearout due to excessive writes
- Move the system partition to an external USB stick or drive
... and much more
## Hardware
### Hardware recommendation
Let's put this first: our current recommendation is to get a RPi 4 with 2 or 4 GB,
a 3 A power supply and a 16 GB SD card.
Also get another 32 GB or larger SD card and a USB card reader to make use of the
["auto backup" feature](docs/openhabian.md#Auto-Backup).
::: warning ATTENTION
Avoid getting the 8 GB model of RPi 4. 8 GB are a waste of money and it has issues,
you must [disable ZRAM](https://github.com/openhab/openhabian/blob/master/docs/openhabian.md#disable-zram) or use the 64bit image (untested).
:::
### Hardware and OS support
As of openHABian version 1.6 and later, all Raspberry Pi models are supported as
hardware. Anything x86 based may work or not. Anything else ARM based such as ODroids,
OrangePis and the like may work or not. NAS servers such as QNAP and Synology
boxes will not work. Support for PINEA64 was dropped in this current release.<br>
We strongly recommend that users choose Raspberry Pi 2, 3 or 4 systems to have
1 GB of RAM or more. RPi 1 and 0/0W only have a single CPU core and 512 MB.
This can be sufficient to run a smallish openHAB setup, but it will
not be enough to run a full-blown system with many bindings and memory consuming
openHABian features/components such as ZRAM, InfluxDB or Grafana.
We do not actively prohibit installation on any hardware, including unsupported
systems, but we might skip or deny to install specific extensions such as those
memory hungry applications named above.
Supporting hardware means testing every single patch and every release. There
are simply too many combinations of SBCs, peripherals and OS flavors that
maintainers do not have available, or, even if they did, the time to spend on
the testing efforts that is required to make openHABian a reliable system.
Let's make sure you understand the implications of these statements: it means
that to run on hardware other than RPi 2/3/4 or (bare metal i.e. not virtualized)
x86 may work but this is **not** supported.
It may work to install and run openHABian on unsupported hardware. If it does
not, you are welcome to find out what's missing and contribute it back to
the community with a Pull Request. It is sometimes simple things like a naming
string. We'll be happy to include that in openHABian so you can use your box
with openHABian unless there's a valid reason to change or remove it.
However, that does not make your box a "supported" one as we don't have it
available for our further development and testing. So there remains a risk that
future openHABian releases will fail to work on your SBC because we changed a
thing that broke support for your HW - unintentionally so however inevitable.
For ARM hardware that we don't support, you can try any of the [fake hardware parameters](openhabian.md/#fake-hardware-mode)
to 'simulate' RPi hardware and Raspi OS. If that still doesn't work for
you, give [Ubuntu](https://ubuntu.com/download/iot) or [ARMbian](https://www.armbian.com/) a try.
Going beyond what the RPi image provides, as a manually installed set of
scripts, we support running openHABian on x86 hardware on generic Debian.
On ARM, we only support Raspberry Pi OS.
These are what we develop and test openHABian against.
We do **not** actively **support Ubuntu** so no promises but we provide code
"as-is" that is known to run on there. Several optional components though,
such as WireGuard or Homegear, are known to expose problems.
We expect you to use the current stable distribution, 'buster' for Raspberry
Pi OS (ARM) and Debian (x86) and 'focal' for Ubuntu (x86) this is.
To install openHABian on anything older or newer may work or not. If you
encounter issues, you may need to upgrade first or to live with the consequences
of running an OS on the edge of software development.
Either way, please note that you're on your own when it comes to configuring and
installing the HW with the proper OS yourself.
### 64 bit ?
RPi3 and 4 have a 64 bit processor and you may want to run openHAB in 64 bit.
We provide a 64bit version of the image but it is unsupported so use it at your
own risk. Please don't ask for support if it does not work for you.
It's just provided as-is.
Be aware that to run in 64 bit has a major drawback: increased memory usage.
That is not a good idea on a heavily memory constrained platform like a RPi.
Also remember openHABian makes use of Raspberry Pi OS which as per today still
is a 32 bit OS.
We are closely observing development and will adapt openHABian once it will
reliably work on 64 bit.<br/>
On x86 hardware, 64 bit is the standard.
## Raspberry Pi prepackaged SD card image
**Flash, plug, wait, enjoy:**
The provided image is based on the [Raspberry Pi OS Lite](https://www.raspberrypi.org/software/operating-systems/#raspberry-pi-os-32-bit) (previously called Raspbian) standard system.
On first boot, the system will set up openHAB and the mentioned settings and tools.
All packages will be downloaded in their newest version and configured to work without further modifications.
The whole process will take a few minutes, then openHAB and all other needed tools to get started will be ready to use without further configuration steps.
openHABian is designed as a headless system, you will not need a display or a keyboard.
**Setup:**
- [Download the latest "openHABian" SD card image file](https://github.com/openhab/openhabian/releases) (Note: the file is *xz* compressed)
- Write the image to your SD card (e.g. with [Etcher](https://www.balena.io/etcher/) or official [Raspberry Pi Imager](https://www.raspberrypi.org/software/), both able to directly work with *xz* files
- Insert the SD card into your Raspberry Pi, connect Ethernet ([WiFi also supported](#wifi-based-setup-notes)) and power on.
- Wait approximately **15-45 minutes** for openHABian to do its magic. <br>(You can check the progress in your web-browser [here](http://openhabiandevice).)
- Enjoy!
- The device will be accessible by its IP or via the local DNS name `openhabiandevice` (or whatever you changed 'hostname' in `openhabian.conf` to)
- Connect to the openHAB UI at [http://openhabiandevice:8080](http://openhabiandevice:8080)
- [Connect to the Samba network shares](https://www.openhab.org/docs/installation/linux.html#mounting-locally) with username `openhabian` and password `openhabian`
- Connect to the openHAB Log Viewer (frontail): [http://openhabiandevice:9001](http://openhabiandevice:9001)
- If you encounter any setup problem, [please continue here](#successful)
You can stop reading now, openHABian has installed and configured your openHAB system and you can start to use it right away.
If you want to get in touch with the system or want to install one of the previously mentioned optional features, come back here later.
Ready for more?
[Connect to your Raspberry Pi SSH console](https://www.raspberrypi.org/documentation/remote-access/ssh/windows.md) using the username `openhabian` and password `openhabian`.
You will see the following welcome screen:
![openHABian login screen](images/openHABian-SSH-MotD.png)
➜ Continue at the ["openHABian Configuration Tool"](#openhabian-configuration-tool) chapter below!
<a id="manual-setup"></a>
### Other Linux Systems (add openHABian just like any other software)
Going beyond what the RPi image provides, you can also openHABian on x86 hardware on top of any existing Debian installation.
Please note that the unattended install is tailored to work for Raspberries. We cannot test HW/OS combos beyond RPis upfront so there is no promise for this work.
See the [Hardware and OS section](#hardware-and-os-support) for details on supported hardware and OSs before you proceed.
Note that although the core parts of openHABian were reported to work on there, Ubuntu is not supported and untested.
If you try and fail, please help and drop us a note on Github with debug log enabled, see [DEBUG guide](openhabian-DEBUG.md).
***
Start with a fresh installation of your operating system, login and run
```shell
# start shell as root user
sudo bash
```
then start installation
```shell
# install git - you can skip this if it's already installed
apt-get update
apt-get install git
# download, link and create config file
git clone -b openHAB3 https://github.com/openhab/openhabian.git /opt/openhabian
ln -s /opt/openhabian/openhabian-setup.sh /usr/local/bin/openhabian-config
cp /opt/openhabian/openhabian.conf.dist /etc/openhabian.conf
```
Edit `/etc/openhabian.conf` to match your needs, then finally use
```shell
openhabian-config unattended
```
to install.
#### Interactive install on generic x86 Linux
We strongly recommend you to use the automated install but you actually *can* walk through the interactive tool.
Start `openhabian-config`.
Get the bare minimum you will *need* installed by selecting menu option 03.
To install the recommended components that automated install will get in one go select menu options 33, 32, 31, 11, 12, 15, Zulu 11 OpenJDK 64-bit (in menu 4X), 13, 16, 14, 21, 38, 53, 52.
We try to make install options independent of each other but there may be dependencies we are not aware of left so any other order may or may not work.
➜ Continue at the ["openHABian Configuration Tool"](#openhabian-configuration-tool) chapter below
## openHABian Configuration Tool
The following instructions are developed for a Raspberry Pi but should be applicable to all hardware / all openHABian environments.
Once connected to the command line console of your system, please execute the openHABian configuration tool by typing the following command:
(Hint: sudo executes a command with elevated rights and will hence ask for your password: `openhabian`).
```shell
sudo openhabian-config
```
![openHABian-config menu](images/openHABian-config.png)
The configuration tool is the heart of openHABian.
It is not only a menu with a set of options, it's also used in a special unattended mode to automate the setup run, either as part of the RPi image or in a manual install run.
⌨ - A quick note on menu navigation.
Use the cursor keys to navigate, <kbd>Enter</kbd> to execute, <kbd>Space</kbd> to select and <kbd>Tab</kbd> to jump to the actions on the bottom of the screen. Press <kbd>Esc</kbd> twice to exit the configuration tool.
### Linux Hints
Many helpful articles can be found on the internet, for example:
- "Learn the ways of Linux-fu, for free" interactively with exercises at [linuxjourney.com](https://linuxjourney.com).
- The official Raspberry Pi help articles over at [raspberrypi.org](https://www.raspberrypi.org/help)
- "Now what?", Tutorial on the Command line console at [LinuxCommand.org](http://linuxcommand.org/index.php)
*The good news:* openHABian helps you to stay away from Linux - *The bad news:* not for long...
Regardless of if you want to copy some files or are on the search for a solution to a problem, sooner or later you'll have to know some Linux.
Take a few minutes to study the above Tutorials and get to know the most basic commands and tools to be able to navigate on your Linux system, edit configurations, check the system state or look at log files.
It's not complicated and something that doesn't hurt on one's résumé.
### First steps with openHAB
After your first setup of openHABian is successful and you are able to access the openHAB dashboard, you should dig into the possibilites.
Install [Bindings](https://www.openhab.org/addons/), discover your devices, and [configure your smart home](https://www.openhab.org/docs/configuration/).
You might want to start defining [Items](https://www.openhab.org/docs/configuration/items.html), [Sitemap](https://www.openhab.org/docs/configuration/sitemaps.html) and [HABPanel](https://www.openhab.org/docs/configuration/habpanel.html) dashboard for your home, but these are just some first hints.
Be sure to read up on the [Configuration](https://www.openhab.org/docs/configuration/) section of the documentation pages to learn more.
### Further configuration steps
openHABian is supposed to provide a ready-to-use openHAB base system.
There are a few things, however, we need you to decide and act on right now at the beginning:
- **Delayed Rules loading** openHAB startup times can be annoyingly long. There's an optimization available that *delays* loading the rules. It quickly renames rules forth and back after 2 minutes, *effectively speeding up* openHAB startup. This is setup by default, you can disable this via \[menu option: 44\].
- **Timezone:** The time zone of your openHABian system will be determined based on your internet connection. In some cases you might have to adjust that setting.
- **Language:** The `locale` setting of the openHABian base system is set to "en_US.UTF-8". While this setting will not do any harm, you might prefer e.g. console errors in German or Spanish. Change the locale settings accordingly. Be aware, that error solving might be easier when using the English error messages as search phrases.
- **Passwords:** Relying on default passwords is a security concern you should care about! The openHABian system is preconfigured with a few passwords you should change to ensure the security of your system. This is especially important if your system is accessible from outside your private subnet.
All of these settings can be changed via the openHABian configuration tool.
Here are the passwords in question with their respective default "username:password" values.
They can be changed from openHABian menu.
### Passwords
- User password needed for SSH or sudo (e.g. "openhabian:openhabian")
- Samba share password (e.g. "openhabian:openhabian")
- openHAB remote console (e.g. "openhab:habopen")
- Amanda backup password (no default, applied when installing)
- Nginx reverse proxy login (no default, applied when installing) *For manual configuration see [here](https://www.openhab.org/docs/installation/security.html#adding-or-removing-users).*
- InfluxDB (No password set by default)
- Grafana visualization ("admin:admin")
## Availability and Backup
openHAB is designed to reliably run 24 hours a day, seven days a week - and so should be your server.
This is the right time to prepare your system for disasters such as getting hit by the SD card wearout/corruption problem which is quite common among users of single board computers such as Raspberry Pis. openHABian has a number of features built in to enhance resilience:
1. the ZRAM feature moves write intensive parts of openHABian into RAM to mitigate the risk of SD card corruption. See [community thread](https://community.openhab.org/t/zram-status/80996) for more up to date information.
WARNING: power failure will result in some data to get lost (albeit the system should continue to run). Get an UPS.
ZRAM is enabled by default for swap, logs and persistence data. You can toggle use in \[menu option 38\].
2. Move the root filesystem to USB-attached memory. WARNING: USB sticks are as susceptible to flash wearout as SD cards are, making ZRAM the better choice for a standard Pi to run off its internal SD card. But you can use this option to migrate your system to a safe medium such as an SSD or HDD. \[menu option 37\]
3. Use the openHAB integrated [openhab-cli tool](https://community.openhab.org/t/recommended-way-to-backup-restore-oh2-configurations-and-things/7193/82) to interactively backup/restore your openHAB **config** \[menu option 50/51\].
4. Use [Amanda Network Backup](http://www.amanda.org/) for full system backups, documentation [here](https://github.com/openhab/openhabian/blob/master/docs/openhabian-amanda.md). \[menu option 52\]
Standard openHABian install enables ZRAM by default (#1). Once you attach a *safe* external medium to your system (such as an SSD), you can disable ZRAM (#1) and move the system over using menu options 37 (#2).
Finally, we strongly suggest you install Amanda (#4) right after you finish your setup. Amanda is to take care to backup the whole system to be able to quickly restore it when in need.
This is not done by default because it requires a number of user inputs, but you should not skip it for your own safety !
`Delayed rules load` will be enabled by default in openHAB 2 but disabled in openHAB 3 (which has a new startlevel system).
This function will rename the rules files so they get ignored by the starting openHAB instance, then after 2 minutes they're renamed back. You can toggle to use this feature in menu option 44.
## Setup notes
### On openHAB3
Starting with its general release, openHABian will install **openHAB 3** by default.
There's some big changes also to openHABian such as to install Java 11 and to use changed file and directory names.
Most directory names `... /openhab2/ ...` will become `... /openhab/ ...` (NOTE: not `openhab3`) plus there's changes in a number of places, often subtle ones like the name of Samba export shares to change.
As openHABian users will be running openHAB 2.X by the time 3.0 gets released, `openhabian-config` offers to migrate the openHABian environment and install openHAB3 for you.
Menu option 42 will do the upgrade. Be aware that it isn't the universal answer to all your migration needs - there is ONLY an openHAB upgrade path. You cannot downgrade from OH3 to OH2.
::: warning No downgrades
Take an openHAB config backup BEFORE you upgrade from openHAB v2 to v3. You should also take a system level backup !
:::
Menu option 42 can also do the downgrade and change the environment back to match openHAB 2 **BUT** it'll ONLY exchange the binary packages. There is no migration to change your configuration back to a OH2 compatible one. So it is essential that you take a backup before you upgrade. You will have to restore your setup from that backup after a downgrade using menu option 51 or by manually using `openhab-cli restore <archive file>`.
Note option 42 will also not downgrade Java. openHAB 2 however is known to run with Zulu Java 11 as well.
### `openhabian.conf`
You can actually set a number of parameters _before_ you run an unattended installation. This applies to the RPi image on an SD card as well as to a manual installation.
You can also try with a different set of parameters if your initial attempt fails:
- Flash the system image to your micro SD card as described, do not remove the SD card yet
- Access the first SD card partition. It's a vfat/FAT-32 (Windows) filesystem so just use the file explorer of your client PC.
- Open the file `openhabian.conf` in a text editor
- Uncomment and complete the lines to contain the parameters you want to set
- Save, unmount/eject, remove and insert into the RPi and boot it
- Continue with the instructions for your hardware
Mind the comments for each configuration parameter. Browse the next documentation section for more explanations.
#### Administration user
Raspberry Pi OS images include a Linux user (`pi`) that you can use for openHAB administration.
openHABian renames the user to what you specify in the `username` parameter and assigns the `userpw` password first, then it proceeds and makes various settings that are either useful (such as some aliases) or required to run openHAB.
You can also make use of this if you don't use the image but unattended installation on non-RPi hardware, openHABian will then _create_ that user for you if it does not yet exist.
#### admin key
Make the `adminkeyurl` point to an URL to contain a public SSH key. This will be included with your administration
user's `.ssh/authorized_keys` and the openHAB console so the admin user (yourself, usually) can login after installation.
#### WiFi based setup notes
If you own a RPi3, RPi3+, RPi4, a RPi0W or any other model with a compatible WiFi dongle you can set up and use openHABian via WiFi only.
For the WiFi based setup to work, you'll need to make your SSID and password known to the system before the first boot.
So in addition to the setup instructions given above, uncomment and complete the lines reading `wifi_ssid=""` and `wifi_psk=""` in `openhabian.conf`.
#### WiFi Hotspot
Whenever the WiFi interface wlan0 exists but does not have connectivity, openHABian will launch a **Hotspot**.
When you use your mobile phone to scan for WiFi networks, you should be seeing a new network called `openHABian-<n>`.
Connecting will work without a password. Once connected, open your browser and point it at `http://raspberrypi.local` or `http://comitup-<n>`.
This may or may not work for your mobile browser as it requires Bonjour/ZeroConf abilities. If you cannot connect to this address, go to `http://10.41.0.1`.
On that page you can select the SSID of the network you want to connect your system to. Provide the password and press the button.
Note that as soon as you do, the wlan0 IP address changes so your mobile browser will not be able to provide you any feedback if that worked out.
Try to ping the new system's hostname (default is `openHABianDevice`) or check DHCP on your router if your openHABian system appeared there.
For more information on this feature see [comitup-cli](https://davesteele.github.io/comitup/).
You can use `sudo comitup-cli` inside openHABian to change networks and eventually remove network credentials.
Note the hotspot may not only become available during installation: it will remain on standby and will show up again every time your `wlan0` interface is losing connectivity.
The hotspot feature is known to work on RPi 0W, 3 and 4 but is known to often expose problems with WiFi USB adapters.
#### Disable ZRAM
ZRAM is activated by default on fresh installations on ARM hardware except on a 8GB RPi4 as that is known to be incompatible at the time of writing, leading to kernel crashes.
If you want to disable ZRAM for a different reason, use `zraminstall=disable` in `openhabian.conf` to install without.
#### Debug mode
See [Troubleshooting](#troubleshooting) section if you run into trouble installing. If you want to turn on debug mode,
edit `openhabian.conf` and set the `debugmode=` parameter to either `off`, `on` or `maximum`.
Mind you that if you intend to open an issue, we need you to provide the output of `debugmode=maximum` so if you're in interactive mode, set your terminal to record output.
#### Auto-backup
You might want to setup openHABian to automatically backup and mirror your internal SD card to an external unit.
We suggest to use another SD card in an external card writer device so that in case your internal SD card fails,
you can switch SD cards to get the system back up running fast.
Note most "16GB" cards are not _exactly_ 16 GB and your new one mustn't have less bytes than the old one so
openHABian enforces the second card to have at least twice the size of your internal card.
We make use of that extra space as storage for the backup system.
To setup right at installation time:
Define `backupdrive=/dev/sdX` (replace X with the proper character) to enable this functionality right during unattended installation.
Eventually change `storagedir=/storage` to any other name.
The first attached disk type device is usually called `/dev/sda`.
openHABian will create partitions 1 and 2 to be mirrors of your internal card and will assign the remaining space
to a storage partition.
Full mirroring will take place semiannually and for the 2nd partition (Linux root), changes will be synced once a week.
See `systemctl list-timers`, timers are defined in `/etc/systemd/system/sd*.timer`.
The unattended install routine will also setup Amanda to take daily backups and store them to that third partition.
Use `storagecapacity=xxx` to override how much space to consume at most for Amanda backup storage (in MB).
If you choose to skip this during system installation, you can still setup both, mirroring and Amanda, at
any later time using the 5X menu options.
Menu 5X provides interactive access to the aforementioned functions:
`53 Setup SD monitoring` prepares the partitions on an SD card and sets up timers to execute both, a full mirroring
and complementary rsync 'diff' runs in a backup schedule.
`54 Raw copy SD` is a one-time raw copy (mirror) run.
`55 Sync SD` proagates (syncs) differences from your main SD card to your external card.
Should you need to switch over to your backup card, get a another new SD card to match the size of the broken card and use menu option 54 to copy your active backup card back to the new one and switch cards back as soon as possible.
#### Tailscale VPN network
Tailscale is a management toolset to establish a WireGuard based VPN between multiple systems if you want
to connect to openHAB(ian) instances outside your LAN over Internet.
It'll take care to detect and open ports when you and your peers are located behind firewalls.
[Download the client](https://tailscale.com/download) and eventually get the Solo service plan from Tailscale,
that's free for private use. This free service will automatically be selected when you fire up your first VPN node.
The Windows client has a link to the admin console where you can create pre-auth one-time keys. These you can put
as the `preauthkey` into `openhabian.conf` to automatically deploy remote openHABian nodes (unattended install)
and have them join the VPN.
#### IPv6 notes
You might encounter problems when you make use of IPv6 on some networks and systems. openHABian installation may stop or hang forever.
In that case *or if you are sure that you do not need IPv6 on your openHABian server*, you can disable IPv6.
Follow the instructions in the previous section and insert a line into `openhabian.conf` reading `ipv6=disable`.
#### Fake hardware mode
If to install openHABian fails because you have a non-supported hardware or run an unsupported OS release, you can "fake" your hardware and OS to make openHABian behave as if you did own that HW/OS.
In `openhabian.conf`, uncomment and complete the lines reading `hw=`, `hwarch=` and/or `osrelease=` with the hw and os versions you want to attempt installation with.
## Optional Components
openHABian comes with a number of additional routines to quickly install and set up home automation related software.
You'll find all of these in the [openHABian Configuration Tool](#openhabian-configuration-tool)
- [Frontail](https://github.com/mthenw/frontail) - openHAB Log Viewer accessible from [http://openhab:9001](http://openhab:9001)
- [InfluxDB and Grafana](https://community.openhab.org/t/influxdb-grafana-persistence-and-graphing/13761/1) - persistence and graphing available from [http://openhab:3000](http://openhab:3000)
- [Eclipse Mosquitto](http://mosquitto.org) - Open Source MQTT v3.1/v3.1.1 Broker
- [Node-RED](https://nodered.org) - "Flow-based programming for the Internet of Things". Access at [http://openhab:1880](http://openhab:1880).
- [Homegear](https://www.homegear.eu/index.php/Main_Page) - Homematic control unit emulation
- [KNXd](http://michlstechblog.info/blog/raspberry-pi-eibknx-ip-gateway-and-router-with-knxd) - KNX daemon running at `224.0.23.12:3671/UDP`
- [OWServer](http://owfs.org/index.php?page=owserver_protocol) - 1wire control system
- [FIND](https://www.internalpositioning.com/) - the Framework for Internal Navigation and Discovery
- Mi Flora MQTT demon
- Tellstick core
## Troubleshooting
If you're having problems to get openHABian to install properly, check out the [debug guide](openhabian-DEBUG.md). It's also available on your system as `/opt/openhabian/docs/openhabian-DEBUG.md`.
Do not hesitate to ask for help on the [openHABian community forum](https://community.openhab.org/) when the debug guide doesn't help.
Remember to [mind the rules](https://community.openhab.org/t/how-to-ask-a-good-question-help-us-help-you/58396) please.
If you want to get involved, you found a bug, or just want to see what's planned for the future, visit us on GitHub:
- [https://github.com/openhab/openhabian/](https://github.com/openhab/openhabian/)
<a id="changelog"></a>
### Where can I find a changelog for openHABian?
Official announcements are co-located with the download links [here](https://github.com/openhab/openhabian/releases).
If you want to stay in touch with all the latest code changes under the hood, see [commit history](https://github.com/openhab/openhabian/commits/master) for openHABian.
You'll also see commits "fly by" when executing the "Update" function within the openHABian Configuration Tool.
<a id="successful"></a>
### Did my Installation succeed? What to do in case of a problem?
Don't panic ;-)
openHABian setup will take 15 up to 45 minutes to complete all steps, depending on your device's performance and a number of external factors such as your internet connection.
Watch the progress on the console or the web interface at https://<yourip>/ or <http://openhabiandevice/> if that name has become available.
Double-check the IP address and name with your router while you wait.
If there is absolutely no output for more than 10 minutes, your installation has failed in the first initialization phase. There probably is a problem
with the way your router or local network are setup.
Read on in the [Troubleshooting](#troubleshooting) section or move on to the [DEBUG guide](openhabian-DEBUG.md).
You can set `debugmode=on` (or even = `maximum`) right on first install, too, to get to see what openHABian is doing.
After a few minutes of boot up time, you can [connect to the SSH console](https://www.raspberrypi.org/documentation/remote-access/ssh/windows.md) of your device.
During the setup process you'll be redirected to the live progress report of the setup (you can Ctrl-C to get into the shell).
The report can also be checked for errors at any time, see `/boot/first-boot.log`
The progress of a successful installation will look like this:
![openHABian installation log](images/openHABian-install-log.png)
Wait till the log tells you that the setup was "successful", then reconnect to the device.
#### SSH Login Screen
If the installation was **successful** you will see the normal login screen as shown in the first screenshot.
If the installation was **not successful** you will see a warning and further instructions as shown in the second screenshot.
<div class="row">
<div class="col s12 m5"><img src="images/openHABian-SSH-MotD.png" alt="openHABian installation successful" title="openHABian installation successful"></div>
<div class="col s12 m5 offset-m2"><img src="images/openHABian-install-failed.png" alt="openHABian installation failed warning and instructions" title="openHABian installation failed warning and instructions"></div>
</div>
#### openHAB Dashboard
After the installation of openHABian was successful, you should be able to access the openHAB dashboard:
- Raspberry Pi image setup: [http://openhab:8080](http://openhab:8080)
- In any case: [http://your-device-hostname:8080](http://your-device-hostname:8080) or [http://192.168.0.2:8080](http://192.168.0.2:8080) (replace name/IP with yours)
#### What's next?
If you are not able to access your system via the openHAB dashboard or SSH after more than one hour, chances are high that your hardware setup is the problem. Consult the [debug guide](openhabian-DEBUG.md) and move on from there.
<a id="switch-openhab-branch"></a>
#### Can I switch openHAB 2 and 3 via openHABian branches ?
openHABian installs the latest stable build of openHAB.
The standard openHABian `stable` and `master` branches will install openHAB version 2 and the `openHAB3` branch will install the new openHAB version 3.
You can migrate between versions by selecting the corresponding 4X menu option. That should also result in an openHABian branch change.
If you want to choose from stable, snapshot or milestone releases, please do so via `openhabian-config` tool (also menu 4X).
Note this will **not** result in any openHABian branch change.
Switching from stable to newer development releases might introduce changes and incompatibilities, so please be sure to make a full openHAB backup first!
Check the Linux installation article for all needed details: [Linux: Changing Versions](linux.html#changing-versions)
<a id="headache"></a>
#### Where is the graphical user interface?
I've just installed openHABian and now I'm confused.
No fancy login screen, no windows, no mouse support. What did I get into?
You are not the first one to get confused about the **intended use case of openHABian**.
Maybe it helps to not think of the RPi as a PC as we know it.
An RPi is not (well, not *necessarily*) to be used with a keyboard and display.
Its intended use case is to sit in a corner and provide a service reliably 24 hours a day, 7 days a week.
You already own a **powerful PC or Mac** to work on.
It would be a shame to have a powerful computer at your fingertips and then have to **restrict yourself** to a very limited graphical frontend on another device, wouldn't you agree?
What we actually want openHABian to be is a **dedicated, headless system** to **reliably run openHAB** and to **expose all interfaces** needed to interact and configure it (MainUI, HABPanel, openHAB LogViewer, Samba Network Shares, openHABian Configuration Tool, SSH, you-name-it).
If you know how to work with these interfaces, you are set for a way better experience than the alternatives.
The main challenge is to **get used to the Linux command line**, not even a GUI (like Pixel, see below) will relieve you from that in the long run.
If you are not willing to teach yourself a few fundamental Linux skills you will not become happy with any Linux system and should resort to a e.g. Windows machine.
However as you are willing to tinker with smart home technology, I'm sure you are ready to **teach yourself new stuff** and expand your experience.
<a id="faq-other-platforms"></a>
#### Can I use openHABian on ...?
See the [README](https://github.com/openhab/openhabian/blob/master/README.md#hardware-and-os-support) for a list of supported HW and OS.
openHABian is developed for Debian based systems.
If your operating system is based on these or if your hardware supports one, your chances are high openHABian can be used.
Check out the [Manual Setup](#manual-setup) instructions for guidance and consult the [debug guide](openhabian-DEBUG.md) if you run into problems.
Do not hesitate to ask for help on the [openHABian community forum](https://community.openhab.org/) !

10
installation/qnap.md
View File

@ -10,8 +10,6 @@ title: QNAP NAS
The [QNAP NAS](https://www.qnap.com) is a NAS server solution for your home, allowing the installation of additional packages.
Please find all details about the openHAB package for QNAP [here](https://github.com/openhab/openhab-qnap-qpkg).
![AppCenter enabled](https://github.com/openhab/openhab-qnap-qpkg/raw/master/docs/QTS_4.2.0_AppCenter%20enabled.png)
## How to install
Check that your NAS has the most recent firmware version.
@ -29,20 +27,18 @@ Follow the instructions shown if a new version is announced when opening the adm
1. Open the "Install manually" dialog in the App Center by clicking the gear-wheel on the upper-right corner of the App Center and choose the `qpkg` you have downloaded.
![AppCenter choose](https://github.com/openhab/openhab-qnap-qpkg/raw/master/docs/QTS_4.2.0_AppCenter%20choose.png)
![AppCenter choose](https://raw.githubusercontent.com/openhab/openhab-qnap-qpkg/main/docs/QTS_4.2.0_AppCenter%20choose.png)
1. Confirm the installation
![AppCenter confirm](https://github.com/openhab/openhab-qnap-qpkg/raw/master/docs/QTS_4.2.0_AppCenter%20confirm.png)
![AppCenter confirm](https://raw.githubusercontent.com/openhab/openhab-qnap-qpkg/main/docs/QTS_4.2.0_AppCenter%20confirm.png)
1. Wait while the package is being installed
![AppCenter installing](https://github.com/openhab/openhab-qnap-qpkg/raw/master/docs/QTS_4.2.0_AppCenter%20installing.png)
1. When finished just close the dialog and wait for a while until openHAB has completely started.
This may take several minutes.
![AppCenter finished](https://github.com/openhab/openhab-qnap-qpkg/raw/master/docs/QTS_4.2.0_AppCenter%20finished.png)
![AppCenter finished](https://raw.githubusercontent.com/openhab/openhab-qnap-qpkg/main/docs/QTS_4.2.0_AppCenter%20finished.png)
1. Access openHAB via `http://NAS_IP_or_DNS_address:8090`.
If the interface does not start, retry after another minute.

2
installation/rasppi.md
View File

@ -244,7 +244,7 @@ sudo systemctl enable openhab.service
You are all set.
## What next?
## What next ?
You can:

4
installation/security.md
View File

@ -62,7 +62,7 @@ There are many different solutions for VPN, so we cannot give any specific advic
### myopenHAB Cloud Service
You can use an [openHAB Cloud](https://github.com/openhab/openhab-cloud/blob/master/README.md) instance to which openHAB creates a tunnel connection and which forwards all requests through this tunnel.
You can use an [openHAB Cloud](https://github.com/openhab/openhab-cloud/blob/main/README.md) instance to which openHAB creates a tunnel connection and which forwards all requests through this tunnel.
openHAB will see these incoming requests as originating from the local loopback interface.
The simplest way to get hold of such an openHAB Cloud is to register an account at [myopenHAB.org](https://www.myopenhab.org/), which is operated by the [openHAB Foundation](https://www.openhabfoundation.org/).
@ -604,7 +604,7 @@ Back in the GUI, go to Control Panel > Application Portal > Reverse Proxy, make
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.
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:

31
installation/windows.md
View File

@ -82,8 +82,8 @@ By installing the openHAB process as a service in Windows, you can:
1. Update the newly created `C:\openHAB\userdata\etc\openHAB-wrapper.conf` to include all necessary parameters:
- Copy all the config text from the below section and paste it in your `openHAB-wrapper.conf`, replacing all existing content.
- Adapt the first entry (`OPENHAB_HOME`) to match your openHAB installation directory.
1. Copy all the config text from the below section and paste it in your `openHAB-wrapper.conf`, replacing all existing content.
1. Adapt the first entry (`OPENHAB_HOME`) to match your openHAB installation directory.
```conf
#*******************************************************
@ -166,16 +166,12 @@ By installing the openHAB process as a service in Windows, you can:
![Wrapper_Start_Windows](images/Wrapper_Start_Windows.jpg)
1. Your openHAB Windows service is now installed and running.
Validate proper operations by:
- Browsing to [http://localhost:8080](http://localhost:8080)
Validate proper operations by browsing to `http://localhost:8080` and verifying that the Windows Service is running and set to Automatic Startup type.
Use `services.msc` and find the `openHAB` service.
Or by logging in with an SSH client to the console (see info below)
- Verifying that the Windows Service is running and set to Automatic Startup type.
Use `services.msc` and find the `openHAB` service.
![Windows Service](images/Windows_Service.jpg)
- Logging in with an SSH client to the console (see info below)
![Windows Service](images/Windows_Service.jpg)
### File Locations
@ -235,13 +231,16 @@ C:\openHAB\userdata\bin\openHAB-service.bat remove
You can connect to openHAB's console using the the `C:\openHAB\runtime\bin\client.bat` script on the local machine.
Alternatively, you can use a standard SSH client:
- Install an SSH client application, e.g., [Putty](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html), [KiTTY](http://kitty.9bis.net/) or [Xshell 5](https://www.netsarang.com/products/xsh_overview.html)
1. Install an SSH client application, e.g., [Putty](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html), [KiTTY](http://kitty.9bis.net/) or [Xshell 5](https://www.netsarang.com/products/xsh_overview.html)
- Setup a session with the following parameters:
- Host: 127.0.0.1
- Port: 8101
- Username: `openhab`
- Password: `habopen`
1. Setup a session with the following parameters:
```text
Host: 127.0.0.1
Port: 8101
Username: openhab
Password: habopen
```
![SSH Connection 1](images/SSH_Connection_1.jpg)

6
introduction.md
View File

@ -20,7 +20,11 @@ h1.welcome {
<img src="/openhab-logo-square.png" width="150" height="150" class="intro-logo" />
<h1 class="welcome">Welcome!</h1>
<h1 class="welcome">
# Welcome!
</h1>
The **open H**ome **A**utomation **B**us (openHAB, *pronounced ˈəʊpənˈhæb*) is an open source, technology agnostic home automation platform which runs as the center of your smart home!

10
tutorials/getting_started/first_steps.md
View File

@ -17,7 +17,7 @@ The following instructions will guide you through the initial steps after first
## Create the Admin User
Once openHAB is installed and started, launch the user interface by navigating to `http://localhost:8080` (if not running locally, replace localhost with the server's address or hostname accordingly).
If you installed from the openHABian image, you can use `http://openhab:8080`.
If you installed from the openHABian image, you can use `http://openhabianpi:8080`.
By default, the administration pages can only be accessed if you are logged in with an administrator account.
Since there are no users yet, openHAB will ask you to create an administrator account.
@ -61,16 +61,18 @@ You can also set your preferred measurement system (openHAB defaults to the Metr
### Set your geographic location (latitude and longitude) and measurement system
1. In the left-hand menu under Administration, select Settings to open the Settings page.
![initial settings](images/initial_settings.png)
![initial settings](images/initial_settings.png)
1. Under System Settings, select Regional Settings.
![regional settings](images/regional_settings.png)
![regional settings](images/regional_settings.png)
1. Under Location, click the Map button to add your geographic coordinates.
1. If you also want to set your measurement system, click "Show advanced" and choose between Metric and Imperial.
![unit settings](images/units_settings.png)
![unit settings](images/units_settings.png)
## Additional Settings

8
tutorials/getting_started/index.md
View File

@ -5,7 +5,7 @@ title: Getting Started - Introduction
{% include base.html %}
# Welcome!
# Welcome
Welcome to openHAB.
We hope that your journey with openHAB is a rewarding one.
@ -30,7 +30,9 @@ Whilst it is possible to mix the two, for example use the UI for things and file
To help you choose between the two approaches, the following is a summary of the pros & cons for each:
### File-based
Pros:
- File based has been the only really practical way to define most objects (things excluded) in previous versions, so a lot of examples in the docs and the forum will assume that approach. However, as time passes there will be more and more UI driven examples.
- With file based configs it is easier to make bulk changes and bulk updates, to duplicate similar objects, and to separate domains into distinct files.
- The config files can be treated as source files, easing backups and version control. Though that does not mean that source control, backups, and version control cannot be done with UI driven configs.
@ -38,13 +40,16 @@ Pros:
- Easier to share configurations between multiple openHAB instances.
Cons:
- Config files are more prone to errors. The slightest typo leads to a syntax error that could cause the file to become invalid, which will result in everything defined in that file being removed from the system until you fix it.
- The syntax for the config files can be a little overwhelming for novice users, as you have to learn and understand the syntax in addition to openHAB concepts and home automation technologies.
- You will see most objects defined in files in the UI but you won't be able to edit them (those objects will have a lock besides their name/label :lock:).
- You need to sit in front of a computer with access to the files to make changes.
### UI-driven
Pros:
- Easier to understand for novices. The UI assists you with its built in documents and help. There are fewer opportunities to make mistakes since the syntax is almost impossible to get wrong.
- All objects can be altered from anywhere the UI can be reached (including on mobile).
- Things can be auto-discovered.
@ -53,6 +58,7 @@ Pros:
- A backup of the internal database is created on every change.
Cons:
- Can be slower to reach one's goal if you already know what you're doing and if there's a lot of bulk changes or duplicating required.
- Harder to remove obsolete stuff.
- Some things cannot be configured with the UI yet (e.g. persistence).

36
tutorials/getting_started/model.md
View File

@ -33,7 +33,7 @@ The semantic model, when set up correctly, will allow openHAB to turn all lights
## Introduction to the Ontology and Relationships
![](images/ontology_relationships.jpeg)
![ontology relationships](images/ontology_relationships.jpeg)
The above drawing shows the relationship between the four main concepts in the model.
@ -44,7 +44,7 @@ The above drawing shows the relationship between the four main concepts in the m
Example of an advanced model:
![](images/example_model.png)
![example model](images/example_model.png)
<!--(made with https://www.diagrameditor.com - file here: [Semantic Model.txt|attachment](upload://qEPmmmDomSr4F5dRBHMXajOzO0c.txt) (3.3 KB) change extension to .drawio) -->
We have an Indoor location which has a House.
@ -77,11 +77,11 @@ Using the example above, the Z-Wave plug might be modeled as a subequipment of t
From the Settings screen, click on Model.
![](images/start_model.png)
![start model](images/start_model.png)
Let's start with a hierarchy of Locations. Click on Add Location.
![](images/create_location.png)
![create location](images/create_location.png)
Add your first item, a Group representing the ground floor.
Give it a name, but choose carefully as you cannot change it afterward.
@ -102,7 +102,7 @@ Add the ground floor and its rooms (master bedroom, bathroom, etc...) to your mo
You should end up with something resembling this:
![](images/locations_model.png)
![model locations](images/locations_model.png)
## Modeling Equipment
@ -114,7 +114,7 @@ If the Equipment you're adding is one of the Things that you have already added,
Select where in the model you want to add the Equipment, for instance the kitchen, and click on Create Equipment from Thing.
![](images/create_equipment_model.png)
![model create equipment](images/create_equipment_model.png)
Select the Thing you want to create the Equipment from, and alter the details of the Equipment item that will be created.
If you don't find an appropriate Equipment class, choose **Equipment**.
@ -123,7 +123,7 @@ Below are all the Channels defined by the Thing.
Sometimes Things will have hundreds of channels, so here you have the opportunity of choosing which ones will be linked to new Points items.
Check the channels you're interested in and only those.
![](images/create_equipment_model_channels.png)
![model create equipment channels](images/create_equipment_model_channels.png)
For the plant sensor Thing added earlier, we have an opportunity to change the default basic Number types and make them quantifiable.
Quantity types (Number with a dimension) provide conversion facilities between Units of Measurement, and the default persistence is more granular.
@ -134,7 +134,7 @@ Also set the semantic class to Measurement and choose an appropriate related pro
When you're finished, click Add in the title bar.
The Equipment and Points should be added to the model where you wanted.
![](images/create_equipment_model_added.png)
![model created equipment added](images/create_equipment_model_added.png)
The "Plant Sensor" Equipment has now been created under the Kitchen location, and all the selected Points represent the selected Channels of the Thing.
@ -143,25 +143,25 @@ The "Plant Sensor" Equipment has now been created under the Kitchen location, an
From the Settings, click on Things and then click on the Thing you wish to add to the model.
Switch to the Channels tab.
![](images/create_equipment_things_channels.png)
![create equipment things channels](images/create_equipment_things_channels.png)
Click on Add Equipment to Model below the list.
You'll encounter a similar screen to the one above.
The difference is, rather than selecting the Thing, you have to select where in the model you want to add the Equipment.
![](images/create_equipment_things_location.png)
![create equipment things location](images/create_equipment_things_location.png)
Select Pick From Model in the Parent Group section, and the tree view of the Locations and Equipments will appear.
Select the parent group, for instance Living Room, then choose Pick in the top-right corner of the dialog box.
If this equipment is a part of another equipment, choose that equipment as the parent instead of a location.
![](images/create_equipment_things_parent.png)
![create equipment things parent](images/create_equipment_things_parent.png)
Then do the same as above, configure the Equipment item and the Points, then click Add.
Go back to the Model by choosing Model in the sidebar and verify that the Equipment added to the model from the thing page is effectively there as well as, its Points.
![](images/create_equipment_things_added.png)
![create equipment things added](images/create_equipment_things_added.png)
Note how the Channel Links section lists the link to the Thing/Channel, and you also have a control widget to control the item.
Since it's linked to the Color channel of the Hue bulb, the light will reflect the state of the item.
@ -169,6 +169,7 @@ Since it's linked to the Color channel of the Hue bulb, the light will reflect t
Finish adding Equipment and Points from your Things.
## Retrofitting Existing Items to the Model
There may be times where a user needs to add existing Items to their model.
Perhaps they are migrating from an older version of OH, they did not follow the advice above to start with the model to begin with, or they are following a tutorial or example that doesn't include the model.
In this case all is not lost.
@ -178,21 +179,22 @@ Then add the Point as a member of the appropriate Equipment or Location Group.
If the Equipment Group doesn't exist yet, create a Group and use the appropriate Equipment semantic tag first and add the Equipment to the appropriate Location Group.
## Modifying the Model
As illustrated here, the model consists mainly of Group membership and tags on Items.
To change the location of an equipment or room, simply change the parent Group.
To change the type of an equipment or point, simply edit the tags.
Some of these edits are possible from the Model Page itself.
Where that's not supported, you can make the changes through the Item's Page.
## Controls and Sensor types
## Controls and Sensor types
This is a table descibing the Equipment types and point class and type to enable display of badges and measurements on the location cards.
This is based off the sources linked below.
- https://github.com/openhab/openhab-webui/blob/master/bundles/org.openhab.ui/web/src/components/cards/glance/location/status-badge.vue#L63
- https://github.com/openhab/openhab-webui/blob/master/bundles/org.openhab.ui/web/src/components/cards/glance/location/measurement-badge.vue#L48
- <https://github.com/openhab/openhab-webui/blob/main/bundles/org.openhab.ui/web/src/components/cards/glance/location/status-badge.vue#L63>
- <https://github.com/openhab/openhab-webui/blob/main/bundles/org.openhab.ui/web/src/components/cards/glance/location/measurement-badge.vue#L48>
### Badges
### Badges
| Type | Equipment | Equipment subtypes allowed | Point Class | Point Type | Point Subtypes allowed |
| ----------- | --- | ---- | ----------- | ---- | ----- |
@ -215,7 +217,7 @@ This is based off the sources linked below.
| Projectors | Projector | no | Control | Power | yes |
| Alarms | ANY | NA | Alarm | ANY | yes |
### Measurements
### Measurements
These don't care about equipment and just look at points

5
tutorials/getting_started/persistence.md
View File

@ -26,8 +26,10 @@ Note that Persistence only saves Item states.
{:toc}
## Persistence Concepts
As previously mentioned, Persistence saves Item states.
But the question is, when does it save those Item states?
- Every time the Item changes?
- Every time the Item is updated (an update does not necessarily result in the Item changing state)?
- Only when the Item receives a command?
@ -41,6 +43,7 @@ One special persistence strategy is `restoreOnStartup` which will update the Ite
The good news here is that if you don't know what you may want to use persistence for, you can just keep the defaults and move to the next step.
## Persistence Configuration
Each persistence add-on comes with it's own default persistence strategy.
See the documentation for the specific persistence add-on for what the default strategy is.
This default can be overridden.
@ -54,12 +57,14 @@ One may not even want to save all their Items, or may want to save different Ite
For example, a common approach would be to use [`MapDB`]({{base}}/addons/persistence/mapdb/) only for those Items that should be restored on startup, [`rrd4j`]({{base}}/addons/persistence/rrd4j) with an `everyChange` and every minute strategy for number and binary (Switch, Contact) type Items that are to be charted, and [`Influxdb`]({{base}}/addons/persistence/influxdb) with an `everyUpdate` strategy for analysis with external tools.
## Default Persistence
openHAB ships with [`rrdj4`]({{base}}/addons/persistence/rrd4j) as the default persistence database and comes with a default persistence strategy of `everyChange`, `everyMinute`, and `restoreOnStartup` for every supported Item.
The good thing about `rrd4j` is that the database never grows beyond a given size, so you never have to clean it up.
However, the way it achieves this (replacing ten readings with the average of the ten readings as the data gets older) makes the database not work for all Item types.
If you need to `restoreOnStartup` unsupported Item types, `MapDB` might be a better choice for you.
## Why Bother with Persistence?
The reason one would set up both the Model discussed in the previous tutorial and Persistence is that it will make creating your user interfaces much easier and much more rich.
For example, a set of UI pages will be created automatically in MainUI based on the model.
And just about anyplace you can interact with an Item in MainUI, there will be an "Analyze" button that will generate a chart based on the data saved in persistence.

23
tutorials/getting_started/things_advanced.md
View File

@ -22,28 +22,31 @@ Instead, it is publishing metrics regularly on a preconfigured MQTT topic in a s
```json
{"light": 5424, "moisture": 30, "temperature": 21.4, "conductivity": 1020, "battery": 100}
```
{::options toc_levels="2..4"/}
- TOC
{:toc}
## Prerequisites
- A basic understanding of how MQTT works (HiveMQ provides a good [tutorial](https://www.hivemq.com/blog/mqtt-essentials-part-3-client-broker-connection-establishment/)
- An installed and configured MQTT Broker (e.g. Mosquitto, which can be installed through openHABian if that is how you installed openHAB)
- A MiFlora device configured to connect to the MQTT Broker, or an MQTT client application (e.g. [MQTT Explorer](https://mqtt-explorer.com/), [MQTT.fx](http://mqttfx.org/) that allows one to publish and subscribe to MQTT topics
## Install the Binding and Transformation
This device publishes JSON formatted messages, so we need to install an add-on that can process JSON: the JSONPath Transformation.
A Transformation takes incoming data and transformes is somehow.
In this case it will extract certain fields from the JSON.
From Settings, click on Transformations under Add-ons.
![](images/choose_transformation.png)
![choose transformation](images/choose_transformation.png)
Click on the blue "+" button and find JSONPath Transformation.
Click on it, then click Install.
![](images/install_jsonpath.png)
![install_jsonpath](images/install_jsonpath.png)
Wait for it to disappear from the list, then click back twice to go back to Settings.
@ -52,6 +55,7 @@ Click on it, then click Install.
Wait for it to disappear from the list, then go back twice to return to the main Settings screen.
## Create the Bridge Thing
First we need to add the broker, which is a Bridge.
Click on Things.
@ -59,15 +63,16 @@ Click on the blue "+" button.
Choose "MQTT Binding", then choose "MQTT Broker".
![](images/mqtt_things.png)
![mqtt things](images/mqtt_things.png)
Fill in the details to connect to the broker.
You may also alter its ID and name.
If you need credentials to connect to the broker, click on "Show advanced" to reveal additional options, including Username and Password.
![](images/mqtt_bridge_config.png)
![mqtt bridge config](images/mqtt_bridge_config.png)
## Create the Generic MQTT Thing
Now we have to add the plant sensor itself as a generic Thing.
On the Things page, first verify that the broker is indeed present and online; if so, click on the blue "+" button then on the MQTT Binding.
@ -86,7 +91,7 @@ Back on the Things page, choose the Thing you created.
It should be marked online, but it will not have any Channels on the Channel tab.
You have to configure them yourself.
![](images/mqtt_generic_thing.png)
![mqtt generic thing](images/mqtt_generic_thing.png)
Click on Add Channel.
@ -102,16 +107,16 @@ Click on "Show advanced" above MQTT State Topic to reveal more settings.
Scroll down, find the "Incoming Value Transformations" setting, and specify the transformation to apply there:
```
```json
JSONPATH:$.temperature
```
![](images/mqtt_temp_channel.png)
![mqtt temp channel](images/mqtt_temp_channel.png)
Click Done in the title bar to add the channel.
It should now be added to the Channels tab.
![](images/mqtt_temp_channel_created.png)
![mqtt temp channel created](images/mqtt_temp_channel_created.png)
Repeat the procedure for the other channels:
@ -126,7 +131,7 @@ All channels should specify the MQTT topic where the JSON message is published.
If you want to check the configuration for a channel, or if you made a mistake while adding it, open the channel details by clicking on it, and choose Configure Channel.
![](images/mqtt_config_channel.png)
![mqtt config channel](images/mqtt_config_channel.png)
Note that you cannot change the channel type if you picked the wrong one.
In that case, remove the channel by clicking on Remove Channel and then add it again.

13
tutorials/getting_started/things_intermediate.md
View File

@ -18,36 +18,39 @@ Scenario: you have some Z-Wave devices, including a wall plug and a rollershutte
{:toc}
## Install the Binding
From Settings, go to Things, then click the blue "+" button.
We need to install the Z-Wave binding.
Click "Install More Bindings".
![](images/install_zwave.png)
![install zwave](images/install_zwave.png)
Find the Z-Wave binding, click on it, then click Install.
![](images/installing_zwave.png)
![installing zwave](images/installing_zwave.png)
Wait for it to disappear from the list, then go back.
![](images/installed_zwave.png)
![installed zwave](images/installed_zwave.png)
## Create the Bridge Thing
Click on the new option: Z-Wave Binding.
Click on Z-Wave Serial Controller to add the controller.
![](images/zwave_add_controller.png)
![add zwave controller](images/zwave_add_controller.png)
We need to specify one required parameter, the serial port.
In certain cases, depending on your system, you will be provided with a list of options for this setting.
![](images/zwave_port_config.png)
![zwave port config](images/zwave_port_config.png)
Choose the correct port, alter the name and/or ID of the controller Thing, then click Add in the top-right corner.
## Discover Things
Once back on the Things screen, click on the "+" button then on Z-Wave Binding again.
Click scan and all the devices already paired with the Zwave controller will be discovered and appear in the Inbox.
To pair a new device, while on this screen, perform the procedure specific to the device to include it in your network.

32
tutorials/getting_started/things_simple.md
View File

@ -27,18 +27,17 @@ In this case, the Hue binding supports auto-discovery of both the bridge and the
- TOC
{:toc}
## Install the Binding
After logging in as an administrator, click on `Settings` from the sidebar, then click on `Things`.
![](images/empty_things_menu.png)
![empty things menu](images/empty_things_menu.png)
Click on the blue "+" button located at the bottom-right corner.
Since you have no bindings, this screen will appear:
![](images/choose_binding.png)
![choose binding](images/choose_binding.png)
Click on `Install Bindings`.
@ -46,17 +45,17 @@ Look for the Hue binding.
Note the search bar at the top can help find bindings quickly by filtering the long list.
Click on the binding, then on Install.
![](images/install_hue.png)
![install hue](images/install_hue.png)
It will take from a few seconds to a minute for the binding to install...
![](images/installing_hue.png)
![installing hue](images/installing_hue.png)
Wait for it to disappear from the list, then click < Back (or use the browser controls).
The Hue binding will now appear on the previous screen.
You will notice that the auto-discovery has already detected something (note the red "1" badge).
![](images/installed_hue.png)
![installed hue](images/installed_hue.png)
## Accept the Discovered Bridge Thing
@ -65,35 +64,35 @@ Click on the binding.
The bridge has indeed been detected and appears under Discovered Things.
If not, you can try again by clicking the `Scan Again` button.
![](images/hue_things_discover_bridge.png) Thing
![hue things discover bridge](images/hue_things_discover_bridge.png) Thing
Click on the discovered `Hue Bridge`.
![](images/add_hue_bridge.png)
![add hue bridge](images/add_hue_bridge.png)
openHAB will ask you to confirm or change the label/name.
Click OK after naming the new Thing.
You will be taken back to the Things page, where the Hue Bridge should now appear.
![](images/hue_bridge_offline.png)
![hue bridge offline](images/hue_bridge_offline.png)
However, we can see that it's marked offline.
To find out why we can click on the `Hue Bridge`.
![](images/hue_bridge_config_error.png)
![hue bridge config error](images/hue_bridge_config_error.png)
The error description below the status gives some more information: You have to press the physical button on the device to let openHAB authenticate to it.
Once you've done this, the Thing will become online.
![](images/hue_bridge_online.png)
![hue bridge online](images/hue_bridge_online.png)
## Accept the Light Bulb Things
Go back to Things.
You will notice a new red button on that screen.
![](images/hue_inbox.png)
![hue inbox](images/hue_inbox.png)
This means that there are newly discovered devices that you can add.
Since the Hue bridge is now working, the binding has detected all the Hue devices (bulbs, switches and so on) attached to it.
@ -103,15 +102,16 @@ Alternatively, you can also click on the "+" button to get a per-binding view an
Click Inbox.
![](images/discovered_hue_things.png)
![dicsovered hue things](images/discovered_hue_things.png)
You can either click on an individual thing to see actions related to it, or you can click on Select in the top-right corner to add check boxes beside items, which will allow you to perform actions on several inbox entries at once.
![](images/hue_individual_add.png)
![hue individual add](images/hue_individual_add.png)
![](images/hue_bulk_add.png)
![hue bulk add](images/hue_bulk_add.png)
These actions are:
- Approve: To promote the candidate from the Inbox to a Thing.
- Ignore: To hide the candidate from the list (you will be able to see it again and un-ignore it by clicking on "Show ignored" above the list).
- Remove: To remove the candidate from the Inbox (it might be detected again later).
@ -119,7 +119,7 @@ These actions are:
Now go back to Things.
The newly approved Hue Things should appear on the list.
![](images/hue_things_added.png)
![hue things added](images/hue_things_added.png)
You now have the Bridge Thing and the two light bulbs added to openHAB.
Thankfully most of the bindings you will work with in openHAB will work in this simple way.