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

openHAB 4 and Java 17 refactoring (#1975) 

* Remove or rename openHAB Version where useful.

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

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

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

* Java bulk edit
Signed-off-by: Jerome Luckenbach <github@luckenba.ch>

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

* Update installation/synology.md

Co-authored-by: Wouter Born <github@maindrain.net>

Signed-off-by: Jerome Luckenbach <github@luckenba.ch>
Co-authored-by: Wouter Born <github@maindrain.net>
pull/1989/head
Jerome Luckenbach 2022-12-30 16:24:19 +01:00 committed by GitHub
parent 9f1ee6d20e
commit 7a87fdc06b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
18 changed files with 49 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
README.md
View File

@ -1,8 +1,8 @@
# openHAB 3.x Documentation Project
# openHAB Documentation Project
## Introduction
This repository contains the documentation for openHAB 3.x.
This repository contains the documentation for openHAB.x.
The result is available at [https://openhab.org/docs/](https://www.openhab.org/docs/) and [https://openhab.org/addons/](https://www.openhab.org/addons/).
@ -53,7 +53,7 @@ So we are saving time for everyone by keeping those files at their original loca
::: tip UNDER REVIEW
The process below is subject to changes until the openHAB 3.x website become the production one.
The process below is subject to changes until the openHAB.x website become the production one.
:::

2
addons/actions.md
View File

@ -61,7 +61,7 @@ You have different options to execute a command through an action.
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.
Check out the [Java Documentation](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html?is-external=true) for possible units.
#### Scripts with parameters

4
administration/logging.md
View File

@ -62,7 +62,7 @@ Please see the [Karaf documentation](https://karaf.apache.org/manual/latest/#_co
The config file for logging is located in the `userdata/etc` folder (manual setup) or in `/var/lib/openhab/etc` (apt/deb-based setup).
::: tip Attention OH2 users
The format and filename to store log settings has changed. It used to be `org.ops4j.pax.logging.cfg` in openHAB 2 and is `log4j2.xml` in openHAB 3.
The format and filename to store log settings has changed. It used to be `org.ops4j.pax.logging.cfg` in openHAB 2 and is `log4j2.xml` since openHAB 3.
Do not delete the `.cfg` though, it needs to include the new `.xml`.
:::
@ -168,7 +168,7 @@ An example output of the last log statement above is:
2016-06-04 16:28:39.482 [DEBUG] [org.openhab.core.model.script.heating] Bedroom: Temperature 21.3°C, Mode NORMAL
```
Note that, in the last example above, inclusion and formatting of values is done using [Java Formatter String Syntax](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Formatter.html).
Note that, in the last example above, inclusion and formatting of values is done using [Java Formatter String Syntax](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Formatter.html).
## Log4j configuration and logging into separate files

2
configuration/index.md
View File

@ -35,7 +35,7 @@ This section does not cover building user interfaces; this subject has its own s
## Versatility
openHAB 3 provides a _single_ graphical user interface to modify settings, to manage your components and rules, and to provide a UI for users.
openHAB provides a _single_ graphical user interface to modify settings, to manage your components and rules, and to provide a UI for users.
While there are no full-scale starter and migration tutorials available yet, see the [recording of the recent 2020 openHAB virtual meetup](https://youtu.be/pwZ8AOwRDEk?t=1586) for a tour of the new Main UI (starting at 26:26).

2
configuration/items.md
View File

@ -260,7 +260,7 @@ Number Livingroom_Temperature "Temperature [%.1f °C]"
If no state presentation and no square brackets are given, the Item will not provide a textual presentation of its internal state (i.e. in UIs no state is shown).
This is often meaningful when an Item is presented by a non-textual UI elements like a switch or a diagram.
Formatting of the presentation is done applying [Java formatter class syntax](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Formatter.html#syntax).
Formatting of the presentation is done applying [Java formatter class syntax](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Formatter.html#syntax).
If square brackets are given, the leading `%` and the trailing formatter conversion are mandatory.
Free text, like a unit, can be added before or after the formatter string.

2
configuration/jsr223.md
View File

@ -217,7 +217,7 @@ For example, with the following scripts and directory structure...
... the load order will be: (`sl30/script_x.py` & `sl30/script_y.py`) at start level 30, `script.sl38.py` at start level 38, then (`/dir1/script_a.py`, `/dir1/script_b.py`, `script.py`) at start level 40.
The script file watching mechanism itself is activated at start level 20, so scripts cannot be executed earlier than this.
Note that prior to openHAB 3, script ordering was performed alphanumerically based on file path. This is no longer supported as of openHAB 3.
Note that prior to openHAB 3, script ordering was performed alphanumerically based on file path. This is no longer supported as of openHAB 3 and later versions.
### `ScriptExtension` Objects (all JSR223 languages)

22
configuration/migration/index.md
View File

@ -1,12 +1,12 @@
---
layout: documentation
title: Migration to openHAB 3
description: Description of Beaking Changes and needed steps for a proper Migration to openHAB 3
title: Migration from openHAB 2
description: Description of Beaking Changes and needed steps for a proper Migration from openHAB 2
---
# Migrating from openHAB 2 to openHAB 3
# Migrating from openHAB 2
There are different approaches to get your openHAB 2 Environment upgraded to openHAB 3.
There are different approaches to get your openHAB 2 Environment upgraded.
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.
@ -15,14 +15,14 @@ Since this is a major version release you have to pay attention to some **Breaki
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.
Below you can find some general informations for the technical upgrade process to openHAB 3.
Below you can find some general informations for the technical upgrade process from openHAB 2.
Please be aware of possible changes needed for your specific environment in case of the breaking changes after upgrading.
## Upgrade Process for different installation variants
### openHABian
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:
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 x.0.0 stable is done in just a few steps:
1. Connect to the SSH command line and run `sudo openhabian-config`
1. When being asked to update openHABian, answer yes. Do not change the branch, it should read `stable` if you are on 2.X and `openHAB3` or `main` if on 3.X.
@ -33,7 +33,7 @@ If you are working with an [openHABian](https://www.openhab.org/docs/installatio
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.
Unfortunately, it means that in terms of openHAB 2 and newer openHAB versions, you cannot install both at the same time and openHAB 2 will not automatically update, but if you use the commands to install newer openHAB versions 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.
@ -45,9 +45,9 @@ You should probably do your usual OS backup too to make sure you can get back to
#### Prerequisites
openHAB 3 requires Java 11. Most modern Linux OS have an `openjdk-11-jdk` package available for you to install but alternative solutions such as [Zulu's OpenJDK](https://www.azul.com/downloads/zulu-community/?version=java-11-lts&package=jdk) (which openHABian can install for you) are available and these may run faster on 32-bit armhf platforms such as the Raspberry Pi.
openHAB (since version 4) requires Java 17. Most modern Linux OS have an `openjdk-17-jdk` package available for you to install but alternative solutions such as [Zulu's OpenJDK](https://www.azul.com/downloads/zulu-community/?version=java-17-lts&package=jdk) (which openHABian can install for you) are available and these may run faster on 32-bit armhf platforms such as the Raspberry Pi.
You must also be on the relevant repository for openHAB, this hasn't changed for openHAB 3.x so the [same instructions for moving to it](https://www.openhab.org/docs/installation/linux.html#package-repository-installation) are still valid.
You must also be on the relevant repository for openHAB, this hasn't changed for openHAB 4.x so the [same instructions for moving to it](https://www.openhab.org/docs/installation/linux.html#package-repository-installation) are still valid.
For DEB based installers (apt), your `.list` file should contain the line:
@ -68,7 +68,7 @@ enabled=1
#### Upgrading
If the install of openHAB 3 detects an existing openHAB 2 install, then it will copy the configurations across and update using those files. There are several major differences between openHAB 2 and 3 which may mean that this will cause issues, let us know if you experience anything strange.
If the install of openHAB detects an existing openHAB 2 install, then it will copy the configurations across and update using those files. There are several major differences between openHAB 2 and 3 which may mean that this will cause issues, let us know if you experience anything strange.
After a successful update, you can use commands like `sudo systemctl start openhab` (notice no 2 at the end) immediately, but `openhab-cli` will complain of path errors until you restart your shell session (e.g. by logging out and in).
@ -137,7 +137,7 @@ Replace "dnf" with "yum" for older Red Hat based OSes.
### Manual Installations
Note that openHAB 3 now requires a Java 11 runtime, so please make sure to [install such a JVM](https://next.openhab.org/docs/installation/#prerequisites) before continuing.
Note that openHAB (since version 4) now requires a Java 17 runtime, so please make sure to [install such a JVM](https://next.openhab.org/docs/installation/#prerequisites) before continuing.
Official update scripts are available that let you update your 2.x installation to version 3.0:

2
developers/guidelines.md
View File

@ -132,7 +132,7 @@ Data-transfer-objects (DTOs map from JSON/XML to Java classes) do not require Ja
## D. Language Levels and Libraries
1. openHAB generally targets the long time supported Java 11 release.
1. openHAB generally targets the long time supported Java 17 release.
1. The [OSGi Core Release 7](https://osgi.org/download/r7/osgi.core-7.0.0.pdf) with [OSGi Compendium Release 7](https://osgi.org/download/r7/osgi.cmpn-7.0.0.pdf) is targeted, and newer features should not be used.
1. [SLF4J](http://slf4j.org) is used for logging.

4
developers/ide/eclipse.md
View File

@ -15,10 +15,10 @@ If you already have Eclipse installed it is recommended to perform a separate Ec
## Eclipse IDE Setup
1. Install the Java 11 JDK if you did not have it installed.
1. Install the Java 17 JDK if you did not have it installed.
::: warning Attention
openHAB development requires **Java JDK version 11**.
openHAB development requires **Java JDK version 17**.
:::
1. Download the "Eclipse Installer": [can be downloaded from the Eclipse web site](https://wiki.eclipse.org/Eclipse_Installer)

2
developers/ide/intellij.md
View File

@ -7,7 +7,7 @@ title: IntelliJ
## Prerequisities
- git, Maven, IntelliJ and Java 11 are installed
- git, Maven, IntelliJ and Java 17 are installed
## Install openHAB distribution

4
developers/index.md
View File

@ -16,7 +16,7 @@ Try [git - the simple guide](https://rogerdudler.github.io/git-guide/) as a star
Add-ons and the openHAB core itself are written in Java.
Java is not hard to learn, but it helps if you have a general technical understanding of programming languages.
The different guides of this chapter assume that you are somewhat familiar with Java 11 and that you have a rough understanding of Git's workflow (e.g. "checkout", "branches", "push").
The different guides of this chapter assume that you are somewhat familiar with Java 17 and that you have a rough understanding of Git's workflow (e.g. "checkout", "branches", "push").
## Choose the Right Concept
@ -49,7 +49,7 @@ Please ensure that you have the following prerequisites installed as well:
1. [Git](https://git-scm.com/downloads) For retrieving our source code and push changes back. On Windows: Must be available in %PATH%
1. [Maven 3.x](https://maven.apache.org/download.cgi) Our buildsystem tool. On Windows: Must be available in %PATH%
1. Java JDK 11, for example from Oracle [Oracle JDK 11](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html). On Windows: %JAVA% must be set.
1. Java JDK 17, for example from Oracle [Oracle JDK 17](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html). On Windows: %JAVA% must be set.
You can use any IDE that is suitable for OSGi/Java development.
We have prepared some step-by-step guides for the following IDEs:

4
developers/utils/events.md
View File

@ -151,7 +151,7 @@ A string representation of an event type can be found by a public member `TYPE`
To subscribe to all available event types, use the public member `ALL_EVENT_TYPES` of the event subscriber interface.
The event subscriber provides a `TopicEventFilter` which is a default openHAB `EventFilter` implementation that ensures filtering of events based on a topic.
The argument of the filter is a [Java regular expression](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/regex/Pattern.html).
The argument of the filter is a [Java regular expression](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/regex/Pattern.html).
The filter method `EventFilter.apply()` will be called for each event on the event bus to which the event subscriber is subscribed (in the example above `ItemStateEvent` and `ItemCommandEvent`).
If the filter applies (in the given example for all item events with the item name "ItemX"), the event will be received by the `EventSubscriber.receive()` method.
Received events can be cast to the event implementation class for further processing.
@ -174,7 +174,7 @@ The listing below summarizes some best practices in order to implement event sub
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/17/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.

15
installation/index.md
View File

@ -34,14 +34,14 @@ openHABian is also available to kickstart your openHAB experience on existing De
## Prerequisites
Make sure that you have an up to date **Java 11** JVM platform installed on your host system.
Make sure that you have an up to date **Java 17** JVM platform installed on your host system.
We recommended to use the openjdk package that comes with your Linux distro.
If in doubt, explicitly install a JVM based on OpenJDK.
You could also [download Azul Zulu](https://www.azul.com/downloads/zulu-community/?&architecture=x86-64-bit&package=jdk#) [Installation](https://docs.azul.com/zulu/zuludocs/ZuluUserGuide/InstallingZulu/InstallationWindowsUsingZuluMSIFile.htm) instructions can be found on Azul Systems' Zulu website.
Oracle Java is also suitable for most configurations but it's not recommended. Licensing restrictions may apply.
::: warning
Please note that versions of Java higher than 11 are not supported at the moment.
Please note that versions of Java higher than 17 are not supported at the moment.
:::
| Java Platform | Advantages | Disadvantages |
@ -50,8 +50,7 @@ Please note that versions of Java higher than 11 are not supported at the moment
| [Oracle Java](https://java.com/en/) | Full openHAB support on all platforms | [Licensing restrictions](https://blog.takipi.com/running-java-on-docker-youre-breaking-the-law/), manual installation required on many Linux systems: [Ubuntu](https://help.ubuntu.com/community/Java), [Mint](https://community.linuxmint.com/tutorial/view/1091), and [Debian](https://wiki.debian.org/Java/Sun) are some examples |
| [AdoptOpenJDK](https://adoptopenjdk.net) | Open Source JDK backed by many large companies | |
Please download and install the **Java 11** version of the JVM.
Note that openHAB 3 will run under Java 11, and you _can_ use it with openHAB 2.X as well. But be aware that although developers are working hard to make this work, there might be problems with the oldest parts of openHAB 2.x, such as some of the v1 bindings, due to non-backward compatible changes in Java 11.
Please download and install the **Java 17** version of the JVM.
The **64-bit version** of the JVM is **only** recommended on platforms using a 64-bit OS and an Intel or AMD processor.
@ -61,9 +60,9 @@ The 32-bit JVM performs better on the ARM platform. Some add-ons use libraries t
Check your current Java version by opening a command line console and typing `java -version`:
```text
openjdk version "11.0.9.1" 2020-11-04 LTS
OpenJDK Runtime Environment Zulu11.43+55-CA (build 11.0.9.1+1-LTS)
OpenJDK 64-Bit Server VM Zulu11.43+55-CA (build 11.0.9.1+1-LTS, mixed mode)
openjdk version "17.0.5" 2022-10-18 LTS
OpenJDK Runtime Environment Zulu17.38+21-CA (build 17.0.5+8-LTS)
OpenJDK 64-Bit Server VM Zulu17.38+21-CA (build 17.0.5+8-LTS, mixed mode, sharing)
```
## Setup variants
@ -95,7 +94,7 @@ openhab-cli info
will result in e.g. for an [openHABian](https://www.openhab.org/docs/installation/openhabian.html) installation
```shell
Version: 3.0.2 (Build)
Version: 4.0.0 (Build)
User: openhab (Active Process 7466)
User Groups: openhab tty dialout audio bluetooth gpio

2
installation/linux.md
View File

@ -33,7 +33,7 @@ If you're unsure which manual file you should download, using `dpkg --print-arch
When installing Zulu or Zulu Embedded from a .zip or .tar archive, make sure to [set Zulu as the main Java "alternative"](https://docs.azul.com/zulu/zuludocs/#ZuluUserGuide/SwitchingBetweenJavaAlternatives/SwitchBetweenJavaAlts.htm).
::: tip Note
Make sure to download Zulu or Java **11**.
Make sure to download Zulu or Java **17**.
:::
## Installation

9
installation/synology.md
View File

@ -3,6 +3,15 @@ layout: documentation
title: Synology DiskStation
---
:::tip Note
openHAB 4 and higher need Java 17.
You will need to provide a working Java installation on your DiskStation.
The sections below are written for Java 11 but the docs are not updated currently, since we have not secured knowledge about how to install Java 17 on the DiskStation.
If you can provide some proper sources and explanation, we are happy to include your contribution into this article.
:::
# Synology DiskStation DSM 7.0 and higher
The [DiskStation by Synology](https://www.synology.com/en-us/dsm) is a famous NAS server solution for your home, allowing the installation of additional packages.

2
tutorials/getting_started/model.md
View File

@ -16,7 +16,7 @@ For example, instead of dealing with `zwave:1231242:node12:switch` we can deal w
Items are the main entities that the rest of openHAB works with including Pages, Sitemaps, Rules, and persistence.
There are many ways to organize your items, one of which is to make use of the semantic model (descriptions for location, type of equipment and more).
openHAB 3 makes extensive use of the semantic model to automatically create Pages (see next section) and to provide natural language interaction.
openHAB makes extensive use of the semantic model to automatically create Pages (see next section) and to provide natural language interaction.
Therefore we recommend creating the semantic model right from the start and sticking to it.
This will make your life easier in the long run.
Taking the time to understand and choose a logical structure for your home will save you from needing to re-do the work in the future.

4
tutorials/getting_started/pages_intro.md
View File

@ -5,7 +5,7 @@ title: Pages - Introduction
# Introduction to Pages
openHAB 3 introduces a new unified user interface called MainUI.
openHAB 3 introduced a new unified user interface called MainUI.
Almost everything that can be configured in openHAB can be configured through MainUI.
In addition to being used for the administration of openHAB, MainUI can serve as the interface presented to the users of your home automation system.
@ -46,7 +46,7 @@ Notice the new Settings and Developer Tools menus are accessible to administrato
Every openHAB deployment is unique.
Consequently every administrator of an openHAB instance will need to create a custom interface for the users of their bespoke home automation system.
openHAB 3 provides a number of options to supports this in addition to MainUI Pages.
openHAB provides a number of options to support this in addition to MainUI Pages.
Interface | Purpose | How the UI is Defined | Notes
-|-|-|-

2
ui/building-pages.md
View File

@ -8,7 +8,7 @@ title: Building Pages - Components & Widgets
## UI Components: introduction and structure
**UI components** are the basic building blocks for many UIs in openHAB 3.
**UI components** are the basic building blocks for many UIs in openHAB.
The Main UI Pages and Personal Widgets are notable UI components, but Sitemaps that were created in the UI and HABPanel dashboards are as well.
These structures make up hierarchies that notably define the pages in their entirety, and are relatively simple.