• Previously I mentioned an “ERASE” mode, this is actually “EXCLUDE” mode. This mode should only be used if your thermostat was previously installed in a z-wave network, I guess this was the case when I first set-up my thermostat. The protocol reset does more or less the same but is more extensive. It removes any network information from the HRT4-ZW and returns it to the factory default state (The double press of the dial is to avoid accidental operation)
• The way incorporate the devices with a controller (in my case the Aeon Labs Z-Stick) is to start with both in an unassigned state. Install each device separately on to your controller. The Association between the two devices may be done using the ‘A’ command on the HRT4-ZW and pressing the install button on the ASR. This does not require knowledge of the node numbers. The install (network) button is required for installation. You need to hold the button down for over a second.
• I forgot to mention about the wake-up time, I changed the wake-up time while it was in the LI (listen) mode. The default wake-up time is around 23 hours, which is a bit long when you want your thermostat changed. I changed it to 256 seconds or in other words 4 minutes and 16 seconds (the bare minimum value), but I might change it to a higher value again later on.. please see the point below why..
• The 2 year battery life (as reported by Horstmann) is based on normal use as a stand-alone thermostat. Use in a network where the HRT4-ZW is woken up regularly will reduce this time. That’s why there is a minimum wake-up interval. Battery life should not be a problem in practice, but please note that when the HRT4-ZW is in installer mode (switch 1 up) the Z-Wave module is permanently powered and takes much more power. This is why my battery life reported 90% after some tests. 0% is 2V and 100% is 3V or above. A new set of batteries will normally give just over 3V (2xAAA, 1.5v each)
• There is actually a second and third configuration parameter I forgot to mention about. The second one allows you to change to Fahrenheit messages. The third one allows you to set a delta t for reporting temperature changes. A message will be sent to associated nodes if the temperature changes by delta t. This parameter defaults to 1°C.
• When controlled by Z-Wave messages rather than turning the dial, you can actually set the setpoint to 0.1°C steps. This will not show up on the display as it’s only 2 digits, but it will attempt to control to it. For example you could set the setpoint to 20.6°C if you wished. 21°C will be shown on the display as the demand temperature is rounded up. Fahrenheit temperatures are converted internally to the nearest 0.1°C so will not give you more accuracy.

Some really valuable additional information, thanks a lot Mr.Anonymous ! :-)

I did not expect anything from that whole social coding thing. But then after a couple of days two guys (Steve Davidson and Drew Perttula) started commiting code (a lot of code!) to the project. Here’s the result of 3 weeks on Github:

52 commits with 5,421 additions and 510 deletions

Really impressive, thanks a lot guys!
Steve even made a really nice curses interface to it, here are some screenshots (click for full view):

This interface available on Github as well.

• Control the setpoint
• Get a setpoint report when it is manually changed (also notifications of battery levels and the room temperature)
• Get the actual room temperature

There are several posts on the Micasa Verde and Homeseer forums that device is not working in their software, despite this fact I decided to take the risk and order this device. The total cost including shipping costs was just under €100.
The HRT4-ZW is a thermostat system that consists of two devices, one controller (the user side of the system, where you control the set point etc.) and a receiver (this one needs to be attached to your HVAC system). Here’s a picture of both devices:

Getting my feet wet: the first steps

The first step I took when I got the device was creating a test setup, I connected an old PC power supply cable to the receiver (it needs 230v). Put in the batteries of the controller device and I was good to go! I decided the first step I had to take was getting values from the device (temperature, current set point and battery level as a bonus). Horstmann has provided detailed z-wave information in a separate document, available here.
One of the requirements for me was to include the controller device into my existing z-wave network, that appears to be a pretty trivial task. But, it turned out it was one of the most difficult tasks.
I completely read through the z-wave document over and over again, but after 2 evenings of playing around with I was about to give up. The L mode as described in the document does include the controller within an existing z-wave network, but that loses the connection with the device that you attach to your HVAC.
Separately re-associating that unit is not an option as the network button on the device does not do anything. Or, maybe it can be used?
I figured out that once you put the controller unit into ERASE mode, the receiver network LED will blink as if it is ready for association. This turned out to be the key to getting both nodes included within my existing z-wave network! Here are the steps in detail:

1) Put the thermostat into program mode (dip switch 1 into position ON)
2) Select the P option, double click the rotary wheel until PP appears on the display.
3) Now go to the E, for ERASE mode. Click the rotary wheel once again until the E starts blinking.
4) At this point the receiver network LED should be blinking, this means the node is ready for inclusion.
5) Now, remove the batteries from the controller! Yes, just do it :-)
6) Include the receiver by pushing the include button on your z-wave network stick (in my case an Aeon Labs z-stick), after that press the network button on the receiver until the ON led starts to blink.
7) The receiver is now included!
8) Include the controller by using the L function as described in the z-wave documentation.

You should now end up with two thermostat devices in your z-wave network. Here’s a screenshot from HouseAgent:

Node number 3 is the receiver and node 4 is the controller. Node 3 is quite useless (it doesn’t report any z-wave classes, except basic) but it needs to be included within the same network in order to work with the controller. Here are the z-wave classes reported by the controller, again a screenshot from HouseAgent:

Please note that the controller is a sleeping z-wave device, requests for this device need to be queued until the device comes available. The device will send a wakeup notification once it comes online. You can queue commands to the controller, and when it gets online send these commands.

Associations

In order to receive updates from the controller once a value changes you need to set associations. The thermostat supports associations for unsollicited room temperature, setpoint and battery reports. I set associations for each of these reports to my z-wave stick. Here’s an overview of my configuration (more information of the specifications of these groups can be found in the Horstmann document):

Setting the setpoint

This was my final task to be actually able to control the thermostat. Because this is a sleepjng device commands need to be queued, this was an easy thing to do in open-zwave. The problem was however that my Python z-wave wrapper had no support for setting values.. yet. I commited a new version of my open-zwave python wrapper, with setvalue support to github!

Here’s an example of the setvalue command being executed after the device woke up:


2011-05-19 20:10:01:771 Received Wakeup Notification from node 4
2011-05-19 20:10:01:772 Node 4 has been marked as awake
2011-05-19 20:10:01:774 Queuing command: Set Thermostat Setpoint (Node=4): 0x01, 0x0c, 0x00, 0x13, 0x04, 0x05, 0x43, 0x01, 0x01, 0x01, 0x0f, 0x05, 0x09, 0xa0
2011-05-19 20:10:01:817 Sending command (Callback ID=0x09, Expected Reply=0x13) - Set Thermostat Setpoint (Node=4): 0x01, 0x0c, 0x00, 0x13, 0x04, 0x05, 0x43, 0x01, 0x01, 0x01, 0x0f, 0x05, 0x09, 0xa0
2011-05-19 20:10:01:822 ACK received CallbackId 0x09 Reply 0x13
2011-05-19 20:10:01:825 Received: 0x01, 0x04, 0x01, 0x13, 0x01, 0xe8
2011-05-19 20:10:01:828 ZW_SEND_DATA delivered to Z-Wave stack
2011-05-19 20:10:01:838 Received: 0x01, 0x05, 0x00, 0x13, 0x09, 0x00, 0xe0
2011-05-19 20:10:01:840 ZW_SEND_DATA Request with callback ID 0x09 received (expected 0x09)
2011-05-19 20:10:01:845 Expected reply was received
2011-05-19 20:10:01:869 Message transaction complete


Physical/electrical connections

I was unsure about the electrical connections required from the receiver to my HVAC, so I decided to hook up two wires to the points I expected to be the required connections. After that I tested it with the continuity function of my multimeter. Here’s a video of my test setup:

Parameters

One more sidenote, there are two configuration parameters available. Configuration parameter 1 must be set in order for room temperature reporting to work! This does not work out of the box..

This concludes my long post about this thermostat, next up for me is creating a nice GUI for it… now that I got everything figured out.

• Add the needed HTML templates for the GUI interface
• Create some Python code to query the right information from the specific plugin
• Add some device types to the database

So after two/three hours of work I created the following:

This screenshot shows general information about the z-wave network, I want to expand that overview with more network parameters later on. HouseAgent also includes a control page, which now allows me to switch z-wave modules on or off. That is shown in the following screenshot:

(click for a better view)
So there you have it, software evolution: from a somewhat hacky Python module up to a usable GUI.

Enough talking, py-openzwave can be found here: http://projects.maartendamen.com/projects/pyopenzwave/
There are some usage notes on the wiki page.

Any help with the project is greatly appreciated.

MinGW also uses a make command, to built and maintain c/c++ programs. So the first step I had to take was to create a Makefile for MinGW.
This was actually quite easy, I took the Linux Makefile and modified it accordingly:

#
# Makefile for OpenZWave Linux build
# Greg Satz
# Modified for use with MinGW by Maarten Damen

# Requires libudev-dev

.SUFFIXES:	.d .cpp .o .a
.PHONY:	default clean

CC     := $(CROSS_COMPILE)gcc
CXX    := $(CROSS_COMPILE)g++
LD     := $(CROSS_COMPILE)g++
AR     := $(CROSS_COMPILE)ar rc
RANLIB := $(CROSS_COMPILE)ranlib

DEBUG_CFLAGS    := -Wall -Wno-format -g -DDEBUG -DLOG_STDERR
RELEASE_CFLAGS  := -Wall -Wno-unknown-pragmas -Wno-format -O3

DEBUG_LDFLAGS	:= -g

# Change for DEBUG or RELEASE
CFLAGS	:= -c $(DEBUG_CFLAGS)
LDFLAGS	:= $(DEBUG_LDFLAGS)

LIBDIR	:= ../../lib/windows-mingw32

INCLUDES	:= -I ../../src -I ../../src/command_classes/ -I ../../src/value_classes/ \
	-I ../../src/platform/ -I ../../src/platform/windows -I ../../tinyxml/ -I ../../hidapi/hidapi/
SOURCES		:= ../../src ../../src/command_classes ../../tinyxml ../../hidapi/windows \
	../../src/value_classes ../../src/platform ../../src/platform/windows

VPATH = ../../src:../../src/command_classes:../../tinyxml:../../hidapi/windows:\
	../../src/value_classes:../../src/platform:../../src/platform/windows

%.d : %.cpp
	@set -e; rm -f $@; \
	$(CXX) -MM $(INCLUDES) $< > $@.$$$$; \
	sed 's,\($*\)\.o[ :]*,\1.o $@ : ,g' < $@.$$$$ > $@; \
	rm -f $@.$$$$

tinyxml := $(notdir $(wildcard ../../tinyxml/*.cpp))
hidapi := $(notdir $(wildcard ../../hidapi/linux/hid.c)) # we do not want the libusb version
cclasses := $(notdir $(wildcard ../../src/command_classes/*.cpp))
vclasses := $(notdir $(wildcard ../../src/value_classes/*.cpp))
pform := $(notdir $(wildcard ../../src/platform/*.cpp)) \
	$(notdir $(wildcard ../../src/platform/windows/*.cpp))
indep := $(notdir $(wildcard ../../src/*.cpp))

%.o : %.cpp
	$(CXX) $(CFLAGS) $(INCLUDES) -o $@ $<

%.o : %.c
	$(CC) $(CFLAGS) $(INCLUDES) -o $@ $<

default:	$(LIBDIR)/openzwave.a

clean:
	rm -f *.d *.o

-include $(tinyxml:.cpp=.d)
-include $(hidapi:.c=.d)
-include $(cclasses:.cpp=.d)
-include $(vclasses:.cpp=.d)
-include $(pform:.cpp=.d)
-include $(indep:.cpp=.d)

vers.c:
	echo 'char ozw_vers[] = "OpenZWave version 1.0.'`svnversion ../..`'";' > vers.c

vers.o:	vers.c

$(LIBDIR)/openzwave.a:	$(patsubst %.cpp,%.o,$(tinyxml)) \
			$(patsubst %.c,%.o,$(hidapi)) \
			$(patsubst %.cpp,%.o,$(cclasses)) \
			$(patsubst %.cpp,%.o,$(vclasses)) \
			$(patsubst %.cpp,%.o,$(pform)) \
			$(patsubst %.cpp,%.o,$(indep)) vers.o
	$(AR) $@ $?

For the sake of maintainability I created the following folders in the open-zwave folder structure:

- openzwave/cpp/build/windows-mingw32 <- for the custom Makefile
- openzwave/cpp/lib/windows-mingw32 <- for the output library file

After setting all of this up, I was ready to run the 'make' command.
Uh oh, troubles:

This is caused because a non c++ standard function “sprintf_s” is used within some of open-zwave’s files.
Fortunately there is a similar standard c++ function called snprintf, the fix was easy (put this on top of the cpp/src/platform/windows/HidControllerImpl.cpp file):

#define sprintf_s snprintf

Will it build now? No, way..

This is again caused by use of non-standard functions: fprint_s and fopen_s. The fix is to put this in the head section of the cpp/src/platform/windows/LogImpl.cpp file:

#define sprintf_s snprintf

The fix for the fopen_s command is a bit trickier, I replaced it with the standard fopen command. Replace all parts in the LogImpl.cpp file where opening of files takes place:

FILE* pFile = NULL;
if( !fopen_s( &pFile, m_filename.c_str(), "a" ) )

Replace it with the fopen equivalent:

FILE* pFile = fopen( m_filename.c_str(), "a" );
if ( pFile != NULL )

Rerun the ‘make’ command and open-zwave should now compile correctly with MinGW! The output library is roughly 31MB.

This means node 1 and 2 are in use, another example:

0000 1011

This would indicate node 4, 2 and 1 being used. So, how do we figure this out from code? This is where bitwise AND comes into play. A bitwise AND takes two binary representations of equal length and performs the logical AND operation on each pair of corresponding bits. In each pair, the result is 1 if the first bit is 1 AND the second bit is 1. Otherwise, the result is 0.
We can use this from our python code in the following matter:

    length = ord(response[7]) - 1
    index = 1

    for i in range(0, length):
        buffer_index = response[8+i]
        num = 1
        j = 0

        while j <= 7:
            if (ord(buffer_index) & num > 0):
                print "node exists!", index
            else:
                print "node does not exist", index

            index = index+1

            if j < 7:
                num = num * 2 

            j = j+1

And does it work?

Looks fine!

After playing around a bit with a demo Homeseer license to test whether the stick and module worked (setup was really easy), I quickly switched over to my ‘bits and bytes view’..
Here’s a log of the Aeon-Labs stick initializing:

The yellow text is the command that get’s transmitted from the PC to the controller. This article will focus just on the sending command (my first starting point with python and z-wave)
So let’s have a look at the basics, these are the 5 bytes that get send to the controller: #01#03#00#02#FE
Let’s translate these bytes to bits (a lot of people still seem to have trouble to distinct between the two of them):

01 = 0000 0001
03 = 0000 0011
00 = 0000 0000
02 = 0000 0010
FE = 1111 1110

From some z-wave documentation publicly available, I figured out that the checksum is the last byte of the command. In most documents they referred to the checksum as a CRC checksum, I actually think it’s an LRC (Longitudinal Redundancy Check). A LRC is computed by XOR all the byte values of the packet together. XOR stands for a bitwise eXclusive OR. A bitwise exclusive or takes two bit patterns of equal length and performs the logical XOR operation on each pair of corresponding bits. The result in each position is 1 if the two bits are different, and 0 if they are the same. For example:

    0101
XOR 0011
  = 0110

So how does our calculation look at bit level? (remember that we skip the first byte):

00000011 (03) XOR 00000000 (00) = 00000011 (03) (Nothing happens on this operation)
00000011 (03) XOR 00000010 (02) = 00000001 (01) (See how one + one is 0 here?)

So the outcome is 01.. hmm, not quite the LRC value we’d expected. We expected ‘FE’ (last byte in our command). This is because the LRC calculation z-wave uses starts with a starter value, which is “FF” or 1111 1111. So let’s try our calculation again, now with three steps:

11111111 (FF) XOR 00000011 (03) = 11111100 (FC) (Note the last two bits as a result of our XOR operation)
11111100 (FC) XOR 00000000 (00) = 11111100 (FC) (Nothing happens on this operation)
11111100 (FC) XOR 00000010 (02) = 11111110 (FE) (Aha! There’s our value!)

So, there we go.. through some calculations we figured out the checksum algorithm that z-wave uses. This is an important first step in understanding the protocol.
Now for the python part, here’s the code I used to test the checksum:

def generateChecksum(message):
    lrc = 0xFF
    for b in message:
        lrc ^= ord(b)
    message += chr(lrc)
    return message

testmessage = "\x03\x00\x02"
generateChecksum(testmessage)

And this is me, testing the code :-)

Here’s the schematic I used (all at 5V, USB power):

Using this schematic I doubled the range of my IR LED, the power drawn in the circuit is now 37mA. My former circuit, without using a NPN transistor drew 20mA (JeeNode max per digital pin). So that’s almost twice the power.
You could increase this even further using smaller valued resistors, but that would push the boundaries of the LED and transistor. I didn’t need any bigger range anyway as I use IR emitter cables attached to my devices.
Now that I’m satisfied with the hardware part of sending I can start looking at the software side!

p.s: here’s a picture of the box right now.. cables anyone?

The main ingredients to get this going are:

• Hot glue (love that stuff)
• Solder
• Some wires
• A Jeelabs carrier board with case
• A drill
• A lot of patience…

I started out drilling a hole for the power supply. I used an USB cable to power the Jeenode (I cut the unused wires). USB is on a lot of devices nowadays (media boxes, media tanks, sat receivers you name it) so this is an ideal power source for my IR box.

Here is the hole in place (one part of the box is shown):

And here is the result of the closed box:

The next step I took was to give the IR receiver a nice position, I choose the opposite of the power connector. I did this because I want the power connector, and other connectors out of sight.
Once again I drilled a hole, inside the box I had to make a little piece of plastic tube to lift the IR sensor (I soldered it to a little hobby print board)

Here’s a picture of the plastic tube, and the IR sensor soldered on the hobby print board:

And here is it glued to the box (I am a sloppy solderer, but hey it’s inside a box anyway :-) )

And this is how it looks on the outside:

Next up was wiring the cables the same way as on the breadboard, this was more work then I expected it to be. Took me quite a while to get everything wired up.
Here’s the result of the wiring inside the box:

And this is how it looks from the outside:

That’s it! The receiver has been put inside the box, I need some more time to fit the sender inside the box. I have some different idea’s for that instead of drilling holes.
This step in the project required quite some different skills (drilling, glue’ing, soldering etc)