Migration from OH 1.x to OH 2 Tutorial

Tags: #<Tag:0x00007f4349f783f0>

This Tutorial is Deprecated. Please see the Official Docs

I’ll leave this content up for posterity but please use the official docs. It has been significantly updated with new sections including how to configure using addons.cfg and runtime.cfg.


I am starting the migration from OH 1 to OH 2 with the intent of both upgrading my deployment and creating a tutorial for the official OH 2 docs.

I tend to be very thorough and deliberate so this may take a few days and it might become longer than necessary.

This thread is to be the initial place to write up the document and to provide discussion. I welcome all comments, suggestions, and recommendations for additional content or removal of content.

I will come back to this top posting and add content as I make progress.

There are still come unanswered questions. See the bolded lines below that start with
####HELP!

If you can help, please comment so this tutorial can be as complete as possible.

Instructions for Migration from openHAB 1.x to openHAB 2

This tutorial provides a step-by-step procedure for migrating an existing openHAB 1.x installation to openHAB 2 snapshot. These procedures were generated starting from an apt-get installed openHAB 1.8.3, though they should work for previous versions. Where needed, additional details are provided for other platforms (Windows, OSX, non-Debian based Linux, etc.) and manually installed openHAB 1.x installs.

Based on feedback these instructions will emphasize the text based procedures over the use of PaperUI and Habmin, which should be closer to the openHAB 1.x experience.

1. Preparation

Now is the time to consider and plan for your newly installed openHAB. Some questions to ask and answer include:

  • Are you happy with your current deployment and maintenance of the deployment?
  • Do you have or need to change your backup and configuration management practices?
  • Have you wanted to migrate to a container (e.g. Docker) or a virtual machine?
  • 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 prepare your installation before you start the migration. For example, if you want to start using git to backup and configuration manage your openHAB configurations, now is a good time to create a git repo and check in your configuration files. If you are considering moving to Docker or a VM or starting over fresh (e.g. openHABian).

The following procedure primarily focuses on an in-place migration. If you are migrating to a fresh install, container, or another VM some of the following steps can be skipped. Those steps will be identified.

One major thing to be aware of is that authentication is not yet implemented in openHAB 2. So if you have set up port forwarding to access your openHAB realize that here is no longer a username and password protection. So don’t forget to disable this port forward. Until authentication is implemented you can: use my.openhab (see below), set up a reverse proxy, use ssh tunneling, or set up a VPN to remotely access your openHAB instance.

2. Backups

The first step is to backup everything that you have modified in existing your openHAB 1.x installation. These files may include:

  • /etc/openhab/* - Configuration files
  • /var/lib/openhab/* - The openhab user’s home directory, zwave and embedded persistence database files
  • /usr/share/openhab/webapps - Custom icons, custom webviews (e.g. Weather Binding), other static webpages and web content
  • /usr/share/openhab/bin - custom command line arguments to the JVM, changes to the default ports, etc.
  • /etc/default/openhab - an alternative place to change the default ports

If you are on another platform or performed a manual installation, just create a backup of your <openHAB home> directory where <openHAB home> is the root directory where openHAB is installed.

3. Shutdown openHAB 1

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 some bindings require exclusive access to hardware resources (e.g. zwave and RFXCOM bindings).

On an apt-get installed openHAB 1.x installed on a systemd based OS (Ubuntu 15+, Raspbian Jessy+) run:

sudo systemctl stop openhab.service

On older systems run:

sudo service openhab stop

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).

4. Install openHAB 2

Full instructions for installation of openHAB 2 are located here. Choose your desired platform from the list.

One has two choices to make: Beta or SNAPSHOT, and Offline or Online.

At the time of this writing, the recommended release to install is the SNAPSHOT release. There are numerous known bugs that have been fixed since the last Beta release that impact both usability and stability. However, if receiving constant updates every time you run apt-get upgrade is a problem, choose either the Beta release or a manual installation. Once the first stable release of openHAB 2 occurs that will become the recommended release.

The difference between Offline and Online is whether or not all the bindings are included in the initial installation (i.e. one can install any openHAB 2 binding without connecting to the Internet) or individual bindings are downloaded as needed.

Choose which release and version of openHAB 2 to install and follow the installation instructions for your platform.

Notes on Docker

If you have any openHAB 1 bindings that are not already included with the openHAB 2 distribution, in addition to creating and mounting /opt/openhab/conf and /opt/openhab/userdata to the container, you will also want to add /user/openhab/addons so you can install openHAB 1 bindings. Other bindings will have additional requriements (e.g. the Nest binding will require you to mount /var/openhab/.java to /openhab/.java. The log config file can also be mounted as a volume so you can modify the logging without entering the container.

To run the openHAB container as a service on a systemd based system you can use the following openhab2.service file:

Requires=docker.service
After=docker.service

[Service]
[Unit]
Description=openHAB 2
Requires=docker.service
After=docker.service

[Service]
Restart=always
ExecStart=/usr/bin/docker run --name=%n --net=host -v /etc/localtime:/etc/localtime:ro -v /etc/timezone:/etc/timezone:ro -v /opt/openhab/conf:/openhab/conf -v /opt/openhab/userdata:/openhab/userdata -v /opt/openhab/addons:/openhab/addons -v /opt/openhab/.java:/openhab/.java -v /opt/openhab/conf/org.ops4j.pax.logging.cfg:/openhab/runtime/karaf/etc/org.ops4j.pax.logging.cfg:ro --device=/dev/ttyUSB0 openhab/openhab:amd64-offline
ExecStop=/usr/bin/docker stop -t 2 %n ; /usr/bin/docker rm -f %n

[Install]
WantedBy=multi-user.target

Caution: The above .service file destroys and recreates a brand new container every time the service starts. If there are files you want to persist between restarts add more volumes to the command above. Also, because the container is recreated every time the service restarts the ssh keys get recreated every time it restarts. Fixing this is a TODO. For now one must remove and reaccept the key anew every time the service is restarted.

Finally, the openHAB installation inside the Docker container is a manual installation. Consequently the paths to certain files will match those for a manually installed deployment with <openhab home> located at /openhab.

5. Prepare openHAB 2 for the existing openHAB 1 Configuration

Start your newly installed openHAB 2 instance per the instructions in the installation guide for you platform and navigate to http://openhab-machine-address:8080.

Congratulations, you have a running openHAB 2! See the User Guide and Migration from openHAB 1 to openHAB 2 for important information about differences between the two.

Theoretically one should be able to just enable the OH 1 compatibility layer and copy over their addons and config. However, when I tried this I encountered numerous errors with vital bindings like MQTT and Zwave so I cannot recommend this approach. Instead we will set up and configure the 1.9 version of all the bindings you are using one at a time.

It is important now to decide whether you want to configure openHAB using PaperUI, Habmin, or all text based. This is because when you use PaperUI config parameters are stored in a database and not configuration files.

####HELP!
If one tries to make a cfg file after configuring a parameter in PaperUI, which takes precidence?

It is best to be consistent in your approach where possible.

All Text Based

ssh into the openHAB Karaf console using:

ssh openhab@localhost -p 8101

Use habopen as the password.

See the Karaf Reference for details about navigating and using the console.

Run the following command to see the list of addon repositories current installed.

feature:repo-list

####HELP!
If you do not see openhab-addons-legacy-1.9.0-SNAPSHOT install it by running ???

If you do not see openhab-addons-experimental-2.0.0-SNAPSHOT install it by running ???

For now see the PaperUI section for how to enable Legacy and Experimental and Remote Repositories.

You can get a list of all available bindings with the command:

feature:list

You can narrow the list down using grep

feature:list | grep weather

Find all of the bindings you currently use on openHAB 1.x and install them using

feature:install <addon name>

For example, to install the Weather Binding run:

feature:install openhab-binding-weather

To get a list of all currently installed bindings you can run:

feature:list | grep Started

This is great opportunity to identify those addons you are actually using and only install those.

As you install each binding you should find a new .cfg file for that binding in your conf/services folder. For example, the Weather binding will create a default weather.cfg file. Transfer the settings for the binding that were in your old openhab.cfg file for the binding to this new file. However, because each binding now has its own config file, you no longer need the first part of the parameter. For example, pushover:defaultToken becomes defaultToken in the pushover.cfg file.

While installing bindings and actions, watch the openhab.log for errors by tailing it in another console (tail -f /var/log/openhab/openhab.log, or for manual installs tail -f <openhabhome>/userdata/logs/openhab.log) or from another Karaf console session by running log:tail.

At this time only install bindings that are 1.9.0.SNAPSHOT. We will get to the 2.0.0.SNAPSHOT bindings later.

Also, do not install the myopenhab binding yet. Instructions for that are below.

NOTE: A config file is not always automatically added. If it is not create one yourself. I saw this with the NTP binding.

NOTE: If you are running openHAB 2 in Docker, you need to create /opt/openhab/userdata/persistence manually prior to installing any of the persistence bindings.

Finally, you must install the various transformation services that you use yourself. They no longer come with the core by default.

Certain bindings generate and use unique tokens which are used for authentication with a service. Two of these include the Nest binding and my.openhab binding. In all of these cases, you must go through the setup procedures again for your openHAB 2 installation.

If all of your addons were available to install through the Karaf console you may continue on to Final Step below. However, if you have non-official addons or addons perform skip to the Unofficial Addons step.

PaperUI Approach

Select the PaperUI from the menu that appears when you go to your openHAB 2 server in the browser. Go to Configuration -> System on the left hand side and enable “Include Legacy 1.x Bindings”. Also enable “Access Remote Repositories”. This will allow you to install your current bindings even if there is an OH 2 version available. Press “Save”.

Now select “Extensions” from the left and browse or search for each of the bindings you currently use. Make note of those that do not appear in the list. Do not install any binding that has version “2.0.0.SNAPSHOT”. If there isn’t a “1.9.0.SNAPSHOT” version we will install that binding manually.

This is a great opportunity to identify those bindings that you are actually using and only install those.

When you find the a binding to install, press the Install button and wait for installation to complete. Once installed you will find a new cfg for that addon in the conf/services folder. Transfer the settings for that binding from your openhab.cfg file to this new binding file.

For example, upon installing the Pushover action I get the new file /etc/openhab2/conf/services/pushover.cfg. I then transferred the pushover: parameters to this new file, removing the “pushover:” part. So pushover:defaultToken in openhab.cfg becomes defaultToken in pushover.cfg.

Instructions for dealing with the My.openHAB binding are below. Do not install this binding until this later step.

NOTE: A config file is not always automatically added. If it is not create one yourself. I saw this with the NTP binding.

NOTE: If you are running openHAB 2 in Docker, you need to create /opt/openhab/userdata/persistence manually prior to installing any of the persistence bindings.

NOTE: For some bindings, you can configure them in the PaperUI under Configuration -> Bindings.

Finally, you must install the various transformation services that you use yourself. They no longer come with the core by default.

Certain bindings generate and use unique tokens which are used for authentication with a service. Two of these include the Nest binding and my.openhab binding. In all of these cases, you must go through the setup procedures again for your openHAB 2 installation.

If all of your addons were available to install through the Karaf console you may continue on to Final Steps below. However, if you have non-official addons or addons perform skip to the Unofficial Addons step.

Installing Unofficially Supported openHAB 1.x Addons

----SKIP If All Addons Were Available and Installed Already----

First check the list of addons that are known not to work with openHAB 2 and make sure yours are not among them.

Next install the openHAB 1 compatibility layer using either the Karaf Console instructions for installing features above.

Copy your openhab.cfg file to the openHAB 2’s conf/services folder. If you are running an apt-get installed openHAB 1.x openhab.cfg is located in /etc/openhab/configurations. For an apt-get installed openHAB 2 the conf folder is located in /etc/openhab2/conf.

For maually inistalled openHAB 1.x this file is located in <openhab home>/configurations and manually installed openHAB 2 if goes to <openhab2 home>/conf.

This file will have a lot of configuration information that you have already moved over to individual binding configs. Make sure to comment out all of these parameters and just leave the core config parameters and those for the bindings you are manually copying over uncommented.

Now copy over the contents of your openHAB 1 addons folder to openHAB 2. Before we do this we want to watch the logs for errors (see the Karaf console instructions above).

While watching the logging copy the jar files in your openHAB 1 addons folder to the openHAB 2 addons folder one-by-one. Pay particular attention to any errors in the log that may occur. For example:

cp /usr/share/openhab/addons/org.openhab.binding.astro-1.8.3.jar /usr/share/openhab2/addons

You may see some errors complaining about there not being a bind and unbind method. But if it worked you should see the same log entries you would normally see when restarting openHAB 1 from that binding.

NOTE: Some actions require the corresponding binding to be installed first. If you see errors similar to the following, try copying over the binding jar file first. From personal experience I can say this is the case for the Astro binding (though you shouldn’t be installing the Astro binding in this way :angry:).

2016-09-08 15:15:04.613 [WARN ] [org.apache.felix.fileinstall        ] - Error while starting bundle: file:/openhab/addons/org.openhab.action.astro-1.8.3.jar
org.osgi.framework.BundleException: Could not resolve module: org.openhab.action.astro [210]
  Unresolved requirement: Import-Package: org.openhab.binding.astro.internal.calc

Final Steps

Apparently, as with openHAB 1.x, one must restart openHAB 2 to pick up changes to the *.cfg files. Restart openHAB 2 now.

The next step is to configure a default persistence.

If using text configuration only, add the following to conf/services/runtime.cfg

org.eclipse.smarthome.persistence:default=<default persistence>

If using PaperUI go to Configuration -> System and scroll down to the bottom. Choose whatever was the default persistence as set in your openhab.cfg.

####HELP!
NOTE: I have no idea how/if this can be done through a text config file or the Karaf console.*

Alternatively you can modify all the persistence calls in your rules to specify the persistence service to use

Now openHAB 2 is ready to receive your other configurations. As you copy each set of files over, watch the log for errors which may indicate a missing transform addon.

cp /etc/openhab/configurations/items/*.items /etc/openhab2/conf/items
cp /etc/openhab/configurations/persistence/*.persist /etc/openhab2/conf/persistence
cp /etc/openhab/configurations/scripts/* /etc/openhab2/conf/scripts
cp /etc/openhab/configurations/transform/* /etc/openhab2/conf/transform
cp /etc/openhab/configurations/rules/*.rules /etc/openhab2/conf/transform
cp /etc/openhab/configurations/sitemaps/*.sitemap /etc/openhab2/conf/sitemaps
Copy any custom icons from your addons to /etc/openhab2/conf/icons/classic

NOTE: openHAB 2 currently supports static webviews. However, it does not support the dynamic webview for the Weather Binding. however, Habpanel is an excellent alternative approach.

NOTE: If you keep png icons you need to change the default in Configuration -> Service -> Basic UI and Classic UI. Set “Default Icon Format” to Bitmap.

####HELP!
** I’ve no idea how to set this parameter through text files or Karaf console **

NOTE: Not all of the default icons that came with openHAB 1 exist in openHAB 2. If you see missing icon on your sitemap you may need to copy over the openHAB 1 icon, or switch to another one. Also, there is no longer a default icon provided for Items that do not specify an icon.

In order for dynamic icons to work, openHAB 2 requires there to be a default version of that icon in addition to the ones for each state. For example, if you have downloaded a bunch of wunderground icons and have wunderground-chanceflurries.png and so on, you must also have a wunderground.png or the dynamic icons will not work.

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 persist.

Next we need to remove any imports in your rules that reference org.openhab. These imports are done for you now. Also, if you have any checks for Undefined, they need to be changed to NULL.

Now watch your logs for any errors. Your home automation should be up and running as is at this point.

6. Testing

  • Items: Watch userdata/logs/events.log and methodically work through all of your Items activating and deactivating them one by one and verify the events appear in that log as expected. This may require running OH 2 for some period of time and/or writing new rules or testing Items to cause events to occur.

  • Persistence: Check your persistence locations to see if all of your persisted Items are listed. Check your charts on your sitemap to make sure that they are up to date. Check the logs for errors when rules try to get historic states.

  • Rules: When you first copy over your rules you are likely to see many errors, particularly if your rules assume that all Items have a state as because your persistence has not yet been populated there will be many Items that are undefined because the expected restoreOnStartup could not happen. Methodically exercise all of your rules one by one and look for errors.

  • Sitemap: The most common issue will be missing icons. Browse through your sitemap methodically and identify those entries that have a missing or wrong icon. Select an alternative or copy the one you were using from openHAB 1 to the conf/icons/classic folder. Both Basic UI and Classic UI pull from that folder. I notice that the visibility tag does not work quite as well as it did in openHAB 1. I recommend using the Classic UI for now. The Basic UI has a number of capabilities that do not work or do not work the same way regarding dynamic content, in particular visibility. Habpanel is rapidly maturing and uses a completely different approach to the UI. I highly recommend exploring these and the other UIs that openHAB 2 supports, only later once everything else is working.

Once you are satisfied that your auto system is up and running take a deep breadth and take a break. Let it run for a few days or a week and verify that everything is working as it should. Once you have confirmed this, you can optionally start migrating to the openHAB 2 native Bindings and start to take advantage of Things and Channels.

Now is a good time to install Eclipse SmartHome Designer to aid in the editing and review of your files. See below for details.

6. Migrating to openHAB 2 Bindings

Eclipse SmartHome Designer

A new Designer exists for openHAB 2 which is hosted by the Eclipse SmartHome project. Full installation and configuration details are located here:

http://docs.openhab.org/installation/designer.html

NOTE: Designer is still in active development. Plan on manually performing frequent updates.

My.openHAB

There is no 1.9 My.openHAB binding listed in PaperUI for installation. You can only install the 2.0 version. Furthermore, one can only have one openHAB instance linked to your my.openhab.org account at a time. Finally, each openHAB instance generates its own uuid and secret so you cannot simply reuse those from your openHAB 1 instance. This is why the above instructions said to wait to install the my.openHAB binding until this point.

Install the My.openHAB binding through PaperUI.

This will automatically generate a uuid file and secret file. However, these files are in a different location than they were for openHAB 1 and the documentation on the my.openhab.org website has not yet been updated. The uuid file is located in userdata/uuid and the secret file is located in userdata/myopenhab/secret.

Now log into http://my.openhab.org and select “Account” from the pull down menu under your email:

Copy the contents of the uuid file into the openHAB UUID field. Copy the contents of the secret file into the openHAB Secret field.

You may need to restart openHAB at this point to get the binding to reconnect. It should now show your system as being online and running openHAB 2.

General Approach

Identify a binding where there is a 2.0 version that you want to upgrade to. Note that the behaviors and capabilities of the two versions of the bindings are not always the same. For example, the Astro 2.0 binding does not support creating a Switch that triggers at the indicated celestial time. See the binding’s documentation for details.

Once you choose a binding to move to start by identifying those Items in your configuration that use that binding. On Linux/OSX this can easily be done with the following command:

grep <binding> conf/items/*

where <binding> is the binding string used. A couple of examples follow:

grep zwave conf/items/*
grep astro conf/items/*
grep mqtt conf/items/*

Now comment out those Items to ensure that there is no interactions between the old configurations and the new ones.

Next uninstall the 1.9 binding. You can do this through the Karaf console using feature:uninstall <addon name> or the PaperUI Extensions.

Move the binding’s .cfg file to a backup location so you have the parameters saved. Not all bindings have a cfg file so this step may not be necessary.

Install the new binding. If this is the zwave binding, install Habmin at this time as well.

Configure the new binding according to the instructions on the binding’s documentation page (link above). If it is a binding that does automatic discovery, give it time to find all the devices. They will appear as new Things in your Inbox. For me, it took 10 minutes to find all of my zwave devices. However if you press the Scan button in PaperUI or run the following from the Karaf console:

####HELP!
** I need someone to verify this works as I expect, there are no errors printed if you choose a non-existant binding ID**

smarthome:discovery openhab-binding-<binding name>

Things represent the stuff between the curly brackets in your old OH 1.x Items configuration. As such these auto discovered things must be mapped to Items. Adding you own Things for cases where the binding doesn’t support auto-discovery is below.

In the Karaf console you can see all the Things that were autodiscovered in the Inbox. To see the Inbox from the Karaf console run:

smarthome:inbox

NOTE: the screenshot above shows my Ignored Inbox Items. Your’s will not show “IGNORED”.

For all of the Things you wish to accept run the command:

smarthome:inbox approve <thingId>

Once approved, you can discover the Channels and Channel IDs for that Thing with the command:

smarthome:links list

####HELP!
This command shows all the Items that are bound to Items as well as all Things mapped to Channels.

In PaperUI, Select a Thing from the Inbox and press the blue check to add it to your configuration. The Thing will now appear under Configuration->Things. You can navigate to it and change any parameters necessary if desired by pressing the pencil icon. If you click on the Thing’s name it will tell you the available Channels on that Item. Each Things can have one or more Channels and these are what gets bound to an Item.

To bind an Item to a channel, replace the contents of your previous { } binding configuration with channel="<channel id>" where the channel ID is copy and pasted from the Karaf console or PaperUI. an example is highlighted in orange in the screen capture below.

Repeat this process for each of your Things/Items.

For example, this Item:

Switch S_L_Family "Family Room Lamp" <light> {zwave="10:command=switch_binary,respond_to_basic=true"}

became

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 behaviors are the same, there are no changes required to your Rules or your Sitemap.

Test your Items on each step of the way to verify they are working.


The current Migration article includes a lot of great information about what is different between OH 1.x and 2. A question remains as to whether that information should be included inline with the steps above, or remain separate sections of the article, or become a separate article entirely that this one links to. Right now the existing article purports to be a tutorial but it really is only informational right now, not a tutorial.

20 Likes
Clarification of how to configure OH2 with txt files?
OpenHAB 2 beginners / n00b guide?
Help with things, items and sitemap (files) in OH2 needed
Migration OH1 -> OH2, especially z-wave related
FHT CUL device migration
openHAB2 and Z-Wave - Recommended combo?
OpenHAB2 Setup recommendations
Interested in hardware
HowTo: Manage OpenHab 2 configurations
Help me with dashboard configuration!
openHAB2 Beta Snapshot - Addons folder is empty?
Missing openhab.cfg - New OH2 installation on rpi2
Need a good guide link
gCal Binding
Undertaking a volunteer effort using OpenHab and have CalDAV, Ecobee, and OH2 questions
Undertaking a volunteer effort using OpenHab and have CalDAV, Ecobee, and OH2 questions
Problems with Items/Things in Habmin/PaperUI
Using 1.0 denon binding in openhab 2.0
Things config doc not found
OH2 and EnOcean?
My.openhab after a fresh openHAB install
My.openhab oh2 wont create files
Is the piXtend binding available for OpenHab2?
OpenHAB 2 up but not showing icons
Converting an OH1 Item to OH2
Clarification of how to configure OH2 with txt files?
Migration from 1.8.x to 2.0 - My Feedback and Issues
Openhab 1 and Openhab2 installed on the same RPI
Remote access (SSH) through my.openHAB?
Unable to load persistence service in OH Docker container
Switch from OH2 Offline to Online
Does sitemap in OH2 no longer important?
OpenHAB2 with FS20 / FHT80B-2
How to add a OH1 binding addon to OH2
Solved - Problem with rule - error: the name 'Undefined' cannot be resolved to an item or type -- wifi detection
openHABian hassle-free openHAB Setup
Recently Openhab is missing some rules....strange
Z-Wave and Nest discovery?
Migrating groups and rules from openhab1

Great beginning! I think OH2 adoption will go much faster one a roadmap for migration is produced. Thanks for the work.

Added some notes relevant to Docker.

Major update but somthing is broken and I’m hoping someone can help.

  • My sitemap is blank (both Classic and Basic). The logs do indicate that my sitemap is being loaded and there are no errors when it does so.

  • I have installed the XSLT transform but I’m still getting

2016-09-08 17:11:53.975 [WARN ] [.core.transform.TransformationHelper] - Cannot get service reference for transformation service of type XSLT
2016-09-08 17:11:53.976 [WARN ] [ab.binding.http.internal.HttpBinding] - couldn't transform response because transformationService of type 'XSLT' is unavailable

Any and all help is appreciated.

Minor updates, mostly notes on testing.

additionally /etc/default/openhab should be backed up if it exists in your installation

1 Like

Lots of little updates including adding /etc/defaults/openhab to the list of things to backup per @arnold’s suggestion, adding instructions for Designer, adding instructions for My.openHAB, and adding some notes of gotchas I’ve encountered along the way.

Added instructions for migrating to a 2.0 binding.

RE: missing sitemaps
Rich you may have already solved this but fwiw it was the default sitemap being set to _default in both the classicui and basicuic cfg files on my instance.

OK, it’s late; I’ve just completed a first run through of this…many questions…

I’ve installed the following bindings:

Installed via paper UI, Config auto created
=================
org.openhab.binding.astro-1.9.0.jar
org.openhab.binding.http-1.9.0.jar
org.openhab.binding.mios-1.9.0.jar
org.openhab.binding.modbus-1.9.0.jar
org.openhab.binding.mqtt-1.9.0.jar
org.openhab.binding.networkhealth-1.9.0.jar
org.openhab.binding.weather-1.9.0.jar - Fails?
org.openhab.persistence.influxdb-1.9.0.jar
org.openhab.persistence.mapdb-1.9.0.jar

Installed via paper UI, manual config file
==============================
org.openhab.binding.milight-1.8.3.jar - Installed, manual config file
org.openhab.binding.ntp-1.8.3.jar - Installed, manual config file

Manual - copied over
====================
org.openhab.action.astro-1.8.3.jar
org.openhab.binding.rfxcom-1.8.3.jar
org.openhab.io.squeezeserver-1.8.3.jar
org.openhab.action.squeezebox-1.8.3.jar
org.openhab.binding.squeezebox-1.8.3.jar
org.openhab.io.transport.serial-1.8.3.jar
  1. Do these questions need a thread of their own?
    2a) Only the NTP binding has anything which appears as a Thing?
    2b) When I select the ‘+’ for a thing, I only get the option to add an NTP thing?
  2. The weather binding fails, however when I comment out the config lines, and restart, it still remembers the config?

Cheers
James

Thanks! I did figure out how to bring up the sitemap using ?sitemap=default. I’ll try renaming my file to _default.sitemap and see if I no longer need to specify the sitemap.

I’m still trying stuff and need to rework the above pretty heavily to emphasize the text file only approach (Kai has indicated this would be the preferred approach for OH 1 migrators).

If they are problems with the migration itself, I think here is pretty appropriate. If they are specific to a single binding then a new thread might be more appropriate.

That is correct. For the most part 1.x bindings will not create Things. Only 2.0 native bindings support things, and even then not all of them will automatically discover and create Things for you.

I too only had NTP put something into my inbox until I installed the zwave 2.0 binding.

For most of the bindings listed, you will need to create traditional OH 1.x Items with a regular Binding config, not Things. Only the 2.0 bindings are guaranteed to support Things and honestly the the NTP 1.9 binding is the only 1.9 binding that I’ve used that has anything to do with Things and only it and the Nest binding added a configuration widget to PaperUI.

In short, what you see is expected. Even once you add new 2.0 bindings, you may have to populate a .things file manually. And as I responded to kamajo, text files is the preferred approach (and the tutorial above will be edited to reflect that).

I’m not using the Weather binding so I’ve no direct experience to bring to bear. However, if there is a configuration widget in PaperUI for the Weather Binding AND you configured it through that widget, those settings end up in a MapDB database. I don’t think it is really known what takes precedence in this case. You will also find some versions of the file in userdata/cache/org.eclipse.osgi/7/data/config/org/openhab/ and /userdata/cache/org.eclipse.osgi/7/data/config/binding/ but I don’t know if those are just temps or what they are.

(After answering I’d say the answer to 1) is they most definitely belong in this thread, not new threads).

I’m going to rework the above to downplay the importance and use of PaperUI. Now that I know a bit more about it, where it came from, and what it is/is not capable of, and Kai’s recomendations I think it is important to deemphasize its use in OH 2, at least for now.

I have a question regarding linking of channels/items. As suggested (I am a recent OH1 user), I have kept my items file and now wanted to link all items (mainly zwave) to the appropriate channels using the items file {channel="…"}.

My question: Can I see anywhere if the creation of a link using the items file was successfully? Is there a log entry? Anywhere in HABmin or PaperUI? I see that the items file was loaded again but I can’t see the link in PaperUI or HABmin. Also I don’t get any values when I load my sitemap. But I see values in the channels of the things in HABmin. So I assume the channels are correctly set up.

When I link a channel to an item with PaperUI (so that it’s stored in the DB), I’ll get a log entry and after that I can see the link in PaperUI and HABmin. But I want to go the old fashioned way…

Further notice: I have defined several groups in my items file. And in the log file I get error messages like this when launching the sitemap:

Cannot retrieve item 'gSicherheit' for widget org.eclipse.smarthome.model.sitemap.Frame

So it seems that the items file is loaded, but not parsed at all?

Any suggestions? Am I doing something wrong?

I looked through my logs and do not see anything printed with the logs set at the default level nor do I see anything from zwave when set to trace.

I also see nothing in PaperUI to show there is a link. I’ve not used Habmin much yet but it does appear there is a spot hidden away in the Things section that does show the channels and what Items are mapped to them.

Configuration -> Things -> Select a Thing -> Select Channels from the bottom right -> It will now show all the Channels and what Items are linked to them.

You can also see if all your Items and Groups appear in Configuration -> Items on Habmin so if you are unsure that your file is being fully loaded you can check there to see if everything is there that you expect. If not there is likely an error in your Items file preventing it from being fully parsed.

I’m not sure what could be wrong but maybe looking at Habmin will help up narrow it down.

Thanks Rich. For whatever reason, I couldn’t get it to go with my installation. No item was linked and therefore the sitemap produced nothing useful. I still don’t know why this happened (or better: not happened). So I decided to do a clean install and go from scratch. And et voila, this time it worked. I linked the items in the .items file and after that I found active links in HABmin (as you described) and also in PaperUI I got the blue circle with the white dot in it! Even the karaf console now shows all links when I enter “smarthome:links list”.

I am getting there with my new OH2 installation. :wink:

Added a bunch more detail about manual configuration and working with the Karaf console instead of PaperUI. There are still several HELP! s above I need some expert to tell me how it works.

As far as I’m concerned, with the exception of the remaining questions, this tutorial is complete unless there are some additional suggestions offered.

I might edit it sometime later this week for grammar, spelling and consistency (and I’d love to figure out how to do those in post links @ThomDietrich put in his Influx+Grafana tutorial).

It’s the markdown language which is also used by github:
https://help.github.com/articles/basic-writing-and-formatting-syntax/

  1. create text and format as heading
  2. create the text for the link
  3. use [linktext](#target-heading):

linktext

Note: for each space in the heading text you need to write a dash.

https://help.github.com/articles/basic-writing-and-formatting-syntax/#links
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

target heading

.
.
.
.
.
.
.
.
.
.

Thanks! It was the dashes replacing spaces that I was missing.

That would be great but no, it’s not implemented that way in Discourse. There is a proposal to add that functionality over at meta.discourse.org but it’s not implemented yet.

My solution is HTML based:


* [Starting Point](#starting-point)
* [InfluxDB Installation and Setup](#influxdb-setup)

...

## <a name="starting-point"></a>Starting Point

This guide is based on and was tested with the following components:

I am not an expert but I’ll have a look tomorrow!

Close … but not close enough :joy: