210 lines
13 KiB
HTML
210 lines
13 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>Compatibility - openHAB 2 - Empowering the Smart Home</title>
|
|
|
|
<!-- CSS -->
|
|
<link type="text/css" rel="stylesheet" href="/v2.2/css/materialize.css" media="screen,projection" />
|
|
<link type="text/css" rel="stylesheet" href="/v2.2/css/pygments-jekyll-style.css" />
|
|
<link type="text/css" rel="stylesheet" href="/v2.2/css/styles.css" />
|
|
<link type="text/css" rel="stylesheet" href="/v2.2/css/openhab.css" />
|
|
<link type="text/css" rel="stylesheet" href="/v2.2/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="https://docs.openhab.org/developers/development/compatibilitylayer.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.2/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.2/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.2/index.html">Home</a></li>
|
|
<li><a href="/tutorials/index.html">Tutorials</a></li>
|
|
<li><a href="/v2.2/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">
|
|
<div class="side-nav-wrapper">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<ul class="nav">
|
|
<li><a href="/v2.2/developers">Overview</a></li>
|
|
<li><a href="/v2.2/developers/contributing/contributing">Contributing</a></li>
|
|
<li><a href="/v2.2/developers/prerequisites/osgi.html">Prerequisites</a>
|
|
<ul>
|
|
<li><a href="/v2.2/developers/prerequisites/osgi.html">OSGi</a>
|
|
<ul>
|
|
<li><a href="/v2.2/developers/prerequisites/osgi.html">Overview</a></li>
|
|
<li><a href="/v2.2/developers/prerequisites/osgids.html">Declarative Services</a></li>
|
|
<li><a href="/v2.2/developers/prerequisites/configadmin.html">Configuration Admin</a></li>
|
|
<li><a href="/v2.2/developers/prerequisites/osgitasks.html">Coding tasks</a></li>
|
|
<li><a href="/v2.2/developers/prerequisites/eventadmin.html">Event Admin</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="/v2.2/developers/prerequisites/tycho.html">Tycho</a></li>
|
|
<li><a href="/v2.2/developers/prerequisites/equinox.html">Equinox</a></li>
|
|
<li><a href="/v2.2/developers/prerequisites/targetplatform.html">Target Platform</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="/v2.2/developers/development/ide.html">Basics</a>
|
|
<ul>
|
|
<li><a href="/v2.2/developers/development/ide.html">IDE Setup</a></li>
|
|
<li><a href="/v2.2/developers/development/guidelines.html">Code Guidelines</a></li>
|
|
<li><a href="/v2.2/developers/development/bindings.html">Developing Bindings</a></li>
|
|
<li><a href="/v2.2/developers/development/logging.html">Logging</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="/v2.2/developers/development/evolution.html">Migration from 1.x</a>
|
|
<ul>
|
|
<li><a href="/v2.2/developers/development/evolution.html">Technical Differences</a></li>
|
|
<li><a href="/v2.2/developers/development/compatibilitylayer.html">Compatibility Layer</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
</div>
|
|
<div class="content">
|
|
|
|
<h1 id="compatibility-layer-for-openhab-1x-add-ons">Compatibility Layer for openHAB 1.x Add-ons</h1>
|
|
|
|
<p>openHAB 2 used <a href="https://www.eclipse.org/smarthome/">Eclipse SmartHome</a> as its core framework. Although many classes are similar, all of them have at least a different namespace (<code class="highlighter-rouge">org.eclipse.smarthome</code> instead of <code class="highlighter-rouge">org.openhab</code>) - as a result, none the existing 1.x add-ons would work on openHAB 2.</p>
|
|
|
|
<p>To still make it possible to use 1.x add-ons, there is a special bundle in openHAB 2, which serves as a compatibility layer. It effectively exposes and consumes all relevant classes and services from the <code class="highlighter-rouge">org.openhab</code> namespace and internally delegates or proxies them to the according <code class="highlighter-rouge">org.eclipse.smarthome</code> classes and services.</p>
|
|
|
|
<p>Currently, the compatibility layer focuses on the official APIs, i.e. an add-ons that does no dirty things should be able to run. Taking the huge number of 1.x add-ons into account, it is likely that there are a couple of problems with one or another. Some problems might be due to bugs in the compatibility bundle, others might be solvable within the add-on.</p>
|
|
|
|
<h2 id="how-to-use-openhab-1x-add-ons-that-are-not-part-of-the-distribution">How to use openHAB 1.x Add-ons that are not part of the distribution</h2>
|
|
|
|
<p>While the openHAB distribution already contains many add-ons of openHAB 1, there are still quite some of them missing - please help testing them - if they are confirmed to be working, they can be included in the distribution.
|
|
Test a not included add-on is very straight forward:</p>
|
|
<ul>
|
|
<li>Start your runtime</li>
|
|
<li>Install the 1.x compatibility layer by running <code class="highlighter-rouge">feature:install openhab-runtime-compat1x</code> in the openHAB console</li>
|
|
<li>As with openHAB 1.x, simply take the jar file of your add-on and place it in the <code class="highlighter-rouge">${openhab.home}/addons</code> folder.</li>
|
|
<li>Copy your personal <code class="highlighter-rouge">openhab.cfg</code> file to <code class="highlighter-rouge">${openhab.home}/conf/services/openhab.cfg</code>.</li>
|
|
</ul>
|
|
|
|
<h2 id="how-to-solve-problems-with-a-certain-add-on">How to solve problems with a certain add-on?</h2>
|
|
|
|
<p>All developers are encouraged to help on this in order to quickly make as many 1.x add-ons compatible with the openHAB 2 runtime as possible.
|
|
Here is what you need to do:</p>
|
|
<ul>
|
|
<li>Setup a the <a href="../development/ide.html">openHAB 2 IDE</a>.</li>
|
|
<li>Import your 1.x add-on from your local openHAB 1 git clone into your workspace.</li>
|
|
<li>If it compiles, the first major step is already done. If not, try to figure out why there are compilation problems and if you cannot solve them, ask on the mailing list for help.</li>
|
|
<li>After adding some configuration, start up the runtime through the launch configuration (make sure your bundle is activated and started by default) from within the IDE.</li>
|
|
<li>Go and test and report your findings by creating issues or pull requests for the <a href="https://github.com/openhab/openhab/issues">add-on in openHAB 1</a>.</li>
|
|
</ul>
|
|
|
|
<h2 id="how-to-add-a-successfully-tested-1x-add-on-to-the-distribution">How to add a successfully tested 1.x Add-on to the distribution</h2>
|
|
|
|
<ol>
|
|
<li>The first step is to create a “Karaf feature” for it, in which required dependencies (i.e. to io.transport bundles) can also be declared. Such a feature can also include the required configuration, therefore you should create a file <code class="highlighter-rouge"><youraddon>.cfg</code> in <code class="highlighter-rouge">features/openhab-addons-external/src/main/resources/conf</code> with the same content as what is within <code class="highlighter-rouge">openhab.cfg</code>, but without the <code class="highlighter-rouge"><yourbinding>:</code> prefix on the lines of the parameters.
|
|
This config file then needs to be added to <code class="highlighter-rouge">features/openhab-addons-external/pom.xml</code> so that the build is aware of it.
|
|
The feature itself is then added to <code class="highlighter-rouge">features/openhab-addons/src/main/feature/feature.xml</code>, referencing the bundle, the config file and its dependencies (if any). The result should look <a href="https://github.com/openhab/openhab/pull/3988/files">similar to this</a>.
|
|
This will automatically make the add-on a part of the distro with the next build.</li>
|
|
<li>Note that with defining a Karaf feature, bindings are available for installation through the Paper UI in the “Extensions” menu, but they are not listed under “Configuration->Bindings” (although it is fully operational after installation). In order to have bindings listed there as well, you need to add some meta-information to the binding bundle. This information should be put into <code class="highlighter-rouge">ESH-INF/binding/binding.xml</code> and its content is <a href="https://www.eclipse.org/smarthome/documentation/development/bindings/xml-reference.html#xml-structure-for-binding-definitions">described here</a>. Do not forget to add <code class="highlighter-rouge">ESH-INF</code> to your <code class="highlighter-rouge">build.properties</code>, so that it is packaged in the bundle. See a <a href="https://github.com/openhab/openhab/blob/master/bundles/binding/org.openhab.binding.nest/ESH-INF/binding/binding.xml">real life example of such meta-data here</a> - note the <code class="highlighter-rouge">service-id</code> element in the XML, which needs to point to the service id of your binding, which is by default <code class="highlighter-rouge">org.openhab.<bindingId></code> for all 1.x bindings.</li>
|
|
</ol>
|
|
|
|
<h2 id="future-plans">Future Plans</h2>
|
|
|
|
<p>Note that the maintenance and support of the 1.x add-ons will continue. There is absolutely no need and no rush to port them to the new 2.x APIs - especially as there are only new APIs for bindings so far, but nothing yet for actions, persistence services or other types of add-ons. Even for bindings you have to be aware that the new APIs are not yet stable and are likely to change over time. Nonetheless, if you <a href="../development/bindings.html">start a completely new binding</a> for openHAB, you are encouraged to go for openHAB 2 APIs directly - especially, if your devices can be discovered and formally described. A positive side effect of implementing a binding against the new APIs is the fact that your code is potentially automatically compatible with other Eclipse-SmartHome-based systems (of which there will be more in future).</p>
|
|
|
|
</div>
|
|
</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>
|
|
<li><a href=# onclick="printPage()">Print This Page</a></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</footer>
|
|
<script src="/v2.2/js/jquery.min.js"></script>
|
|
<script src="/v2.2/js/jquery.scrollme.min.js"></script>
|
|
<script src="/v2.2/js/jquery.sticky.js"></script>
|
|
<script src="/v2.2/js/materialize.min.js"></script>
|
|
<script src="/v2.2/js/init.js"></script>
|
|
<script src="/v2.2/js/functions.js"></script>
|
|
</body>
|
|
</html>
|
|
|
|
<script>
|
|
var host = "docs.openhab.org";
|
|
if (!(window.location.host.startsWith("127.0.0.1")) && (host == window.location.host) && (window.location.protocol != "https:"))
|
|
window.location.protocol = "https";
|
|
</script>
|
|
|