[HOW-TO] Using the Z-Wave Association Tool in Hubitat

EricM_Inovelli · January 22, 2020, 7:08pm

The Z-Wave Association Tool is an App that was created to allow our customers to easily create device-to-device “associations” with Inovelli devices and other compatible Z-Wave devices. The tool requires special code to be present in the driver so it will only work with Inovelli devices. Anyone is free to add the code to other drivers though if they would like.

The purpose of a direct association is to have one z-wave device speak directly to another to create something like a “virtual 3-way” between two switches, or have a dimmer be able to directly dim up & down bulbs in real time. The communication is usually much faster than if it were to go through your hub and the hub is not required for the association to work after it is setup. For example, the hub could even be completely shut down and the 3-way or the communication with the bulbs would still work.

Code
The most up-to-date code for the app can be found here. It consists of 2 pieces of code that need to be installed in the “Apps Code” section of Hubitat. One is a parent app and one is a child.

Parent App

github.com

InovelliUSA/Hubitat/blob/master/Apps/z-waveat/zwave-association-tool.src/zwave-association-tool.groovy

definition(
    name: "Z-Wave Association Tool",
    namespace: "erocm123",
    author: "Eric Maycock",
    description: "Create direct associations from one Z-Wave device to another",
    category: "My Apps",
    iconUrl: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png",
    iconX2Url: "https://s3.amazonaws.com/smartapp-icons/Convenience/[email protected]",
    iconX3Url: "https://s3.amazonaws.com/smartapp-icons/Convenience/[email protected]")

preferences {
    page(name: "mainPage", title: "Associations", install: true, uninstall: true,submitOnChange: true) {
        section {
            app(name: "association", appName: "Z-Wave Association", namespace: "erocm123", title: "Create New Association", multiple: true)
            }
        section {
            paragraph "This tool allows you to create direct associations between multiple Z-Wave devices. In order for it to create the association, the source device handler needs to have support for this tool added to it. Some examples of handlers that have support are the Inovelli Plug handlers, Inovelli Dimmer & Switch handlers, and the Inovelli Door/Window Sensor handler. The destination does not need anything added to it's handler, but does need to be a Z-Wave device.\n\nFor more information on how this SmartApp works click the link below."
            href(name: "hrefNotRequired",
             title: "Z-Wave Association Tool on Github",
             required: false,

This file has been truncated. show original

Child App

github.com

InovelliUSA/Hubitat/blob/master/Apps/z-waveat/zwave-association.src/zwave-association.groovy

/**
 *  Z-Wave Association
 *  Author: Eric Maycock (erocm123)
 *  Date: 2020-04-16
 *
 *  Copyright 2019 Eric Maycock / Inovelli
 *
 *  Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
 *  in compliance with the License. You may obtain a copy of the License at:
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software distributed under the License is distributed
 *  on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License
 *  for the specific language governing permissions and limitations under the License.
 *
 *  2020-04-16: Adding option to reset association variables. Use this if you need to remove the source device from
 *              your network (to OTA update it) and add it back to the association later.
 *
 *  2019-10-10: Changing name of switch capability to switch / dimmer / bulb

This file has been truncated. show original

Terminology
Source Device:

This is typically going to be the device that does not have the “load” (or light) attached to it. It is the device that you want to use to control the other device. Generally an Inovelli Switch or Dimmer.

Destination Device:

This is the device that you want to be controlled. If it is in a virtual 3-way, it is the switch or dimmer that has a “load” (light) attached to it. Technically, you can put multiple devices in this group which may be the case if you are trying to control multiple bulbs.

Group

An “association group” is a z-wave concept that lets you define a “group” of devices that are controlled from a “master” device. The groups can have different capabilities, but our devices use these particular groups:

Group 2: Used to send ON / OFF commands to the devices in this group.
Group 4: Used to DIM UP / DIM DOWN devices in this group.

So, when you create an association from a switch to another, you simply need to create an association for group 2. When you create an association for a dimmer device, you configure an association for BOTH groups 2 & 4.

Now that this is defined, below is a simple step by step on how to create an association for ON / OFF.

First, we open the Z-Wave Association Tool app from the “Apps” section of your Hubitat Hub.

Next, click on “Create New Association”

Then, click the “capability” drop down and choose “Switch / Dimmer / Bulb”. Next, select the source device. Use the terminology above to decide which device you want to be the source. It is the device that you want to use to control the other(s).

For the destination device, choose “Switch / Dimmer / Bulb” and select your device(s) as needed. Also, use the terminology to determine which devices to choose here. They are typically going to be the devices that you "want to control.

Lastly, select the group that you want to use in this association. Group 2 to control ON / OFF or Group 4 to control DIM UP / DIM DOWN.

Note: When using a dimmer you are likely going to want to control BOTH ON / OFF & DIMMING. You will need to go through the process shown above again and create a second association for the other group.

In the end it would look something like this:

That should be it. After a few seconds the app will configure the associations on the “Source” device and you should be able to start enjoying the benefit of direct Z-Wave associations!

If you are interested in adding the association tool code into your own device handler / driver, check out this post:

EricM_Inovelli · January 22, 2020, 7:11pm

Pelted · February 16, 2020, 4:32pm

After several attempts to get this to work (turns out of you rename the association during the setup processes it doesn’t work), my bulb turns on, flashes off/on, then stays on. I’ve tried a dozen combinations of things but every time we tap the switch on the light flashes before staying on. This “smart” bulb and switch combination is just not worth the hassle.

MRobi · February 16, 2020, 5:45pm

It should be extremely simple. Do you by chance have a rule in rule machine setup that the 2 could be conflicting? OR, are you using the switch to physically cut power to the bulbs as well as using zwave association? That flash you’re seeing could be the bulbs going into inclusion mode.

Here’s my association. It’s really as simple as that.

Pelted · February 18, 2020, 8:15pm

Nope, no other rule. This one association if the only “smart” thing of this type. Mine looks the same but with only one bulb. I have the switch control disabled to prevent the load from getting turned off to the bulb. I’ve excluded and included both devices a couple of times. Mainly in figuring out the renaming bug in the tool.

As it stands, tap the dimmer on and the light turns right on then flashes off and back on before staying on.

MRobi · February 19, 2020, 3:21pm

When the bulbs are in “inclusion” mode, that’s the exact behavior they do. Come on, flash once, the stay on. They flash again when they pair.

justindthomas · February 19, 2020, 9:03pm

So I got this to work roughly following these directions. But it doesn’t look the same in my interface - I had to click “Add User App” to add the custom Z-wave Association app (after creating the two files in the “Apps Code” section).

And I did that twice - once for on/off and once for up/down. That all seemed to work fine and the dimmer works as I’d expect. But now I can’t find those created associations in the interface anywhere. In the Apps section, it just shows the built-in apps, I don’t see the new Innovelli app at all.

That worries me a little - any advice on where to track these down?

justindthomas · February 19, 2020, 9:09pm

Okay. Two things I just discovered.

I can get the Z-Wave Association Tool to show up if I just add it without going the extra step of actually creating an association. But it doesn’t show my previously created associations.
I can find the previously created associations on the source dimmer and get to them there.

But now how do I link those to the master app in the “Apps” section? Do I need to delete them and recreate them? Will that cause any problems?

MRobi · February 19, 2020, 11:46pm

Yes, after you add the app code for the parent and child app, you go to the apps page, select add user app and choose the z-wave association tool from the list. You should only have to do this once. If you’re clicking on “add user app” every time you want to access the zwave association tool, you’re installing multiple instances of the app.

Once it’s installed, you can access the association tool from your apps list. The same spot you’d access Rule Machine, HSM, Simple Lighting, etc… Also any created associations should be shown underneath it as child apps.

justindthomas · February 19, 2020, 11:49pm

Okay, thanks. I had to go through and delete the associations I created (by navigating to them from the associated Device) before just adding the App by itself. Once I re-added those (after adding the App), they now show up in the list as I’d expect.

It would be good if the code checked to see if the App is present when creating a new association and then added the App automatically before adding the association to prevent this weirdness.

Either that or just disable the ability to add an association from the App before the App itself is enabled.

EricM_Inovelli · February 21, 2020, 10:23pm

That is a good idea, but I don’t think it is possible to check the existence of another SmartApp. Glad you got it figured out though!

Just to emphasize for others:

Once you install the SmartApp you don’t need to install it again for other devices. You can just go back into the Association Tool app and add a new association.

justindthomas · February 21, 2020, 10:37pm

And also, don’t set an Association until after you’ve added just the App. That was the core of my confusion - I used “Add User App” and then immediately created an Association from the interface I was provided. I needed to just add the App first for things to work correctly.

adamkempenich · February 21, 2020, 10:37pm

I’m having one heck of a time getting associations set on Hubitat. I was originally just trying to use the association tool to link an LZW31-SN with one of my RGBGenie controllers. The logs for the association tool all seemed fine — no errors or anything — but the association never fired (I was using group 2, on/off)

When this failed, I tried to connect an LZW31-SN to another LZW31-SN via association: that isn’t working, either. No errors get logged, and my Z-Wave mesh is stable for everything else.

Any thoughts? I’m on hub software 2.1.9.

Edit: this has magically started working. Not sure why, but I’m not mad!

gbenrus25 · April 2, 2020, 10:15pm

@EricM_Inovelli I’m seeing some interesting association behaviour. I had thought the association commands (e.g. basicSet) only got sent when a physical push of the button/switch occurred. However, using this code, it appears the commands are also sent out when a device is virtually turned on/off e.g. through Alexa or through the Hubitat app. Is that normal? I don’t see the app code adding any features like that.

When I had GE switches, I had associated 2 of them in the past (similar to a mirror function) so they were always on at the same time or off at the same time. I tried that now and I got into an recursive loop because they kept trying to turn each other on endlessly. As such, it doesn’t seem like I can associate each of them together.

EricM_Inovelli · April 2, 2020, 10:42pm

What hub are you using and which device? (LZW30-SN)?

If you are using the ON / OFF switch you can set parameter 4 to 11 on one or both of them. If you want to keep them in sync when you adjust them via your z-wave hub, then just configure parameter 4 on one of them. Then always send commands to the other one and it will mirror its commands to the other switch.

If that isn’t important to you, just set parameter 4 on both of them.

gbenrus25 · April 2, 2020, 11:08pm

I’m using Hubitat and LZW30-SN and LZW31-SN i.e. a dimmer and a switch. When either is on or off, I’d like the other to also be on or off.

I didn’t realize your association behavior had so many options for when to send the commands. I mean, I had seen them but never looked into them. Very impressive though. I thought association was pretty fixed and was always only local. What’s timer and 3-way? Does that imply a GE add-on switch can trigger the association command?

Thanks

gbenrus25 · April 2, 2020, 11:13pm

Also, I’m assuming that the reason why it goes into an infinite loop is that the z-wave hub option actually means a zwave event i.e. if 1 switch sends a basicSet via association to another (without the zwave hub being involved at all), the 2nd switch receives that and assumes it came from a “zwave hub” (zwave event) and so sends a command to all its associated members (which includes the 1st switch). Then the merry go round begins even without a zwave hub being involved!

gbenrus25 · April 2, 2020, 11:16pm

Hmmm, I’m not seeing a similar option on the dimmer. Does that not include a parameter for “association behaviour”? If it doesn’t, what’s the default behaviour please? All of them include zwave hub?

EricM_Inovelli · April 3, 2020, 3:49am

Yep, you are correct on the 3-way. It is when you use an aux switch to turn on / off the device whether it will send the commands to the associated devices. Timer is the “Auto Off” config parameter which turns the device off after x seconds. If the timer is enabled, when the device turns off after the timer expires it will turn off associated devices as well.

Oh, and you are also correct on your assumptions of the command loop.

The dimmer also has this parameter but it is number 12. You can enable it by changing the following in the code. To be honest, I had disabled it because I hadn’t fully tested it but my reports are that it does work.

def getParameterNumbers(){
return [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,17,18,19,20,21,22]
}

anthonyc · April 9, 2020, 4:59pm

I would like to use the association and associate a Motion Sensor to a Switch. The motion sensor is a Zooz ZSE18 and the switch is an Inovelli On/Off LZW30 switch. The thread started with a comment that this only works with Inovelli devices but we can add code to other drivers. Could you point me to the code I would need to add to the Zooz driver? Thank you!