openHAB quick tryout

openhab-tryout.md

openHAB tryout

This is a quick tutorial to get openHAB 4 up and running and see some feedback. Make the system react to MQTT events, send a mail and create a dashboard.

openHAB can be configured with the GUI or programmed with a configuration in text files. Let's use the latter for now for readers who think in infrastruktur as code or are more at home in the Unix shell.

you need Java 17

on a computer running Linux, FreeBSD, Windows or even Android.

Download openhab zip and unzip into a folder

https://www.openhab.org/download/

Select Linux - APT - Stable. (Select Linux even if you're running another OS, the downloadable zip is generic.)

Scroll down to Option 2: Manual Installation and the red box "Download openHAB 4.0.x Stable Runtime", it should link to a .zip

unzip -d openHAB openhab-4.0.0.zip

From now on this folder is referred simply by openHAB.

Things and Items

Things represent physical devices like a sensor. A thing needs a binding, which is a software driver for its physical device. A Thing has attributes that are called Channels, e.g. a temperature sensor might have channels temperature, humidity, batterylevel.

Within openHAB these values like temperature are represented by items. Items have a type and are linked to Channels of Things. They can even live standalone without a Channel link.

While a Thing is more like an Object, with its Channels as attributes, an Item is a scalar.

an Item

We will create an Item without a Channel link:

create openHAB/conf/items/tryout.items with content

Number tryout_Temperature

Listen Ports

openHAB uses by default http/s ports 8080 and 8443. If they are not available add

export OPENHAB_HTTP_PORT=2080
export OPENHAB_HTTPS_PORT=2083

to the top of openHAB/start.sh

run openHAB

cd to openHAB and run

./start.sh

open two other terminals and

tail -F openHAB/userdata/logs/openhab.log
	
tail -F openHAB/userdata/logs/events.log

when the server is up the first shell shows

~/openHAB $ ./start.sh
Launching the openHAB runtime...

                           _   _     _     ____
   ___   ___   ___   ___  | | | |   / \   | __ )
  / _ \ / _ \ / _ \ / _ \ | |_| |  / _ \  |  _ \
 | (_) | (_) |  __/| | | ||  _  | / ___ \ | |_) )
  \___/|  __/ \___/|_| |_||_| |_|/_/   \_\|____/
       |_|       4.0.0 - Release Build

Use '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
To exit, use '<ctrl-d>' or 'logout'.

openhab>

change an Item value

The openHAB shell understands a lot of commands.

try

shell:info

Look for our item defined in tryout.items (the shell understands command line completion)

openhab> openhab:status tryout_Temperature
NULL

set it to a value

openhab> openhab:update tryout_Temperature 32.5
Update has been sent successfully.

Check its status. See if there is a entry in events.log

Find the item in the web gui (yourhost:8080 or the port you defined)

Settings / Items

(you might have to enter your geo position first)

stop the server

with ctrl-D in the openhab shell

MQTT Thing

Physical Devices, Things, can be defined by a driver (called binding) or even by MQTT, which gives a software defined Thing.

Install Eclipse mosquitto on your machine and run the mosquitto server.

in openHAB/conf/services/addons.cfg add some bindings:

binding = astro,mqtt,http,exec,mail,mpd

define a MQTT bridge

create openHAB/conf/things/mqttbridge.things

Bridge mqtt:broker:yourhost [ host="yourhost" ]
{}

create an MQTT Thing: openHAB/conf/things/mqtt.things

Thing mqtt:topic:yourhost:mqttthing1 "MQTT Thing 1"  (mqtt:broker:yourhost) {
    Channels:
            Type number : temperature  [
				stateTopic="openhab/test/temperature" ]
}

add an item to openHAB/conf/items/tryout.items

Number tryout_OutsideTemperature
	{ channel="mqtt:topic:yourhost:mqttthing1:temperature" }

Start the server

send an MQTT command

first run in a terminal

mosquitto_sub -F "%I %t %p" -t 'openhab/#'		

then in another

mosquitto_pub -t 'openhab/test/temperature' -m 22

Check in the openHAB console, events.log or in the Gui if the item changed.

Mail Thing

We'll send an email if the temperature item has changed.

To send mail, we need an SMTP Thing:

create openHAB/conf/things/smtp.things with content

Thing mail:smtp:gmx [ hostname="mail.gmx.net", sender="some-user@gmx.de", security="STARTTLS", username="some-user@gmx.de", password="some-user-password" ]

These are sample values for the gmx provider, of course. You need to enable POP3 and IMAP access from the GMX web gui.

trigger a Rule and send Mail

Now we can write a rule that sends mail if the temperature item changed.

create openHAB/conf/rules/tryoutmail.rules with content

rule "TestSendMail"
	when
		Item tryout_OutsideTemperature changed
	then
		var Number t = tryout_OutsideTemperature.state
		logInfo("SendMail", "tryout_OutsideTemperature changed to: " + t)
		
		val mailActions = getActions("mail","mail:smtp:gmx")
		val success = mailActions.sendMail("some-user@gmail.com", "Test subject", "mail content: temperature: " + t)
end

Set the tryout_OutsideTemperature item with the openhab shell or MQTT to a new value and see if you get mail.

openhab> openhab:update tryout_Temperature 40

Display Items in a Sitemap

Sitemaps are dashboards for items and render as web pages.

create openHAB/conf/sitemaps/tryout.sitemap with content

sitemap tryout label="Tryout Dashboard" {
   Frame label="Sensors" {
        Text icon="temperature" label="Outside Temperature" item=tryout_OutsideTemperature
		Text icon="temperature" label="Temperature" item=tryout_Temperature
    }
}

Navigate to http://yourhost:8080/basicui/app?sitemap=tryout

Change the item values and see how the sitemap is updating.