A Proliphix thermostat driver for NetStreams’ HVAC interface

Technorati Tags: NetStreams,DigiLinX,Proliphix,HVAC,Home Automation,Lua

The DigiLinX system has a nice looking interface that allows users to monitor and control the current status of their HVAC system. The screen’s appearance and layout make it one of the more compelling features of the Digi system. Unfortunately, it was built to support the AprilAire line of automated thermostats. I’ll resist my compulsion to lambaste the AprilAire system, but as a whole it

• costs a heckuva lot to put together because of the cost of the individual parts, and the number of devices required to make it work
• only offers setback programming if you purchase a “system controller” which can cost consumers ~$850. This is amazing – several thousand dollars into an install you may find that you can’t turn the A/C off when you go to work every day unless you do it manually at each thermostat.
• has been reported that it occasionally stops responding to third party system commands, including NetStreams, Crestron, and AMX
• offers no remote administration or interface without the part mentioned above

Anyway, it’s safe to say that I’m not a fan. At all. I suppose it could be that pile of thermostats, controllers, and temp sensors that I have sitting in the corner of my office. I ripped it out of my home after the above points came to light when I began testing the Digi integration. A nice lesson that only cost me ~$1500. Yes, I’m bitter.

Enter Proliphix

But good things come to those who hate overpriced crap! I discovered the Proliphix line of thermostats when looking for a replacement for my AprilAire system. Proliphix thermostats are great, and include the following features:

• They are IP based, like DigiLinX, and require no central brain to operate.
• They have an embedded web server that enables remote monitoring, setback scheduling, and the ability to set vacation cooling schedules
• They have a fully documented open API that is based upon the open standard of Http
• They offer advanced features found in top quality systems, such as humidity monitoring, remote sensors, and alarms
• They have a free service that allows you to monitor all your thermostats while away from home. The thermostats report to a central server stored at Proliphix, and you can pull up a dashboard in a web browser from anywhere.
• They are competitively priced for the feature set that they provide

More good news for those of you who have wired for an AprilAire system – they use the same cabling approach. A Cat-5 run back to a head end connects the thermostats to a mini hub which provides network access and Power Over Ethernet to the devices themselves.

So once I decided on Proliphix, I went to work on writing a driver to tie the HVAC interface found in DigiLinX to the API made available by Proliphix. The API allows a programmer to retrieve and configure many of the settings and statuses related to the HVAC system. By sending simple HTTP POSTs to a device, one can change the setback temperature, query for current zone temps (both local and remote), determine if the fan is running, and more. The API is secured with a username and password configured when you first install the thermostat, which you pass along with your commands using the Basic Authentication scheme. I adopted an implementation of HTTP from LuaSocket, which I’ve posted on my projects page. This library allowed me to focus on the basics of the API in my driver implementation.

Driver Design

I won’t get into the details of how the driver works in this post, but I wanted to point out one design decision that I made. Since a home usually has more than one thermostat in it, I broke the driver into two files. The first, pro.lua, is simply the setup and scheduler for the implementation. It is responsible for binding to the thermostats during the initial load, and then scheduling and executing the status updates.

The second part of the driver is a module that marries the Proliphix API and the DigiLinX system. ProliphixAdapter.lua is self-contained, and is an implementation wrapper for a single thermostat. The host driver (pro.lua) actually creates one adapter for each thermostat in the system. This gives good code isolation, and makes it easier to determine which thermostat is generating trace messages.

I plan to write more posts in the future explaining how the driver works, especially if I see questions from the community on it.

Caveats and Configuration

Since this driver was not built by NetStreams, you must configure it manually by editing the text of the driver file. In pro.lua you will see  the following code:

thermostatIPlist = {“10.15.15.55″,”10.15.15.56″}
userName=”testuser”
password=p@ssword1

Replace the list of IP addresses with the IP addresses of the thermostats that are installed in the home. You should ensure that the thermostats are on the same subnet as the DigiLinX system, and that a patch cable connects the SwitchLinX to the POE hub that the thermostats are wired to. You will also want to replace the username and password values with the admin username and password for your Proliphix thermostats. Note that all thermostats must have the same username and password configured. That’s is for pro.lua, unless you want to flip debugging categories on and off.

ProliphixAdapter.lua doesn’t require any configuration if you have Proliphix thermostats installed. However, the driver also supports using the asp emulators I developed during the authoring of this driver. If you would like to use these instead, drop them in the root of the web server for the development machine that will emulate the Proliphix thermostat, and change the doDebug in proliphixadapter.lua variable from false to true. Note! The drivers ship in Debug mode!

Read the comments at the top of both files for more information on driver assumptions and caveats.

Lastly, here is a list of all the files that will need to be installed on the ControlLinX that hosts the HVAC interface. You’ll need to use the Dealer Setup “Load Files ” feature, as explained in my Sample HTTP Driver posting to download them all. As I mentioned, the actual driver to use as the Driver File for the ControlLinX is pro.lua.

• http.lua
• httpPrivate.lua
• url.lua
• ProliphixAdapter.lua
• pro.lua

Don’t Skip This Section!

I hope everyone who downloads this driver reads this first: I’m releasing this driver before I get it fully working. Yes, that’s right – the driver only works a little. Occasionally. My decision to release this was based upon wanting to help people understand the HVAC interface, and to offer more code samples to the DigiLinX development community. This driver should be treated as an alpha build, and should not be installed at a customer location. If you want to play with it without installing a Proliphix ’stat, you can run it against the Proliphix emulator I wrote in classic ASP.

Also, these drivers contain a ton of debugging messages. The sheer volume of messages introduced into your network may have some adverse effect on your Digi system. When I feel that the drivers are stable enough, I will maintain two versions of each of these files – one that has debugging stubs left in, and another that doesn’t.

This driver is the result of a lot of work, so I’d really appreciate any feedback, bug reports, or overall comments from those who use it.

More information on where to obtain the drivers can be found on my projects page.