|
|
|
@ -22,21 +22,21 @@ This page is structured as follows:
|
|
|
|
|
|
|
|
|
|
|
|
## Preparation
|
|
|
|
## Preparation
|
|
|
|
|
|
|
|
|
|
|
|
Now is the time to consider and plan for your newly installed openHAB. Some
|
|
|
|
Now is the time to consider and plan for your newly installed openHAB. Some
|
|
|
|
questions to ask and answer include:
|
|
|
|
questions to ask and answer include:
|
|
|
|
|
|
|
|
|
|
|
|
- Are you happy with your current deployment and maintenance of the deployment?
|
|
|
|
- Are you happy with your current deployment and maintenance of the deployment?
|
|
|
|
- Do you have or need to change your backup and configuration management
|
|
|
|
- Do you have or need to change your backup and configuration management
|
|
|
|
practices?
|
|
|
|
practices?
|
|
|
|
- Have you wanted to migrate to a container (e.g.
|
|
|
|
- Have you wanted to migrate to a container (e.g.
|
|
|
|
[Docker]({{base}}/installation/docker.html) or a virtual machine)?
|
|
|
|
[Docker]({{base}}/installation/docker.html) or a virtual machine)?
|
|
|
|
- Do you want to start over fresh on a brand new OS install?
|
|
|
|
- Do you want to start over fresh on a brand new OS install?
|
|
|
|
|
|
|
|
|
|
|
|
Your answers to these and other similar questions will help guide you to
|
|
|
|
Your answers to these and other similar questions will help guide you to
|
|
|
|
prepare your installation before you start the migration. For example, if you
|
|
|
|
prepare your installation before you start the migration. For example, if you
|
|
|
|
want to start using git to back up and configuration manage your openHAB
|
|
|
|
want to start using git to back up and configuration manage your openHAB
|
|
|
|
configurations, or if you are considering moving to
|
|
|
|
configurations, or if you are considering moving to
|
|
|
|
[Docker]({{base}}/installation/docker.html) or a VM or starting over fresh (e.g.
|
|
|
|
[Docker]({{base}}/installation/docker.html) or a VM or starting over fresh (e.g.
|
|
|
|
[openHABian](https://github.com/ThomDietrich/openhabian)), now is a good time
|
|
|
|
[openHABian](https://github.com/ThomDietrich/openhabian)), now is a good time
|
|
|
|
to start the process.
|
|
|
|
to start the process.
|
|
|
|
|
|
|
|
|
|
|
|
@ -52,27 +52,27 @@ we highly recommend [setting up a reverse proxy]({{base}}/configuration/nginx.ht
|
|
|
|
|
|
|
|
|
|
|
|
## Backups
|
|
|
|
## Backups
|
|
|
|
|
|
|
|
|
|
|
|
The first step is to backup everything that you have modified in the existing
|
|
|
|
The first step is to backup everything that you have modified in the existing
|
|
|
|
openHAB 1.x installation. If you installed using apt-get these files may include:
|
|
|
|
openHAB 1.x installation. If you installed using apt-get these files may include:
|
|
|
|
|
|
|
|
|
|
|
|
- `/etc/openhab` - configuration files
|
|
|
|
- `/etc/openhab` - configuration files
|
|
|
|
- `/var/lib/openhab` - openhab user's home directory, zwave and embedded
|
|
|
|
- `/var/lib/openhab` - openhab user's home directory, zwave and embedded
|
|
|
|
persistence database files
|
|
|
|
persistence database files
|
|
|
|
- `/usr/share/openhab/webapps` - custom icons, custom webviews (e.g.
|
|
|
|
- `/usr/share/openhab/webapps` - custom icons, custom webviews (e.g.
|
|
|
|
[Weather Binding](https://github.com/openhab/openhab/wiki/Weather-Binding))
|
|
|
|
[Weather Binding](https://github.com/openhab/openhab/wiki/Weather-Binding))
|
|
|
|
- `/usr/share/openhab/bin` - custom command line arguments to the Java Virtual
|
|
|
|
- `/usr/share/openhab/bin` - custom command line arguments to the Java Virtual
|
|
|
|
Machine, changes to the default ports, etc.
|
|
|
|
Machine, changes to the default ports, etc.
|
|
|
|
- `/etc/default/openhab` - an alternative place to change default ports
|
|
|
|
- `/etc/default/openhab` - an alternative place to change default ports
|
|
|
|
|
|
|
|
|
|
|
|
If you are on an operating system that does not support apt-get or performed a
|
|
|
|
If you are on an operating system that does not support apt-get or performed a
|
|
|
|
manual installation for some other reason simply backup the whole
|
|
|
|
manual installation for some other reason simply backup the whole
|
|
|
|
`<openhab home>` directory.
|
|
|
|
`<openhab home>` directory.
|
|
|
|
|
|
|
|
|
|
|
|
## Shutdown openhab 1.x
|
|
|
|
## Shutdown openhab 1.x
|
|
|
|
|
|
|
|
|
|
|
|
One cannot run openHAB 1.x and openHAB 2 at the same time on the same
|
|
|
|
One cannot run openHAB 1.x and openHAB 2 at the same time on the same
|
|
|
|
machine with default settings. They both use the same networking ports and
|
|
|
|
machine with default settings. They both use the same networking ports and
|
|
|
|
some bindings require exclusive access to hardware resources (e.g. zwave,
|
|
|
|
some bindings require exclusive access to hardware resources (e.g. zwave,
|
|
|
|
RFXCOM).
|
|
|
|
RFXCOM).
|
|
|
|
|
|
|
|
|
|
|
|
On an apt-get installed openHAB 1.x running on a systemd based OS (Ubuntu 15+,
|
|
|
|
On an apt-get installed openHAB 1.x running on a systemd based OS (Ubuntu 15+,
|
|
|
|
@ -82,20 +82,20 @@ Raspbian Jessy+) run:
|
|
|
|
sudo systemctl stop openhab.service
|
|
|
|
sudo systemctl stop openhab.service
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
On manually installed systems follow your usual procedure for stopping openHAB
|
|
|
|
On manually installed systems follow your usual procedure for stopping openHAB
|
|
|
|
(e.g. `<ctrl>-c` in the window where start.sh or start.bat was run).
|
|
|
|
(e.g. `<ctrl>-c` in the window where start.sh or start.bat was run).
|
|
|
|
|
|
|
|
|
|
|
|
## Install openHAB 2
|
|
|
|
## Install openHAB 2
|
|
|
|
|
|
|
|
|
|
|
|
Follow the instructions for your platform [here]({{base}}/installation/index.html).
|
|
|
|
Follow the instructions for your platform [here]({{base}}/installation/index.html).
|
|
|
|
|
|
|
|
|
|
|
|
There are two choices to make: Beta or SNAPSHOT, and Offline or Online. Once
|
|
|
|
There are two choices to make: Beta or SNAPSHOT, and Offline or Online. Once
|
|
|
|
the final release of openHAB 2 is made, the Beta will turn into the latest
|
|
|
|
the final release of openHAB 2 is made, the Beta will turn into the latest
|
|
|
|
stable version.
|
|
|
|
stable version.
|
|
|
|
|
|
|
|
|
|
|
|
The Beta release represents a point in the development of openHAB where the
|
|
|
|
The Beta release represents a point in the development of openHAB where the
|
|
|
|
core of openHAB and most of its bindings are deemed stable and ready for broad
|
|
|
|
core of openHAB and most of its bindings are deemed stable and ready for broad
|
|
|
|
test. The SNAPSHOT releases come from the nightly builds and represent the
|
|
|
|
test. The SNAPSHOT releases come from the nightly builds and represent the
|
|
|
|
absolute most recent version. While SNAPSHOT is less stable in terms that it is
|
|
|
|
absolute most recent version. While SNAPSHOT is less stable in terms that it is
|
|
|
|
undergoing lots of changes, this does not mean that SNAPSHOT is inherently less
|
|
|
|
undergoing lots of changes, this does not mean that SNAPSHOT is inherently less
|
|
|
|
stable. And since new features are added and bugs fixed after the Beta release
|
|
|
|
stable. And since new features are added and bugs fixed after the Beta release
|
|
|
|
@ -116,45 +116,45 @@ sudo systemctl disable openhab2.service
|
|
|
|
|
|
|
|
|
|
|
|
## Prepare openHAB 2 for the Existing openHAB 1.x Configuration
|
|
|
|
## Prepare openHAB 2 for the Existing openHAB 1.x Configuration
|
|
|
|
|
|
|
|
|
|
|
|
Start your newly installed openHAB 2 instance per the instruction in the
|
|
|
|
Start your newly installed openHAB 2 instance per the instruction in the
|
|
|
|
installation guide for your platform and navigate to
|
|
|
|
installation guide for your platform and navigate to
|
|
|
|
`http://<openhab server ip>:8080` where `<openhab server ip>` is the address of
|
|
|
|
`http://<openhab server ip>:8080` where `<openhab server ip>` is the address of
|
|
|
|
the server where openHAB 2 is running.
|
|
|
|
the server where openHAB 2 is running.
|
|
|
|
|
|
|
|
|
|
|
|
Congratulations, you have a running openHAB 2! See
|
|
|
|
Congratulations, you have a running openHAB 2! See
|
|
|
|
[Concepts]({{base}}/concepts/index.html) and below for important differences between
|
|
|
|
[Concepts]({{base}}/concepts/index.html) and below for important differences between
|
|
|
|
openHAB 1.x and openHAB 2.
|
|
|
|
openHAB 1.x and openHAB 2.
|
|
|
|
|
|
|
|
|
|
|
|
Theoretically one should be able to just enable the
|
|
|
|
Theoretically one should be able to just enable the
|
|
|
|
[openHAB 1.x Compatibility Layer]({{base}}/developers/development/compatibilitylayer.html#how-to-use-openhab-1x-add-ons-that-are-not-part-of-the-distribution),
|
|
|
|
[openHAB 1.x Compatibility Layer]({{base}}/developers/development/compatibilitylayer.html#how-to-use-openhab-1x-add-ons-that-are-not-part-of-the-distribution),
|
|
|
|
copy over the existing add-ons and config files and have it work. However, while
|
|
|
|
copy over the existing add-ons and config files and have it work. However, while
|
|
|
|
the compatibility layer is very good and very capable, this approach will
|
|
|
|
the compatibility layer is very good and very capable, this approach will
|
|
|
|
result in errors and end up being more work than the steps below. Therefore the
|
|
|
|
result in errors and end up being more work than the steps below. Therefore the
|
|
|
|
first steps will be to get it running using the 1.9 version of the bindings
|
|
|
|
first steps will be to get it running using the 1.9 version of the bindings
|
|
|
|
installed through openHAB 2's new add-on management system.
|
|
|
|
installed through openHAB 2's new add-on management system.
|
|
|
|
|
|
|
|
|
|
|
|
There are three approaches one can use to install and configure bindings, an
|
|
|
|
There are three approaches one can use to install and configure bindings, an
|
|
|
|
all text based one, using the Karaf console, or using one of the administration
|
|
|
|
all text based one, using the Karaf console, or using one of the administration
|
|
|
|
GUIs (i.e. PaperUI or Habmin 2). While all three approaches are presented below,
|
|
|
|
GUIs (i.e. PaperUI or Habmin 2). While all three approaches are presented below,
|
|
|
|
the text based approach is the recommended one for those coming from openHAB 1.x
|
|
|
|
the text based approach is the recommended one for those coming from openHAB 1.x
|
|
|
|
as it will be more familiar and flexible.
|
|
|
|
as it will be more familiar and flexible.
|
|
|
|
|
|
|
|
|
|
|
|
### Text Based
|
|
|
|
### Text Based
|
|
|
|
|
|
|
|
|
|
|
|
In your configurations folder for openHAB 2 (`/etc/openhab2` on apt-get
|
|
|
|
In your configurations folder for openHAB 2 (`/etc/openhab2` on apt-get
|
|
|
|
installed instances) there is a new folder named `services`. In this folder you
|
|
|
|
installed instances) there is a new folder named `services`. In this folder you
|
|
|
|
will find a file named `runtime.cfg`. This file contains global openHAB 2
|
|
|
|
will find a file named `runtime.cfg`. This file contains global openHAB 2
|
|
|
|
parameters. Open this file for editing and you will find a number of parameters
|
|
|
|
parameters. Open this file for editing and you will find a number of parameters
|
|
|
|
you may want to set. In particular for this tutorial we recommend setting:
|
|
|
|
you may want to set. In particular for this tutorial we recommend setting:
|
|
|
|
|
|
|
|
|
|
|
|
- `org.eclipse.smarthome.persistence:default=mapdb` - default persistence, use
|
|
|
|
- `org.eclipse.smarthome.persistence:default=mapdb` - default persistence, use
|
|
|
|
whatever was set in `persistence:default` in openhab.cfg
|
|
|
|
whatever was set in `persistence:default` in openhab.cfg
|
|
|
|
- `autoapprove:enabled=false` - makes it so you must manually approve
|
|
|
|
- `autoapprove:enabled=false` - makes it so you must manually approve
|
|
|
|
automatically discovered Things in the Inbox (see below)
|
|
|
|
automatically discovered Things in the Inbox (see below)
|
|
|
|
- `org.eclipse.smarthome.links:autoLinks=false` - prevents openHAB from
|
|
|
|
- `org.eclipse.smarthome.links:autoLinks=false` - prevents openHAB from
|
|
|
|
automatically creating an Item for each automatically discovered Thing.
|
|
|
|
automatically creating an Item for each automatically discovered Thing.
|
|
|
|
|
|
|
|
|
|
|
|
Next open for editing `addons.cfg`. This file contains parameters related to
|
|
|
|
Next open for editing `addons.cfg`. This file contains parameters related to
|
|
|
|
add-ons including allowing one to choose which add-ons to install. For now just
|
|
|
|
add-ons including allowing one to choose which add-ons to install. For now just
|
|
|
|
set the following parameters:
|
|
|
|
set the following parameters:
|
|
|
|
|
|
|
|
|
|
|
|
@ -162,37 +162,37 @@ set the following parameters:
|
|
|
|
UIs, all transformation services and the 1.x compatibility layer,
|
|
|
|
UIs, all transformation services and the 1.x compatibility layer,
|
|
|
|
though you can choose your UIs and add-ons individually later.
|
|
|
|
though you can choose your UIs and add-ons individually later.
|
|
|
|
- `remote = true` - required for the installation of legacy 1.x add-ons
|
|
|
|
- `remote = true` - required for the installation of legacy 1.x add-ons
|
|
|
|
- `legacy = true` - required to install the 1.9 version of an add-on for which
|
|
|
|
- `legacy = true` - required to install the 1.9 version of an add-on for which
|
|
|
|
there is a 2.0 native version
|
|
|
|
there is a 2.0 native version
|
|
|
|
- `binding = ` - a comma separated list of the bindings from openHAB 1.x that
|
|
|
|
- `binding = ` - a comma separated list of the bindings from openHAB 1.x that
|
|
|
|
you use. If you are in doubt of the name of a binding, look in openhab.cfg for
|
|
|
|
you use. If you are in doubt of the name of a binding, look in openhab.cfg for
|
|
|
|
that binding's configurations. The first part of the tag in openhab.cfg will be
|
|
|
|
that binding's configurations. The first part of the tag in openhab.cfg will be
|
|
|
|
that name of the binding. For example, the configuration parameters for the
|
|
|
|
that name of the binding. For example, the configuration parameters for the
|
|
|
|
MQTT Binding start with "mqtt" in openhab.cfg so the name of the binding is
|
|
|
|
MQTT Binding start with "mqtt" in openhab.cfg so the name of the binding is
|
|
|
|
"mqtt". For those bindings that have a 2.0 version, use the name followed by a
|
|
|
|
"mqtt". For those bindings that have a 2.0 version, use the name followed by a
|
|
|
|
"1", for example, to use the 1.9 SNAPSHOT version of the Astro binding instead
|
|
|
|
"1", for example, to use the 1.9 SNAPSHOT version of the Astro binding instead
|
|
|
|
of the 2.0 version, use the name "astro1". You can find the list of 2.0
|
|
|
|
of the 2.0 version, use the name "astro1". You can find the list of 2.0
|
|
|
|
bindings [here]({{base}}/addons/bindings.html).
|
|
|
|
bindings [here]({{base}}/addons/bindings.html).
|
|
|
|
- `ui = ` - if you intend on using PaperUI include "paper", if you use zwave I
|
|
|
|
- `ui = ` - if you intend on using PaperUI include "paper", if you use zwave I
|
|
|
|
recommend "habmin". The list of UIs are [here]({{base}}/addons/uis.html).
|
|
|
|
recommend "habmin". The list of UIs are [here]({{base}}/addons/uis.html).
|
|
|
|
- `action = ` - the list of action add-ons you used in openHAB 1.x.
|
|
|
|
- `action = ` - the list of action add-ons you used in openHAB 1.x.
|
|
|
|
- `transformation = ` = the list of transformations you use. Unlike in openHAB 1,
|
|
|
|
- `transformation = ` = the list of transformations you use. Unlike in openHAB 1,
|
|
|
|
one must install transformations separately.
|
|
|
|
one must install transformations separately.
|
|
|
|
- `voice = ` - see [here]({{base}}/addons/voice.html)
|
|
|
|
- `voice = ` - see [here]({{base}}/addons/voice.html)
|
|
|
|
- `misc = ` - myopenhab, homekit, etc. Do not list myopenhab at this time,
|
|
|
|
- `misc = ` - myopenhab, homekit, etc. Do not list myopenhab at this time,
|
|
|
|
instructions for it are below.
|
|
|
|
instructions for it are below.
|
|
|
|
|
|
|
|
|
|
|
|
If you have any doubt as to what add-ons are available and in which category
|
|
|
|
If you have any doubt as to what add-ons are available and in which category
|
|
|
|
they belong you can follow the instructions below for listing the bundles in
|
|
|
|
they belong you can follow the instructions below for listing the bundles in
|
|
|
|
the Karaf console or install PaperUI and browse the list through it.
|
|
|
|
the Karaf console or install PaperUI and browse the list through it.
|
|
|
|
|
|
|
|
|
|
|
|
This is a great opportunity to identify those add-ons you are not actively
|
|
|
|
This is a great opportunity to identify those add-ons you are not actively
|
|
|
|
using and avoid their installation.
|
|
|
|
using and avoid their installation.
|
|
|
|
|
|
|
|
|
|
|
|
When you save this file openHAB will begin the download (if using the Online
|
|
|
|
When you save this file openHAB will begin the download (if using the Online
|
|
|
|
version) and installing the add-ons.
|
|
|
|
version) and installing the add-ons.
|
|
|
|
|
|
|
|
|
|
|
|
Note: if running in Docker, create <openHAB 2 home>/userdata/persistence prior to saving the
|
|
|
|
Note: if running in Docker, create <openHAB 2 home>/userdata/persistence prior to saving the
|
|
|
|
file if there are any persistence add-ons.
|
|
|
|
file if there are any persistence add-ons.
|
|
|
|
|
|
|
|
|
|
|
|
An example addons.cfg:
|
|
|
|
An example addons.cfg:
|
|
|
|
@ -215,7 +215,7 @@ package = standard
|
|
|
|
#
|
|
|
|
#
|
|
|
|
remote = true
|
|
|
|
remote = true
|
|
|
|
|
|
|
|
|
|
|
|
# Include legacy 1.x bindings. If set to true, it also allows the installation of 1.x bindings for which there is
|
|
|
|
# Include legacy 1.x bindings. If set to true, it also allows the installation of 1.x bindings for which there is
|
|
|
|
# already a 2.x version available (requires remote repo access, see above). (default is false)
|
|
|
|
# already a 2.x version available (requires remote repo access, see above). (default is false)
|
|
|
|
#
|
|
|
|
#
|
|
|
|
legacy = true
|
|
|
|
legacy = true
|
|
|
|
@ -257,7 +257,7 @@ Use `habopen` as the password.
|
|
|
|
See the [Karaf Reference]({{base}}/administration/console.html) for details about
|
|
|
|
See the [Karaf Reference]({{base}}/administration/console.html) for details about
|
|
|
|
navigating and using the console.
|
|
|
|
navigating and using the console.
|
|
|
|
|
|
|
|
|
|
|
|
Run the following command to see the list of add-on repositories currently
|
|
|
|
Run the following command to see the list of add-on repositories currently
|
|
|
|
installed.
|
|
|
|
installed.
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
```bash
|
|
|
|
@ -292,26 +292,26 @@ To get a list of all currently installed items run:
|
|
|
|
feature:list | grep Started
|
|
|
|
feature:list | grep Started
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
At this time only install add-ons that are 1.9.0 SNAPSHOT. The 2.0 add-ons will
|
|
|
|
At this time only install add-ons that are 1.9.0 SNAPSHOT. The 2.0 add-ons will
|
|
|
|
be installed later.
|
|
|
|
be installed later.
|
|
|
|
|
|
|
|
|
|
|
|
Note: if running in Docker, create `<openHAB home>/userdata/persistence` manually prior to
|
|
|
|
Note: if running in Docker, create `<openHAB home>/userdata/persistence` manually prior to
|
|
|
|
installing persistence add-ons.
|
|
|
|
installing persistence add-ons.
|
|
|
|
|
|
|
|
|
|
|
|
### PaperUI Approach
|
|
|
|
### PaperUI Approach
|
|
|
|
|
|
|
|
|
|
|
|
These instructions assume no edits have been made to `runtime.cfg` or
|
|
|
|
These instructions assume no edits have been made to `runtime.cfg` or
|
|
|
|
`addons.cfg` as described in the previous section.
|
|
|
|
`addons.cfg` as described in the previous section.
|
|
|
|
|
|
|
|
|
|
|
|
Navigate your browser to `http://<openhab server address>:8080` and select
|
|
|
|
Navigate your browser to `http://<openhab server address>:8080` and select
|
|
|
|
PaperUI from the list of UIs. Navigate to `Configuration -> System` on the left
|
|
|
|
PaperUI from the list of UIs. Navigate to `Configuration -> System` on the left
|
|
|
|
hand side and enable "Include Legacy 1.x Bindings" and "Access Remote
|
|
|
|
hand side and enable "Include Legacy 1.x Bindings" and "Access Remote
|
|
|
|
Repositories". This will allow you to install your current bindings even if
|
|
|
|
Repositories". This will allow you to install your current bindings even if
|
|
|
|
there is an openHAB 2 version available. Press "Save".
|
|
|
|
there is an openHAB 2 version available. Press "Save".
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Now select "Extensions" from the left and browse or search for each of the
|
|
|
|
Now select "Extensions" from the left and browse or search for each of the
|
|
|
|
bindings and add-ons you currently use. Make note of those that do not appear in
|
|
|
|
bindings and add-ons you currently use. Make note of those that do not appear in
|
|
|
|
the list. Do not install any binding that has a version 2.0. If there is not a
|
|
|
|
the list. Do not install any binding that has a version 2.0. If there is not a
|
|
|
|
1.9.0 version we will install the binding manually (see below).
|
|
|
|
1.9.0 version we will install the binding manually (see below).
|
|
|
|
@ -319,43 +319,43 @@ the list. Do not install any binding that has a version 2.0. If there is not a
|
|
|
|
This is a great opportunity to identify those bindings you actually use and
|
|
|
|
This is a great opportunity to identify those bindings you actually use and
|
|
|
|
only install those.
|
|
|
|
only install those.
|
|
|
|
|
|
|
|
|
|
|
|
When you find a binding to install, press the Install button and wait for
|
|
|
|
When you find a binding to install, press the Install button and wait for
|
|
|
|
installation to complete. Do not install the My.openHAB Binding yet.
|
|
|
|
installation to complete. Do not install the My.openHAB Binding yet.
|
|
|
|
|
|
|
|
|
|
|
|
If you are running openHAB in a Docker container you need to create
|
|
|
|
If you are running openHAB in a Docker container you need to create
|
|
|
|
`<openHAB home>/userdata/persistence` manually prior to installing a persistence
|
|
|
|
`<openHAB home>/userdata/persistence` manually prior to installing a persistence
|
|
|
|
add-on.
|
|
|
|
add-on.
|
|
|
|
|
|
|
|
|
|
|
|
One thing to be aware of is any configuration done in PaperUI or Habmin gets
|
|
|
|
One thing to be aware of is any configuration done in PaperUI or Habmin gets
|
|
|
|
saved to a non-human readable database. And since none of the administration
|
|
|
|
saved to a non-human readable database. And since none of the administration
|
|
|
|
UIs are currently capable of doing everything, you will end up with a mix of
|
|
|
|
UIs are currently capable of doing everything, you will end up with a mix of
|
|
|
|
database and text based configuration. This is why we recommend not using
|
|
|
|
database and text based configuration. This is why we recommend not using
|
|
|
|
PaperUI for those migrating to openHAB 2 from openHAB 1.x.
|
|
|
|
PaperUI for those migrating to openHAB 2 from openHAB 1.x.
|
|
|
|
|
|
|
|
|
|
|
|
### Configure Add-ons
|
|
|
|
### Configure Add-ons
|
|
|
|
|
|
|
|
|
|
|
|
As bindings and other add-ons are installed, you can watch for errors in the
|
|
|
|
As bindings and other add-ons are installed, you can watch for errors in the
|
|
|
|
logs. Errors at this time may not be important but make note of those that did
|
|
|
|
logs. Errors at this time may not be important but make note of those that did
|
|
|
|
generate errors during installation for special attention later.
|
|
|
|
generate errors during installation for special attention later.
|
|
|
|
|
|
|
|
|
|
|
|
Once a binding or add-on is installed, it will create a
|
|
|
|
Once a binding or add-on is installed, it will create a
|
|
|
|
`<openHAB 2 conf>/services/<add-on name>.cfg` file. Unlike in openHAB 1.x where all the
|
|
|
|
`<openHAB 2 conf>/services/<add-on name>.cfg` file. Unlike in openHAB 1.x where all the
|
|
|
|
binding configurations are placed in the one openhab.cfg file, openHAB 2 has a
|
|
|
|
binding configurations are placed in the one openhab.cfg file, openHAB 2 has a
|
|
|
|
separate .cfg file for each binding. Transfer the settings for each binding from
|
|
|
|
separate .cfg file for each binding. Transfer the settings for each binding from
|
|
|
|
openhab.cfg to its new .cfg file, removing the binding name from the parameter.
|
|
|
|
openhab.cfg to its new .cfg file, removing the binding name from the parameter.
|
|
|
|
For example, the parameter `nest:refresh=300000` in openhab.cfg becomes
|
|
|
|
For example, the parameter `nest:refresh=300000` in openhab.cfg becomes
|
|
|
|
`refresh=300000` in nest.cfg.
|
|
|
|
`refresh=300000` in nest.cfg.
|
|
|
|
|
|
|
|
|
|
|
|
Note that a .cfg file is not always generated. If one is not generated and it is
|
|
|
|
Note that a .cfg file is not always generated. If one is not generated and it is
|
|
|
|
a binding that has a section in openhab.cfg, you can create one yourself and
|
|
|
|
a binding that has a section in openhab.cfg, you can create one yourself and
|
|
|
|
transfer the settings as described above.
|
|
|
|
transfer the settings as described above.
|
|
|
|
|
|
|
|
|
|
|
|
One important thing to note is that bindings and add-ons that require extra steps to register
|
|
|
|
One important thing to note is that bindings and add-ons that require extra steps to register
|
|
|
|
with a cloud service like Nest and My.openHAB will require reregistering again
|
|
|
|
with a cloud service like Nest and My.openHAB will require reregistering again
|
|
|
|
as if this were the first installation and configuration (e.g. you need to
|
|
|
|
as if this were the first installation and configuration (e.g. you need to
|
|
|
|
generate a new pin code for Nest).
|
|
|
|
generate a new pin code for Nest).
|
|
|
|
|
|
|
|
|
|
|
|
Unlike in openHAB 1.x, transformations are not automatically included in
|
|
|
|
Unlike in openHAB 1.x, transformations are not automatically included in
|
|
|
|
openHAB 2. Make sure you include these in your installation as well.
|
|
|
|
openHAB 2. Make sure you include these in your installation as well.
|
|
|
|
|
|
|
|
|
|
|
|
### Installing Unofficially Supported openHAB 1.x Add-ons
|
|
|
|
### Installing Unofficially Supported openHAB 1.x Add-ons
|
|
|
|
@ -365,22 +365,22 @@ Skip this section if all the add-ons you need have been installed already.
|
|
|
|
First check the [list of add-ons that are known not to work in openHAB 2]({{base}}/addons/1xaddons.html#currently-incompatible-1x-add-ons)
|
|
|
|
First check the [list of add-ons that are known not to work in openHAB 2]({{base}}/addons/1xaddons.html#currently-incompatible-1x-add-ons)
|
|
|
|
and make sure yours is not among them.
|
|
|
|
and make sure yours is not among them.
|
|
|
|
|
|
|
|
|
|
|
|
Next install the openHAB 1.x compatibility layer using the Karaf Console
|
|
|
|
Next install the openHAB 1.x compatibility layer using the Karaf Console
|
|
|
|
instructions above.
|
|
|
|
instructions above.
|
|
|
|
|
|
|
|
|
|
|
|
Copy your openhab.cfg file to `<openHAB 2 conf>/services`. If you are running an apt-get
|
|
|
|
Copy your openhab.cfg file to `<openHAB 2 conf>/services`. If you are running an apt-get
|
|
|
|
installed openHAB 1.x openhab.cfg is located in `/etc/openhab/configurations`.
|
|
|
|
installed openHAB 1.x openhab.cfg is located in `/etc/openhab/configurations`.
|
|
|
|
For an apt-get installed openHAB 2 the `<openHAB 2 conf>` folder is located in
|
|
|
|
For an apt-get installed openHAB 2 the `<openHAB 2 conf>` folder is located in
|
|
|
|
`/etc/openhab2`. For manually installed openHAB 1.x this file is located
|
|
|
|
`/etc/openhab2`. For manually installed openHAB 1.x this file is located
|
|
|
|
in `<openhab home>/configurations` and in manually installed openHAB 2 it is
|
|
|
|
in `<openhab home>/configurations` and in manually installed openHAB 2 it is
|
|
|
|
`<openhab home>/conf`.
|
|
|
|
`<openhab home>/conf`.
|
|
|
|
|
|
|
|
|
|
|
|
This file will have a lot of redundant configuration information in it that you
|
|
|
|
This file will have a lot of redundant configuration information in it that you
|
|
|
|
have already moved over to individual binding .cfgs. Make sure to comment those
|
|
|
|
have already moved over to individual binding .cfgs. Make sure to comment those
|
|
|
|
out and just leave the config parameters for the bindings you are manually
|
|
|
|
out and just leave the config parameters for the bindings you are manually
|
|
|
|
installing.
|
|
|
|
installing.
|
|
|
|
|
|
|
|
|
|
|
|
Now copy the add-on's jar files that you want to install to the `<openHAB conf>/addons` folder for
|
|
|
|
Now copy the add-on's jar files that you want to install to the `<openHAB conf>/addons` folder for
|
|
|
|
openHAB 2. For example:
|
|
|
|
openHAB 2. For example:
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
```bash
|
|
|
|
@ -388,11 +388,11 @@ cp /usr/share/openhab/addons/org.openhab.binding.astro-1.8.3.jar /usr/share/open
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
There may be some errors about there not being a `bind` and `unbind` method. If
|
|
|
|
There may be some errors about there not being a `bind` and `unbind` method. If
|
|
|
|
everything worked you should see in the log the same entries from the binding
|
|
|
|
everything worked you should see in the log the same entries from the binding
|
|
|
|
you see when openHAB 1.x starts.
|
|
|
|
you see when openHAB 1.x starts.
|
|
|
|
|
|
|
|
|
|
|
|
Watch the logs for errors as they can be informative. For example, some Actions
|
|
|
|
Watch the logs for errors as they can be informative. For example, some Actions
|
|
|
|
require a corresponding Binding be installed first. An example error of this
|
|
|
|
require a corresponding Binding be installed first. An example error of this
|
|
|
|
sort looks like:
|
|
|
|
sort looks like:
|
|
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
```text
|
|
|
|
@ -401,12 +401,12 @@ org.osgi.framework.BundleException: Could not resolve module: org.openhab.action
|
|
|
|
Unresolved requirement: Import-Package: org.openhab.binding.astro.internal.calc
|
|
|
|
Unresolved requirement: Import-Package: org.openhab.binding.astro.internal.calc
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Note, the above error is for illustration purposes. You should not be
|
|
|
|
Note, the above error is for illustration purposes. You should not be
|
|
|
|
installing Astro this way.
|
|
|
|
installing Astro this way.
|
|
|
|
|
|
|
|
|
|
|
|
### Final Add-ons Installation Steps
|
|
|
|
### Final Add-ons Installation Steps
|
|
|
|
|
|
|
|
|
|
|
|
openHAB 2 has a different
|
|
|
|
openHAB 2 has a different
|
|
|
|
[folder layout]({{base}}/installation/linux.html#file-locations).
|
|
|
|
[folder layout]({{base}}/installation/linux.html#file-locations).
|
|
|
|
Of particular node are the configuration folders and userdata folders. See the
|
|
|
|
Of particular node are the configuration folders and userdata folders. See the
|
|
|
|
previous link for the location of these folders for your installtion.
|
|
|
|
previous link for the location of these folders for your installtion.
|
|
|
|
@ -414,11 +414,11 @@ previous link for the location of these folders for your installtion.
|
|
|
|
As with openHAB 1.x, one must restart openHAB 2 to pick up changes to .cfg files.
|
|
|
|
As with openHAB 1.x, one must restart openHAB 2 to pick up changes to .cfg files.
|
|
|
|
Therefore restart openHAB 2 now.
|
|
|
|
Therefore restart openHAB 2 now.
|
|
|
|
|
|
|
|
|
|
|
|
If you haven't already, configure default persistence now. You can do this
|
|
|
|
If you haven't already, configure default persistence now. You can do this
|
|
|
|
through `runtime.cfg` or PaperUI.
|
|
|
|
through `runtime.cfg` or PaperUI.
|
|
|
|
|
|
|
|
|
|
|
|
Now openHAB 2 is ready to receive your other configurations, items and such.
|
|
|
|
Now openHAB 2 is ready to receive your other configurations, items and such.
|
|
|
|
Watch the log file as you transfer over files for errors. These errors will
|
|
|
|
Watch the log file as you transfer over files for errors. These errors will
|
|
|
|
have to be fixed.
|
|
|
|
have to be fixed.
|
|
|
|
|
|
|
|
|
|
|
|
Copy over your files in the following order:
|
|
|
|
Copy over your files in the following order:
|
|
|
|
@ -444,9 +444,9 @@ Items may use.
|
|
|
|
|
|
|
|
|
|
|
|
The **SCALE** transformation has evolved.
|
|
|
|
The **SCALE** transformation has evolved.
|
|
|
|
|
|
|
|
|
|
|
|
- Old syntax that was `[minbound,maxbound]` has to be changed to
|
|
|
|
- Old syntax that was `[minbound,maxbound]` has to be changed to
|
|
|
|
`[minbound..maxbound]`.
|
|
|
|
`[minbound..maxbound]`.
|
|
|
|
- Note that you now have the ability to exclude bounds from the ranges (e.g.
|
|
|
|
- Note that you now have the ability to exclude bounds from the ranges (e.g.
|
|
|
|
`]minbound..maxbound]`) and also define open ranges`[minbound..]`
|
|
|
|
`]minbound..maxbound]`) and also define open ranges`[minbound..]`
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@ -456,39 +456,39 @@ If you use png icons, you must change the default icons from svg to png for
|
|
|
|
ClassicUI and BasicUI. This can be done in PaperUI in `Configuration -> Service -> BasicUI and ClassicUI`.
|
|
|
|
ClassicUI and BasicUI. This can be done in PaperUI in `Configuration -> Service -> BasicUI and ClassicUI`.
|
|
|
|
Set the "Default Icon Format" to "Bitmap".
|
|
|
|
Set the "Default Icon Format" to "Bitmap".
|
|
|
|
|
|
|
|
|
|
|
|
Note that not all of the default icons that came with openHAB 1.x are avaialble
|
|
|
|
Note that not all of the default icons that came with openHAB 1.x are avaialble
|
|
|
|
in the default set for openHAB 2. If you are missing an icon in your sitemap
|
|
|
|
in the default set for openHAB 2. If you are missing an icon in your sitemap
|
|
|
|
that could be the cause. The full list of openHAB 2 icons is [here]({{base}}/addons/iconsets/classic/readme.html).
|
|
|
|
that could be the cause. The full list of openHAB 2 icons is [here]({{base}}/addons/iconsets/classic/readme.html).
|
|
|
|
|
|
|
|
|
|
|
|
Also, in openHAB 2 there is a new requirement for dynamic icons: there must be a
|
|
|
|
Also, in openHAB 2 there is a new requirement for dynamic icons: there must be a
|
|
|
|
default. For example, if one has a bunch of Wunderground icons (e.g.
|
|
|
|
default. For example, if one has a bunch of Wunderground icons (e.g.
|
|
|
|
wunderground-chanceflurries.png) there mst be a `wunderground.png` icon as well.
|
|
|
|
wunderground-chanceflurries.png) there mst be a `wunderground.png` icon as well.
|
|
|
|
|
|
|
|
|
|
|
|
Note that the path to the Sitemap UIs have changed. If one goes
|
|
|
|
Note that the path to the Sitemap UIs have changed. If one goes
|
|
|
|
to `http://<hostname>:8080` you will see a list of all the installed UIs,
|
|
|
|
to `http://<hostname>:8080` you will see a list of all the installed UIs,
|
|
|
|
including the administration UIs. To get to ClassicUI the URL is
|
|
|
|
including the administration UIs. To get to ClassicUI the URL is
|
|
|
|
`http://<hostname>:8080/classicui/app?sitemap=<your sitemap>`. If you previously
|
|
|
|
`http://<hostname>:8080/classicui/app?sitemap=<your sitemap>`. If you previously
|
|
|
|
used `default.sitemap` as your file name so you could skip the `?sitemap=` part
|
|
|
|
used `default.sitemap` as your file name so you could skip the `?sitemap=` part
|
|
|
|
you must now rename the file to `_default.sitemap` and change the very first
|
|
|
|
you must now rename the file to `_default.sitemap` and change the very first
|
|
|
|
line of the file to read `sitemap _default label="<sitemap name>`.
|
|
|
|
line of the file to read `sitemap _default label="<sitemap name>`.
|
|
|
|
|
|
|
|
|
|
|
|
openHAB changes where the files for dynamic webviews like the one created for the
|
|
|
|
openHAB changes where the files for dynamic webviews like the one created for the
|
|
|
|
Weather Binding in openHAB 1.x. Instead of the deeply buried `/usr/share/openhab/webapps`
|
|
|
|
Weather Binding in openHAB 1.x. Instead of the deeply buried `/usr/share/openhab/webapps`
|
|
|
|
the files are placed in `<openHAB 2 conf>/html`. For example, if following the
|
|
|
|
the files are placed in `<openHAB 2 conf>/html`. For example, if following the
|
|
|
|
1.x Weather Binding tutorial for a dynamic webview, one would create a
|
|
|
|
1.x Weather Binding tutorial for a dynamic webview, one would create a
|
|
|
|
`<openHAB 2 conf>/html/weather` folder and put the `images` and layout folders there.o
|
|
|
|
`<openHAB 2 conf>/html/weather` folder and put the `images` and layout folders there.o
|
|
|
|
|
|
|
|
|
|
|
|
### Rules
|
|
|
|
### Rules
|
|
|
|
One set of errors that will occur in rules that refer to the packages of openHAB
|
|
|
|
One set of errors that will occur in rules that refer to the packages of openHAB
|
|
|
|
core classes (e.g. org.openhabs.core.*). These classes have moved to
|
|
|
|
core classes (e.g. org.openhabs.core.*). These classes have moved to
|
|
|
|
org.eclipse.smarthome.core.*. Furthermore, these classes as well as the Joda
|
|
|
|
org.eclipse.smarthome.core.*. Furthermore, these classes as well as the Joda
|
|
|
|
time classes no longer need to be imported.
|
|
|
|
time classes no longer need to be imported.
|
|
|
|
|
|
|
|
|
|
|
|
In addition, to test an Item to see if it is Undefined one tests against `NULL`
|
|
|
|
In addition, to test an Item to see if it is Undefined one tests against `NULL`
|
|
|
|
instead of `Undefined`. For example `if(MyItem.state == Undefined)` becomes
|
|
|
|
instead of `Undefined`. For example `if(MyItem.state == Undefined)` becomes
|
|
|
|
`if(MyItem.state == NULL)`. Note that `NULL` is not to be confused with `null`.
|
|
|
|
`if(MyItem.state == NULL)`. Note that `NULL` is not to be confused with `null`.
|
|
|
|
`NULL` is only valid when testing an Item's state to see if it is undefined.
|
|
|
|
`NULL` is only valid when testing an Item's state to see if it is undefined.
|
|
|
|
`null` is used pretty much everywhere else to mean "no value" and usually
|
|
|
|
`null` is used pretty much everywhere else to mean "no value" and usually
|
|
|
|
indicates no result or an error.
|
|
|
|
indicates no result or an error.
|
|
|
|
|
|
|
|
|
|
|
|
Finally, the `HSBType` state type can no longer be constructed using a `java.awt.Color` object, and there is no longer a `toColor()` method. Use the following alternatives:
|
|
|
|
Finally, the `HSBType` state type can no longer be constructed using a `java.awt.Color` object, and there is no longer a `toColor()` method. Use the following alternatives:
|
|
|
|
@ -498,60 +498,60 @@ var HSBType hsb = HSBType::fromRGB(color.red, color.green, color.blue)
|
|
|
|
var Color color = Color::getHSBColor(hsb.hue.floatValue / 360, hsb.saturation.floatValue / 100, hsb.brightness.floatValue / 100)
|
|
|
|
var Color color = Color::getHSBColor(hsb.hue.floatValue / 360, hsb.saturation.floatValue / 100, hsb.brightness.floatValue / 100)
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Continue watching the logs as you move files over. There will likely be a number
|
|
|
|
Continue watching the logs as you move files over. There will likely be a number
|
|
|
|
of errors. Take note of them with plans to return and correct them if they
|
|
|
|
of errors. Take note of them with plans to return and correct them if they
|
|
|
|
persist.
|
|
|
|
persist.
|
|
|
|
|
|
|
|
|
|
|
|
## Testing
|
|
|
|
## Testing
|
|
|
|
|
|
|
|
|
|
|
|
- **Items**: Watch `<openHAB 2 userdata>/logs/events.log` and methodically work through all
|
|
|
|
- **Items**: Watch `<openHAB 2 userdata>/logs/events.log` and methodically work through all
|
|
|
|
of your Items activating and deactivating them one-by-one to verify the events
|
|
|
|
of your Items activating and deactivating them one-by-one to verify the events
|
|
|
|
appear in the logs as expected. This may require running openHAB 2 for some
|
|
|
|
appear in the logs as expected. This may require running openHAB 2 for some
|
|
|
|
period of time and/or writing new rules, using the REST API, or external scripts
|
|
|
|
period of time and/or writing new rules, using the REST API, or external scripts
|
|
|
|
to exercise all the Items.
|
|
|
|
to exercise all the Items.
|
|
|
|
- **Persistence**: Check your persistence locations to see if all your persisted
|
|
|
|
- **Persistence**: Check your persistence locations to see if all your persisted
|
|
|
|
Items are listed, if possible. Check your charts on your sitemap to make sure
|
|
|
|
Items are listed, if possible. Check your charts on your sitemap to make sure
|
|
|
|
they are being updated. Check openhab.log or the Karaf console log:tail for
|
|
|
|
they are being updated. Check openhab.log or the Karaf console log:tail for
|
|
|
|
errors when Rules call persistence methods to get historical data (e.g.
|
|
|
|
errors when Rules call persistence methods to get historical data (e.g.
|
|
|
|
lastUpdate). Restart openHAB and verify those Items configured with
|
|
|
|
lastUpdate). Restart openHAB and verify those Items configured with
|
|
|
|
restoreOnStartup are initialized to their last state.
|
|
|
|
restoreOnStartup are initialized to their last state.
|
|
|
|
- **Rules**: When you first copy over your rules there will be many errors,
|
|
|
|
- **Rules**: When you first copy over your rules there will be many errors,
|
|
|
|
particularly if the rules assume that all Items have a state. One can easily
|
|
|
|
particularly if the rules assume that all Items have a state. One can easily
|
|
|
|
forget to check for NULL in an openHAB instance that has been running for some
|
|
|
|
forget to check for NULL in an openHAB instance that has been running for some
|
|
|
|
time and one is using restoreOnStartup. But because this is a brand new instance
|
|
|
|
time and one is using restoreOnStartup. But because this is a brand new instance
|
|
|
|
there are no values in the database to restore the Items to when openHAB starts.
|
|
|
|
there are no values in the database to restore the Items to when openHAB starts.
|
|
|
|
- **Sitemap**: The most
|
|
|
|
- **Sitemap**: The most
|
|
|
|
common Sitemap issue will be missing icons. Browse through your sitemap
|
|
|
|
common Sitemap issue will be missing icons. Browse through your sitemap
|
|
|
|
methodically and identify those entries that have a missing or wrong
|
|
|
|
methodically and identify those entries that have a missing or wrong
|
|
|
|
icon. Select an alternative from the [defaults]({{base}}/addons/iconsets/classic/readme.html)
|
|
|
|
icon. Select an alternative from the [defaults]({{base}}/addons/iconsets/classic/readme.html)
|
|
|
|
or copy the one you were using from openHAB 1.x to the conf/icons/classic folder.
|
|
|
|
or copy the one you were using from openHAB 1.x to the conf/icons/classic folder.
|
|
|
|
Both BasicUI and ClassicUI pull their icons from that folder. For a sitemap that
|
|
|
|
Both BasicUI and ClassicUI pull their icons from that folder. For a sitemap that
|
|
|
|
most closely resembles your current sitemap I recommend using ClassicUI.
|
|
|
|
most closely resembles your current sitemap I recommend using ClassicUI.
|
|
|
|
|
|
|
|
|
|
|
|
Once you are satisfied that your new openHAB system is up and running take a
|
|
|
|
Once you are satisfied that your new openHAB system is up and running take a
|
|
|
|
deep breath and take a break. Let it run for a few days or a week and verify
|
|
|
|
deep breath and take a break. Let it run for a few days or a week and verify
|
|
|
|
that everything is working as it should. Watch the logs for inexplicable errors.
|
|
|
|
that everything is working as it should. Watch the logs for inexplicable errors.
|
|
|
|
Once you are happy with how it is running you can start migrating to the openHAB
|
|
|
|
Once you are happy with how it is running you can start migrating to the openHAB
|
|
|
|
2 native bindings and start taking advantage of Things and Channels (see the
|
|
|
|
2 native bindings and start taking advantage of Things and Channels (see the
|
|
|
|
next section).
|
|
|
|
next section).
|
|
|
|
|
|
|
|
|
|
|
|
Now is also a good time to install [Eclipse SmartHome Designer](https://www.eclipse.org/smarthome/documentation/community/downloads.html)
|
|
|
|
Now is also a good time to install [Eclipse SmartHome Designer](https://www.eclipse.org/smarthome/documentation/community/downloads.html)
|
|
|
|
to edit and review your files.
|
|
|
|
to edit and review your files.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## New Concepts: Things and Channels
|
|
|
|
## New Concepts: Things and Channels
|
|
|
|
|
|
|
|
|
|
|
|
One of the new notions that people quickly come across when moving to openHAB 2
|
|
|
|
One of the new notions that people quickly come across when moving to openHAB 2
|
|
|
|
native bindings is that of a ["Thing"]({{base}}/concepts/things.html). To understand
|
|
|
|
native bindings is that of a ["Thing"]({{base}}/concepts/things.html). To understand
|
|
|
|
what they are and how they relate to Items, we will compare them to how Items
|
|
|
|
what they are and how they relate to Items, we will compare them to how Items
|
|
|
|
are "bound" and configured in openHAB 1.x.
|
|
|
|
are "bound" and configured in openHAB 1.x.
|
|
|
|
|
|
|
|
|
|
|
|
In openHAB 1.x (and importantly still for 1.9 version bindings running in openHAB
|
|
|
|
In openHAB 1.x (and importantly still for 1.9 version bindings running in openHAB
|
|
|
|
2) one had to add
|
|
|
|
2) one had to add
|
|
|
|
["binding configuration"](https://github.com/openhab/openhab/wiki/Explanation-of-items#binding-config)
|
|
|
|
["binding configuration"](https://github.com/openhab/openhab/wiki/Explanation-of-items#binding-config)
|
|
|
|
in curly brackets to the end of Item definitions in order to link that Item to
|
|
|
|
in curly brackets to the end of Item definitions in order to link that Item to
|
|
|
|
some control point on a physical device or API. The
|
|
|
|
some control point on a physical device or API. The
|
|
|
|
[openHAB wiki](https://github.com/openhab/openhab/wiki) gives a nice examples of
|
|
|
|
[openHAB wiki](https://github.com/openhab/openhab/wiki) gives a nice examples of
|
|
|
|
how this looks:
|
|
|
|
how this looks:
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
```java
|
|
|
|
@ -563,31 +563,31 @@ String Error_Ventilation "Error in Ventilation %s" { comfoair="error_mes
|
|
|
|
Number DiningRoomTemp "Maximum Away Temp. [%.1f °F]" { nest="<[thermostats(Dining Room).away_temperature_high_f]" }
|
|
|
|
Number DiningRoomTemp "Maximum Away Temp. [%.1f °F]" { nest="<[thermostats(Dining Room).away_temperature_high_f]" }
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Every binding came up with its own syntax for this binding configuration and
|
|
|
|
Every binding came up with its own syntax for this binding configuration and
|
|
|
|
while the rest of the item file had nice syntax checks and content assist when
|
|
|
|
while the rest of the item file had nice syntax checks and content assist when
|
|
|
|
using Designer, this wasn't possible to provide for the binding configurations
|
|
|
|
using Designer, this wasn't possible to provide for the binding configurations
|
|
|
|
themselves. The only way for the user to figure out what to put in there was to
|
|
|
|
themselves. The only way for the user to figure out what to put in there was to
|
|
|
|
visit the wiki page of the binding. This not only are syntax errors and typos
|
|
|
|
visit the wiki page of the binding. This not only are syntax errors and typos
|
|
|
|
difficult to detest but it also prevents any "automated" editing of the binding
|
|
|
|
difficult to detest but it also prevents any "automated" editing of the binding
|
|
|
|
configurations, e.g. through user-friendly UIs.
|
|
|
|
configurations, e.g. through user-friendly UIs.
|
|
|
|
|
|
|
|
|
|
|
|
Besides the syntax, the old scheme leaves the binding developers the choice to
|
|
|
|
Besides the syntax, the old scheme leaves the binding developers the choice to
|
|
|
|
implement multi-instance support or not. Usually most bindings started off
|
|
|
|
implement multi-instance support or not. Usually most bindings started off
|
|
|
|
supporting a single instance only to notice later on that it would be useful to
|
|
|
|
supporting a single instance only to notice later on that it would be useful to
|
|
|
|
add support for more than one. For example, you can see in the KNX binding
|
|
|
|
add support for more than one. For example, you can see in the KNX binding
|
|
|
|
configuration above that it simply does not allow one to select an interface
|
|
|
|
configuration above that it simply does not allow one to select an interface
|
|
|
|
(KNX system) to use for that Item. Instead, a single globally configured
|
|
|
|
(KNX system) to use for that Item. Instead, a single globally configured
|
|
|
|
connection is defined in the openhab.cfg file.
|
|
|
|
connection is defined in the openhab.cfg file.
|
|
|
|
|
|
|
|
|
|
|
|
These issues were identified
|
|
|
|
These issues were identified
|
|
|
|
[a long time ago](https://groups.google.com/d/msg/openhab/NSiveF9U1vk/PVLemrdrpVsJ)
|
|
|
|
[a long time ago](https://groups.google.com/d/msg/openhab/NSiveF9U1vk/PVLemrdrpVsJ)
|
|
|
|
and the concept of
|
|
|
|
and the concept of
|
|
|
|
[Things and Channels](https://www.eclipse.org/forums/index.php/t/668424/)
|
|
|
|
[Things and Channels](https://www.eclipse.org/forums/index.php/t/668424/)
|
|
|
|
were introduced to solve them. The general idea is to standardize
|
|
|
|
were introduced to solve them. The general idea is to standardize
|
|
|
|
the binding configuration and move it away from the .items file. A Thing
|
|
|
|
the binding configuration and move it away from the .items file. A Thing
|
|
|
|
represents a configurable device/system/unit, which provides different
|
|
|
|
represents a configurable device/system/unit, which provides different
|
|
|
|
functionality through a set of one or more Channels. Each Channel corresponds
|
|
|
|
functionality through a set of one or more Channels. Each Channel corresponds
|
|
|
|
exactly to one binding configuration string (stuff in { }) in openHAB 1.x.
|
|
|
|
exactly to one binding configuration string (stuff in { }) in openHAB 1.x.
|
|
|
|
|
|
|
|
|
|
|
|
Let's look at a concrete example. The [Yahoo Weather Binding]({{base}}/addons/bindings/yahooweather/readme.html)
|
|
|
|
Let's look at a concrete example. The [Yahoo Weather Binding]({{base}}/addons/bindings/yahooweather/readme.html)
|
|
|
|
supports exactly one Thing which takes two parameters: a WOEID location and unit.
|
|
|
|
supports exactly one Thing which takes two parameters: a WOEID location and unit.
|
|
|
|
@ -609,7 +609,7 @@ Number Temperature { yahooweather="woeid=638242,value=temperature,unit=c" }
|
|
|
|
Number Humidity { yahooweather="woeid=638242,value=humidity,unit=c" }
|
|
|
|
Number Humidity { yahooweather="woeid=638242,value=humidity,unit=c" }
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
with everything defined on in the { } part of the Item, we now merely reference
|
|
|
|
with everything defined on in the { } part of the Item, we now merely reference
|
|
|
|
the Channels.
|
|
|
|
the Channels.
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
```java
|
|
|
|
@ -618,13 +618,13 @@ Number Temperature { channel="yahooweather:weather:berlin#temperature" }
|
|
|
|
Number Humidity { channel="yahooweather:weather:berlin#humidity" }
|
|
|
|
Number Humidity { channel="yahooweather:weather:berlin#humidity" }
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
As you can see, the Channel ID consists of the Thing's name, a "#" and the
|
|
|
|
As you can see, the Channel ID consists of the Thing's name, a "#" and the
|
|
|
|
Channel name.
|
|
|
|
Channel name.
|
|
|
|
|
|
|
|
|
|
|
|
For manually defined Things, you can find the syntax for defining a Thing on a
|
|
|
|
For manually defined Things, you can find the syntax for defining a Thing on a
|
|
|
|
given Item in that Binding's readme.
|
|
|
|
given Item in that Binding's readme.
|
|
|
|
|
|
|
|
|
|
|
|
However, with the concept of Things some openHAB 2.0 bindings are able to
|
|
|
|
However, with the concept of Things some openHAB 2 bindings are able to
|
|
|
|
automatically discover and create Things for you. These automatically created
|
|
|
|
automatically discover and create Things for you. These automatically created
|
|
|
|
Things will appear in your Inbox which you can access in PaperUI, Habmin, or
|
|
|
|
Things will appear in your Inbox which you can access in PaperUI, Habmin, or
|
|
|
|
the Karaf console. These Things can be accepted by the user. When you view these
|
|
|
|
the Karaf console. These Things can be accepted by the user. When you view these
|
|
|
|
@ -633,8 +633,8 @@ Thing supports. To define an Item for one of these Channels, simply copy the
|
|
|
|
Channel ID into your Item's definition like the above.
|
|
|
|
Channel ID into your Item's definition like the above.
|
|
|
|
|
|
|
|
|
|
|
|
Finally, I will reiterate, Things and Channels only exist for 2.0 version bindings.
|
|
|
|
Finally, I will reiterate, Things and Channels only exist for 2.0 version bindings.
|
|
|
|
Any 1.9 bindings still use the traditional binding configuration as described on
|
|
|
|
Any 1.9 bindings still use the traditional binding configuration as described on
|
|
|
|
the [openHAB 1.x wiki](https://github.com/openhab/openhab/wiki).
|
|
|
|
the [openHAB 1.x wiki](https://github.com/openhab/openhab/wiki).
|
|
|
|
|
|
|
|
|
|
|
|
## Retire openHAB 1.x
|
|
|
|
## Retire openHAB 1.x
|
|
|
|
|
|
|
|
|
|
|
|
@ -662,8 +662,8 @@ Back up your openHAB 1.x configurations and uninstall openHAB 1.x if desired.
|
|
|
|
|
|
|
|
|
|
|
|
### Eclipse SmartHome Designer
|
|
|
|
### Eclipse SmartHome Designer
|
|
|
|
|
|
|
|
|
|
|
|
As mentioned above, there is a new Integrated Development Environment (IDE) for
|
|
|
|
As mentioned above, there is a new Integrated Development Environment (IDE) for
|
|
|
|
openHAB 2 configurations,
|
|
|
|
openHAB 2 configurations,
|
|
|
|
[Eclipse SmartHome Designer](https://www.eclipse.org/smarthome/documentation/community/downloads.html).
|
|
|
|
[Eclipse SmartHome Designer](https://www.eclipse.org/smarthome/documentation/community/downloads.html).
|
|
|
|
The old openHAB Designer is not compatible with openHAB 2.
|
|
|
|
The old openHAB Designer is not compatible with openHAB 2.
|
|
|
|
|
|
|
|
|
|
|
|
@ -677,9 +677,9 @@ binding until now.
|
|
|
|
Each openHAB instance generates its own unique UUID and Secret so one cannot simply
|
|
|
|
Each openHAB instance generates its own unique UUID and Secret so one cannot simply
|
|
|
|
copy these files from your old openHAB 1.x installation.
|
|
|
|
copy these files from your old openHAB 1.x installation.
|
|
|
|
|
|
|
|
|
|
|
|
Using your preferred method for add-on installation (see above) install the
|
|
|
|
Using your preferred method for add-on installation (see above) install the
|
|
|
|
My.openHAB binding. Once installed a new `uuid` and `secret` file will be created.
|
|
|
|
My.openHAB binding. Once installed a new `uuid` and `secret` file will be created.
|
|
|
|
These two files are located in a different place in openHAB 2:
|
|
|
|
These two files are located in a different place in openHAB 2:
|
|
|
|
`<openhab 2 userdata>/uuid` and `<openHAB 2 userdata>/myopenhab/secret`.
|
|
|
|
`<openhab 2 userdata>/uuid` and `<openHAB 2 userdata>/myopenhab/secret`.
|
|
|
|
As of this writing, the http://my.openhab.org documentation still references the
|
|
|
|
As of this writing, the http://my.openhab.org documentation still references the
|
|
|
|
openHAB 1.x locations.
|
|
|
|
openHAB 1.x locations.
|
|
|
|
@ -699,11 +699,11 @@ should now show your system as being online and running openHAB 2.
|
|
|
|
|
|
|
|
|
|
|
|
### Other Bindings
|
|
|
|
### Other Bindings
|
|
|
|
|
|
|
|
|
|
|
|
One is not required to use 2.0 version addi-ons with openHAB 2. It is highly
|
|
|
|
One is not required to use 2.0 version addi-ons with openHAB 2. It is highly
|
|
|
|
recommended to do so as most cases where there is a 1.9 and a 2.0 add-on only the
|
|
|
|
recommended to do so as most cases where there is a 1.9 and a 2.0 add-on only the
|
|
|
|
2.0 binding is undergoing continued development. On-the-other-hand, some of the
|
|
|
|
2.0 binding is undergoing continued development. On-the-other-hand, some of the
|
|
|
|
2.0 bindings are currently lacking certain features their older version has (e.g.
|
|
|
|
2.0 bindings are currently lacking certain features their older version has (e.g.
|
|
|
|
Astro). See the add-on's [wiki page]({{base}}/addons/1xaddons.html) and
|
|
|
|
Astro). See the add-on's [wiki page]({{base}}/addons/1xaddons.html) and
|
|
|
|
[readme page]({{base}}/addons/bindings.html) to compare and contrast the two versions.
|
|
|
|
[readme page]({{base}}/addons/bindings.html) to compare and contrast the two versions.
|
|
|
|
|
|
|
|
|
|
|
|
Identify an add-on where there is a 2.0 version that you want to migrate to. Begin
|
|
|
|
Identify an add-on where there is a 2.0 version that you want to migrate to. Begin
|
|
|
|
@ -723,20 +723,20 @@ grep astro /opt/openhab2/conf/items/*
|
|
|
|
Now comment out those Items to ensure there are no unexpected interactions between
|
|
|
|
Now comment out those Items to ensure there are no unexpected interactions between
|
|
|
|
the old configurations and the new ones.
|
|
|
|
the old configurations and the new ones.
|
|
|
|
|
|
|
|
|
|
|
|
Next uninstall the 1.9 binding. In the Karaf console use the command
|
|
|
|
Next uninstall the 1.9 binding. In the Karaf console use the command
|
|
|
|
`feature:uninstall <add-on name>`. If you used addons.cfg to install the addons you
|
|
|
|
`feature:uninstall <add-on name>`. If you used addons.cfg to install the addons you
|
|
|
|
must uninstall it using the Karaf console. In PaperUI, browse to the add-on and
|
|
|
|
must uninstall it using the Karaf console. In PaperUI, browse to the add-on and
|
|
|
|
choose uninstall.
|
|
|
|
choose uninstall.
|
|
|
|
|
|
|
|
|
|
|
|
Move the add-on's .cfg file to a backup location. Some bindings have significantly
|
|
|
|
Move the add-on's .cfg file to a backup location. Some bindings have significantly
|
|
|
|
changed their configurations but much of the old information will still be
|
|
|
|
changed their configurations but much of the old information will still be
|
|
|
|
relevant.
|
|
|
|
relevant.
|
|
|
|
|
|
|
|
|
|
|
|
Install the 2.0 version of the add-on using your preferred method as described
|
|
|
|
Install the 2.0 version of the add-on using your preferred method as described
|
|
|
|
above. If this is the zwave binding, install the Habmin UI at this time as well if
|
|
|
|
above. If this is the zwave binding, install the Habmin UI at this time as well if
|
|
|
|
you have not done so already.
|
|
|
|
you have not done so already.
|
|
|
|
|
|
|
|
|
|
|
|
Configure the add-on as described in the add-on's readme file. Once it is properly
|
|
|
|
Configure the add-on as described in the add-on's readme file. Once it is properly
|
|
|
|
configured and if the binding supports automatic Thing discovery, new Things will
|
|
|
|
configured and if the binding supports automatic Thing discovery, new Things will
|
|
|
|
start to slowly appear in the Inbox. If left on its own this process can take five
|
|
|
|
start to slowly appear in the Inbox. If left on its own this process can take five
|
|
|
|
minutes to an hour. However, one can press the scan button in PaperUI -> Inbox to
|
|
|
|
minutes to an hour. However, one can press the scan button in PaperUI -> Inbox to
|
|
|
|
@ -750,11 +750,11 @@ smarthome:discovery openhab-binding-<binding name>
|
|
|
|
|
|
|
|
|
|
|
|
### Managing the Inbox using PaperUI
|
|
|
|
### Managing the Inbox using PaperUI
|
|
|
|
|
|
|
|
|
|
|
|
In PaperUI, review the Items in the Inbox and accept those that should be included
|
|
|
|
In PaperUI, review the Items in the Inbox and accept those that should be included
|
|
|
|
in your configuration. You can press the eye icon to hide the Thing from the list
|
|
|
|
in your configuration. You can press the eye icon to hide the Thing from the list
|
|
|
|
if you never plan on including it, such as a dead zwave node. Once approved
|
|
|
|
if you never plan on including it, such as a dead zwave node. Once approved
|
|
|
|
browsing to the Configuration -> Things menus and selecting the Thing from the list
|
|
|
|
browsing to the Configuration -> Things menus and selecting the Thing from the list
|
|
|
|
one can get the list of Channel IDs for that Thing.
|
|
|
|
one can get the list of Channel IDs for that Thing.
|
|
|
|
|
|
|
|
|
|
|
|
### Managing the Inbox Using the Karaf Console
|
|
|
|
### Managing the Inbox Using the Karaf Console
|
|
|
|
|
|
|
|
|
|
|
|
@ -796,7 +796,7 @@ smarthome:inbox ignore <thingId>
|
|
|
|
### Linking Channels to Items
|
|
|
|
### Linking Channels to Items
|
|
|
|
|
|
|
|
|
|
|
|
There is more than one way to link Channels to Items using PaperUI, Karaf console,
|
|
|
|
There is more than one way to link Channels to Items using PaperUI, Karaf console,
|
|
|
|
and through the text configuration files. Only the text configuration files are
|
|
|
|
and through the text configuration files. Only the text configuration files are
|
|
|
|
covered here as they are closer to the openHAB 1.x way of doing things and will
|
|
|
|
covered here as they are closer to the openHAB 1.x way of doing things and will
|
|
|
|
cause the least amount of work to migrate.
|
|
|
|
cause the least amount of work to migrate.
|
|
|
|
|
|
|
|
|
|
|
|
@ -814,21 +814,21 @@ becomes
|
|
|
|
Switch S_L_Family "Family Room Lamp" <light> {channel="zwave:device:528f7aca:node10:switch_binary"}
|
|
|
|
Switch S_L_Family "Family Room Lamp" <light> {channel="zwave:device:528f7aca:node10:switch_binary"}
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Congratulations, you are now using the 2.0 version of the binding. Assuming the
|
|
|
|
Congratulations, you are now using the 2.0 version of the binding. Assuming the
|
|
|
|
behaviors of the binding are the same, there should be no required changes to your
|
|
|
|
behaviors of the binding are the same, there should be no required changes to your
|
|
|
|
Rules, Sitemaps, or Persitence. Test your Items each step of the way to verify
|
|
|
|
Rules, Sitemaps, or Persitence. Test your Items each step of the way to verify
|
|
|
|
they are working.
|
|
|
|
they are working.
|
|
|
|
|
|
|
|
|
|
|
|
### Manually Creating Things
|
|
|
|
### Manually Creating Things
|
|
|
|
|
|
|
|
|
|
|
|
Not all 2.0 bindings support automatic discovery of Things or by their very nature
|
|
|
|
Not all 2.0 bindings support automatic discovery of Things or by their very nature
|
|
|
|
require manual creation of Things. As with linking Channels to Items, there is
|
|
|
|
require manual creation of Things. As with linking Channels to Items, there is
|
|
|
|
more than one way to do this including through PaperUI, Habmin, the REST API, or
|
|
|
|
more than one way to do this including through PaperUI, Habmin, the REST API, or
|
|
|
|
through text files. This tutorial will only cover creating Things in text files as
|
|
|
|
through text files. This tutorial will only cover creating Things in text files as
|
|
|
|
that will be closer to the openHAB 1.x way of doing things.
|
|
|
|
that will be closer to the openHAB 1.x way of doing things.
|
|
|
|
|
|
|
|
|
|
|
|
All definitions of new Things are written to .things files in the
|
|
|
|
All definitions of new Things are written to .things files in the
|
|
|
|
`<openHAB 2.0 conf>/things` folder. The syntax for a Thing definition varies from
|
|
|
|
`<openHAB 2 conf>/things` folder. The syntax for a Thing definition varies from
|
|
|
|
binding to binding. See the binding's readme for the specific format and parameters
|
|
|
|
binding to binding. See the binding's readme for the specific format and parameters
|
|
|
|
required. Also see the binding's readme for the list of channels the Thing
|
|
|
|
required. Also see the binding's readme for the list of channels the Thing
|
|
|
|
supports. As discussed above, the Channel ID will be the `<Thing ID>#<channel>`.
|
|
|
|
supports. As discussed above, the Channel ID will be the `<Thing ID>#<channel>`.
|
|
|
|
|
Thomas Dietrich
Kai Kreuzer