openHAB

First and foremost: openHAB allows you to have an intranet of things, not an internet of things.  You're not depending on outside connections to clouds and so on, something I dislike.  

I like to keep  my home automation system "internal": far less vulnerable for outside attacks (in fact, not vulnerable at all...).

Next to this, there's a flexible web interface and also an Android application available so that you can also control your home automation system by means of your smartphone.

With openHAB, you have the possibility to retain messages.  That is, every message processed is stored in a database maintained by MQTT.

The location of the database is /var/lib/mosquitto/mosquitto.db.

Advantages: when restarting the system, openHAB will submit all messages that were active before stopping the system.

Disadvantages: each time you restart the system, the messages will be forced onto the system, which is maybe not what you want.

Luckily, there's a possibility to switch on or off the retained messages by means of a flag that can be set in the openhab.cfg file.  By default, the retained flag is not set and defaults to false.

When you have switch on the flag for one reason or another, the only way to avoid forcing the previous messages onto the system is:

• switch off the flag again in the openhab.cfg file

• remove the mosquitto.db file in /var/lib/mosquitto (must be done as sudo: sudo rm /var/lib/mosquitto/mosquitto.db).

By default, openHAB runs on port 8080.  If for one reason or another that port is occupied by another application there's always the possibility to change the port openHAB uses for both HTTP as well as HTTPS.

For openHAB 1.8.3 it's very easy to change the default port(s).  Edit the start.sh (or start_debug.sh) script and change the values for one or both of the following items:

• HTTP_PORT: defaults to 8080, change to whatever value you like (but port must not be used by some other app, of course)

• HTTPS_PORT: defaults to 8443, can also be changed

Don't forget to update the URL with the modified port number once you restart the openHAB server.

PS: later versions of openHAB started to use a file in /etc/defaults but I have no experience with that approach yet since I'm planning on continue to use version 1.8.3.  

I don't want to swim through all the mud and misery time and again of those latest and (absolutely not) "greatest" versions of openHAB!

openHAB1 addons and other stuff

Sitemap

The sitemap is a subdirectory of the configuration map (part of the openHAB directory structure).

The sitemap contains the initial UI of the openHAB application when opening it in a browser.  It should contain at least a sitemap section.  There's no need to give a name parameter to the sitemap parameter but it's useful to pass a string to the label parameter like so:
sitemap label="immC TEST SETUP PI41"

In this example, immC TEST SETUP PI41 will be shown as title for the openHAB application.

Next to this, you can define a frame inside the sitemap parameter.  The frame can have a label which represents the title of the section(s) you define on the initial openHAB page.

In its simplest form, it can look like this:

sitemap label="immC TEST SETUP PI41" 

{ 

Frame label="Levels" { 

Group item=gGF     label="Ground Floor" icon="groundfloor" 

Group item=gFF     label="First Floor"  icon="firstfloor" 

} 

} 

Here we have a frame labeled Levels and it contains two groups: group gGF and group gFF.  Each group has its label and an icon which explains graphically what this group is about.

The labels are important since they will be used to filter the items files, contained in the subdirectory items of the configuration map.

Items

The items map contains one or more files describing all the items that should appear in the groups defined in the sitemap file.  Only files with the extension items will be taken into account by openHAB.  So, if there's more than one items file, all the files will be scanned.

The scanning of the items files is based on the Group items defined in the sitemap file.  In our case, only the items files that contain the Group parameter referring to gGF or gFF will be taken into account.  All other groups will be skipped.

So, in the Frame example given above, only the Group items in the items file that have the definition gGF will be shown in the Ground Floor group.  Only the items in the items file that have the definition gFF will be shown in the First Floor group.

Example:
If we have this:

Group gGF       (All)  // GF = Ground Floor

Group gFF       (All)  // FF = First Floor

// Ground floor

Group GF_Relays        "Relays"               <office> (gGF)

Group GF_Teleruptors   "Teleruptorketetje..."   <office> (gGF)

// First floor

Group FF_Corridor      "Corridor only home"     <corridor> (gFF)

Group FF_Studyroom     "Study room only home"   <office> (gFF)

then the groups GF_Relays and GF_Teleruptors will be shown in the section Ground Floor and the groups FF_Corridor and FF_Studyroom will be shown in the section First Floor since they are part of the group gGF and gFF respectively.  The groups they belong to are put between parenthesis.

Note,: the parameter shown between the < and > characters is the icon that will be given to that items group.

However, if we have this (mind the red section):

Group gGF       (All)  // GF = Ground Floor

Group gFF       (All)  // FF = First Floor

// Ground floor

Group GF_Relays        "Relays"               <office>    (gGF_dontshow)

Group GF_Teleruptors   "Teleruptor"             <office>    (gGF)

// First floor

Group FF_Corridor      "Corridor only home"     <corridor>  (gFF_dontshow)

Group FF_Studyroom     "Study room only home"   <office>    (gFF)

then we won't see the section GF_Relays on the Ground Floor page since it's not belonging to the group gGF anymore.  Same is valid for the FF_Corridor section: it won't be present on the First Floor page.

To show items in the GF_Relays section, the items themselves must refer to the group GF_Relays.  Same is valid for items that must be shown in the Teleruptor section.

To do this, the following must be defined for one or more items:

Switch Relay_1_GF "Relay 1" <office> (GF_Relays)

You can have items that show up in more than one section on the same page or on different pages.  In this case, you have to define more than one group item like so:

Switch Relay_1_GF "Relay 1" <office> (GF_Relays,GF_Teleruptors,FF_Corridor)

In this case the item "Relay 1" will be shown in 3 different sections.

If a group name in an items file is found in other items files too and they belong to the same group, then the  group name of the last items file scanned will be taken into account.

Suppose we have the following in  file 1.items:

Group FF_Corridor      "Corridor in items file 1"     <corridor> (gFF)

Suppose we have the following in file 2.items:

Group FF_Corridor      "Corridor in items file 2"     <corridor> (gFF)

Since both files have exactly the same group name (FF_Corridor) and they belong to the same frame group (gFF), only "Corridor in items file 2" will be shown on the UI page, since 2.items will be scanned as last (when ordered alphabetically, file 1.items will be processed before file 2.items).

If we define FF_Corridor1 in 1.items and we define FF_Corridor2 in 2.items then both items will be shown on the UI page.