974 lines
59 KiB
HTML
974 lines
59 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
|
||
|
||
|
||
|
||
<!--<link rel="shortcut icon" href="https://www.openhab.org/favicon.png"></link>-->
|
||
<title>openHAB 2 - Empowering the Smart Home</title>
|
||
|
||
<!-- CSS -->
|
||
<link type="text/css" rel="stylesheet" href="/v2.1/css/materialize.css" media="screen,projection" />
|
||
<link type="text/css" rel="stylesheet" href="/v2.1/css/pygments-jekyll-style.css" />
|
||
<link type="text/css" rel="stylesheet" href="/v2.1/css/styles.css" />
|
||
<link type="text/css" rel="stylesheet" href="/v2.1/css/openhab.css" />
|
||
<link type="text/css" rel="stylesheet" href="/v2.1/css/collapsible.css" />
|
||
|
||
<!-- Font -->
|
||
<link type="text/css" rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons" />
|
||
<link type="text/css" rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:300,400,700" />
|
||
<link rel="canonical" href="http://docs.openhab.org/tutorials/migration.html" />
|
||
<script type="text/javascript">var gaProperty = 'UA-47717934-3';var disableStr = 'ga-disable-' + gaProperty;if (document.cookie.indexOf(disableStr + '=true') > -1) {window[disableStr] = true;}</script>
|
||
<script>
|
||
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
||
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
||
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
||
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
|
||
ga('create', 'UA-47717934-3', 'auto');
|
||
ga('set', 'anonymizeIp', true);
|
||
ga('send', 'pageview');
|
||
</script>
|
||
</head>
|
||
|
||
|
||
<body class="documentation">
|
||
<div id="header" class="navbar-fixed">
|
||
<nav role="navigation">
|
||
<div class="container">
|
||
<div class="nav-wrapper">
|
||
<a href="/v2.1/index.html"><img id="logo" src="/images/logo.png" /></a>
|
||
<a href="#" data-activates="nav-mobile" class="button-collapse"><i class="material-icons">menu</i></a>
|
||
<ul class="right hide-on-med-and-down">
|
||
<li><a href="/tutorials/index.html">Tutorials</a></li>
|
||
<li><a href="/v2.1/introduction.html">User Manual</a></li>
|
||
<li><a href="/developers/index.html">Developer Guide</a></li>
|
||
<li><a target="_blank" href="https://community.openhab.org">Community Forum</a></li>
|
||
<li><a target="_blank" href="https://github.com/openhab">GitHub</a></li>
|
||
<li class="search"><i class="material-icons">search</i></li>
|
||
<li class="search">
|
||
<form method="GET" id="searchform" class="search-form" action="/search">
|
||
<input id="query" name="q" type="text" class="search-form-input" placeholder="search" />
|
||
</form>
|
||
</li>
|
||
</ul>
|
||
<ul id="nav-mobile" class="side-nav">
|
||
<li><a href="/v2.1/index.html">Home</a></li>
|
||
<li><a href="/tutorials/index.html">Tutorials</a></li>
|
||
<li><a href="/v2.1/introduction.html">User Manual</a></li>
|
||
<li><a href="/developers/index.html">Developer Guide</a></li>
|
||
<li><a target="_blank" href="https://community.openhab.org">Community Forum</a></li>
|
||
<li><a target="_blank" href="https://github.com/openhab">GitHub</a></li>
|
||
<li class="search">
|
||
<form method="GET" id="searchformmob" class="search-form" action="/search">
|
||
<input id="querymob" name="q" type="text" class="search-form-input" placeholder="search" />
|
||
</form>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</nav>
|
||
</div>
|
||
|
||
|
||
<section id="documentation" class="text content-wrapper">
|
||
<div class="container">
|
||
|
||
<h1 id="migration-from-openhab-1x-to-openhab-2">Migration from openHAB 1.x to openHAB 2</h1>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>These instructions emphasize the text based procedures over the use of PaperUI and Habmin which is closer to the openHAB 1.x experience.</p>
|
||
|
||
<p>Note: In all of the other pages in this documentation, openHAB 2 is simply referred to as openHAB. In order to distinguish between the two versions in this, the current version is referred to as openHAB 2.</p>
|
||
|
||
<p>This page is structured as follows:</p>
|
||
|
||
<ul id="markdown-toc">
|
||
<li><a href="#preparation" id="markdown-toc-preparation">Preparation</a></li>
|
||
<li><a href="#backups" id="markdown-toc-backups">Backups</a></li>
|
||
<li><a href="#shutdown-openhab-1x" id="markdown-toc-shutdown-openhab-1x">Shutdown openhab 1.x</a></li>
|
||
<li><a href="#install-openhab-2" id="markdown-toc-install-openhab-2">Install openHAB 2</a></li>
|
||
<li><a href="#prepare-openhab-2-for-the-existing-openhab-1x-configuration" id="markdown-toc-prepare-openhab-2-for-the-existing-openhab-1x-configuration">Prepare openHAB 2 for the Existing openHAB 1.x Configuration</a> <ul>
|
||
<li><a href="#text-based" id="markdown-toc-text-based">Text Based</a></li>
|
||
<li><a href="#karaf-console" id="markdown-toc-karaf-console">Karaf Console</a></li>
|
||
<li><a href="#paperui-approach" id="markdown-toc-paperui-approach">PaperUI Approach</a></li>
|
||
<li><a href="#configure-add-ons" id="markdown-toc-configure-add-ons">Configure Add-ons</a></li>
|
||
<li><a href="#installing-unofficially-supported-openhab-1x-add-ons" id="markdown-toc-installing-unofficially-supported-openhab-1x-add-ons">Installing Unofficially Supported openHAB 1.x Add-ons</a></li>
|
||
<li><a href="#final-add-ons-installation-steps" id="markdown-toc-final-add-ons-installation-steps">Final Add-ons Installation Steps</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#necessary-changes" id="markdown-toc-necessary-changes">Necessary Changes</a> <ul>
|
||
<li><a href="#items" id="markdown-toc-items">Items</a></li>
|
||
<li><a href="#sitemap" id="markdown-toc-sitemap">Sitemap</a></li>
|
||
<li><a href="#rules" id="markdown-toc-rules">Rules</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#testing" id="markdown-toc-testing">Testing</a></li>
|
||
<li><a href="#new-concepts-things-and-channels" id="markdown-toc-new-concepts-things-and-channels">New Concepts: Things and Channels</a></li>
|
||
<li><a href="#retire-openhab-1x" id="markdown-toc-retire-openhab-1x">Retire openHAB 1.x</a></li>
|
||
<li><a href="#migrating-to-openhab-2-bindings" id="markdown-toc-migrating-to-openhab-2-bindings">Migrating to openHAB 2 Bindings</a> <ul>
|
||
<li><a href="#eclipse-smarthome-designer" id="markdown-toc-eclipse-smarthome-designer">Eclipse SmartHome Designer</a></li>
|
||
<li><a href="#myopenhab" id="markdown-toc-myopenhab">My.openHAB</a></li>
|
||
<li><a href="#other-bindings" id="markdown-toc-other-bindings">Other Bindings</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#managing-the-inbox-things-and-channels" id="markdown-toc-managing-the-inbox-things-and-channels">Managing the Inbox, Things, and Channels</a> <ul>
|
||
<li><a href="#managing-the-inbox-using-paperui" id="markdown-toc-managing-the-inbox-using-paperui">Managing the Inbox using PaperUI</a></li>
|
||
<li><a href="#managing-the-inbox-using-the-karaf-console" id="markdown-toc-managing-the-inbox-using-the-karaf-console">Managing the Inbox Using the Karaf Console</a></li>
|
||
<li><a href="#linking-channels-to-items" id="markdown-toc-linking-channels-to-items">Linking Channels to Items</a></li>
|
||
<li><a href="#manually-creating-things" id="markdown-toc-manually-creating-things">Manually Creating Things</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h2 id="preparation">Preparation</h2>
|
||
|
||
<p>Now is the time to consider and plan for your newly installed openHAB. Some
|
||
questions to ask and answer include:</p>
|
||
|
||
<ul>
|
||
<li>Are you happy with your current deployment and maintenance of the deployment?</li>
|
||
<li>Do you have or need to change your backup and configuration management
|
||
practices?</li>
|
||
<li>Have you wanted to migrate to a container (e.g.
|
||
<a href="/v2.1/installation/docker.html">Docker</a> or a virtual machine)?</li>
|
||
<li>Do you want to start over fresh on a brand new OS install?</li>
|
||
</ul>
|
||
|
||
<p>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 back up and configuration manage your openHAB
|
||
configurations, or if you are considering moving to
|
||
<a href="/v2.1/installation/docker.html">Docker</a> or a VM or starting over fresh (e.g.
|
||
<a href="https://github.com/ThomDietrich/openhabian">openHABian</a>), now is a good time
|
||
to start the process.</p>
|
||
|
||
<p>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 are identified.</p>
|
||
|
||
<p>One major consideration is that at the time of this writing openHAB 2 does not
|
||
implement authentication and authorization (i.e. no username and password). If
|
||
you are relying upon port forwarding to access your openHAB server remotely
|
||
instead of via a VPN, SSH tunneling, or <a href="https://my.openhab.org/">my.openhab</a>,
|
||
we highly recommend <a href="/v2.1/configuration/nginx.html">setting up a reverse proxy</a>.</p>
|
||
|
||
<h2 id="backups">Backups</h2>
|
||
|
||
<p>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:</p>
|
||
|
||
<ul>
|
||
<li><code class="highlighter-rouge">/etc/openhab</code> - configuration files</li>
|
||
<li><code class="highlighter-rouge">/var/lib/openhab</code> - openhab user’s home directory, zwave and embedded
|
||
persistence database files</li>
|
||
<li><code class="highlighter-rouge">/usr/share/openhab/webapps</code> - custom icons, custom webviews (e.g.
|
||
<a href="https://github.com/openhab/openhab/wiki/Weather-Binding">Weather Binding</a>)</li>
|
||
<li><code class="highlighter-rouge">/usr/share/openhab/bin</code> - custom command line arguments to the Java Virtual
|
||
Machine, changes to the default ports, etc.</li>
|
||
<li><code class="highlighter-rouge">/etc/default/openhab</code> - an alternative place to change default ports</li>
|
||
</ul>
|
||
|
||
<p>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
|
||
<code class="highlighter-rouge"><openhab home></code> directory.</p>
|
||
|
||
<h2 id="shutdown-openhab-1x">Shutdown openhab 1.x</h2>
|
||
|
||
<p>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,
|
||
RFXCOM).</p>
|
||
|
||
<p>On an apt-get installed openHAB 1.x running on a systemd based OS (Ubuntu 15+,
|
||
Raspbian Jessy+) run:</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">sudo </span>systemctl stop openhab.service
|
||
</code></pre></div></div>
|
||
|
||
<p>On manually installed systems follow your usual procedure for stopping openHAB
|
||
(e.g. <code class="highlighter-rouge"><ctrl>-c</code> in the window where start.sh or start.bat was run).</p>
|
||
|
||
<h2 id="install-openhab-2">Install openHAB 2</h2>
|
||
|
||
<p>Follow the instructions for your platform <a href="/v2.1/installation/index.html">here</a>.</p>
|
||
|
||
<p>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
|
||
stable version.</p>
|
||
|
||
<p>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
|
||
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
|
||
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
|
||
in some ways the SNAPSHOT is more stable and more capable.</p>
|
||
|
||
<p>The difference between the Offline and Online versions is whether or not all
|
||
the bindings are included in the initial installation (included does not mean
|
||
installed) or whether openHAB 2 needs to connect to and download the latest
|
||
bindings on demand. Offline is a good choice if your openHAB server does not
|
||
have access to the internet all the time.</p>
|
||
|
||
<p>If you plan on running openHAB 1.x as your primary while migrating make sure to
|
||
disable openHAB 2 from starting automatically.</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">sudo </span>systemctl disable openhab2.service
|
||
</code></pre></div></div>
|
||
|
||
<h2 id="prepare-openhab-2-for-the-existing-openhab-1x-configuration">Prepare openHAB 2 for the Existing openHAB 1.x Configuration</h2>
|
||
|
||
<p>Start your newly installed openHAB 2 instance per the instruction in the
|
||
installation guide for your platform and navigate to
|
||
<code class="highlighter-rouge">http://<openhab server ip>:8080</code> where <code class="highlighter-rouge"><openhab server ip></code> is the address of
|
||
the server where openHAB 2 is running.</p>
|
||
|
||
<p>Congratulations, you have a running openHAB 2! See
|
||
<a href="/v2.1/concepts/index.html">Concepts</a> and below for important differences between
|
||
openHAB 1.x and openHAB 2.</p>
|
||
|
||
<p>Theoretically one should be able to just enable the
|
||
<a href="/v2.1/developers/development/compatibilitylayer.html#how-to-use-openhab-1x-add-ons-that-are-not-part-of-the-distribution">openHAB 1.x Compatibility Layer</a>,
|
||
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
|
||
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
|
||
installed through openHAB 2’s new add-on management system.</p>
|
||
|
||
<p>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
|
||
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
|
||
as it will be more familiar and flexible.</p>
|
||
|
||
<h3 id="text-based">Text Based</h3>
|
||
|
||
<p>In your configurations folder for openHAB 2 (<code class="highlighter-rouge">/etc/openhab2</code> on apt-get
|
||
installed instances) there is a new folder named <code class="highlighter-rouge">services</code>. In this folder you
|
||
will find a file named <code class="highlighter-rouge">runtime.cfg</code>. This file contains global openHAB 2
|
||
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:</p>
|
||
|
||
<ul>
|
||
<li><code class="highlighter-rouge">org.eclipse.smarthome.persistence:default=mapdb</code> - default persistence, use
|
||
whatever was set in <code class="highlighter-rouge">persistence:default</code> in openhab.cfg</li>
|
||
<li><code class="highlighter-rouge">autoapprove:enabled=false</code> - makes it so you must manually approve
|
||
automatically discovered Things in the Inbox (see below)</li>
|
||
<li><code class="highlighter-rouge">org.eclipse.smarthome.links:autoLinks=false</code> - prevents openHAB from
|
||
automatically creating an Item for each automatically discovered Thing.</li>
|
||
</ul>
|
||
|
||
<p>Next open for editing <code class="highlighter-rouge">addons.cfg</code>. This file contains parameters related to
|
||
add-ons including allowing one to choose which add-ons to install. For now just
|
||
set the following parameters:</p>
|
||
|
||
<ul>
|
||
<li><code class="highlighter-rouge"><span class="k">package</span> <span class="p">=</span> <span class="n">expert</span></code> - expert is a good choice here. It will include the standard
|
||
UIs, all transformation services and the 1.x compatibility layer,
|
||
though you can choose your UIs and add-ons individually later.</li>
|
||
<li><code class="highlighter-rouge">remote = true</code> - required for the installation of legacy 1.x add-ons</li>
|
||
<li><code class="highlighter-rouge">legacy = true</code> - required to install the 1.9 version of an add-on for which
|
||
there is a 2.0 native version</li>
|
||
<li><code class="highlighter-rouge">binding = </code> - 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
|
||
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
|
||
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
|
||
“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
|
||
bindings <a href="/v2.1/addons/bindings.html">here</a>.</li>
|
||
<li><code class="highlighter-rouge">ui = </code> - if you intend on using PaperUI include “paper”, if you use zwave I
|
||
recommend “habmin”. The list of UIs are <a href="/v2.1/addons/uis.html">here</a>.</li>
|
||
<li><code class="highlighter-rouge">action = </code> - the list of action add-ons you used in openHAB 1.x.</li>
|
||
<li><code class="highlighter-rouge">transformation = </code> - the list of transformations you use. Unlike in openHAB 1,
|
||
one must install transformations separately.</li>
|
||
<li><code class="highlighter-rouge">voice = </code> - see <a href="/v2.1/addons/voice.html">here</a></li>
|
||
<li><code class="highlighter-rouge">misc = </code> - myopenhab, homekit, etc. Do not list myopenhab at this time,
|
||
instructions for it are below.</li>
|
||
</ul>
|
||
|
||
<p>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
|
||
the Karaf console or install PaperUI and browse the list through it.</p>
|
||
|
||
<p>This is a great opportunity to identify those add-ons you are not actively
|
||
using and avoid their installation.</p>
|
||
|
||
<p>When you save this file openHAB will begin the download (if using the Online
|
||
version) and installing the add-ons.</p>
|
||
|
||
<p>Note: if running in Docker, create <openHAB 2 home>/userdata/persistence prior to saving the
|
||
file if there are any persistence add-ons.</p>
|
||
|
||
<p>An example addons.cfg:</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># The base installation package of this openHAB instance (default is "standard")</span>
|
||
<span class="c"># Valid options:</span>
|
||
<span class="c"># - minimal : Installation only with dashboard, but no UIs or other addons</span>
|
||
<span class="c"># - simple : Setup for using openHAB purely through UIs - you need to expect MANY constraints in functionality!</span>
|
||
<span class="c"># - standard : Default setup for normal users, best for textual setup</span>
|
||
<span class="c"># - expert : Setup for expert users, especially for people migrating from openHAB 1.x</span>
|
||
<span class="c"># - demo : A demo setup which includes UIs, a few bindings, config files etc.</span>
|
||
<span class="c">#</span>
|
||
package <span class="o">=</span> standard
|
||
|
||
<span class="c"># Access Remote Add-on Repositories</span>
|
||
<span class="c"># Defines whether the remote openHAB add-on repository should be used for browsing and installing add-ons.</span>
|
||
<span class="c"># This not only makes latest snapshots of add-ons available, it is also required for the installation of</span>
|
||
<span class="c"># any legacy 1.x add-on and all experimental features. (default is false for offline distro, true for online distro)</span>
|
||
<span class="c">#</span>
|
||
remote <span class="o">=</span> <span class="nb">true</span>
|
||
|
||
<span class="c"># Include legacy 1.x bindings. If set to true, it also allows the installation of 1.x bindings for which there is</span>
|
||
<span class="c"># already a 2.x version available (requires remote repo access, see above). (default is false)</span>
|
||
<span class="c">#</span>
|
||
legacy <span class="o">=</span> <span class="nb">true</span>
|
||
|
||
<span class="c"># A comma-separated list of bindings to install (e.g. "sonos,knx,zwave")</span>
|
||
binding <span class="o">=</span> zwave,astro1,http,mqtt,nest,networkhealth,ntp
|
||
|
||
<span class="c"># A comma-separated list of UIs to install (e.g. "basic,paper")</span>
|
||
ui <span class="o">=</span> paper,classic,habmin,habpanel
|
||
|
||
<span class="c"># A comma-separated list of persistence services to install (e.g. "rrd4j,jpa")</span>
|
||
persistence <span class="o">=</span> influxdb,rrd4j,mapdb
|
||
|
||
<span class="c"># A comma-separated list of actions to install (e.g. "mail,pushover")</span>
|
||
action <span class="o">=</span> nma,mail
|
||
|
||
<span class="c"># A comma-separated list of transformation services to install (e.g. "map,jsonpath")</span>
|
||
transformation <span class="o">=</span> xslt,map,regex,javascript
|
||
|
||
<span class="c"># A comma-separated list of voice services to install (e.g. "marytts,freetts")</span>
|
||
voice <span class="o">=</span>
|
||
|
||
<span class="c"># A comma-separated list of miscellaneous services to install (e.g. "myopenhab")</span>
|
||
misc <span class="o">=</span> myopenhab
|
||
</code></pre></div></div>
|
||
|
||
<h3 id="karaf-console">Karaf Console</h3>
|
||
|
||
<p>Following the instructions above to populate <code class="highlighter-rouge">runtime.cfg</code> parameters.</p>
|
||
|
||
<p>Log into the Karaf console with:</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ssh openhab@localhost <span class="nt">-p</span> 8101
|
||
</code></pre></div></div>
|
||
|
||
<p>Use <code class="highlighter-rouge">habopen</code> as the password.</p>
|
||
|
||
<p>See the <a href="/v2.1/administration/console.html">Karaf Reference</a> for details about
|
||
navigating and using the console.</p>
|
||
|
||
<p>Run the following command to see the list of add-on repositories currently
|
||
installed.</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>feature:repo-list
|
||
</code></pre></div></div>
|
||
|
||
<p><img src="images/feature-list.png" alt="result of running feature:repo-list" /></p>
|
||
|
||
<p>The following command will give the list of available add-ons.</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>feature:list
|
||
</code></pre></div></div>
|
||
<p><img src="images/feature-available.png" alt="result of running feature:list" /></p>
|
||
|
||
<p>For each add-on you are using in openHAB 1.x, and for each transformation type
|
||
you are using, install the corresponding add-on using:</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>feature:install <add-on name>
|
||
</code></pre></div></div>
|
||
|
||
<p>using the name from the list. For example, to install the Weather Binding run:</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>feature:install openhab-binding-weather
|
||
</code></pre></div></div>
|
||
|
||
<p>To get a list of all currently installed items run:</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>feature:list | <span class="nb">grep </span>Started
|
||
</code></pre></div></div>
|
||
|
||
<p>At this time only install add-ons that are 1.9.0 SNAPSHOT. The 2.0 add-ons will
|
||
be installed later.</p>
|
||
|
||
<p>Note: if running in Docker, create <code class="highlighter-rouge"><openHAB home>/userdata/persistence</code> manually prior to
|
||
installing persistence add-ons.</p>
|
||
|
||
<h3 id="paperui-approach">PaperUI Approach</h3>
|
||
|
||
<p>These instructions assume no edits have been made to <code class="highlighter-rouge">runtime.cfg</code> or
|
||
<code class="highlighter-rouge">addons.cfg</code> as described in the previous section.</p>
|
||
|
||
<p>Navigate your browser to <code class="highlighter-rouge">http://<openhab server address>:8080</code> and select
|
||
PaperUI from the list of UIs. Navigate to <code class="highlighter-rouge">Configuration -> System</code> on the left
|
||
hand side and enable “Include Legacy 1.x Bindings” and “Access Remote
|
||
Repositories”. This will allow you to install your current bindings even if
|
||
there is an openHAB 2 version available. Press “Save”.</p>
|
||
|
||
<p><img src="images/PaperUI-Config-System.png" alt="PaperUI System Settings" /></p>
|
||
|
||
<p>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
|
||
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).</p>
|
||
|
||
<p>This is a great opportunity to identify those bindings you actually use and
|
||
only install those.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>If you are running openHAB in a Docker container you need to create
|
||
<code class="highlighter-rouge"><openHAB home>/userdata/persistence</code> manually prior to installing a persistence
|
||
add-on.</p>
|
||
|
||
<p>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
|
||
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
|
||
PaperUI for those migrating to openHAB 2 from openHAB 1.x.</p>
|
||
|
||
<h3 id="configure-add-ons">Configure Add-ons</h3>
|
||
|
||
<p>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
|
||
generate errors during installation for special attention later.</p>
|
||
|
||
<p>Once a binding or add-on is installed, it will create a
|
||
<code class="highlighter-rouge"><openHAB 2 conf>/services/<add-on name>.cfg</code> file. Unlike in openHAB 1.x where all the
|
||
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
|
||
openhab.cfg to its new .cfg file, removing the binding name from the parameter.
|
||
For example, the parameter <code class="highlighter-rouge">nest:refresh=300000</code> in openhab.cfg becomes
|
||
<code class="highlighter-rouge">refresh=300000</code> in nest.cfg.</p>
|
||
|
||
<p>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
|
||
transfer the settings as described above.</p>
|
||
|
||
<p>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
|
||
as if this were the first installation and configuration (e.g. you need to
|
||
generate a new pin code for Nest).</p>
|
||
|
||
<p>Unlike in openHAB 1.x, transformations are not automatically included in
|
||
openHAB 2. Make sure you include these in your installation as well.</p>
|
||
|
||
<h3 id="installing-unofficially-supported-openhab-1x-add-ons">Installing Unofficially Supported openHAB 1.x Add-ons</h3>
|
||
|
||
<p>Skip this section if all the add-ons you need have been installed already.</p>
|
||
|
||
<p>First check the <a href="/v2.1/addons/1xaddons.html#currently-incompatible-1x-add-ons">list of add-ons that are known not to work in openHAB 2</a>
|
||
and make sure yours is not among them.</p>
|
||
|
||
<p>Next install the openHAB 1.x compatibility layer using the Karaf Console
|
||
instructions above.</p>
|
||
|
||
<p>Copy your openhab.cfg file to <code class="highlighter-rouge"><openHAB 2 conf>/services</code>. If you are running an apt-get
|
||
installed openHAB 1.x openhab.cfg is located in <code class="highlighter-rouge">/etc/openhab/configurations</code>.
|
||
For an apt-get installed openHAB 2 the <code class="highlighter-rouge"><openHAB 2 conf></code> folder is located in
|
||
<code class="highlighter-rouge">/etc/openhab2</code>. For manually installed openHAB 1.x this file is located
|
||
in <code class="highlighter-rouge"><openhab home>/configurations</code> and in manually installed openHAB 2 it is
|
||
<code class="highlighter-rouge"><openhab home>/conf</code>.</p>
|
||
|
||
<p>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
|
||
out and just leave the config parameters for the bindings you are manually
|
||
installing.</p>
|
||
|
||
<p>Now copy the add-on’s jar files that you want to install to the <code class="highlighter-rouge"><openHAB conf>/addons</code> folder for
|
||
openHAB 2. For example:</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>cp /usr/share/openhab/addons/org.openhab.binding.astro-1.8.3.jar /usr/share/openhab2/addons
|
||
</code></pre></div></div>
|
||
|
||
<p>There may be some errors about there not being a <code class="highlighter-rouge">bind</code> and <code class="highlighter-rouge">unbind</code> method. If
|
||
everything worked you should see in the log the same entries from the binding
|
||
you see when openHAB 1.x starts.</p>
|
||
|
||
<p>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
|
||
sort looks like:</p>
|
||
|
||
<div class="language-text highlighter-rouge"><div class="highlight"><pre class="highlight"><code>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
|
||
</code></pre></div></div>
|
||
|
||
<p>Note, the above error is for illustration purposes. You should not be
|
||
installing Astro this way.</p>
|
||
|
||
<h3 id="final-add-ons-installation-steps">Final Add-ons Installation Steps</h3>
|
||
|
||
<p>openHAB 2 has a different
|
||
<a href="/v2.1/installation/linux.html#file-locations">folder layout</a>.
|
||
Of particular node are the configuration folders and userdata folders. See the
|
||
previous link for the location of these folders for your installtion.</p>
|
||
|
||
<p>As with openHAB 1.x, one must restart openHAB 2 to pick up changes to .cfg files.
|
||
Therefore restart openHAB 2 now.</p>
|
||
|
||
<p>If you haven’t already, configure default persistence now. You can do this
|
||
through <code class="highlighter-rouge">runtime.cfg</code> or PaperUI.</p>
|
||
|
||
<p>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
|
||
have to be fixed.</p>
|
||
|
||
<p>Copy over your files in the following order:</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>cp <openHAB 1.x conf>/configurations/transform/<span class="k">*</span> <openHAB 2 conf>/transform/<span class="k">*</span>
|
||
cp <openHAB 1.x conf>/configurations/scripts/<span class="k">*</span> <openHAB 2 conf>/scripts/<span class="k">*</span>
|
||
cp <openHAB 1.x conf>/configurations/persistence/<span class="k">*</span> <openHAB 2 conf>/persistence
|
||
Copy any custom icons added from webapps/images to <openHAB 2 conf>/icons/classic
|
||
Copy any custom webviews from webapps to <openHAB 2 conf>/html
|
||
cp <openHAB 1.x conf>/configurations/items/<span class="k">*</span> <openHAB 2 conf>/items/<span class="k">*</span>
|
||
cp <openHAB 1.x conf>/configurations/rules/<span class="k">*</span> <openHAB 2 conf>/rules/<span class="k">*</span>
|
||
cp <openHAB 1.x conf>/configurations/sitemaps/<span class="k">*</span> <openHAB 2 conf>/sitemaps/<span class="k">*</span>
|
||
</code></pre></div></div>
|
||
|
||
<h2 id="necessary-changes">Necessary Changes</h2>
|
||
|
||
<h3 id="items">Items</h3>
|
||
|
||
<ul>
|
||
<li>
|
||
<p>You must now manually install any Transformation engine your Items may use.</p>
|
||
</li>
|
||
<li>
|
||
<p>The <strong>SCALE</strong> transformation has evolved.</p>
|
||
<ul>
|
||
<li>Old syntax that was <code class="highlighter-rouge">[minbound,maxbound]</code> has to be changed to <code class="highlighter-rouge">[minbound..maxbound]</code>.</li>
|
||
<li>Note that you now have the ability to exclude bounds from the ranges (e.g. <code class="highlighter-rouge">]minbound..maxbound]</code>) and also define open ranges<code class="highlighter-rouge">[minbound..]</code>.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h3 id="sitemap">Sitemap</h3>
|
||
|
||
<ul>
|
||
<li>
|
||
<p>Change the default icons to png for ClassicUI and BasicUI if migrating custom icons. This can be done in PaperUI under Configuration -> Service -> BasicUI and ClassicUI. Set the “Default Icon Format” to “Bitmap”.</p>
|
||
</li>
|
||
<li>
|
||
<p>Not all of the default icons that came with openHAB 1.x are available 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 <a href="/v2.1/addons/iconsets/classic/readme.html">here</a>.</p>
|
||
</li>
|
||
<li>
|
||
<p>Dynamic icons must have a default. For example, if one has a bunch of Wunderground icons (e.g. wunderground-chanceflurries.png) there must be a <code class="highlighter-rouge">wunderground.png</code> icon as well.</p>
|
||
</li>
|
||
<li>The URLs to the openHAB frontends have changed:
|
||
<ul>
|
||
<li>An overview of all installed UIs, including the administration UIs: <a href=""><code class="highlighter-rouge">http://<hostname>:8080</code></a></li>
|
||
<li>The direct link to your Sitemap on BasicUI <a href=""><code class="highlighter-rouge">http://<hostname>:8080/basicui/app?sitemap=<your-sitemap></code></a>.</li>
|
||
<li>The direct link to your Sitemap on ClassicUI <a href=""><code class="highlighter-rouge">http://<hostname>:8080/classicui/app?sitemap=<your-sitemap></code></a>.</li>
|
||
<li>These and all further UIs can be accessed through the overview page.</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p>The default sitemap is configured through a parameter for BasicUI and ClassicUI instead of naming the sitemap <code class="highlighter-rouge">default.sitemap</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p>Static webview files are now located in <code class="highlighter-rouge"><openhab 2 conf>/html</code> instead of <code class="highlighter-rouge">/usr/share/openhab/webapps</code></p>
|
||
</li>
|
||
<li>The name of the sitemap (i.e. the word right after <code class="highlighter-rouge">sitemap</code> at the top of the file) must match the file name. For example the file named <code class="highlighter-rouge">myhome.sitemap</code> should start with <code class="highlighter-rouge">sitemap myhome</code>.</li>
|
||
</ul>
|
||
|
||
<h3 id="rules">Rules</h3>
|
||
<ul>
|
||
<li>All references to org.openhab.core.* in imports and class references should be removed. All of these classes are automatically included and have moved.</li>
|
||
<li>import org.joda.time.* statements should also be removed.</li>
|
||
<li>To test for Items with an Undefined state replace <code class="highlighter-rouge">if(MyItem.state == Undefined)</code> with <code class="highlighter-rouge">if(MyItem.state == NULL)</code>. Case matters. <code class="highlighter-rouge">NULL</code> is only valid when testing an Item’s state to see if it is undefined. <code class="highlighter-rouge">null</code> is used pretty much everywhere else to mean “no value” and usually indicates no result or an error.</li>
|
||
<li>The <code class="highlighter-rouge">HSBType</code> state type can no longer be constructed using a <code class="highlighter-rouge">java.awt.Color</code> object, and there is no longer a <code class="highlighter-rouge">toColor()</code> method. Use the following alternatives:</li>
|
||
</ul>
|
||
|
||
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">var</span> <span class="n">HSBType</span> <span class="n">hsb</span> <span class="o">=</span> <span class="nl">HSBType:</span><span class="o">:</span><span class="n">fromRGB</span><span class="o">(</span><span class="n">color</span><span class="o">.</span><span class="na">red</span><span class="o">,</span> <span class="n">color</span><span class="o">.</span><span class="na">green</span><span class="o">,</span> <span class="n">color</span><span class="o">.</span><span class="na">blue</span><span class="o">)</span>
|
||
<span class="n">var</span> <span class="n">Color</span> <span class="n">color</span> <span class="o">=</span> <span class="nl">Color:</span><span class="o">:</span><span class="n">getHSBColor</span><span class="o">(</span><span class="n">hsb</span><span class="o">.</span><span class="na">hue</span><span class="o">.</span><span class="na">floatValue</span> <span class="o">/</span> <span class="mi">360</span><span class="o">,</span> <span class="n">hsb</span><span class="o">.</span><span class="na">saturation</span><span class="o">.</span><span class="na">floatValue</span> <span class="o">/</span> <span class="mi">100</span><span class="o">,</span> <span class="n">hsb</span><span class="o">.</span><span class="na">brightness</span><span class="o">.</span><span class="na">floatValue</span> <span class="o">/</span> <span class="mi">100</span><span class="o">)</span>
|
||
</code></pre></div></div>
|
||
|
||
<p>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.</p>
|
||
|
||
<h2 id="testing">Testing</h2>
|
||
|
||
<ul>
|
||
<li><strong>Items</strong>: Watch <code class="highlighter-rouge"><openHAB 2 userdata>/logs/events.log</code> and methodically work through all
|
||
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
|
||
period of time and/or writing new rules, using the REST API, or external scripts
|
||
to exercise all the Items.</li>
|
||
<li><strong>Persistence</strong>: Check your persistence locations to see if all your persisted
|
||
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
|
||
errors when Rules call persistence methods to get historical data (e.g.
|
||
lastUpdate). Restart openHAB and verify those Items configured with
|
||
restoreOnStartup are initialized to their last state.</li>
|
||
<li><strong>Rules</strong>: 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
|
||
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
|
||
there are no values in the database to restore the Items to when openHAB starts.</li>
|
||
<li><strong>Sitemap</strong>: The most
|
||
common Sitemap issue will be missing icons. Browse through your sitemap
|
||
methodically and identify those entries that have a missing or wrong
|
||
icon. Select an alternative from the <a href="/v2.1/addons/iconsets/classic/readme.html">defaults</a>
|
||
or copy the ones you were using from openHAB 1.x to the conf/icons/classic folder.
|
||
Both BasicUI and ClassicUI pull their icons from that folder. For details on custom icons make
|
||
sure to check the icons section in the <a href="/v2.1/configuration/items.html#icons">Items</a> documentation.
|
||
One important change since openHAB 1.x is that icon filenames need to be lowercase only in openHAB 2.</li>
|
||
</ul>
|
||
|
||
<p>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
|
||
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
|
||
2 native bindings and start taking advantage of Things and Channels (see the
|
||
next section).</p>
|
||
|
||
<p>Now is also a good time to install <a href="https://www.eclipse.org/smarthome/documentation/community/downloads.html">Eclipse SmartHome Designer</a>
|
||
to edit and review your files.</p>
|
||
|
||
<h2 id="new-concepts-things-and-channels">New Concepts: Things and Channels</h2>
|
||
|
||
<p>One of the new notions that people quickly come across when moving to openHAB 2
|
||
native bindings is that of a <a href="/v2.1/concepts/things.html">“Thing”</a>. To understand
|
||
what they are and how they relate to Items, we will compare them to how Items
|
||
are “bound” and configured in openHAB 1.x.</p>
|
||
|
||
<p>In openHAB 1.x (and importantly still for 1.9 version bindings running in openHAB
|
||
2) one had to add
|
||
<a href="https://github.com/openhab/openhab/wiki/Explanation-of-items#binding-config">“binding configuration”</a>
|
||
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
|
||
<a href="https://github.com/openhab/openhab/wiki">openHAB wiki</a> gives a nice examples of
|
||
how this looks:</p>
|
||
|
||
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">Switch</span> <span class="n">Light_Floor</span> <span class="s">"Light at Floor"</span> <span class="o">{</span> <span class="n">knx</span><span class="o">=</span><span class="s">"1/0/15+0/0/15"</span> <span class="o">}</span>
|
||
<span class="n">Switch</span> <span class="n">Presence</span> <span class="s">"I'm at home"</span> <span class="o">{</span> <span class="n">bluetooth</span><span class="o">=</span><span class="s">"123456ABCD"</span> <span class="o">}</span>
|
||
<span class="n">Switch</span> <span class="n">Doorbell</span> <span class="s">"Doorbell"</span> <span class="o">{</span> <span class="n">serial</span><span class="o">=</span><span class="s">"/dev/usb/ttyUSB0"</span> <span class="o">}</span>
|
||
<span class="n">Contact</span> <span class="n">Garage</span> <span class="s">"Garage is [MAP(en.map):%s]"</span> <span class="o">{</span> <span class="n">zwave</span><span class="o">=</span><span class="s">"21:command=sensor_binary,respond_to_basic=true"</span> <span class="o">}</span>
|
||
<span class="n">String</span> <span class="n">Error_Ventilation</span> <span class="s">"Error in Ventilation %s"</span> <span class="o">{</span> <span class="n">comfoair</span><span class="o">=</span><span class="s">"error_message"</span> <span class="o">}</span>
|
||
<span class="n">Number</span> <span class="n">DiningRoomTemp</span> <span class="s">"Maximum Away Temp. [%.1f °F]"</span> <span class="o">{</span> <span class="n">nest</span><span class="o">=</span><span class="s">"<[thermostats(Dining Room).away_temperature_high_f]"</span> <span class="o">}</span>
|
||
</code></pre></div></div>
|
||
|
||
<p>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
|
||
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
|
||
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
|
||
configurations, e.g. through user-friendly UIs.</p>
|
||
|
||
<p>Besides the syntax, the old scheme leaves the binding developers the choice to
|
||
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
|
||
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
|
||
(KNX system) to use for that Item. Instead, a single globally configured
|
||
connection is defined in the openhab.cfg file.</p>
|
||
|
||
<p>These issues were identified
|
||
<a href="https://groups.google.com/d/msg/openhab/NSiveF9U1vk/PVLemrdrpVsJ">a long time ago</a>
|
||
and the concept of
|
||
<a href="https://www.eclipse.org/forums/index.php/t/668424/">Things and Channels</a>
|
||
were introduced to solve them. The general idea is to standardize
|
||
the binding configuration and move it away from the .items file. A Thing
|
||
represents a configurable device/system/unit, which provides different
|
||
functionality through a set of one or more Channels. Each Channel corresponds
|
||
exactly to one binding configuration string (stuff in { }) in openHAB 1.x.</p>
|
||
|
||
<p>Let’s look at a concrete example. The <a href="/v2.1/addons/bindings/yahooweather/readme.html">Yahoo Weather Binding</a>
|
||
supports exactly one Thing which takes two parameters: a WOEID location and unit.</p>
|
||
|
||
<p>Thus, as described in the Binding’s readme one would manually define a Thing in
|
||
a .things file (located in conf/things) with the line:</p>
|
||
|
||
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">Thing</span> <span class="nl">yahooweather:weather:</span><span class="n">berlin</span> <span class="o">[</span> <span class="n">location</span><span class="o">=</span><span class="mi">638242</span> <span class="o">]</span>
|
||
</code></pre></div></div>
|
||
|
||
<p>As described in the Binding’s readme, three Channels are supported: temperature,
|
||
humidity, and pressure. Thus, rather than the old openHAB 1.x syntax:</p>
|
||
|
||
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// openHAB 1 Syntax</span>
|
||
<span class="n">Number</span> <span class="n">Temperature</span> <span class="o">{</span> <span class="n">yahooweather</span><span class="o">=</span><span class="s">"woeid=638242,value=temperature,unit=c"</span> <span class="o">}</span>
|
||
<span class="n">Number</span> <span class="n">Humidity</span> <span class="o">{</span> <span class="n">yahooweather</span><span class="o">=</span><span class="s">"woeid=638242,value=humidity,unit=c"</span> <span class="o">}</span>
|
||
</code></pre></div></div>
|
||
|
||
<p>with everything defined on in the { } part of the Item, we now merely reference
|
||
the Channels.</p>
|
||
|
||
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// openHAB 2 Syntax</span>
|
||
<span class="n">Number</span> <span class="n">Temperature</span> <span class="o">{</span> <span class="n">channel</span><span class="o">=</span><span class="s">"yahooweather:weather:berlin:temperature"</span> <span class="o">}</span>
|
||
<span class="n">Number</span> <span class="n">Humidity</span> <span class="o">{</span> <span class="n">channel</span><span class="o">=</span><span class="s">"yahooweather:weather:berlin:humidity"</span> <span class="o">}</span>
|
||
</code></pre></div></div>
|
||
|
||
<p>As you can see, the Channel ID consists of the Thing’s name, a “#” and the
|
||
Channel name.</p>
|
||
|
||
<p>For manually defined Things, you can find the syntax for defining a Thing on a
|
||
given Item in that Binding’s readme.</p>
|
||
|
||
<p>However, with the concept of Things some openHAB 2 bindings are able to
|
||
automatically discover and create Things for you. These automatically created
|
||
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
|
||
Things in one of the admin UIs it will list all of the supported Channels the
|
||
Thing supports. To define an Item for one of these Channels, simply copy the
|
||
Channel ID into your Item’s definition like the above.</p>
|
||
|
||
<p>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
|
||
the <a href="https://github.com/openhab/openhab/wiki">openHAB 1.x wiki</a>.</p>
|
||
|
||
<h2 id="retire-openhab-1x">Retire openHAB 1.x</h2>
|
||
|
||
<p>Now that you have a fully running and tested openHAB 2 instance, now is the time to
|
||
disable and remove openHAB 1.x. Stop openHAB 1.x if it is running:</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">sudo </span>systemctl stop openhab.service
|
||
</code></pre></div></div>
|
||
|
||
<p>Next disable openHAB 1.x from starting as a service.</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">sudo </span>systemctl disable openhab.service
|
||
</code></pre></div></div>
|
||
|
||
<p>Finally, enable openHAB 2 to start as a service.</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">sudo </span>systemctl <span class="nb">enable </span>openhab2.service
|
||
</code></pre></div></div>
|
||
<p>Back up your openHAB 1.x configurations and uninstall openHAB 1.x if desired.</p>
|
||
|
||
<h2 id="migrating-to-openhab-2-bindings">Migrating to openHAB 2 Bindings</h2>
|
||
|
||
<h3 id="eclipse-smarthome-designer">Eclipse SmartHome Designer</h3>
|
||
|
||
<p>As mentioned above, there is a new Integrated Development Environment (IDE) for
|
||
openHAB 2 configurations,
|
||
<a href="https://www.eclipse.org/smarthome/documentation/community/downloads.html">Eclipse SmartHome Designer</a>.
|
||
The old openHAB Designer is not compatible with openHAB 2.</p>
|
||
|
||
<h3 id="myopenhab">My.openHAB</h3>
|
||
|
||
<p>There is no 1.9 My.openHAB binding that is compatible with openHAB 2, only a
|
||
native 2.0 binding. Furthermore, one can have only one openHAB instance linked to
|
||
a http://my.openhab.org account at a time. This is why we have saved migrating this
|
||
binding until now.</p>
|
||
|
||
<p>Each openHAB instance generates its own unique UUID and Secret so one cannot simply
|
||
copy these files from your old openHAB 1.x installation.</p>
|
||
|
||
<p>Using your preferred method for add-on installation (see above) install the
|
||
My.openHAB binding. Once installed a new <code class="highlighter-rouge">uuid</code> and <code class="highlighter-rouge">secret</code> file will be created.
|
||
These two files are located in a different place in openHAB 2:
|
||
<code class="highlighter-rouge"><openhab 2 userdata>/uuid</code> and <code class="highlighter-rouge"><openHAB 2 userdata>/myopenhab/secret</code>.
|
||
As of this writing, the http://my.openhab.org documentation still references the
|
||
openHAB 1.x locations.</p>
|
||
|
||
<p>Log into your My.openHAB account and select “Account” from the pull down menu
|
||
under your email:</p>
|
||
|
||
<p><img src="images/myopenhab-account.png" alt="My.openHAB Account Menu" /></p>
|
||
|
||
<p>Copy the contents of the <code class="highlighter-rouge">uuid</code> file into the openHAB UUID field. Copy the contents
|
||
of the <code class="highlighter-rouge">secret</code> file into the openHAB Secret field.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p><img src="images/myopenhab-connected.png" alt="My.openHAB Account Menu" /></p>
|
||
|
||
<h3 id="other-bindings">Other Bindings</h3>
|
||
|
||
<p>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
|
||
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.
|
||
Astro). See the add-on’s <a href="/v2.1/addons/1xaddons.html">wiki page</a> and
|
||
<a href="/v2.1/addons/bindings.html">readme page</a> to compare and contrast the two versions.</p>
|
||
|
||
<p>Identify an add-on where there is a 2.0 version that you want to migrate to. Begin
|
||
by identifying those Items that use this binding. On Linux/OSX this can easily be
|
||
done with the following command</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">grep</span> <binding> <openHAB 2 conf>/items/<span class="k">*</span>
|
||
</code></pre></div></div>
|
||
<p>where <code class="highlighter-rouge"><binding></code> is the string used in the binding config on the Item. For example:</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">grep </span>zwave /etc/openhab2/items/<span class="k">*</span>
|
||
<span class="nb">grep </span>astro /opt/openhab2/conf/items/<span class="k">*</span>
|
||
</code></pre></div></div>
|
||
|
||
<p>Now comment out those Items to ensure there are no unexpected interactions between
|
||
the old configurations and the new ones.</p>
|
||
|
||
<p>Next uninstall the 1.9 binding. In the Karaf console use the command
|
||
<code class="highlighter-rouge">feature:uninstall <add-on name></code>. 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
|
||
choose uninstall.</p>
|
||
|
||
<p>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
|
||
relevant.</p>
|
||
|
||
<p>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
|
||
you have not done so already.</p>
|
||
|
||
<p>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
|
||
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
|
||
speed this up. Or from the Karaf console one can run:</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>smarthome:discovery openhab-binding-<binding name>
|
||
</code></pre></div></div>
|
||
|
||
<h2 id="managing-the-inbox-things-and-channels">Managing the Inbox, Things, and Channels</h2>
|
||
|
||
<h3 id="managing-the-inbox-using-paperui">Managing the Inbox using PaperUI</h3>
|
||
|
||
<p>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
|
||
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
|
||
one can get the list of Channel IDs for that Thing.</p>
|
||
|
||
<h3 id="managing-the-inbox-using-the-karaf-console">Managing the Inbox Using the Karaf Console</h3>
|
||
|
||
<p>In the Karaf console you can see everything in the Inbox with the command:</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>smarthome:inbox
|
||
</code></pre></div></div>
|
||
|
||
<p><img src="images/karaf-inbox.png" alt="Karaf console inbox listing" /></p>
|
||
|
||
<p>NOTE: The screenshot above shows Ignored Inbox Items. New Items will not show
|
||
“IGNORED”.</p>
|
||
|
||
<p>To accept a Thing from the Inbox run:</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>smarthome:inbox approve <thingId>
|
||
</code></pre></div></div>
|
||
|
||
<p>Once approved one can get the list of Channel IDs with the command:</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>smarthome:links list
|
||
</code></pre></div></div>
|
||
|
||
<p>You can narrow down the list using grep:</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>smarthome:links list | <span class="nb">grep</span> <Thing ID>
|
||
</code></pre></div></div>
|
||
|
||
<p>To ignore a Thing in the Inbox use the command:</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>smarthome:inbox ignore <thingId>
|
||
</code></pre></div></div>
|
||
|
||
<h3 id="linking-channels-to-items">Linking Channels to Items</h3>
|
||
|
||
<p>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
|
||
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.</p>
|
||
|
||
<p>Open your .items files where you commented out the Items that used the old version
|
||
of the binding. Replace the old binding’s configuration with the Channel ID that
|
||
Item represents. For example:</p>
|
||
|
||
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">Switch</span> <span class="n">S_L_Family</span> <span class="s">"Family Room Lamp"</span> <span class="o"><</span><span class="n">light</span><span class="o">></span> <span class="o">{</span><span class="n">zwave</span><span class="o">=</span><span class="s">"10:command=switch_binary,respond_to_basic=true"</span><span class="o">}</span>
|
||
</code></pre></div></div>
|
||
|
||
<p>becomes</p>
|
||
|
||
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">Switch</span> <span class="n">S_L_Family</span> <span class="s">"Family Room Lamp"</span> <span class="o"><</span><span class="n">light</span><span class="o">></span> <span class="o">{</span><span class="n">channel</span><span class="o">=</span><span class="s">"zwave:device:528f7aca:node10:switch_binary"</span><span class="o">}</span>
|
||
</code></pre></div></div>
|
||
|
||
<p>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
|
||
Rules, Sitemaps, or Persitence. Test your Items each step of the way to verify
|
||
they are working.</p>
|
||
|
||
<h3 id="manually-creating-things">Manually Creating Things</h3>
|
||
|
||
<p>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
|
||
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
|
||
that will be closer to the openHAB 1.x way of doing things.</p>
|
||
|
||
<p>All definitions of new Things are written to .things files in the
|
||
<code class="highlighter-rouge"><openHAB 2 conf>/things</code> folder. The syntax for a Thing definition varies from
|
||
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
|
||
supports. As discussed above, the Channel ID will be the <code class="highlighter-rouge"><Thing ID>#<channel></code>.</p>
|
||
|
||
</div>
|
||
</section>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<footer>
|
||
<div class="container">
|
||
<div class="row">
|
||
<div class="col s12 m7">
|
||
Copyright © 2017 by the <a href="https://github.com/openhab">openHAB Community</a> and the <a href="http://www.openhabfoundation.org/">openHAB Foundation e.V.</a>
|
||
</div>
|
||
<div class="col s12 m5">
|
||
<ul class="list-inline right-align">
|
||
<li><a href="/imprint.html">Imprint</a></li>
|
||
<li><a href="/privacy.html">Privacy Policy</a></li>
|
||
<li><a href="http://www.openhab.org">openHAB Website</a></li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</footer>
|
||
<script src="/v2.1/js/jquery.min.js"></script>
|
||
<script src="/v2.1/js/jquery.scrollme.min.js"></script>
|
||
<script src="/v2.1/js/jquery.sticky.js"></script>
|
||
<script src="/v2.1/js/materialize.min.js"></script>
|
||
<script src="/v2.1/js/init.js"></script>
|
||
|
||
<script>
|
||
$(document).ready(function () {
|
||
|
||
$('#oh2-checkbox').change(function () {
|
||
if (this.checked) $('.since-2x').show('slow');
|
||
else $('.source-oh2').hide('slow');
|
||
});
|
||
|
||
$('#oh1-checkbox').change(function () {
|
||
if (this.checked) $('.since-1x').show('slow');
|
||
else $('.source-oh1').hide('slow');
|
||
});
|
||
|
||
$('#legacy-checkbox').change(function () {
|
||
if (this.checked) $('.install-legacy').show('slow');
|
||
else $('.install-legacy').hide('slow');
|
||
});
|
||
|
||
$('#manual-checkbox').change(function () {
|
||
if (this.checked) $('.install-manual').show('slow');
|
||
else $('.install-manual').hide('slow');
|
||
});
|
||
|
||
});
|
||
</script>
|
||
|
||
</body>
|
||
</html>
|
||
|