Moving from OpenHAB 1.x to OpenHAB 2 (Linux)

[papa]

I just installed OpenHAB 2 on my Linux laptop.  Having a big investment in installing, tweaking, & using version 1.8.x & not wanting to take time from other DIY Home Automation projects, I postponed the upgrade.  That changed since OpenHAB 2 was recently announced as the official release, 1.8.x maintenance is waning, AND I was noticing more questions about moving to OpenHAB 2.

PS OpenHAB 2 used Mosquitto (MQTT) that I had previously installed for OpenHAB 1.8.x

 Coming from OpenHAB 1.8.x & already having config files, I particularly used this official migration documentation.  I also used the official documentation here & this installation introduction & menu.
I did not use this Tutorial for Beginners but it looks interesting to go back to at some point & may be most helpful for those FIRST installing OpenHAB.

At this point, I won't make a detailed run-down on installing OpenHAB 2, unless that seems to be more effective.  I found the official documentation pretty helpful.  Being fairly familiar with OpenHAB 1.8.x probably helped. Also at this point, I also will not aim to document an install for someone brand new to OpenHAB.  However, what I provide might be useful for that.

This thread will be hints about migrating from OpenHAB 1.x to OpenHAB 2 (Linux). Some of what I will aim to document:  some difficulties I had; at least one warning that should have been earlier; some approaches that I believe are better than what was presented; plus emphasizing some warnings even if they are well placed.

Disclosures: Although OpenHAB baffles & frustrates me sometimes, I'm a big fan.  Also I've mostly worked with Windows in the past.  A year ago, I spent a few months learning & using Linux to implement OpenHAB 1.8.x on my re-purposed Linux laptop & then I mostly set Linux aside until this recent flurry.  So my Linux knowledge / experience is limited & I often look things up.  You may see places below that could be done better in Linux.  I welcome suggestions & corrections.

If you're new to OpenHAB, I no longer recommend installing OpenHAB 1.8.x & transferring your config files to OpenHAB 2 later.  I recommend you start with OpenHAB 2.  You might start with that Tutorial for Beginners, but check this thread to see if anything applies to your situation.

BTW, I invite & welcome others to post on this thread their experience & hints with migrating from OpenHAB 1.x to OpenHAB 2 (Linux).  I also encourage other threads on this forum about "virgins'" experience & hints about installing OpenHAB 2.  Let's help each other make the most of this tool.

    I suggest you keep this thread open in a browser tab so it can be a bread crumb trail through the different pages migration uses.

To be continued below:  hints about migrating from OpenHAB 1.x to OpenHAB 2 (Linux)

[papa]

        If you followed how I migrated from OpenHAB 1 to OpenHAB 2 (& tweaked it in retrospect), I believe you would ...

Start at the Migration Tutorial. I recommend you keep this document open or one might get lost.  Near the top is "This page is structured as follows: (Table of Contents with links to the tutorial sections)" The Table of Contents links jump WITHIN the Migration Tutorial. Links within the Tutorial go to NEW pages so I recommend you right click those links & open them in new browser tabs so you can return to an open Migration Tutorial where you left off.

In the following, I list the Migration Tutorial section name & my comments under it.

    Migration Tutorial / Backups

Backups are a good idea though OpenHAB 2 does not seem to overwrite OpenHAB 1 stuff. Since I used the apt-get method to install OpenHAB 1 & 2, those locations worked.

    Migration Tutorial / Shutown openhab 1.x
sudo systemctl stop openhab.service may work. I use sudo /etc/init.d/openhab stop

    Migration Tutorial / Install openHAB 2
FIRST read about the two choices. To me,  Offline (unless your computer is short on storage) & Beta seemed the best choices.

THEN right click the link at the section's top & open the Installation page in a new browser tab.

    To be continued below

[papa]

                Installation Overview Sections

        Installation / Prerequisites

Latest stable Java version (currently 8, though ?? also listed as 1.8.x) Since I already had openjdk, I tried that, had trouble & then tried Oracle Java & had trouble. After much hassle, I eventually got openjdk working. The section recommends Zulu. I don't know if that would be an easier & workable install.

Another way to get Oracle Java is on another page, in a section called "Meeting the Requirements". Right click, new tab to see it & be able to return to the Installation Overview browser tab.

    Installation / Setup variants (more decisions)
I chose Package Setup (recommended) & Stable

    Installation / Getting started
Come back to this after the install. I chose to work on my own configuration files from OpenHAB 1.x

    Installation / Help ... If you don't know the OpenHAB Community Forum, make note of it.

        To be continued below

[papa]

Still in the Installation document, at the upper left, right click your OS (Linux in this case) & open that in a new tab.

        Installation Linux Sections
(Here you implement the choices previewed above.)

        Installation Linux / Package Repository Installation (Recommended)

As I said above, I chose Package Setup (recommended) & NOT Manual (which is much lower on the page)

     I also chose Official (Stable) Release.

As appropriate to your choices, read & follow instructions through the section about "start openHAB and register it to be automatically executed at system startup"    Added 2/15/2017 ...
        To start openhab 2 I used                                 sudo /etc/init.d/openhab2 start
        To check openhab 2's running I used                     sudo /etc/init.d/openhab2 status
        To set openhab 2 to run at system startup, I used        sudo update-rc.d openhab2 defaults

Caution:  See the Feb 15, 2017 post below:  Before you reboot your computer, be sure you remove OpenHAB ONE from starting automatically at startup.

After following OpenHAB 2 start instructions, note that it says, "The first start may take up to 15 minutes ...

      Caution:  It then says what I recommend you postpone & come back later (because you may start some things prematurely):
"You should be able to reach the openHAB 2 portal at http://openhab-device:8080 at this point. If you’re new to openHAB, then you should checkout the beginner’s tutorial!"

I recommend you just skim the rest of the Installation Linux document & come back to it later & come back to the beginner tutorial later.

Added 2/12/2017, I also recommend you now close the OpenHAB 2 portal tab & stop OpenHAB 2:
    
sudo /etc/init.d/openhab2 stop
(So edited .cfg files are loaded, we'll restart OpenHAB 2 after editing those files.)

    To Be Continued below ...

[papa]

Postponing some things (as mentioned above), now resume the migration tutorial (still open in a browser tab ?) or open this in a new tab.

Resume migration at the section, Prepare openHAB 2 for the Existing openHAB 1.x Configuration.

Updated 2/12/2017:  Do follow the first thing instructed: "navigate to http://<openhab server ip>:8080 where <openhab server ip> is the address of the server where openHAB 2 is running."  That is, if 192.168.10.9 is the IP address of the computer running OpenHAB 2, [In a new browser tab] enter 192.168.10.9:8080  Then return to the Migration Tutorial in the section Prepare openHAB 2 for the Existing openHAB 1.x Configuration.

Then Migration says, "There are three approaches to install & configure bindings [openhab configs]: text based, via Karaf console, or using an administration GUIs (i.e. PaperUI or Habmin 2). ... The text based approach is recommended for those coming from openHAB 1.x as it will be more familiar and flexible."

I also recommend the Text-Based approach (may be more challenging at first, but cause less problems later).  I started the PaperUI approach & then cancelled all because ...

This warning at the end of the PaperUI approach should have been earlier:  "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."  ?? Maybe newcomers to OpenHAB should also take those recommendations & warnings seriously.

    To Be Continued Below:  Text-Based approach to install & configure bindings [openhab configs]

[papa]

Still in the Migration Tutorial, in the section Prepare openHAB 2 for the Existing openHAB 1.x Configuration, work your way through the Text Based section.

For the recommended apt-get installed OpenHAB 2, using a Linux text editor (open as an administrator), edit /etc/openhab2/services/runtime.cfg. There, as in the shown recommendations, edit three openHAB2 global parameters & save the changed file. When you edit the indicated parameter lines, be sure no "#" character starts the line to disable it.

Then as directed, edit items in /etc/openhab2/services/addons.cfg (For a preview, see the sample addons.cfg file below the item list.)
        Papa's supplemental comments about some addons items:
I believe I followed all the recommendations.

Seems entries are lower case (I don't know if case-sensitive applies.), comma separated, & no space after the comma.

        In a file browser window, open /usr/share/openhab/addons (OpenHAB ONE addons)
Note file names that include: binding.xxx (like binding.mqtt), action.xxx, persistence.xxx & what ones you plan to use in OpenHAB 2.

Go to this list & find all the bindings you'll use & note whose buttons say "since 1.x" Add a 1 to that binding name, mqtt1 for example.
    binding  Mine looks like
binding = http,mqtt1,weather,ntp    corrected to ...
binding = http1,mqtt1,weather1,ntp

    ui, mine looks like
ui = paper,classic,habpanel

    persistence, names of persistence addons you noted above. mine ...
persistence = rrd4j,mapdb

    action addons you noted above. mine ...
action = mail

Now in a file browser window, open /etc/openhab/configurations/transform. In this OpenHAB ONE folder, note all the different file tags, like .map.

    For transformation, list what you just noted. mine ...
transformation = map,scale,xslt

misc As directed, wait on myopenhab (the cloud service). Warning: OpenHAB will generate a new UUID & Secret to be registered (at the right time) at myopenhab.org. However, this will knock out any previous cloud connection you have. So wait on registering your OpenHAB 2 until you are ready to switch over.

        To Be Continued Below

[papa]

Still in the Migration Tutorial, skim & skip Karaf Console & PaperUI sections for now. You may want to come back to them later. What's been done with the Text Based section should populate runtime.cfg & addons.cfg

Later in the Migration Tutorial, work through the Configure Add-Ons section.

For example, much on this forum uses the MQTT binding for communicating with end nodes.

If you've been using MQTT with OpenHAB ONE then it should still be there for OpenHAB 2 to use.  If you have not installed the Mosquitto (MQTT) server on this OpenHAB 2 computer, see this thread, the Jan 29, 2016 post that starts "Install Mosquitto (MQTT) server" & come back here.

You still need to edit /etc/openhab2/services/mqtt.cfg  You'll use the settings from OpenHAB ONE at /etc/openhab/configurations/openhab.cfg in the MQTT Transport section.

Tutorial note about syntax change from openhab.cfg <binding section> to /services/<binding>.cfg: "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 nest:refresh=300000 in openhab.cfg becomes refresh=300000 in nest.cfg."  Papa: mqtt:mosquitto.url=... in openhab.cfg becomes mosquitto.url=tcp://localhost:1883 in mqtt.cfg

The following two mqtt.cfg settings may be enough:  (In the last line of each section, notice it has no starting "#")

# URL to the MQTT broker, e.g. tcp://localhost:1883 or ssl://localhost:8883
#<broker>.url=tcp://<host>:1883
mosquitto.url=tcp://localhost:1883

# Optional. Client id (max 23 chars) to use when connecting to the broker.
# If not provided a default one is generated.
#<broker>.clientId=<clientId>
mosquitto.clientId=openhab
If mqtt.cfg (or another binding.cfg file) is not in the /services folder yet, try starting OpenHAB 2 & stopping it again.

sudo /etc/init.d/openhab2 start
sudo /etc/init.d/openhab2 stop
        To see if OpenHAB2 is running:  sudo /etc/init.d/openhab2 status

Repeat the above editing for other bindings you've chosen.  As the Migration Tutorial says, the /services folder should hold a separate .cfg file for each binding.

If you install & edit myopenhab.cfg for the myopenhab cloud service, remember the warning: OpenHAB will generate a new UUID & Secret to be registered (at the right time) at myopenhab.org. However, this will knock out any previous cloud connection you have. So wait on registering your OpenHAB 2 until you are ready to switch over.

[papa]

Still in the Migration Tutorial, move to Final Add-ons Installation Steps.

    So now restart OpenHAB 2:  sudo /etc/init.d/openhab2 start

Also copy your config files from OpenHAB ONE to OpenHAB 2:  (assumes apt-get installed OpenHAB 2)
    (The following terminal commands worked better for me than what the Tutorial had)

sudo cp -ri /etc/openhab/configurations/transform/* /etc/openhab2/transform/
sudo cp -ri /etc/openhab/configurations/scripts/* /etc/openhab2/scripts/
sudo cp -ri /etc/openhab/configurations/persistence/* /etc/openhab2/persistence
sudo cp -ri /etc/openhab/configurations/items/* /etc/openhab2/items/
sudo cp -ri /etc/openhab/configurations/rules/* /etc/openhab2/rules/
sudo cp -ri /etc/openhab/configurations/sitemaps/* /etc/openhab2/sitemaps/
sudo cp -ri /usr/share/openhab/webapps/images/* /etc/openhab2/icons/classic
Also copy any custom webviews from /usr/share/openhab/webapps to /etc/openhab2/html

[papa]

        Still in the Migration Tutorial, move to Necessary Changes (in .items, .rules, etc).

    Items

Earlier changes in addons.cfg should take care of transformation installs.

    Scale Transformation (files ending in .scale)
If soilmoist.scale reads        change it to
[0,350]=dry                            [0..350]=dry                               
[351,900]=moist                      [351..900]=moist

    Rules
Note imports to remove & use of null & NULL.  With OpenHAB 2, several imports are NOT needed in in .rules files

    Sitemap
If you copied over custom icons from OpenHAB ONE, change the default icons to png for ClassicUI and BasicUI . This can be done in PaperUI under Configuration -> Service -> BasicUI and ClassicUI. Set the “Default Icon Format” to “Bitmap”.

        [If for example the computer hosting OpenHAB 2 is at 192.168.10.9   AND
you have a My.sitemap file whose first active line is sitemap My label="My House" ....]

Now should be OK to go to PaperUI via the link at http://<OpenHAB 2 computer's IP>:8080
        Example:  http://192.168.10.9:8080

Then you can see your Classic User Interface either via the link at http://<OpenHAB 2 computer's IP>:8080
    or more directly at http://<OpenHAB 2 computer's IP>:8080/classicui/app?sitemap=<your-sitemap>
            Example:  http://192.168.10.9:8080/classicui/app?sitemap=My

To Be Continued Below

[papa]

    Still in the Migration Tutorial, move to Testing

Study openHAB 2 logs & methodically make sure items, persisted items, etc are working.
    For example, with a Linux text editor, open /var/log/openhab2/events.log OR /var/log/openhab2/openhab.log where you can scroll back & forth in the log entries.

In Linux Terminal, enter the following & see the latest tail end chunk of logged events, updates of various OpenHAB states:
    tail -f /var/log/openhab2/events.log
Enter the following & see OpenHAB's startup messages, error messages, & shut down messages:
    tail -f /var/log/openhab2/openhab.log

    Monitor the log in real time via the log:shell in the Karaf Console
        ssh openhab@localhost -p 8101  [password:]  habopen
               Including these options...
log:display            -> display the last chunk of log entries
log:exception-display -> display the last exception from the log (but apparently not last errors)
log:tail                     ->  continuous display of the log entries

 OpenHAB 2 logged events show in successful blue text & in red text errors.

     This page has more about OpenHAB 2 logs.

Use what you learn in the logs to fix items, rules, etc. If needed copy error messages wording & search the internet for solutions.

There's more to read in the Migration Tutorial after Testing plus areas you postponed above plus more tutorials & user manual where one can continue learning OpenHAB 2, including how to troubleshoot problems.

        For example, there's New Concepts: Things & Channels

        Also be sure you take care of things in Retire openHAB 1.x.

In the Feb 15, 2017 post below, see how my skipping Retire items caused problems & also see alternatives to handle the Retire items.

[papa]

The above is what I noted & remembered in migrating from an OpenHAB 1.8.x install to OpenHAB 2.

        I invite others' corrections & experiences in migrating.

Using Karaf Console log:tail, I see some rule errors with NULL.      I guess I better work on those.

[papa]

OK, I've been working my way through OpenHAB 2 errors. Turns out much of this was due to limitations in the OpenHAB 1 config files I copied over.

Clearing up something else on my User Interface, I just got my first "thing". Looks like 2.0 level bindings require things  & then reference to those things in items' {binding} section. NTP is the only 2.0 binding I have. From the readme file in the /etc/openhab2/things folder, I only learned that the files are named like xxx.things. Then I saw that when we install a 2.0 binding, something goes in the PaperUI inbox, which in this case. said "ntp:ntp:local"   Clicking on that PaperUI link apparently installed the thing. I expected it to show up in the /etc/openhab2/things folder, but no. Then I learned that things installed via PaperUI show up in the /var/lib/openhab2/jsondb folder. The file ends in .Thing.json.  It's a text file & sounds like its editable.

        So my OpenHAB 1.8.x version of an item ...
DateTime Date "Date & Time [%1$tm.%1$td.%1$tY %1$tr]" <calendar> { ntp="America/Chicago:en_EN" }
        for OpenHAB 2, changed to ...
DateTime Date "Date & Time [%1$tm.%1$td.%1$tY %1$tr]" <calendar> { channel="ntp:ntp:local:dateTime" }
                                                                                                    ^^ Note the thing reference. ^^

    My rules I copied over from OpenHAB 2 were not working yet.
        The following terminal command let me see that OpenHAB did not recognize some of the item names I was using:
            tail -f /var/log/openhab2/openhab.log
So it turns out this problem was also was due to limitations in the config files I copied over.  So far the rule syntax I had used is fine.
     As I fix this ^^, the rules are starting to work.

[papa]

        More on working through OpenHAB 2 errors showing up in the logs:

Again hiccups were often due to rules referring to items I did not have in the .items file I was using.

        Also, OpenHAB 2 seems a little more particular than 1.8.x about a couple things ...
1) var String F_Today = Forecast_Today.state < OpenHAB 1.8.x accepted this line, but OpenHAB 2 required:
        var String F_Today = Forecast_Today.state.toString

2) I had screen captured a pic & turned it into a .png icon.
    It worked for the OpenHAB 1.8.x User Interface, but OpenHAB 2 showed the icon broken on the User Interface.
        I'll watch to see if other icons show up broken for the same reason.

[papa]

My Linux computer got sluggish so I rebooted it & that started a long day of hassles. On the rebooted computer, OpenHAB 2 was running but the Classical User Interface (UI) nor Karaf Console nor PaperUI did not work.

I discovered both OpenHAB 1.8.x AND OpenHAB 2 started running with reboot & must conflict with each other. I stopped OpenHAB 1.8.x from running, but still no UI success. Oops, I had not cancelled OpenHAB ONE from starting on reboot.

To set up OpenHAB ONE to start on reboot, I had used sudo update-rc.d openhab defaults
    So to disable that ^^ I used    sudo update-rc.d openhab disable

            ^^ This is supposed to be the official way because it also removes all the symlinks from the /etc/rcX.d folders, which take care of starting and stopping the service when appropriate

In Firefox, I made sure the java plugin always activates.

For several hours of research & attempts, the UI still did not work.

After doing the above & several computer reboots, the UI started working again.  Whew !

[papa]

        Various OpenHAB 2 Documentation & Help               Main OpenHAB 2 Documentation Menu

    Kai Kreuzer (THE OpenHAB Guy) Overviews OpenHAB2

    Tutorials including Beginners & Migration (from 1.8.x)                    User Manual

    Configuration of Items, Rules, Things, etc (Syntax, Types ...)        FAQs

    Community OpenHAB                                                    Finding Help (Links to Community OpenHAB & FAQs)

    OpenHAB 2 Concepts (like Things, Channels ...)                Advanced Functionality & Administrative Tasks (like logging)

    The Concept of Thing                                                        Different Kinds of Addons (Read me pages incl examples)

    Github Depository of Add-ons' Read Me (incl use examples)    OpenHAB 1.x Wiki incl for Addons (like Bindings) not yet version 2

[papa]

        Testing the Basic User Interface (?? more pleasant, better use of screen space ??)

    To this point, I had used the Classic User Interface as I had in OpenHAB 1.8.x
If Classic UI is not already installed, do so via
    PaperUI / Configuration / Addons / User Interfaces
        Then a little Classic UI configuration ...
PaperUI / Configuration / Services / UI / Classic UI / Configure / (click window above "Expert Mode") / Icon Format (in drop down list): Bitmap (to use 1.8.x custom icons)
    Only use Configure / Expert Mode if you're able to type the text of a parameter with no included guidance.

To open Classic UI in browser:  [OpenHAB2 Computer's IP]:8080/classicui/app?sitemap= < [Name you gave to sitemap like, My]

  To try Basic UI, install it if necessary
        PaperUI / Configuration / Addons / User Interfaces
            Then a little Basic UI configuration ...
PaperUI / Configuration / Services / UI / Basic UI / Configure / (click window above "Expert Mode") / Icon Format (in drop down list): Bitmap (to use 1.8.x custom icons)
        ?? including ?? Icon Format: Bitmap (to use 1.8.x custom icons)
    Only use Configure / Expert Mode if you're able to type the text of a parameter with no included guidance.

To open Basic UI in browser:  [OpenHAB2 Computer's IP]:8080/basicui/app?sitemap= < [The SAME name you gave to sitemap like, My]

BTW at least in my apt-get install, the text files ending with basicui.cfg & classicui.cfg are in the /var/lib/openhab2.etc folder.

Apparently Basic UI can use the .sitemap created for Classic UI or I assume a different one.  It also apparently uses the same items, etc.
     Using the above expert configuration, one can use custom bitmap icons or the provided vector graphics

[papa]

I just did another Linux install of OpenHAB2 (the latest stable version) interfaced with an RFM69 gateway & one node. I migrated some of my OpenHAB 1 config files & entries to see that they worked.

Using the official installation instructions worked well for me once I took care of the following ...

My most important action that led to success: Do the latest adequate Linux install on a computer that can handle it & not freeze up often. I had big problems with a laptop computer which had about 1 MB of memory, but other things may have added to the problems (video?) A few operations on GUI apps would freeze it. I installed Linux Mint 18.2 Mate on a desktop computer with 2.87 MB of memory & then the install went smoothly.

[papa]

I would still follow the steps earlier in this thread, but add these updates & notes ...

Seems good practice to update your Linux first. You may use the Update Manager: Click Refresh to get the latest updates & then click Install Updates to install updates Levels 1-3. Sometimes it works better to use Terminal commands:
        $ sudo apt-get update
        $ sudo apt-get upgrade

Right after updating my (adequate version of) Linux, I would install mosquitto & mosquitto-clients BEFORE OpenHAB2. It's good to know that works before the OpenHAB2 install.
        $ sudo apt-get install mosquitto
        $ sudo apt-get install mosquitto-clients

Then with the OpenHAB2 install, if (like me) you do the Package Repository Installation, note that you need to click on Apt Based Systems to see the install commands.  You may need to click on other bulleted items to see the related commands.