Setting Up and Configuring OpenHAB. Part 6 : IoT, Home Automation

So, if you have followed the earlier parts (IoT - 'Intranet' of Things : Home Automation. Part 1 : IoT, Introduction onwards) you will have yourself an IoT network similar to that shown above (pic 2 and 3). In this part we will add the final touch. The user friendly front end which will allow you to view status, effect control, and visualise trending data all of which coming straight from your home environment via your IoT devices. This front end will be provided by OpenHAB (pic 4).

Introduction

This Instructable will detail how to do the following;

Install OpenHAB and configure it to start up during the boot sequence of the Raspberry Pi

Install Samba to allow for easier OpenHAB home site development, including adding new Icons

Install OpenHAB Designer and show how to debug your code.

Provision an example home site based on the earlier parts in this series, allowing the system full access to the exposed functionality in each IoT device.

What parts do I need?

A home network

Router with DCHP server

One Raspberry Pi B+ or better

One USB Hub, Keyboard, Mouse and LCD monitor to set up the Pi

One Win 7 PC

If you have followed all the preceding parts you can use the 3 off IoT devices to live test your OpenHAB server. Failing that you can use MQTTSpy (I have outlined how to carry out live and simulated testing below)

What skills do I need?

Realistically you will need the following;

A truck load of patience.

A better than average knowledge of Linux. If you have been following all the examples in this series, you will have more than adequate ability in this area.

Some knowledge of Java or Eclipse Xtend (if you are looking to do more than just the simple examples you typically find on the internet)

Step 1: Installing OpenHAB on Your Raspberry Pi

As mentioned above we will be using the OpenHAB server software for our user friendly front end, since like the Mosquitto MQTT Broker, its free and runs under Linux so it will work with the Raspberry Pi.

Preamble

As before I am assuming you have followed the steps in my earlier Instructable named 'IoT - Intranet of Things : Home Automation. Part 1 : IoT, Introduction' and have a Raspberry Pi already set up, connected to your network and ready to go.

All you need to do is make the following minor changes. Using PuTTY to connect to the Pi (MYHOSTNAME.local) and from the command line enter;

You can now re-connect PuTTY to this Pi by using the new hostname 'OPENHAB.local'.

Create a PuTTY saved session named 'OpenHAB', it will come in handy later.

Installation

The installation process is as follows;

Connect to your new OpenHAB server via PuTTY and remembering to copy Linux commands from this Instructable and paste them directly into PuTTY to avoid having to type any commands by hand. Answer Yes (y) to any questions.

Ensure you are in the home directory. If you are you will see the following prompt

now (required for sound playing later), edit the openhab file in defaults;

sudo nano /etc/default/openhab

change USER_AND_GROUP to root. ie.;

USER_AND_GROUP=root:root

and edit openhab.service under systemd;

sudo nano /usr/lib/systemd/system/openhab.service

also changing user and group to root ie.;

User=root

Group=root

then, finally;

sudo update-rc.d openhab defaults

sudo systemctl enable openhab

sudo chown -vhR pi:pi /etc/openhab

sudo chown -vhR pi:pi /usr/share/openhab

.

That's it you're done. OpenHAB has now been installed as a service and will automatically start when you boot your Raspberry Pi.

Now we need to configure it and test it works. However, first we will make our life a little easier by mapping some drives.

Note : OpenHAB requires Java version 1.7 or greater. Enter java -version at a PuTTY terminal window to find out what version your Raspberry Pi has installed. However, if you use the 'Rasbian Jessie' I used 2016-03-18-rasbian-jessie.img it is version 1.8, as below;

pi@OPENHAB:~ $ java -version

java version "1.8.0_65"

Java(TM) SE Runtime Environment (build 1.8.0_65-b17)

Java HotSpot(TM) Client VM (build 25.65-b01, mixed mode)

Step 2: Mapping Drives With Samba

In step 8 of the first Instructable of this series on home automation (IoT - 'Intranet' of Things : Home Automation. Part 1 : IoT, Introduction) I explained how to install Samba, the free, Linux drive mapping software. I'm going to recapitulate here and make some additions. These additions will make life a lot easier when it comes to configuration and editing your OpenHAB site with OpenHAB Designer.

Follow these steps with a PuTTY terminal window using OPENHAB.local as the Host Name (see pic 1 above), remember to use the copy and paste method so you don't need to type anything. Answer yes (y) to any prompts.

sudo apt-get install samba samba-common-bin

The next line invokes a command line editor named 'nano'

sudo nano /etc/samba/smb.conf

Once nano has opened the file smb.conf it will look like the picture above. Scroll up and down with the arrow keys until you reach the [global] section and find the line marked;

# wins support = no

and change it to yes and remove the '#'

wins support = yes

Now go to the [homes] section under Share Definitions and ensure;

read only = no

Next, go to the bottom of the file an add the following. Once again you can select all the text below, copy it and paste it into the PuTTY window by right clicking.

######## TEXT TO ADD : START #########

[pi]

comment= Home Directory

path=/home/pi

browseable=yes

writeable=yes

only guest=no

create mask=0777

directory mask=0777

public=no

force user=pi

force group=pi

[OpenHAB Home]

comment= OpenHAB Home

path=/usr/share/openhab

browseable=yes

writeable=yes

only guest=no

create mask=0777

directory mask=0777

public=no

force user=pi

force group=pi

[OpenHAB Config]

comment= OpenHAB Site Config

path=/etc/openhab

browseable=yes

writeable=yes

only guest=no

create mask=0777

directory mask=0777

public=no

force user=pi

force group=pi

######## TEXT TO ADD : END ##########

Now save and quit. Press ^X (the control, key and the 'x' key), then type 'y' followed by return. Thats it.

Finish off the setup with the following commands (this assumes you used the defaults u/n 'pi', p/w 'raspberry');

sudo smbpasswd -a pi

followed by password 'raspberry' twice

sudo update-rc.d smbd enable

sudo update-rc.d nmbd enable

sudo service smbd restart

We're done.

If you got it right you will be able to see your Raspberry Pi in windows explorer Network section named 'OPENHAB' as above (third pic). It will be showing three network connected folders; 'OpenHAB Config', 'OpenHAB Home' and 'pi'. We are going to 'map' two folders to help us use the OpenHAB Developer software; OpenHAB Config and Home. These will be mapped to Windows drive letters O:\ and P:\ respectively. Don't worry if you have something else mapped to these, just pick a different letter.

To Map 'OpenHAB Config';

click on the 'OpenHAB config' share,

right click select 'Map network drive...' from the drop down menu,

Select Drive O:\,

Folder should already be showing '\\OPENHAB\OpenHAB Config' or if it isn'tclick Browse and from dialogue box 'Browse For Folder' locate 'OpenHAB Config' under PC OPENHAB,

Click OK,

Ensure Reconnect at logon and Connect using different credentials are checked,

Click Finish (see pic 4 above),

Next 'Windows Security' dialogue box will appear, now select 'Use Another Account' and enter 'pi' for username and 'raspberry' for Password,

Ensure 'Remember my credentials' is checked (see pic 5 above). You only have to do this once,

Click ok.

Now repeat the process for 'OpenHAB Home' but this time name drive letter as P:\ to map to, and when the 'Map network drive' dialogue box appears don't check 'Connect using different credentials'. They will be remembered from the previous drive mapping for OpenHAB Config.

That's all you need to do, it will now look something like pic 6 above. You can now drag and drop any configuration files straight into the correct OpenHAB directories on the Raspberry Pi right from your windows PC. Each time you boot your windows pc and your OpenHAB server is running, windows will automatically reconnect the drive for you.

Hint : If at anytime you want to remove the drive mapping, just select the drive O:\ or P:\ from windows explorer, right click and choose 'Disconnect' from the drop down menu. Couldn't be any simpler.

Step 3: Configuring OpenHAB Server

General

Now we have installed OpenHAB and extended the Samba drive mappings we need to complete some customisation such that it runs correctly at each power up.

Customising is broken into two main constituent parts;

Edits to OpenHAB configuration file 'openhab.cfg'

Copy over of any addons

For the example home site I developed for this Instructable ('stevequinnhousehold') we will be using the following addon bindings and persistence;

MQTT Binding (for binding think of a way to connect to something. ie. the MQTT Broker, Mosquitto)

NTP Binding (this is to make up for the fact that the Pi doesn't have a real time clock to tell the time)

Finally, under General configurations ensure persistence is set to the following;

persistence:default=rrd4j

Now save and quit nano. Press ^X (Ctrl-X) and y, then press return.

.

Copy over addons

Now we have completed our custom configuration it only remains to copy over the addons we will be using as part of the operation of the home site. To make your life easier in the future should you wish to extend the given example, we will get a copy of all the addons, but only 'install' the ones we need for now.

Enter the following commands to download and take a copy of all the bundled addons OpenHAB has to offer;

NOTE : for '{' read less than and for '}' read greater than. Unfortunately the Instructables editor strips these characters from your text.

Step 4: OpenHAB Designer

Introduction

As mentioned above, in order to create an OpenHAB home site all you need to do is edit some text files (.items, .sitemap as a minimum), to achieve this you can use a 'plain old' text editor like nano on the Raspberry Pi (or indeed use an editor on the PC, I prefer TextPad) and edit the files of interest, then save your changes and see it work via a browser refresh.

It is perfectly possible to work in this way and develop your OpenHAB site. The downside to this is you don't get any fancy 'bells and whistles' that an integrated development environment (IDE) would provide. Such as Microsoft's Visual Studio (TM) or Microchip's MPLABX (TM) offer.

To go some way to address this the OpenHAB team created OpenHAB Designer (OHD) whilst it is by no means as feature rich as the above IDEs it does give you some better feedback when writing your OpenHAB files. I give further details of this in the 'Debugging your rules' step.

Installation

Installation is relatively simple and requires the following three operations (for a Win 7 PC);

Download and install the latest 32bit version of Java Runtime Environment (JRE),

Download and unzip OpenHAB Designer

Edit the file openHAB-Designer.ini file such that it points to the 32bit JRE.

Step 3 : From your unzipped OHD directory locate the file named 'openHAB-Designer.ini' and add the following lines to the top of the file;

-vm

C:\Program Files (x86)\Java\jre1.8.0_92\bin\javaw.exe

I added a copy of the 'openHAB-Designer.ini' file I used below.

.

Editing your OpenHAB Home Site

To start OHD;

Double click 'openHAB-Designer.exe'. You will be greeted by the screen in pic 3

Click on the open file image as in pic 4

Assuming you followed my advice regarding Samba, navigate to the configurations directory on your O:\ drive and click 'ok' (as in pic 5)

You will then get the view in pic 6 detailing the important directories; Items, Persistence, Rules, Scripts, Sitemaps and Transform.

You can now edit your existing files by double clicking on them in the top left hand pane (pic 7).

How do I create new files?

Assuming we want to create a new sitemap named 'sq.sitemap'

Ensure OpenHAB Designer is closed

From Windows explorer navigate to 'O:\configurations\sitemaps'

Right click and select New -> Text Document

Rename the text document sq.sitemap and click ok

Click yes to the 'Rename' dialogue box which moans about a filename extension change making the file unusable

Now start up OpenHAB Designer

You will now see the new file under the Sitemaps folder.

Happy editing...

Gotchas

A. Use Google Chrome to view your OpenHAB Home Site from your PC. Internet Explorer hangs. Chrome is free and you can get it here; https://www.google.com/chrome/

B. One nagging issue I came across when using OpenHAB Designer was, if you restart the OpenHAB deamon via one of the following;

Reboot your Raspberry Pi, sudo reboot now

sudo service openhab restart

You will need to change the user:group on the OpenHAB files on the raspberry Pi from openhab:openhab to pi:pi or you will get a 'Save Problems' dialogue box as above (pic 8). You can do this by entering the following commands from a PuTTY terminal window.

D. Don't use the OpenHAB Designer internal Browser, it's 'buggy'. Each time I used it, it just hung and I needed to use windows task manager to kill it off. Better to use Chrome as I mention. Also see https://github.com/openhab/openhab

.

Footnote

I didn't bother adding any reference to HABMin, since after having evaluating it I found it flaky and didn't integrate well into OpenHAB.

Attachments

Step 6: Steve Quinn Household - OpenHAB User Interface

The above pictures depict the home site I created for my series on home automation.

The main site is named 'stevequinnhousehold' with IoT devices placed in the Garage, Study and Guest Bedroom respectively. Picture one outlines the menu structure and the remaining pictures the contents of these pages.

I have added the ability to view or change all the exposed functionality present in each the IoT devices the earlier parts of this series detail how to create and have also added in 'persistence' such that dynamic graphs of barometric pressure, temperature, humidity and heat index are displayed.

Once the files which make up 'stevequinnhousehold' have been installed on your OpenHAB server, to view the home site you will need to enter the following in Google Chrome.

Hint : What do I mean by exposed functionality? Simply anything within the IoT device which can be read from or written to via MQTT. So for instance, the Garage IoT device has an LED and DHT22 sensor which means it has a local output (red LED) and some local input (temperature and humidity, Heat Index is calculated). The code in the IoT device allows a remote publisher to turn on and off the LED with '/WiFiDevice/Led2Command' topic publications and a remote subscriber to receive topic publications as the device will periodically publish its local Temperature, Humidity and Heat Index if they change via /WiFiDevice/Temp1Status, /WiFiDevice/Humd1Status and /WiFiDevice/HeatInd1Status. If you look at the OpenHAB web page for the Garage you will see all of these items represented by icons, values (Degrees C and percentage) and a switch.

Step 7: There Are IOS OpenHAB Clients

So are there any other ways you can view the OpenHAB home site?

.

Yes, OpenHAB offer applications for iOS and android.

.

Screen shots of the iPad iOS version are shown above

Step 8: And Not to Leave Out Android Users

And for Android users the App Store has the following OpenHAB App.

Step 9: Debugging Your Rules

There are typically a few options open to you when debugging OpenHAB (on the Raspberry Pi) with OpenHAB Designer (on the PC). These are Semantic and Functional debugging.

Semantic Debugging

If you do opt to use OpenHAB Designer, one of the benefits of the software is it will help you pickup any semantic errors by highlighting the line in error with a red 'x' (in pic 3 above), here the software has detected the random text error 'ThisIsABlatantMistake' and highlighted it.

The software will also help you complete your code by offering any potential alternatives (as in pic 2 above). To obtain this help whilst typing, simply press Ctrl-SPACE. A short while later a drop down menu will appear detailing the possible alternatives. Use the up/down arrow keys to make your selection and press enter to make your choice.

Functional Debugging

This area of debug is a little tricky. Once you have entered all your code for .sitemap, .rules, .persist, Transforms(MAPS, Java Scripts etc) and .items which is reasonably straight forward. You can point your Chrome browser to your home site (http://openhab.local:8080/openhab.app?sitemap=stevequinnhousehold), refresh it and see the fruit of your labour before your very eyes.

But what happens if you are working on a rule and you get no response or a response in Chome which makes no sense. If such a situation occurs then you can use logging to help you to debug. See https://github.com/openhab/wiki/Rules for further details (generalised process depicted in pic 1). However in short you can effectively carryout print statement debugging if you do the following (pics 4 and 5 above);

So by using this method you can print debug your software until you fix any issues. To help your understanding I left some debugging code in the stevequinnhousehold.rules file, 'Sync Controls' rule.

.

Hint : Quitting a running command line program.

There are some subtle differences when you exit a program on a Linux system using ^C (Ctrl-C) and ^Z (Ctrl-Z). Depending on how you use these commands you may get what think is strange behaviour.

Ctrl-C : This command will exit and terminate a running program. You could use it to quit from the tailed log example above.

Ctrl-Z : This command suspends a program and gives you back the command line. In effect your previously invoked program is still in memory but gets no processor time. To correctly terminate a program after using ^Z, you will need to re-activate the suspended program by entering fg then ^C. If you restart a program that was suspended with ^Z you may find odd behaviour given the program is effectively still loaded before trying to load over the top.

.

NOTE : for '{' read less than and for '}' read greater than. Unfortunately the Instructables editor strips these characters from your text.

Step 10: Making Your Own Icons

Making your own icons for OpenHAB is reasonably simple. I used Microsoft Paint (TM) to create mine.

All you need to do is to carryout the following steps;

Run up paint,

Select Properties (pic above),

From Image Properties dialogue box, select, Units = Pixels,

Enter Width and Height = 32,

Click Ok,

Zoom in on your image. It will be very small (pic above),

Make your edits,

Save as a .png file.

Copy the .png file to your OpenHAB Rasperry Pi Server in the following directory;

/usr/share/openhab/webapps/images

or if you have mapped the directories as I have you simply drag and drop them into (pic above);

O:\webapps\images

Once you have done this you need to change the file attributes by entering the following from a PuTTY window;

cd /usr/share/openhab/webapps/images

sudo chmod 644 *.png

And that's it. Now you can reference your new icons in your .items file. So for humidity.png that would be {humidity}. You just miss off the .png.

Alternatively you could plagiarise from a web site (I found these useful);

Attachments

Step 11: Testing Your OpenHAB Site

There are essentially two ways you can test your hard work as depicted above.

You can use live IoT device data

You could use simulated MQTT traffic with MQTTSpy

There are merits in using both, which is how I did my testing.

Live data is great for real world testing, but is non-deterministic. In otherwords if you are trying to track down a bug that only occurs after a strange sequence of events. This is not the best method to use. you are better off deploying MQTTSpy.

I have included video clips of both typical test scenarios above.

For the simulated data testing I connected to the MQTT broker 'MQTTSVR' with MQTTSpy using the client-Id 'WIZNet5100-de:ed:ba:fe:fe:ee' such that it looked like the Ethernet Device I had connected earlier in the day.

I then Simulated the following;

From MQTTSpy to OpenHAB : Remote Logfile Open/Close Button Push

From OpenHAB to MQTTSpy : Logging Period Update, Time and Date Set

From MQTTSpy to OpenHAB : Remote Button Pressed/Released

From MQTTSpy to OpenHAB : Barometric Pressure update

For live data testing I picked out a few representative items to check. It was interesting to note that during testing I needed to refresh Chrome for it to pick up the Icon changes when setting the logging state. Also you will notice that the remote temperature is showing 'TR: 00.00' on the blue LCD display, this is because after resetting the Ethernet IoT device prior to shooting the video, the remote garage temperature sensor hadn't picked up any changes in ambient temperature, so there were no updates to the default initialised value of 00.00. However the temperature trend OpenHAB displayed showed a constant (persisted) 19.20 Deg C.

Step 12: Conclusion

So, if you have been following all the steps in this series, you will by now be adept in setting up, developing, debugging and extending your own intranet of things. Hopefully the main thread was relatively easy to follow and you feel confident about making your own IoT network.

What would I have done differently?

The naming convention of the MQTT topics I think was a little on the rushed side and really needs a lot of thought. I did find two useful sites where this topic was discussed to some extent. They are listed in the next step.

Developing rules was a steep learning curve I think I would have done much better had I learned Java and Xtend before trying to tackle home site development. I needed to do a lot of reading round to 'get a grip' on this.

Bones of contention

I was unable to get the System Startup Rule working, no matter what I tried. I did a lot of 'googling' and did not I was not the only OpenHAB user to have experienced this.

Graphs flickering. This is a known issue to overcome this I changed the layout of the home site 'pushing' the graphs down into sub-menus to prevent constant screen updates.

Where next?

I am in the process of developing some extra IoT devices for my network which I will getting round to publishing when the bits arrive from China;