search

openhab / openhab-docs

This repository contains the documentation for openHAB.
https://www.openhab.org/docs/
Other
270 stars 686 forks source link

Add step by step instructions and lessons learned to Migration from 1.x tutorial #86

Closed rkoshak closed 7 years ago

rkoshak commented 7 years ago

The existing "Migration from openHAB 1 to openHAB 2" has a lot of important information about what will be different between OH 1.x and OH 2 but it really isn't a tutorial. there are no step by step instructions. I'm going to start the migration process myself and will use my experiences to beef up these instructions.

ThomDietrich commented 7 years ago

I think it would be important to mention, that you can go with or without PaperUI. These two need to be discussed equally.

ThomDietrich commented 7 years ago

Here's something I wrote a few weeks back for a friend and was planing to post to the forum, never got around doing it. I just browsed through it and it's already a bit outdated... maybe you want to use parts of it.

Paperless OH2 - a config based setup

Regardless of whether you are completely new to openHAB or you already have your home all wired up by the use of openHAB 1.8, the time is here to hop on the openHAB 2 bandwagon. The core seems to be stable and development on bindings you might like or want has mostly moved on to the OH2 ecosystem. In this thread, I'm going to tell you a few things I found useful in my transition from openHAB 1.8 to version 2.0 (latest build). The whole process is mostly clear and most would be able to figure it out. Maybe I can spare you a few minutes ;) For some reasons, I will steer clear from PaperUI (the novel graphical configuration frontend) for the moment.

To be clear: PaperUI is a big step forward in the world of openHAB and will probably soon reach a point where it can be recommended for general use by everybody. I chose to stay with a configuration file based system for now. I will be the first to switch over to the new PaperUI- and database-based configuration system as soon as it hits a finished state. Thanks to all working towards that goal!

The openHAB 2 basics

Here you'll find a few links useful in getting you started:

Getting ready & Installation

For a few reasons (24/7 dedicated system, hardware extensions, modularity) it might be a good idea to have a small linux system serving as your openHAB base (a RaspberryPi is actually a pretty good choise). You can however run openHAB wherever you want, Linux, Windows and Mac OSX are all supported thanks to the Java runtime. From here on out I'll assume a stand alone linux base, if your setup is different, your approach might be different.

If you have an openHAB 1.8 installation, back up your configuration and all other personal openHAB data (icons, logging databases, ...). You'll be able to reuse most of it, even though some modifications will be needed. Start off by stopping and uninstalling the existing setup.

Install the newest release of openHAB 2 on your system. On linux, I'd recommend following the guides for a repository based installation and considering setting up a samba share as described in the RaspberryPi article. You should be able to reach the landing page ([http://:8080]) of your openHAB and have the configuration share mounted on your local system.

Lastly get the Eclipse SmartHome Designer up and running on your local machine.

Logging

It's a good idea to always have a look at the openHAB log and the events log. These will tell you everything you might need to know. In fact, configuring and debugging your setup will be a nightmare without them. You could even set up an SSH configuration (in putty or similar) to automatically connect and show the logs everytime you feel nerdy. Execute the following command in one session or have both files seperated in sessions side by side:

tail -f /var/log/openhab/openhab.log -f /var/log/openhab/events.log

With openHAB2 you can also use the Karaf console to have a colored glance at the logging information.

Karaf console

The Karaf console is an important tool you should accustom yourself with. If your local network is secure, think about configuring the console to bind to a public interface so you can directly connect via SSH. In the console you can view the log, manage bundles (e.g. bindings) or control the openHAB runtime. You will find most useful commands in the documentation.

PaperUI

Even though I said PaperUI will not take part in the configuration, it's a great help in some areas. It's easy to check out the Things Inbox (I will not add Things from there) or you may use it to install Bindings. The same is possible from the Karaf console of course.

Things and Items

You should be ready and set to configure your files for things and items. At this point your steps forward highly depend on the bindings you are going to use. Choose one of those already thoroughly documented in the openHAB2 documentation: Bindings

Let's take the Astro binding and the Homematic binding as examples. It's clearly documented which things you need to define and which items can be linked to these. Examples are given at the bottom. Available bindings a documentation are most probably in the wiki, but these articles might be outdated.

...to be continued...

.. or not

rkoshak commented 7 years ago

I like that write-up a lot. Do you think that information about PaperUIless should be the main thread for the migration path or should I treat it as an aside (i.e. show migration using PaperUI and say by-the-way, you can do it without this way if you want). The nice thing about it is that it keeps OH 2 looking more like OH 1 in terms of configuration. However, I don't want to steer users away from new features unnecessarily.

ThomDietrich commented 7 years ago

"I like that write-up a lot." Thanks! Please shamelessly use as much as you can!

I think this should be a "by-the-way". Saying otherwise I would be in big trouble with @kaikreuzer I guess :laughing:

I do not want to steer away from PaperUI, this is just the alternative path for when users need to know about it. As I said: "PaperUI is a big step forward in the world of openHAB and will probably soon reach a point where it can be recommended for general use by everybody".

I am struggling with it though. In my opinion, it would have been strategically better to start of with configuration files (or any other low level powerful exchange format) being linked in both directions with the new database approach and then building a web frontend around the database, making configuration files obsolete over time without hindering transition. I mentioned this in more detail here

kaikreuzer commented 7 years ago

I think this should be a "by-the-way". Saying otherwise I would be in big trouble with @kaikreuzer I guess 😆

No, you wouldn't! I personally prefer the "paperless" approach myself and will stick to using configuration files. This is also why I forced everybody to add a textual configuration example in the binding READMEs - to make sure that this is easily possible and also documented for the users.

My recommendation for "power users" would be to go this path (and definitely for 1.x users) - and thus I think this should also appear in the documentation as a standard option and not only "by-the-way".

ThomDietrich commented 7 years ago

That's very interesting to know. Now I'm burning to know your opinion on the last paragraph regarding the database. The discrepancy between config files and the database is one of my biggest concerns right now and a topic mentioned in the forum every other day :-/

kaikreuzer commented 7 years ago

I'll try to answer it short: The reason why the UIs do not edit the config files is that nobody implemented it. You should note that the Paper UI + the database-driven providers were contributed to ESH by a company that uses ESH, but not openHAB - and where config files do not play any role and thus the whole Xtext stuff is not part of their stack. I made sure that the textual configuration as known from openHAB is kept and also supported for all new features (e.g. definition of "Things"). The database + Paper UI came "for free" to openHAB (meaning, nobody implemented it for openHAB, but yet it is compatible and brings value) and we have to figure out how to "marry" these two configuration options best.

What would have been the other options?

Hope this explains a bit the background!

rkoshak commented 7 years ago

I will rework the tutorial on the forums to make PaperUI as the secondary approach and paperless as the primary approach. I'm hoping to get some more feedback on the tutorial, and I'm still working through some exercises to make sure I have all of the bases covered (e.g. I don't yet have manually creating Things documented, just auto discovered).

ThomDietrich commented 7 years ago

@kaikreuzer thanks! Knowing the background behind a situation is worth a lot. "new config files that are both human-readable as well as modifiable through UIs" - that is exactly what I would declare as the right approach. From what I can grasp from the PR, this is quite amazing! I'll have to create a comment over there soon :) Regarding removing Xtext from openHAB... fun fact: I am still thinking about how to (elegantly) get correct Xtext syntax highlighting into the docs and the community forum - such a silly endeavor...

@rkoshak Okay great! Please let me know which parts you want me to contribute (if any)!

kaikreuzer commented 7 years ago

such a silly endeavor...

Haha, not really! I guess we will be have Xtext config around for the next years to come, so I don't think such efforts would be in vain.

rkoshak commented 7 years ago

The article has been up on the forum here for awhile. It seems to be pretty complete, at last there are not many problems or questions being generated any longer. If there are no further comments from this group I'll submit the PR.

kaikreuzer commented 7 years ago

If there are no further comments from this group I'll submit the PR.

One month has passed, I would assume it might make sense to move the content over to here now!

ThomDietrich commented 7 years ago

Agreed!