15 minute primer: OpenHAB2 with z-wave

Here's a very rapid guide on how to install openhab2 on Ubuntu 16.04.3 with z-wave support. It may help somebody out there!

I'm using a z-wave AEOTEC z-stick GEN5 which supports the FLiRS feature, mainly because this allows the user to wake a remote device, rather than wait for the device to arbitrarily wake to receive commands.


From a fresh installation of Ubuntu 16.04.3 I suggest deciding whether you wish to use the Stable Release or the Testing Release. I'm using the testing release as I encountered some GUI problems with stable 2.1.0, plus it lets me keep on the crest of the curve in terms of updates.

Have Java?

First up, install the recommended version of java on the host - Zulu. You may already have a version of java installed and it may be fine, but be aware of some of the issues or limitations mentioned in the page linked above.

The downloads for Zulu are here, you need version zulu-8.x with java jdk 1.8 and the command to download it if as follows:

wget http://cdn.azul.com/zulu/bin/zulu8.25.0.1-jdk8.0.152-linux_amd64.deb

Install the java-common package and then zulu:

apt install java-common
dpkg -i zulu8.25.0.1-jdk8.0.152-linux_amd64.deb

To test the installation, run "java -version" to see the installed version:

root@LittleBrick:/# java -version
openjdk version "1.8.0_152"
OpenJDK Runtime Environment (Zulu 8.25.0.1-linux64) (build 1.8.0_152-b16)
OpenJDK 64-Bit Server VM (Zulu 8.25.0.1-linux64) (build 25.152-b16, mixed mode)

Installing openHAB2

To install the Testing Release base-package, follow the instructions listed in the openhab2 documents:

wget -qO - 'https://bintray.com/user/downloadSubjectPublicKey?username=openhab' | sudo apt-key add -

apt-get install apt-transport-https

echo 'deb https://dl.bintray.com/openhab/apt-repo2 testing main' | sudo tee /etc/apt/sources.list.d/openhab2.list

apt-get update

apt-get install openhab2 openhab2-addons

You will then be prompted to setup systemd to start the service automatically with the following message:

### NOT starting on installation, please execute the following statements to configure openHAB to start automatically using systemd
 sudo /bin/systemctl daemon-reload
 sudo /bin/systemctl enable openhab2.service
### You can start openhab2 by executing
 sudo /bin/systemctl start openhab2.service

So, go ahead and setup the automatic startup if desired:

  /bin/systemctl daemon-reload
  /bin/systemctl enable openhab2.service

Next, start the service:

/bin/systemctl start openhab2.service

While the service starts, it's a good idea to monitor the logfiles as this happens, so that you can become familiar with the messages and chatter which occurs, especially at a later stage with z-wave.
The following method allows you to see all of the updates to the critical logs: events.log, openhab.log and audit.log, as they occur:

tail -f /var/log/openhab2/*

Note: If the log files remain blank at this point and the  issue the command "/bin/systemctl status openhab2.service" and review the output from the process. An example of a failed start is below, this was due to the java jdk not being present and karaf could not run:

root@LittleBrick:/# /bin/systemctl status openhab2.service
openhab2.service - openHAB 2 - empowering the smart home
   Loaded: loaded (/usr/lib/systemd/system/openhab2.service; enabled; vendor preset: enabled)
   Active: activating (auto-restart) (Result: exit-code) since Wed 2018-01-10 19:49:40 GMT; 4s ago
     Docs: http://docs.openhab.org
           https://community.openhab.org
  Process: 12695 ExecStop=/usr/share/openhab2/runtime/bin/karaf stop (code=exited, status=1/FAILURE)
  Process: 12676 ExecStart=/usr/share/openhab2/runtime/bin/karaf $OPENHAB_STARTMODE (code=exited, status=1/FAILURE)
 Main PID: 12676 (code=exited, status=1/FAILURE)

Jan 10 19:49:40 LittleBrick systemd[1]: openhab2.service: Unit entered failed state.
Jan 10 19:49:40 LittleBrick systemd[1]: openhab2.service: Failed with result 'exit-code'.

All going well, if you now connect to openhab2 (http://(server-ip):8080) you should be presented with the panels for each of the UI's. Next, let's jump to getting z-wave working...

Configuring the z-wave USB device

First, let's discover the z-wave USB and add a udev claim-rule for it. In my case I have an AEOTEC z-stick GEN5, so I'll need to find the vendor ID and the product ID to add it into the udev claim-rule.

Insert the USB device and run "lsusb":

root@openhab2:/home/root# lsusb
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 003 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 002 Device 002: ID 0658:0200 Sigma Designs, Inc.
Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub

My device is the "Sigma Designs" entry and all of the information which we need for udev is supplied in the output.

0658 = idVendor
0200 = idProduct

Next, create a file called "/etc/udev/rules.d/50-usb-serial.rules" and insert the following udev statement into it with the idVendor and idProduct substituted as needed:

SUBSYSTEM=="tty", SUBSYSTEMS=="usb", ATTRS{idVendor}=="0658", ATTRS{idProduct}=="0200", SYMLINK+="USBzwave", GROUP="dialout", MODE="0666"

In the above case, I'm creating a new dev called USBzwave as part of the dialout group. Then, reload udev:

udevadm trigger --reload

Then setup the openhab account with the required permissions:

adduser openhab dialout
adduser openhab tty

The AEOTEC z-stick GEN5 should now be available at /dev/USBzwave!

Configuring openHAB2

I found this a little tricky to work out as a lot of the documentation for z-wave applies to openHAB (version 1) and not openHAB2.
Very simply, to add the USB device you need to edit the file /etc/default/openhab2 with the following parameters:

EXTRA_JAVA_OPTS="-Dgnu.io.rxtx.SerialPorts=/dev/USBzwave"

Now, restart the openHAB service and then install the z-wave binding. Then, from PaperUI, enter the Inbox and click the blue plus (+) icon, click through to the "Configure Z-Wave Serial Controller" page and select the /dev/USBzwave device as the serial port, the z-wave thing (AEOTEC) should then appear, but still needs to be configured.
Go to Configuration and Things, select the newly discovered USB device, edit it and select the serial port "/dev/USBzwave" from the drop-down menu.

You should now have the AEOTEC thing listed under Configuration -> Things,, and that should be it!

I'll try cover off setting up persistence with the easy to use Influx database next.

Gallery3 - really quick method of resetting the content of the gallery

If like me you can't find out how to delete multiple images at the same time, here's a very quick method of resetting gallery3 back to it's original configuration in 2 steps.
This will delete all of the photos and the settings of gallery3, but will leave the added modules installed but not enabled. Use this process at you your own peril.

Step 1 - Delete Gallery3's var folder, usually maintained under /var/www/gallery3/var.

rm -rf /var/www/gallery3/var/*

 Step 2 - Drop the database.

$> mysql -u root -p (prompts for the root password interactively)
mysql> show databases;
+--------------------+
| Database                 |
+--------------------+
| information_schema |
| gallery3                   |
| mysql                      |
| performance_schema |
| test                          |
+--------------------+
4 rows in set (0.00 sec)

mysql> use gallery3;
mysql> drop gallery3;
mysql> exit

Now, reconnect to gallery3 with a web browser and reconfigure gallery3 from scratch.

Configuring RRDtool to display 1-wire results

I can't claim much credit for the scripting I used to generate graphs as it's all based on this excellent guide on owfs's site: owfs Gardening

Here's something I learned though...
Run the script provided to make the database, but notice the following: The script provided uses '--step 300' and 'AVERAGE' settings. These two items are critical to understand, otherwise like me, you'll be wondering why the rrdtool graphs don't update if you run the data collection script very frequently (for example, every minute).

 rrdtool create temperature.rrd --step 300 \
DS:temp:GAUGE:600:-273:5000 \
RRA:AVERAGE:0.5:1:1200 \
RRA:MIN:0.5:12:2400 \
RRA:MAX:0.5:12:2400 \
RRA:AVERAGE:0.5:12:2400

The sample rrdtool create statement from rrdcreate's man.

To explain this as best I can, rrdtool is fed with a batch of results retrieved from the temperature sensors at 1 minute intervals (assuming you setup cron to do so). As the step is set for 300 seconds, it doesn't populate it's main table with these results until 300 seconds after the last update, instead it retains them in an 'archive'. Then on the 300 second mark, it averages the results and publishes them.
So, if you took 5 readings in that 300 second period, lets say of 5, 10, 15, 20, 15, you won't see this displayed in the graph, instead it will be replaced by the average of 13.

This is well explained in the rrdcreate man.

This leads into a separate question... considering I created the initial database using a step of 300, how can I modify this to a shorter step retrospectively? Well you can do it, but just be aware that it doesn't maintain data integrity.
As the values published to the database are 'points in time' of 300 seconds each, modifying the step will cause the data points to assume this new time-scale. In my case, I ran the command 'rrdtool dump temperature.rrd >> database.xml' to output the database into an XML file. I then modified the step values in the second line of the database from 300 to 120 seconds. I then backed-up my old database and exported or 'rrdrestor'ed the data into a new database with the command 'rrdrestore database.xml temperature.rrd'.

On generating graphs with the new database I noticed that the shorter step of 120 seconds caused the newly graphed data-set to compact, effectively making each of the individual records into 120 second events, rather than the 300 second ones which they really were.

Hence, I believe it's true to say that there is no method of retrospectively adjusting the step of an rrdtool database as it affects the 'point in time' nature of the events contained within it.

Installing and configuring OWFS under Ubuntu Karmic Koala (9.10)

Just after the very cold spell in early January 2010, I read a boards.ie post by a guy called Dave (ravydavygravy) in which he queried the use of 1-wire systems in weather monitoring.
Having an interest in this subject, I read up on this system and was immediately interested in it's capabilities. I have often looked for a simple method of measurement and control and this 1-wire system coupled with owfs seems to offer it. Of course it's early days yet, but I placed an order for a couple of parts online and set about getting this working on Ubuntu 9.10. Here's how...

I ordered the following from homechip in the UK :
6x DS18B20 1-wire temperature sensor
1x DS9490R - USB 1-Wire / iButton Adapter (RJ11)
and a few RJ11 crimp-plugs.

I tested the basic 1-wire system on a breadboard and I used the software test-tool which Maxim supply to initially, and very simply, read the temperatures from a couple of sensors.
OneWireViewer Demo

All functioning, I set about getting it running under OWFS, which proved a test of my limited bash skills.

Instructions came from the ever helpful community.

Generally, I'm not into having to build applications at all under Linux. Having had a bad run-in or two with kernel builds in RedHat 6.2; having to type 'make'-anything left a taste in my mouth. :)
I find that there is variance in Linux/Ubuntu builds, hence it's never a straight-forward process.

So I set about installing the packages to support building OWFS:

'apt-get install automake autoconf autotools-dev gcc g++ libtool libusb-dev fuse-utils libfuse-dev swig python2.4-dev tcl8.4-dev php5-dev'

I got 404's on some packages and a hint from apt that Ubuntu may be short a couple of updates. I realised at this point that my test system hadn't been booted in 4 or more months, so apt wasn't up to date.
So, I ran 'apt-get update' and then re-ran the apt-get as above again. All worked OK this time.

I moved the downloaded source code into directory /usr/src as directed.
Then onto the simple matter of extracting the files:

'tar zxpf owfs-2.7p26.tar.gz'

Move into the /usr/src/owfs directory and then start the process of building in earnest.

'./configure'

While ./configure passed off without issue, I remembered from the past that I had problems with permissions when running the 'make' part of the process, so I sudo'd the command just to be sure.

'sudo make && make install'

Unsurprisingly, to myself anyhow, I got an error:
'/bin/mkdir: cannot create directory `/opt/owfs': Permission denied'.

So, I did a ...
'make clean'
And then retried 'sudo make && make install'

It failed with the same errors.

Rereading over the readme notes which were included with the .tar, it mentioned installing the USB DS9490R controller before running make. So, I attached the USB dongle as instructed and ran:

'sudo make && make install'

This time, it builds OK and installs.

(Note here that in the owfs readme, it mentions running 'make install' as opposed to 'make' and then 'make install'. Try this if you still have issues.)

Then onto the home-run... or so I thought...

'sudo mkdir /var/lib/1wire'

Then I ran

'modprobe fuse'

And I got "FATAL: Module fuse not found."

I reinstalled fuse from apt again but the same error returned. I simply ignored the step and continued on regardless.

I created a directory in mnt called 1wire and used that in the statement instead of the /var directory.

On running :

'/opt/owfs/bin/owfs -U -F /var/1wire'

as per the instructions in the 'community', it gave:
'./owfs: invalid option -- 'U''

I checked the man for owfs and found that the command 'owfs -U -F...' should use a small u instead of a capital U.
Tried this and got a more postive response.

Running

'sudo ./owfs -u -F /mnt/1wire/'

gave:
'DEFAULT: ow_ds9490.c:DS9490_sub_open(552) Opened USB DS9490 adapter at 006/002.
DEFAULT: ow_ds9490.c:DS9490_detect_found(412) Set DS9490 006/002 unique id to 81 D0 3C 2C 00 00 00 A9'

Now
'sudo ls /mnt/1wire' shows:
'28.2F8B87020000 81.D03C2C000000 bus.0 simultaneous structure uncached alarm settings statistics system'

So above, I see a number of devices attached to the USB dongle - one reporting a '28.x' family name.
You can lookup the family names here http://owfs.org and you'll see that 28 is a thermal sensor.
So, I've got the devices reporting on the bus, that's enough for the moment...

Tefal Quick Cup modification

I purchased a Tefal Quick Cup back in 2007 soon after they launched. I initially thought it was a great idea to have 'boiling' water in measured quantities. Not long after, it fell out of favour at home here as the temperature of the water wasn't up to scalding teabags.
I measured the water temperature with a spirit thermometer, coming out at a chilly ~75 degrees C. Couple this with a cold cup and you have insufficient heat to brew tea.

The decision to modify it was simple - it either had to be assigned to the attic as a poorly designed fad-item or get placed in the WEEE recycling bin!

Warnings: I'm not including photos of the process here as anybody who tries this needs to know what they are doing, or face possible electrocution (no, I won't personally administer it). This process will void your warranty on your already useless Quick-Cup. I accept no responsibility for any damage caused or harm done.

Required:
T-15 star bit.
Flat-blade long shaft screwdriver (>15cm).
1x 10k ohm PCB mountable variable resistor.
1x 4k7 ohm resistor. (a 0.25W or mini-resistor should be fine here.)

Process:
1. Open the Quick Cup by removing the two star screws from the underside. Using the cord, lift the base away from the shell of the unit. The base is push-fitted into the body, so needs some force to free it.
2. When the base is loose you will note that the internal piping connects to silicon tubing via push-fit connections. Note the layout of the piping, pump and mains cord. Pull the base away from the pump to free it.
3. Disconnect the pump from the body and disconnect the power leads. The pump is not electrically polarised, so the two grey wires need not be replaced in the same position.
4. Looking into the body, locate the 5 locking tabs which retain the top button-panel to the body. Using the long shaft screwdriver, push the tabs outwards and then down to free them. Work on the tabs in a circular pattern to free the rear of the panel, then pull the panel off once all 5 tabs have been freed. This will expose the circuit board.
5. Loosen the PCB.
6. Remove the heater element and PCB from the body by withdrawing it through the bottom of the base. The heater element is retained with a silicon connection which slides open easily.
7. Observe the heater element connection with four cables running to it. The outer two of these (salmon coloured) serve to deliver power to the element, while the inner two (white) are the thermistor. The thermistor reads ~107k ohms at room temperature (~22 degrees C).
8. Observe the PCB track layout from the two white wires. One of these PCB tracks runs to a resistor (220 ohm I think) and the track is exposed and easily cut.
9. Solder the 10k variable resistor and 4k7 resistor in series on a suitably long twin-core wire to allow it to be installed alongside the PCB.
wire=--------| 4k7 |-------| 10k var |------------=wire

10. The variable resistor needs to be installed in series with the thermistor on the heating coil. This is done by soldering one end to the solder pad for the 220 ohm resistor already on the PCB and the associated solder pad for the connection block for the thermistor, again on the PCB.
11. Break the PCB trace between the resistor and the connector pad. Check the new connection with a multimeter - you should read anything from 4k7 ohms to 14k7 ohms.
12. Using a multimeter, adjust the variable resistor to near to 0 ohms.
13. Reassemble the unit *on the base*, but leave the top button cover off. Reassembly is not the reverse of disassembly.

• With the plastic body of the Quick-Cup aside, attach the pump to the water holder connector, noting the directional flow arrow on the body of the pump.
• Attach the pump to the silicon pipe which leads to the heater unit and push-fit this to the base.
• Attach the wiring to the pump and orientate the wiring so the connections point skywards.
• Ensure that all the wiring passes through the centre of the heater.
• Pass the plastic body down over the PCB and heater element and push-fit onto the base.
• Locate the heater onto the pipe which runs into the neck of the Quick-Cup. Fitting will seem loose as it's a silicon connection again.
  
• Fit the PCB in place, routing the new variable resistor to the side of the unit.
• Check and double-check your work.
  

14. The unit will now be fully reassembled except for the button-panel. Do not replace this just yet as it will lock in place and you won't be able to adjust the variable resistor.
15. *SAFETY WARNING* When plugged in, the PCB is LIVE and has exposed mains wiring. Assume that the variable resistor is also LIVE. DO NOT adjust the variable resistor when the unit is plugged in! Water and mains electricity do not mix!
16. Replace the water holder with a quantity of water which has been allowed to rise to room temperature and plug the unit into the mains.
17. Using an INSULATED screwdriver and one hand behind your back, carefully press the hot water delivery button on the PCB.
18. Measure the temperature of the water at the spout.
19. If the water temperature is too low, DISCONNECT the Quick-Cup from the mains, then adjust the variable resistor to 2k ohms. Retest the water output. DO NOT set the water higher than ~93 degrees (~2.5k ohms on the variable resistor) as the water will boil and splatter on exit.
20. Once the unit has been setup as required, Insulate the variable resistor with electrical tape and locate it safely in the upper lid of the Quick-Cup.
21. Replace the button-panel and also replace the star screws in the base.

Enjoy near boiling water from your Quick-Cup.

A modification of this would be to use a panel-mountable variable resistor and mount this in an accessible part of the quick-cup body. This will allow for temperature changes in the incoming water. I have found that water which comes directly from the tap (at ~7 degrees C) doesn't get up to temperature effectively. This may be a limit on the power of the heater versus the flow-rate of the pump, but I haven't tested this to be sure.

The energy densities of common Irish fuels

These are the energy densities of various fuels commonly used in Ireland, collected from various sources.

Electricity - 3.6 MJ/kWh
Wood chips (@50% Moisture) - 9.5 MJ/kg
Wood - 11 MJ/kg
Sod Peat (Turf) - 12.8 MJ/kg
Coal (Lignite) - 14 MJ/kg
Wood chips (@25% Moisture) - 14.3 MJ/kg
Wood pellets - 16.8 MJ/kg
BNM Briquettes - 17.7 MJ/kg
Coal (Bituminous) - 20 MJ/kg
Coal (Anthracite) - 32.5 MJ/kg
Biodiesel (veg oil) - 33 MJ/L
Petrol - 34.2 MJ/L
Diesel (Fuel Oil) - 37.3 MJ/L
Natural Gas - 38.7 MJ/m3

Sources:
Wikipedia - Energy Density
Green Building Magazine - Wood pellets - a fuel for the 21st century
Bord na Mona - Peat for Energy (pdf)
Natural Gas (Australia) - References

To convert from MJ to BTU, multiply by 947.82.

I'm searching for figures for some of the newer fuel products such as miscanthus logs and compressed wood logs such as Ecoflame from Stafford Fuels.

The efficiency drive - stoves pickup from the closure of the open fire

As the regulation of the air-tightness of our homes evolves, the first item to face the chop was inevitably going to be the open fire-place.
A possible throwback to the bronze-age, the open hearth and chimney acted as a method of preventing your cooking area from engulfing your ráth and sheepskin bed linen.

The chimney, essentially a wind-path into the innermost chambers of a residence, was decorated and centrally located in any room bringing warmth and comfort to the occupiers. It has remained as such to this date in time, even where modern central heating and insulation have removed the basic need of an open fire.
The homely fireplace serves to do much more than to simply provide warmth. You can't close off an open fire and leave a bare chasm and a slightly off-white radiator on the opposite wall. The loss of this family muster-point can't be undervalued from a social perspective, it along with the TV provide the backdrop to the process of the evening wind-down; time to reflect on past and present, catch up on happenings and occurrences.
The drive for efficiency has demanded that we lose the open fire, but we need to fill the physical and social void created by it's loss. It has to be replaced with a substitute which will provide ample heat through efficient combustion of fuel and a flickering flame, all in a small and neat unit and also provide that essential social centre-piece. That's where the solid-fuel stove makes hay and wins out over rivals such as the electrical-effect fireplace.

Typical efficiency figures for open fires, when burning, are put between a lowly 10 and 25 %. Throw three Bord Na Móna briquettes up the chimney for every one you derive heat from! But, neglected in these figures is the effect that the fireplace has when it's not in use. Add to these value possibly another 15% for heat loss up the chimney on a gusty night.

A good draw on a chimney is both a cure and a blessing. Acting like a central vacuum, it whips the warm air from a room with astounding speed. Where in the past we had manually adjustable chimney dampers fitted to the throat, we somehow forgot about their usefulness in the recent years and neglected to consider the open fire as a major source of heat loss.

The stove on the other hand is the almost-ideal solid fuel consumer. By nature, the adjustable vents throttle the rate of airflow through the unit, eliminating heat loss through the updraught otherwise present. More control on the rate of combustion means that the fuel is completely consumed instead of being lost in fuel or gas vapours, or deposited thickly on the chimney pipe.

Taking a standard Bord Na Mona briquette, we can calculate the following outputs for heat released into the room for both an open fire and a closed stove:

For 2kg of BNM Briquettes burned in one hour:

Open fire (10 to 25% efficiency):
Output in MegaJoules: Min: 3.54 Max: 8.85
Output in BTU: Min: 3,355 Max: 8,388

Stove (40 to 80% efficiency):
Output in MegaJoules: Min: 14.16 Max: 28.32
Output in BTU : Min: 13,421 Max: 26,842

Where the Energy Density of BNM Briquettes is 17.7 MJ/kg approx.

The outlook for the solid fuel stove is good. It fits relatively well with the green movement's checklist for suitable sources of primary or secondary residential heating systems.

• It fills the gap left by the now outlawed and uneconomical open fire.
• It reduces our dependence on externally sourced fuel such as oil and gas.
• It supports local business through the provision of fuel production and sales.
• It allows the householder to warm a central area of a house without having to warm a whole central heating zone.
• And dogs love curling up beside a stove which doesn't spit char and sparks.

The rise of the humble stove didn't go unnoticed in Waterford-Stanley's boardroom with a substantial article broadcasting their outlook for the devices.


Bootnote: The Wikipedia article about the stove credits Ireland for having some of the most efficient stoves at 80% efficiency when compared to some stoves in China with 15%.
It appears to make out that back boilers are somewhat unique to our shores.