[RELEASE] Inovelli VZM36 Fan/Light Canopy Community Driver

[bertabcd1234]

Supported Devices

• Inovelli Blue Series Zigbee Fan/Light Canopy Module, model VZM36

For code to install, see How to Obtain, below, or look at the GitHub repo (but please read the information first!): Hubitat/drivers/Inovelli/vzm36-fan-light-module.groovy at master · RMoRobert/Hubitat · GitHub

Not the Official (Inovelli) Driver!

First, it should be noted that Inovelli offers their own Hubitat drivers for all of their products, including this one. Those can be found in HPM, linked to from their website, or at their GitHub repo: Hubitat/Drivers/inovelli-fan-light-canopy-module-blue-series-vzm36.src at master · InovelliUSA/Hubitat · GitHub. If you want more or less official support from the manufacturer for their driver, that may be the one for you instead.

TLDR: This is not the Inovelli driver.

As of my writing, there is no built-in Hubitat driver for this device. This is my attempt at offering something that I believe would resemble such a driver if it existed (see below for more about why).

Why Another Driver?

Besides preferring to write my own drivers in general, I wanted a driver that behaved in a bit more conventional Hubitat-esque manner, including:

• using the built-in component drivers from Hubitat (no need to add custom child drivers)
• offering typical Hubitat logging preferences for debug and descriptionText (info) logging that align with conventional logging output and other behavior for Hubitat drivers
• smaller, easily maintanable codebase targeted for this particular device

How to Obtain

This driver can be found on my GitHub;

RMoRobert/Hubitat/blob/master/drivers/Inovelli/vzm36-fan-light-module.groovy

Or use the "raw" URL for the Import dialog: https://raw.githubusercontent.com/RMoRobert/Hubitat/master/drivers/Inovelli/vzm36-fan-light-module.groovy

This driver is not available in HPM. This is intentional; I am hesitant to do so to reduce confusion with Inovelli's own driver.

More Information

This is a from-the-ground-up driver for the Inovelli VZM36. It is not based on any existing driver.

Differences from the "official" Inovelli driver that I am aware of, besides the above, include:

• all preferences ("parameters" or manufacturer-specific attributes) are located in the parent device, as the child devices are standard Hubitat component devices
• child devices are created as "regular" child devices, not "component" devices, so they can be more easily modified (and removed, though if you keep using this driver they'll come back eventually) if needed -- requires some care when switching; see second post for more details
• events/attributes closely align with Hubitat conventions, minimizing the use of custom commands and attributes
• currently no support for Zigbee binding in this driver, though I am open to adding this in the future once I figure out what users' expectations may be (presumably similar to how Inovelli does it, which I don't know but assume is a function of their driver); I do not believe use if this driver would interfere with any already configured

Discussion

For questions or comments on this driver, I suggest asking here (or creating a new topic if you prefer and including a link to this one for visibility).

For issues with the VZM36 itself, I suggest posting in a separate topic here or on the Inovelli community forums.

Enjoy!

[bertabcd1234]

Switching to This Driver

As mentioned above, switching to this driver requires some extra work if you are currently using Inovelli's driver (this is because their child devices are created as "component" children that prevent modification or deletion).

To switch:

1. If you are current using the fan or light child devices from the Inovelli driver in any apps (automations), remove them from those apps first. You can either remember to add them back later or create a temporary virtual device to hold their places in the meantime if needed.

2. Switch to the "Device" driver on the parent device, and run the "Delete All Child Devices" command. (While you're here, it wouldn't hurt to run "Delete All Current States," "Delete All Scheduled Jobs," and "Delete All States" just to clean things up, but this isn't strictly necessary.)

3. Switch the driver to this one: "Inovelli VZM36 Fan/Light Canopy Module".

4. Run the "Configure" command after switching drivers.

5. If needed, add the new fan and light child devices back into the apps from Step 1.

[kkossev]

I have bookmarked this thread as an excellent example for anyone who wants to learn how to write a custom driver for the Hubitat platform!

[jbwrd3]

Hi, question when I installed the drivers for the canopy from Inovelli there where 3 drivers I had to install does this driver replace one of the 3 or does it replace all 3?

[kkossev]

Robert is the best person to answer this question. Unfortunately, the Inovelly devices are still not available in Europe...

[bertabcd1234]

@jbwrd3

does this driver replace one of the 3 or does it replace all 3?

This driver is for the parent device. The fan and the light components use the built-in Hubitat drivers.

[jbwrd3]

Thank you, so would it be better to delete the 3 drivers I have already installed Canopy, Fan and Light and reinstall this driver? Sorry just want to be clear before I proceed. This is a fresh install yesterday just setting the devices up.

[bertabcd1234]

That is up to you. You might find it less confusing to remove them first since then there is no chance of the device using them if you haven't paired it yet (or removed it and are re-pairing), otherwise, keep mind that you can't delete a driver you're currently using. Those are the only reasons that might matter that I can think of.

[jbwrd3]

Ok i did pair it and have the fan back together so to avoided taking the fan apart to use the pairing button on the canopy I guess following the steps above is my option and just replacing the canopy driver is my best option.

[vitaliy_kh]

@bertabcd1234 Thank you for the excellent driver for the Inovelli VZM36 Canopy Fan/Light Zigbee controller. Just got 2 of them and setting them up om a desk. (They will be a replacement for Sonoff iFan controllers. They works very well but now need a Dimmer for the Lights). Everything looks very good, both devices are working just fine but there are few errors in the Device Logs (hopefully they are benign but just let you know):

[bertabcd1234]

Thanks for the report! I wish the error message had a line number, but I guess this kind doesn't. I've uploaded some changes to the driver that may help, based on the clues I do have; and I added some commented-out trace logging in configure() that may help figure out the culprit if not.

[vitaliy_kh]

@bertabcd1234

I've uploaded some changes to the driver that may help

Update driver to the latest v1.0.4 Unfortunately error is still reported but could be better descriptive:

[bertabcd1234]

Forgot to copy both of the changes I made into the new upload. Oops.

This should be fixed now. I'm not entirely sure why it's happening (I couldn't get it to in my testing), but this should fix it based on the line number and what it says is happening. Thanks!

[vitaliy_kh]

@bertabcd1234

This should be fixed now.

Yes, error is gone. Thank you.
However I found one problem (it could be device itself or driver).
Default On Level for Light and Fan goes to 100% when turned On regardless of what is it set to:

I can fix this by adding extra rules but it will be nice if this will work as expected/should.

[bertabcd1234]

I don't use those settings myself, but as far as I can tell, they are being implemented in accordance with the specifications Inovelli has documented. Here is the relevant code for the fan endpoint (endpoint 2), but it's basically the same for the light other than that:

   14:  [
          desc: "Fan: default speed when turned on", type: "enum", default: 255, dataType: DataType.UINT8, options:
          [[1: "1%"],[25:"10%"],[50:"20%"],[76:"30%"],[102:"40%"],[127:"50%"],[152:"60%"],[178:"70%"],
          [203:"80%"],[229:"90%"],[254:"100%"],[255:"Previous speed [DEFAULT]"]]
       ],

The attribute number (14) and size/type (UNIT8) both appear in line with this to me as well as the Zigbee Herdsman converter I took a quick look at to compare (Inovelli's documentation has not always been accurate with these devices, unfortunately).

It could be related to the recent change, or it could be an existing issue with the driver or device that I have not notice (I did test most of the "parameters" that I could at one point). If you can enable debug logging and see if there are any clues there when saving (which should itself run a configure()), that would probably be the most helpful.

[vitaliy_kh]

@bertabcd1234

If you can enable debug logging and see if there are any clues there when saving (which should itself run a configure()), that would probably be the most helpful.

Here is a log, part - 1 :

Summary

and part - 2:

Summary

and part - 3 :

Summary

I looks like a parameter 14 is/was set correctly:

So, must be a device problem. Yes, no?

[bertabcd1234]

@vitaliy_kh

So, must be a device problem. Yes, no?

I'm going to doubt it or someone would have noticed during testing, if not by now. But anything is possible...

But most importantly for now, I don't know what in my driver could be (not) doing this and won't have time to dig into it for a while. If you are interested, they do have their own drivers for these devices, though I personally find them a bit awkward to use and wrote my own so they conform more to Hubitat conventions. If that is why you chose my driver, I am happy you also saw something in them. However, some workaround or other driver may be best if you need this at the moment. Good luck!

[vitaliy_kh]

@bertabcd1234

I'm going to doubt it or someone would have noticed during testing, if not by now. But anything is possible...

But most importantly for now, I don't know what in my driver could be (not) doing this and won't have time to dig into it for a while.

I did not try Inovelli Drivers and simply started fresh with yours.
I found some unusual driver behavior. This is applicable to the Light and Fan settings.
If Parameter-258 is set to Dimmer/Speed and On/Off settings for the Parameter-14 is ignored, Light and Fan goes to 100% when turned On.
But when Parameter-258 is set On/Off Only suddenly everything started to work as expected (surprise).
Is Parameter-258 setting reversed?
Also Parameter-23 (quick start duration) better to be disabled. Otherwise at least Light briefly goes to 100%.
Bottom line:
After tweaking all settings (some of them are not logical) I got everything working as expected.

PS.
Now just in case I will be willing to try Inovelli Drivers (to see if my observations are related to the driver(s) or the device itself) but I don't see an easy way how to replace drivers without braking many related rules (thanks to these my "lovely" child devices).

[bertabcd1234]

Yes, it looks like parameter 258 is backwards. Thanks for finding that! That also looks like it would explain your problem (since no level would really work).

@vitaliy_kh

Also Parameter-23 (quick start duration) better to be disabled. Otherwise at least Light briefly goes to 100%.

If your lights don't benefit from that behavior, yes -- that is what this option is intended to do (e.g., for lights that won't turn on if dimmed to a low level from off, even if they would be on at that level when dimming down from a higher level). Actually it's used in combination with the option to enable/disable this feature entirely, but if enabled, that is the level it uses. I would say to look at their documentation for more, and you can, but I don't think all the attribute ("parameter") numbers are correct -- one of the thing that made writing this driver so difficult. The descriptions probably are, though: Blue Series Fan/Light Canopy Module • Parameters | Inovelli Help Center

[vitaliy_kh]

@bertabcd1234

Yes, it looks like parameter 258 is backwards.

I am OK with this "as is" but if you are going to fix this please let me know when the update is ready.

@bertabcd1234

If your lights don't benefit from that behavior

Well, Thank you for the info on the lights behavior. In my case nether Lights nor Fans benefit from these options if enabled. So, that things are disabled.