OpenHAB2 Install & Configuration

[papa]

    OpenHAB2 Install & Configuration
Linux vs Windows, Part 1 of My OpenHAB Experience So Far

Until recently, I depended on a working OpenHAB 1.8.x Home Automation System that I installed & configured on a Windows 7 laptop. Out of curiosity & to be informed for this forum, I did 3 minimal Linux installs / configurations of OpenHAB 2 on a desktop, a laptop, & a Raspberry Pi 2 B. I did those Linux installs via the apt-get method. In configuring the Raspberry Pi's OpenHAB, I sometimes used it directly & other times SSHed in from a Windows computer.

Recently on the Windows laptop, I installed OpenHAB 2 & reused my OpenHAB 1 configuration files (editing them where necessary, following this documentation). I used the same Mosquitto (MQTT) server that I had installed for OpenHAB 1.  This OpenHAB 2 install now controls my home automation system & is working well.

On all the above, I mostly or totally used the text-based configuration of OpenHAB, namely I edited text files specific to OpenHAB. For OpenHAB 2, I used PaperUI some, especially for newer aspects like Things related to OpenHAB 2.x bindings.

    Next, Part 2 of My OpenHAB Experience So Far

[papa]

    OpenHAB2 Install & Configuration
Linux vs Windows, Part 2 of My OpenHAB Experience So Far

Currently for experimenting & learning, I've installed OpenHAB 2 on a Raspberry Pi 3 B via OpenHABian, which is "a preconfigured image for the Raspberry Pi, with the latest build of OpenHAB 2 and many useful software components (like Samba or Mosquitto) as optional setup steps." This Raspberry Pi OpenHABian install is "headless." One cannot access it with a connected monitor, keyboard or mouse, but rather via SSH from another computer. Conveniently for SSH, OpenHABian already sets up Samba shares of key OpenHAB folders (configurations, logs, etc) & permissions.

Note:  This tutorial is helpful on SSH access to a Raspberry Pi.  However, if one uses OpenHABian, much of the tutorial-indicated Raspberry Pi preparation for SSH is done for us.

For configuring this Raspberry Pi install of OpenHAB 2, I explored the graphical dashboard (PaperUI) method more to see how far & how well that configuration works currently. In short, at present, one cannot complete OpenHAB configuration via PaperUI & must use at least some text files. For now & for effectiveness & understanding's sake, I recommend that we mostly configure OpenHAB in text files, NOT PaperUI. In later posts, I will give details on why & how & my one possible exception to using PaperUI configuration.

From here on, when I say OpenHAB," I mean OpenHAB 2. When I say "computer" without specifying, it covers any computer: Windows or Linux (including Raspberry Pi) or Mac OS (for which I have no experience).

    Next, OpenHAB, Linux vs Windows

[papa]

    OpenHAB, Linux vs Windows

I divide the OpenHAB installation process into 1a) Satisfy the OpenHAB prerequisite (Java version 8)  1b) Install the Mosquitto MQTT message broker service on the chosen compatible computer 2) Install the OpenHAB platform on the computer  3a) Install the OpenHAB add-ons needed for our forum's Home Automation projects (actions, bindings, persistence methods, transformation, User Interfaces, Misc, Voice) These add to OpenHAB's abilities.
3b) Configure the OpenHAB items, rules, & sitemap needed for our forum's approach to Home Automation.

Note:  Items 1a), 1b), & 2) could be done in any order, but if not accomplished could interfere with results from 3a) & 3b).

I'm more experienced using, tweaking, & troubleshooting Windows computers, but I'm gaining more experience with Linux.

On the whole, in my experience, the ease of accomplishing a working OpenHAB Home Automation system is comparable between Windows & Linux. Both are involved processes & I would not call either of them easy, but they are doable.  For 1a) Install the OpenHAB platform on the computer, I found the official documentation here to be helpful.

Some things on Windows OpenHAB seem easier or more convenient or less confusing than on Linux OpenHAB & some aspects on Linux OpenHAB seem easier or more convenient or less confusing than on Windows OpenHAB. For example, Windows OpenHAB files are stored under one main directory while Linux uses more than one main directory. A couple years ago, installing Mosquitto on Windows was a hassle, but is maybe better now, perhaps at least using MQTT binding hints recently offered here by keshin  OR  older hints I found & documented here. Installing Linux Mosquitto is simple. Fulfilling OpenHAB 2's Java 8 prerequisite on Windows & Linux Raspbian can be a hassle, but is easy with OpenHABian on a Raspberry Pi.

Choosing between Linux OpenHAB & Windows OpenHAB may come down to preference & previous experience with each system. At this point, when I choose Linux, I would choose installing OpenHABian on Raspberry Pi as most convenient.

    Next, OpenHAB Configurations:
Text Files vs Graphical (PaperUI Dashboard)

[papa]

        OpenHAB Configurations:
    Text Files vs Graphical (PaperUI Dashboard)

Study this web document on what OpenHAB configuration is available & recommended via Textual Configuration (text files), Paper UI (dashboard), HABmin, & Karafe Console.

This long discussion (especially this post) & what I've found for now matches this comparison table's tally: Only using text files can achieve almost all of OpenHAB configuration.

As is said below the comparison table, "configuration files & Paper UI ... methods can be used side-by-side or even mixed." However, again, I believe mixing them is mostly not a good idea until Paper UI is a more thorough tool. Otherwise one has OpenHAB configurations stored in different locations which complicates backups, editing, deleting, etc.

One can define Things in a text file that ends in .things, but sometimes a lack of specific Thing documentation (so far) may make it hard to know the right syntax. Paper UI is able to discover Things (which are only relevant for 2.x bindings) & list them in its inbox, which may make Paper UI better for that much. For now I recommend that we generally use text files for OpenHAB configuration, including Things.  However (especially if we have trouble with Thing syntax), we might have Paper UI handle Thing discovery & do the rest about Things (more about this later) with text files.

While I recommend that text files handle most or all of OpenHAB configuration, Paper UI is a fairly good dashboard to see much of those text configurations.  However, from what I've seen, Paper UI shows only part of the items configuration.

Note: OpenHAB developers seem intent on making all configuration possible (eventually) via Paper UI dashboards & to store all OpenHAB configurations in .json database files.  I believe they've made progress since OpenHAB 2 became standard.  However, for a long time & to the present, Paper UI cannot do the whole configuration.  So for now, I believe it is best to rely on text file configuration (except perhaps for discovering things).

    Next, Examples of How Items in a Text File Are More Robust than in PaperUI

[papa]

        Examples of How Items in a Text File
          Are More Robust than in PaperUI

One can use PaperUI to define OpenHAB items, but (unless I'm missing something) what PaperUI can do with items is too limited for this forum's items.

As far as I can tell, Paper UI can only (somewhat ?) configure 2.x bindings.  PaperUI cannot configure 1.x bindings (like MQTT) that are important to this forum.

     Below are two items one can enter into an .items text file ...
(Note for the first item, I had Paper UI discover the NTP dateTime channel & its syntax, but now that I know the syntax for an NTP item, I will let the text item handle configuration, including the Thing. )

DateTime Date "Date & Time [%1$tm.%1$td.%1$tY %1$tr]" <calendar> { channel="ntp:ntp:local:dateTime" }

String Node2Rssi "Node2 RSSI (db) [%s]" <network> (Nodes) {mqtt="<[mosquitto:home/rfm_gw/nb/node02/dev02:state:default]", expire="3m,Offline?" }

In first item above, note the formatting definition after "Date & Time." In the second item above, note the binding definitions after "mqtt=" & "expire="

In PaperUI, when one clicks the edit icon (pencil) for the item (defined in the text file), any binding or formatting definitions will be missing from that configuration window.  If one uses Paper UI to create an item & then clicks the edit icon (pencil), it will let us enter the formatting definition in the Label field, but then it disappears & I see no way to find & edit that formatting definition. Moreover, so far in PaperUI, I see no way to enter an item's binding definitions.

In a text file item, <calendar> means for an OpenHAB to display the icon calendar.svg with the item on the eventual user interface sitemap. PaperUI designates calendar as "Category." "Category" did not help me to know that I was to choose one of OpenHAB's icons.

        Next, Possibly Helpful Ways to Use PaperUI While We Mostly Configure in Text Files

[papa]

        Possibly Helpful Ways to Use PaperUI
    While We Mostly Configure in Text Files

As I've been saying, at least until PaperUI's reach expands much further into OpenHAB's configuration, I recommend that we mostly use configuration text files. Even then, there are still some helpful uses for PaperUI while we mostly configure OpenHAB in text files (more on this later).

Among those helpful uses is discovering Things in PaperUI's inbox & for the sake of .items text entries & getting correct syntax for Things' channels (more on this later). Also helpful is how we can click around in PaperUI & have another way to see configurations we've made in text files.  PaperUI also shows the correct way to list bindings in addons.cfg.

What displays in Paper UI / Configuration / Bindings are only 2.x Bindings such as: Astro Binding, HTTP Binding, Network Binding, & NTP Binding.  These 2.x bindings are more ready for PaperUI to configure them.

1.x Bindings & other Addons used by this forum (especially MQTT) are listed in the Paper UI / Add-ons tabs (like ACTIONS, BINDINGS, etc). In those tabbed lists, before an Addon is installed, the Addon has a large gray circle with the first capitalized letter of the Addon's name. After an Addon is installed, its gray circle turns blue.

    < Click on image for larger view

In the above image, see the gray circle for the yet to be installed Exec Binding.  Also see in that binding's last text line: binding-exec - 2.2.0.  Thus Exec is a 2.x binding & the correct syntax to list in addons.cfg text file is (lower-case after the first dash) exec.  Also see the blue circle for the installed Expire Binding.  In its last text line see: binding-expire1 - 1.11.0.  Expire is a 1.x binding & it is listed in addons.cfg as (lower-case after the first dash) expire1.  << In addons.cfg, do not omit the 1 (one) at the end of expire.

        Next, Configure OpenHAB Via Text Files, Introduction

[papa]

        Configure OpenHAB Via Text Files, Introduction 1

Caution: To edit OpenHAB configuration files, NEVER use native Windows text editors like Wordpad & Notepad. They introduce end of line codes that cause problems to OpenHAB in Linux computers like Raspberry PI. For editing via Windows, download (here), install, & use a text editor like the free Notepad++.

For Notepad++, here's how you can download & install User-Defined Language files that help check our syntax in four types of OpenHAB configuration files (.items, .persist, .rules, .sitemap).

First go to this site to download the .zip of the 4 Language files (Keep track of where you stored them).  Next extract the 4 Language files where you can find them.  After this install, using a file's tag (like .items), Notepad++ color-codes file text according to its function.

Next, in Notepad++'s menu, open the Language submenu & select "Define your language..."  In the resulting window, click the Import... button. Navigate to where you stored the 4 .xml Language files & open them one by one, starting with openHAB-Items.xml. Then you can close the Import window.  At the bottom of Notepad++'s Language submenu under "Define your language...", you should now see the 4 additions.

The next time you open these files they will be treated according to their tag: .items, .rules, etc.

    Next, Configure OpenHAB Via Text Files, Introduction 2

[papa]

    Configure OpenHAB Via Text Files, Introduction 2

In order to edit & create OpenHAB configuration text files, you need to know the configuration folder where your OpenHAB stores them.

On a Windows computer, you probably install OpenHAB in something like C:\openHAB2. Its site configuration folder is C:\openHAB2\conf. Conveniently, all of Window's OpenHAB is stored in that C:\openHAB2 folder.

For most Linux computers (that are not "headless"), see this reference table:
    According to the table, for Repository Installation (like apt-get), look at /etc/openhab2 for folders like items, services, etc.  For Manual Installation, look at /opt/openhab2/conf.

For a "headless" install of OpenHABian on a Raspberry Pi, when you SSH into OpenHABian from another computer, you'll see a Samba-shared folder \\OPENHABIANPI\openHAB-conf.

The following posts assume you found OpenHAB's main configuration folder & the subfolders (items, rules ...)

    Next, Configure OpenHAB Via Text Files, Part 1, Addons

[papa]

        Configure OpenHAB Via Text Files, Part 1, Addons

Addons are added capabilities that allow OpenHAB to gather data & to issue commands beyond itself. Often before we make configuration entries (in .items, .persistence, .rules, .sitemap, & .transform folders & files), we must first add entries to the addons.cfg file in the services folder.  Here's how to take care of that...

First in OpenHAB's services folder (within the main configuration folder), find & open (for editing) the installed addons.cfg file. Immediately in the services folder, save this UNedited file as addons-orig.cff & close the file. << For later reference, this will save the original file, but in an inactive form (with a .cff tag instead of .cfg).

   addons.cfg (2.67 KB)  << Next, download my sample version, save it in the services folder & give permission for it to replace the original addons.cfg.

I believe I have edited this addons.cfg version to be sufficient for what we've done on this forum so far.

I encourage you to open & study this version of addons.cfg.
     I edited this addons.cfg to contain what we might click in package selection & PaperUI Addons
          I chose the Expert package because it maximizes options.
For installation, I also listed the addons (the bindings, UIs, persistence, actions, transformations, voice, & miscellaneous services) you may need to do our forum's projects.

In addons.cfg (& other config files), notice that lines starting with # function as comments. OpenHAB treats them as information, not settings.
    When told to UNcomment a line, we delete the # that starts the line.  Comment out a line means add a # at the start.

In addons,cfg, also notice how addons are in categories like they show in PaperUI Add-ons tabs (Actions, Bindings ...)
    Such addons are in comma-separated, lower-case lists after the category name =
        1.x bindings have a 1 (one) after their lower-case name.
            For example, one addons.cfg line reads
binding = http1,mqtt1,weather1,ntp,expire1,astro,network

Later if default values are not enough, you may need to edit a .cfg file for some addons. When one of our forum threads introduces the use of an addon, we often give hints on configuring that addon in its configuration file.
    See this post about installing & configuring for the MQTT message service which is used by many of this forum's projects.  This includes editing addons.cfg & mqtt.cfg.

Note: When one (correctly) puts a new addon in addons.cfg, PaperUI will soon display it as installed. Through PaperUI, we can uninstall an addon & it will (for the time being) show as uninstalled in PaperUI & the Karafe Console. However, as long as the addon is listed in addons.cfg, the addon will be reinstalled the next time OpenHAB loads addons.cfg.  An addon installed via addon.cfg reliably goes away only by removing it from addons.cfg.

Helpful official documentation on using addons.cfg to install OpenHAB Add-ons are found here & here.

        Next, The items Configuration Folder & .items Files

[papa]

        The items Configuration Folder & .items Files

        Within OpenHAB's main configuration folder (see this post above), find the items sub-folder.
At installation, this folder starts with only a readme file that points to the official items documentation, a good resource.

Within OpenHAB's items sub-folder, we may have more than one .items file. In fact, we are encouraged to use this to help organize items. When we start, we might use one file, like My.items. As that one .items file gets bigger & more complex, we can split up its entries into other .items files. For this, we can create appropriately named .items files to hold categories of items entries (according to a system we devise). For example, we might make a weather.items file to hold all of our items related to weather.

        Next, Items Entries Within .items files

[papa]

        Items Entries Within .items files

Within the items sub-folder, OpenHAB needs at least one .items file. If you have none yet, use an acceptable text editor (a Linux editor or on Windows, Notepad++) to create a new file named My.items or a name you choose (as long as it ends in .items).

Within an .items file, items entries may be in any order, but we are encouraged to list them in an organized way that helps us find & maintain them. For example, we might group together all items related to a device's signal strength. Or we might group together all items related to a certain physical device.

An item is one entry in a file whose name ends in .items & is found in the items sub-folder within OpenHAB's main configuration folder.

        An entry defining an item has this format & this correct order for fields:

itemtype itemname "labeltext [stateformat]" <iconname> (group1, group2, ...) ["tag1", "tag2", ...] {bindingconfig1, bindingconfig2}
        itemtype and itemname are always required & other fields are added as the application requires.
           Fields may be separated by one or more spaces, or tabs.
    An Item definition may span multiple screen lines, but may have only one end-of-line (at the item's end).

An item entry is one continuous line terminating with one end-of-line. In a text editor, depending on an item's length & the editor window's width, the item may display on more than one line.

                An example of an item entry   from a post above:
String Node2Rssi "Node2 RSSI (db) [%s]" <network> (Nodes) {mqtt="<[mosquitto:home/rfm_gw/nb/node02/dev02:state:default]", expire="3m,Offline?" }

Warning: This item ^^ is strictly an example. It won't do anything without more accomplished (including building & programming a Node 2 device). Instructions for such nodes are available elsewhere in this forum.

        Next, Configuring an Entity Represented by a Thing

[papa]

        Configuring an Entity Represented by a Thing
            From This Official Documentation

From start to finish, the process for fully configuring a physical entity represented by a Thing looks like this:

    Identify the [2.x] binding required for the Thing
    Install the binding if it has not already been installed
    Define and configure the Thing
    Identify the Channels provided by the Thing
    Add Items and link them to the Thing’s Channels
At this point Items can be used to control the Thing or consume its information, e.g. in Sitemaps or Rules

There are two methods for defining Things provided by the various bindings: through discovery (as in the PaperUI inbox or maybe the Karafe Console) or by manual definition in configuration text files.

Note: Some bindings do not fully support auto-discovery, others are hard to cover manually by the file-based approach. Please consult the documentation for each binding to determine the best way to add that binding’s Things and Items to openHAB.

Defining Things, Items and other aspects of OpenHAB in configuration text files have the benefits that they are statically defined, unambiguous, flexible and easy to backup and restore. The main downsides of configuration files are the effort needed to compose them and the probability for typing errors.

From here:  "Both methods can be used side-by-side or even mixed, e.g. a Thing is discovered by Paper UI and linked Items are defined in a .items configuration file."

        Next, Papa's Notes on Things

[papa]

        Papa's Notes about Things

Things only relate to OpenHAB's 2.x Bindings, not 1.x Bindings. A Thing may provide a few or many "channels," that is, data of a certain defined type from a device or service.

Warning: If an item is linked to a Thing's channel, one cannot just delete or remove that item. First one must remove the link between Thing & item & then delete the item. Otherwise, it may appear in some places that we deleted the item, but item residue will be stuck in PaperUI until we remove the link.

        Next: An Example of an Item Using a Thing's Channel &
            Constructing an Item with a Thing's Channel

[papa]

        An Example of an Item Using a Thing's Channel:

DateTime Date "Date & Time [%1$tm.%1$td.%1$tY %1$tr]" <calendar> { channel="ntp:ntp:local:dateTime" }
  ^ Type    ^Name    ^Label         {optional formatting}          ^ icon / category       ^ { binding defintion including channel=}

On this forum, when a project needs an item that uses a Thing's channel, we will often supply an example item like the above Date item. The following describes how others might construct such an item for themselves if they cannot find a ready made example.

    Constructing an Item with a Thing's Channel
If you need an item that will use a Thing's channel related to a 2.x Binding, my recommendations: In addons.cfg, install the binding if it has not already been installed (in lower case, add the binding's name to the comma-separated list after "binding ="). Then go to the PaperUI inbox where a related Thing should be listed as discovered. In the inbox, find the Thing you want & click that Thing's large blue circle holding a check mark. Then find that Thing in PaperUI's Configuration / Things. Click on that Thing's token (a large gray circle with a capital letter). That will display the Thing's channels. Find the channel you want to use.

To the right of the channel is a small icon that looks like two stacked pages. Click on that item & see the lower right message "Text copied to clipboard." In the case of the NTP DateTime channel, this copies "ntp:ntp:local:dateTime" This clip can be pasted into an item & edited to create the item's Binding definition: { channel="ntp:ntp:local:dateTime" } That is, put quote marks (") on both sides of the clip, put channel= in front of the first quote mark, & finally put curly brackets { } around the whole binding declaration.

In an .items text file (on a new line which may spread to other screen lines), put a blank space & that item's Binding definition { the text in curly brackets}. Now we'll create the rest of the item in front of the Binding definition. Note: separate each part of an item's entry with at least one blank space.

In the channel list (Configuration / Things / NTP Server), at the bottom of the channel's text is its related Type. The Type for one channel of the NTP binding is DateTime. In an .items text file, enter the item's Type at the start of the line. Next (after blank space) put a unique, descriptive Name for the item, such as Date. (In other OpenHAB configurations, we will refer to the item by its Name.) Next (after blank space & in double quotes) put a Label (& perhaps optional formatting for it) which will display on your chosen OpenHAB User Interface. Next (after blank space) put the name of an icon / category inside < >. Next be sure you have blank space before the binding definition.

One can click on the channel's token & get a window to create an item linked to the channel. HOWEVER, so far, I can see no way to include formatting definitions. My recommendations above represent the best way I've found so far to get the most complete results for items that include a Thing's channel.  So far I recommend using text files for most OpenHAB configurations, except getting some help for Things' channels via the PaperUI's inbox.