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