Lutron HomeWorks QS Support

As of the OpenHAB 2.4 release, the Lutron binding should now work with HomeWorks QS systems, at least to some extent. I am looking for help from people who can test it out and provide feedback so that we can work toward full HWQS support. I do not have access to a HomeWorks QS system myself.

Here is the way things stand today:

Switches, dimmers, fan controllers, switch and relay modules, CCI and CCO modules, seeTouch and Tabletop seeTouch keypads, Pico keypads, VCRX, shades, and motorized drapes should all work properly (at least in theory). If they don’t, I would appreciate details on exactly what problems users encounter.

HWQS Keypad models which are not also supported on RadioRA 2 will not (yet) be explicitly supported by the binding. However, it should be possible to support most or all keypads by simply using the keypad or ttkeypad things and selecting model “Generic”, or by using the virtualkeypad thing (which supports up to 200 buttons/LEDs).

Auto-discovery may work only partially, or may not work at all. This needs to be tested. It would also help to see examples of the XML configuration file (DbXmlInfo.xml) from the HWQS processor. Auto-discovery relies on this file.

Timeclock support needs testing. The current support was aimed at RA2 systems, and may need some tweaks for HWQS.

Many HWQS features not also supported by RadioRA 2 systems still need to be implemented. These include:
• Switch/dimmer device actions, including double-tap and hold.
• System variables
• Shade groups
• Double-tap and hold actions on keypad buttons.
• Flash and rapid-flash settings on keypad button LEDs.
Feedback regarding how to prioritize these, and any other missing features, would be helpful.

Finally, support for Lutron venetian blinds and horizontal sheer blinds is not available yet, but is coming soon. If anyone has Lutron blinds in their RadioRA 2, HomeWorks QS, or Caseta system (if Caseta supports blinds), and is willing to test the new blind thing, please let me know! You would need to be running either 2.4, or a 2.5 snapshot or milestone release.

Many thanks for this.

Autodiscovery unfortunately doesn’t work. The XML is here and my openhab log is here

The bridge nevertheless install and works fine. Dimmers work perfectly. But a seetouch keypad won’t add, giving a “UNINITIALIZED - BRIDGE_UNINITIALIZED” error in paperUI.

To help with the communications, when I press the top button, selecting a scene on the keypad, the binding picks up:


and the LED for that scene lights up:



Thanks Dan. I think I see the problem with the seeTouch keypads. From looking at your xml file, I think your keypads are seeTouch QS International keypads, which have two key columns, rather than the regular seeTouch keypads, which have only one key column. These models aren’t supported by the current seeTouch keypad handler because their button numbering is different, but support can probably be added relatively easily. In the meantime, you might be able to get away with using the tabletop keypad handler to communicate with these keypads. Try setting it as a ttkeypad model T10-RL. Then, for your device 14 for example, it looks like you would need to link items to buttons 2,4,6,7,8,9,10, and LEDs 2,4,6,7,8,9,10. Make sure you link an item to at least one valid keypad LED, or the keypad will not come online properly (because there is no LED number 1 as there would be on a real T10-RL). See the Lutron Integration Protocol Guide ( pp 107-109 and 110-112 for more info on key/LED numbering.

Thanks for the sample XML file! What is the URL used to retrieve it from the device? On a RA2 system it is: http://MainRepeaterIPAddress/DbXmlInfo.xml. Is it the same on HWQS?

Just a quick update: I have created a new keypad handler that should work with the seeTouch QS International keypads on HomeWorks QS systems. Once all of the 2.5 build system change issues have been worked out and we have a new milestone release of 2.5, I will make it available for testing under 2.5.

Until then, I’d appreciate it if anyone could tell me how to access the DbXmlInfo.xml on a HomeWorks QS processor via HTTP, so that I can try to get auto-discovery working for HWQS.

Sorry to take so long to rely!

The url is http://lutron/DbXmlInfo.xml


Thanks Dan. That is the URL that discovery is trying to use already. Does it work without supplying any authentication information or having already authenticated with your browser? For example, will a curl command like the following on a Linux host spit out the XML file?

curl -i http://192.168.xx.xx/DbXmlInfo.xml

The reason I ask is that Lutron’s notes on obtaining the XML file from an HWQS processor say you should log in and then click on a link, although I know that isn’t really necessary on a RadioRA 2 system.

yes - curl works just fine.

if you go to 192.168.x.x you get a login screen (username and password both “lutron”), but it’s completely unnecessary as the xml file is accessible if you access it directly. Lutron’s security model is… interesting…

Ok. Yeah, the RadioRA 2 system behaves exactly the same way. They probably share a lot of code internally. For better or worse.

So I guess it is something about the HWQS DbXmlInfo.xml file itself that the discovery code doesn’t like. That’s unfortunate, because that code is a pain to debug. :slight_smile: I’ll poke at it a bit and see what I can find.

Ouch. Let me know if there’s anything I can do to help with the debugging.

Good news! Support for International seeTouch keypads (PR #5781) and for the QSE-IO interface (PR #5782) have been merged in to 2.5. This means they will be available in the 2.5.0.M2 milestone build whenever it becomes available.

Another PR containing some auto-discovery improvements for HomeWorks QS should be following soon.

I discovered that there is a problem with the embedded web server in older versions of the HomeWorks QS Processor firmware. In responses, it ends header lines with <LF><CR> and ends the header with <LF><CR><LF> rather than ending header lines with <CR><LF> and ending the header with <CR><LF><CR><LF> as required by RFC2616 & RFC7230. This is what has been preventing auto-discovery from working properly with these devices, since the discovery service in the Lutron binding needs to retrieve the configuration XML file from the bridge device using HTTP. Some HTTP clients work with these incorrect header line endings, but many do not.

This bug may exist in older versions of RadioRA 2 as well. I know it does not exist in newer versions of RadioRA 2, and I suspect it does not exist in newer versions of HomeWorks QS either.

In order to work around this problem (as well as to make debugging easier), I’ve added a new option to the ipbridge thing that will allow it to read the discovery data from a local file. This is one of the changes that will be in the upcoming auto-discovery PR.

Many thanks to Dan for answering a lot of questions, testing several versions of the code, and even giving me access to his processor so that I could get these updates working!

1 Like

Um, no - when you spend your time working to make an old version of an unusual system work perfectly for me, it’s me who should be thanking you!

One quick thought - is it possible to detect the error and add a prompt in the logs to use the local xml file?

I believe the newer discovery code will return a different error in the case of a bad response than if it just fails to connect or can’t parse the XML, so… maybe? I’ll take a look and see if I can do that.

1 Like

I opened this github issue to track the HomeWorks discovery problem:

1 Like

Hi! I just found this amazing community and would love to help test and dev HWQS support!
I currently have a Homeworks QS deployment in my apartment, and here is the XML file: DbXmlInfo-Unformatted
Currently, autodiscovery doesn’t work, also with the “Content is not allowed in prolog” exception when parsing the XML file.

Hi Xinyang! Welcome to the openHAB community!

Thanks for posting your DbXmlInfo file! At this point, every example helps a lot as I try to add full support for HomeWorks QS in to the Lutron binding.

The good news for you is that all of the devices in your configuration should be supported under 2.5. At least if manually configured. New handlers for the International seeTouch keypads and the QSE-IO interface were just merged in to 2.5 a week ago. These are in the current nightly 2.5.0 development snapshot builds, and will be in the upcoming 2.5.0.M2 milestone build. I would be very interested to hear how they work for you.

Discovery is a known problem with older versions of the HomeWorks QS software, but probably not with newer versions. It looks like you are running version 5.0 of the HomeWorks QS software? That is a useful data point, too, since I’m trying to get a handle on which versions have the discovery problem.

In any case, I’m working on a discovery update now that should allow auto-discovery to work for you. I’ll let you know when it is available for testing.

Your configuration file is interesting in two ways. First, many of your output devices (i.e. dimmers) are set up to control DALI digitally addressable dimming ballasts. The discovery code would not previously have worked with those, but after seeing your config I’ve added DALI output support in to my dev branch. Second, your system has areas named with the simplified Chinese character set. I don’t know if that has been tested before. It should work, but I will try it out with the new discovery code and fix it if it doesn’t.

The Lutron binding, like all of openHAB, is written in Java. If you’re interested, you can find the current 2.5 development branch here.

Just a quick update: I tested the new discovery code with your configuration file this morning, and it worked fine.

Hooray! That is fantastic news! I guess UTF-8 does work (sometimes). :wink:

In case you have not seen it elsewhere, these HWQS-specific improvements made it in to 2.5.0.M2:

  • Support for HomeWorks QS International seeTouch keypads
  • Support for HomeWorks QS QSE-IO Interface
  • Support for GRAFIK Eye in RadioRA 2 and HomeWorks QS systems

Soon after the M2 build, another PR was merged that contains multiple discovery improvements. Among other things, it adds the ability to automatically discover more device types that are specific to HomeWorks QS. It also adds a feature for HomeWorks QS users who have been having problems with auto-discovery as described in issue 5841. It will allow you to get around this problem by downloading the DbXmlInfo.xml file to your openHAB server and pointing discovery at it using the discoveryFile bridge parameter. This is available now in the nightly builds, and will be in the next milestone build.

Ahhh this is great, I can’t wait to try it out, I have been out of the game for 8 months while my new digs is being built / wired / programmed.

Looking forward to beta testing this binding

I am a Lutron Dealer/Installer/Programmer and I can provide you with more xml files than I can count if you are interested?

Let me know.