[RELEASE] Leviton ZW4SF Driver

⚙️ Custom Apps and Drivers
#1

Disclaimer: I've never written a line of Groovy in my life until this evening. Spent a few hours hacking away on a Decora Dimmer driver shared a few years back by Jason Xia that looked like it was maybe ported from SmartThings. Did a bit of reading, took a stab at cleaning that up and making a proper "fan" driver for this. Unfortunately the enum that comes with FanControl capability has a few entries in it that don't match up with this 4-speed controller's options.

Anyway, hope it helps someone, or (more likely) that someone comes along and fixes my bugs. :smile:

https://github.com/ernie/hubitat/blob/main/drivers/leviton-zw4sf.groovy

2 Likes
Leviton Fan Controller needs SwitchLevel
Leviton 4 speed Fan Controller with Z-Wave speed issues - Am I using the wrong device?
Leviton ZW4SF pairs but doesn't respond
Custom Device Drivers (Wiki)
#2

Following up to say that I was delighted to discover that this driver finally has cured my fan switches of being perceived as lights by Alexa. So I can stop getting stuck in a wind tunnel when I ask her to turn on the lights. :joy:

2 Likes
#3

Added this driver to HPM, for folks who prefer this way of installing.

#4

Thanks for the driver! I see that you said Alexa recognizes this as a fan, but my Google Home still thinks it's a light. Is this fixable? Thanks!

#5

No idea. I don’t own any Google Home devices. The driver should be exposing itself as a fan controller, so I assume it should work if the Google device supports it? I did a quick search and found this, don’t know if it’s related: https://www.reddit.com/r/googlehome/comments/daim9k/cant_control_ceiling_fan_speed/

#6

Thanks! This fixed the mapping of the levels for me. The built-in Leviton Fan Controller driver wouldn't go to the max level even if I asked for "high". However, with both the built-in driver and with yours, Alexa says, "I'm sorry, something went wrong." after most commands. The first command actually works, but then I get this error. Then subsequent commands sometimes result in another error like the one I get when the internet is down, but it resolves in a minute or so. I'm not sure if this is due to Alexa's fan interface, the Hubitat skill, or the driver.

#7

I’ve found that Alexa is very sensitive to how you issue commands. I think I remember reading that it had to do with devices that implemented more than one interface.

In any case, when I say “Alexa, set the living room fan to off” I get the correct result, whereas “Alexa, turn off the living room fan” spouts that something went wrong (but works). My guess is that the first functions through Alexa’s “this is a fan” code path and the other functions through its “this is a switch” (but wait, this is ALSO a fan?! Something must be wrong!) code path.

1 Like
#8

Thanks for the driver, It works well.
Also Alexa works fine with, Turn the __Fan Off, Turn the __Fan to Medium, Turn the__Fan to High.

#9

Sorry for the bump on an old thread but I just wanted to say thanks to @erniemiller for this driver. Ceiling fans are of the utmost importance to me and something my former system (Insteon) did very well. This Leviton controller is about the only one I could find actually available so having a driver that gives access to all the speeds through Alexa is amazing.

#10

After looking at this further, I noticed a few issues with the driver. For me at least, I was unable to set most of the config options. For the record my device is on firmware 1.8. I could not change the indicator status or indicator level timeout for example. I couldn't set preset level either. I wanted to add some more customization to the driver anyway so I dove into the code. It seems those config parameters not setting was because the driver was not explicitly setting a size of 1 when it sent the configuration set commands. With that tiny change I am able out to set all of the settings as expected.

For completeness sake, I also changed it to properly set the "supportedFanModes" attribute exposed by the FanControl capability. I also implemented the cycleSpeed function for that command that cycles through similar to pulling the chain on a ceiling fan.

The biggest change I've made is the ability to customize how the 5 Hubitat speeds (low, med-low, med, med-high, and high) are mapped on to the only 4 of the controller. For my particular use case we use speed 3 out of 4 a lot, and the driver was calling that medium-high and I really didn't want to have to say medium-high to Alexa all the time. :slight_smile:

I've added a config option to choose between a few different ways of mapping the speeds...a couple of the options only use 3 of the 4 speeds. We are using that one for our fan since the controller's lowest speed is kinda worthless...so speed 2 is low, 3 is medium, and 4 is high. That also simplifies what we say to Alexa. The supportedFanModes are set properly based on your choice and the cycleSpeed also obeys the choice.

@erniemiller I sent you a pull request with these changes.

If anyone wants to try it straight away, you can find the code with my changes here:
https://raw.githubusercontent.com/vyrolan/ernie-hubitat/patch-1/drivers/leviton-zw4sf.groovy

Leviton 4 speed Fan Controller with Z-Wave speed issues - Am I using the wrong device?
#11

Thanks! I’ll have a look today. I haven’t touched the driver for ages, and it’s possible the underlying APIs have had changes. The preferences certainly used to stick.

#12

Hey @erniemiller and @Vyrolan... I just installed this fan controller today and am excited to use your code to add it to Hubitat. I am VERY new to Hubitat and installing code. I hate to ask what might be a stupid question, but how do I add a new device using your Groovy code? Any help you could provide would be greatly appreciated!!

#13

You need to install the driver (manually or via HPM*). Then you would pair your device as normal to add it to Hubitat. On its device details page, near the bottom there is a “Type” drop-down for the device which is basically what driver to use. So you’d pick the custom driver and save the device. Most people would say to run the “initialize” command after switching drivers by clicking its box near the top of the device details page.

https://docs2.hubitat.com/how-to/install-custom-drivers
This page shows some of the steps around installing and using a custom driver except it makes a virtual device and sets it type. In your case you want to pair the actual ZWave device and then set its type.

  • HPM stands for Hubitat Package Manager and makes finding, installing, and updating custom drivers and apps much easier. Google it and you will find the forum thread which has good instructions for getting it setup.
1 Like
#14

Great. Thanks man! Sorry for the noob question, but I just couldn't figure it out.

#15

We were ALL noobies at one time. Some people seem to forget that though.
Welcome to a VERY addictive hobby known as Hubitat!

Download the Hubitat app