node-zwave-js
node-zwave-js copied to clipboard
zwave-js
Fan Controller "hinting" for applications
Is your feature request related to a problem? Please describe.
A Z-Wave fan controller looks just like a light dimmer switch (Multilevel Command Class) but in an application the functionality is different. The UI representation might be different (fan icon vs. light icon), and a light may have variable brightness, but a fan has 3 or 4 speeds, so a UI will present the possible values differently. Ideally, the application can automatically determine if a device is a fan or dimmer without user intervention.
This is easy to solve with Z-Wave Plus devices. The Z-Wave Plus Device Type specification defines a Fan Switch type, which reports GENERIC_TYPE_SWITCH_MULTILEVEL and SPECIFIC_TYPE_FAN_SWITCH identifiers. The application can assign the device as a Fan based on the specific type.
This does not work for pre-Z-Wave plus fan controllers, which only appear as dimmers. In order to work around this, applications like HA apply workarounds that check the device IDs (product, mfg, type), and if the IDs match a known fan controller, it will represent it as a fan instead of a light. This is not too bad because there are a limited number of these devices.
For some reason the specification for Z-Wave Plus V2 Device Type has dropped the fan switch device type! Now there is only Multilevel Switch that includes both dimmers and fans. This means applications like HA cannot use the generic/specific types to determine if the most recent generation of fan controllers are fans or dimmer switches. There is some information provided by the Z-Wave Plus Info command class (not useful for pre-Plus), like Installer Icon Type and User Icon Type that do have fan information, but I'm not clear on how reliable that is. For a multi-channel device like the Inovelli LZW36, I don't think the user icon is set to a fan for that endpoint.
It is possible in HA to create a fan template out of the light entity, which works around the problem. Functioning as a fan "out of the box" though is a better experience. The template approach means every user needs to do it themself, again and again.
Describe the solution you'd like
I would like a way for zwave-js to communicate that a device (endpoint in fact) is a fan controller, not a light switch, whether this is determined via the device database or some other means. The benefit of adding this to zwave-js is that it can benefit all applications that use the library, instead of every application doing it on its own.
The easiest method might be to allow overriding the specific device type (per node and/or endpoint) with a device config setting. This would satisfy HA at least, as it uses the specific type to determine whether the device is a fan or not. Not sure if it is useful for other applications. Or, you could add a hint to the value itself (multilevel cc, level), telling the application that this particular value is for a fan, not light. Not sure this approach has any use outside of this particular use case.
This approach would also fix other devices. I know there is an iBlinds roller shutter that reports the wrong specific type, so in HA it too looks like a light instead of a roller shutter.
Describe alternatives you've considered
Instead of the library, the application could check the device IDs to determine if it should represent it as a fan instead. The downside is that all applications need to implement this themselves.
The application could check the Z-Wave Plus Info report. This does not work for pre-Plus devices. It's unknown if all Plus devices confirm to this icon usage.
Additional context
Here is the HA code that implements a workaround for OZW, where it checks the product IDs and if matched, will represent the Multilevel CC "Level" value as a fan, not dimmer. You can even see in the history that the recent edit was to detect a new Z-Wave Plus V2 fan controller. This would be a solution, but the HA devs prefer behavior like this to be upstream.
Here is an HA issue for the OZW Beta integration, which had never implemented the workaround. You can see the devs prefer these "workarounds" to be in the library.
Here is a thread in the Inovelli forums where their fan controller product was discussed, and the lack of support in HA due to this problem.
Do you have an affected device for which you could share your cache files?
@kpine great to see you here :-) This week I've created the device discovery for Home Assistant based on the data from Z-Wave JS and just like before it assumes the upstream specs are in order. So if a device doesn't report itself as Fan, it will not become one in HA.
We were talking about this a bit with the devs working on Z-Wave support for HA and one of the ideas is some sort of mapping/quirks definition file that could be easily updated to "override" the discovery scheme, basically a lot like what you've been working on in your branch for HA-ozw.
The downside of this is that these "quirks" will only apply to HA and not to others consuming Z-Wave-JS so maybe a more upstream approach would be better. Basically some definition (or maybe this should be in the device config files) where either a hint can be given to applications how to treat this device or completely override it.
The HA Zigbee devs have done a great job with this approach with a common quirks database utilized by zigpy Zigbee implementation:
https://github.com/zigpy/zha-device-handlers
I'll get a dump of the cache soon (the node is on my production network with ozwd, I need to get zwave-js setup for a dump). But basically:
- The product is the GE 12730 fan controller (not Z-Wave Plus).
- The Node Generic Type is "Multilevel Switch" (0x11).
- The Node Specific Type is "Multilevel Power Switch" (0x1).
- It supports Multilevel Switch CC v1.
Z-Wave Plus specifies the Node Specific Type "Fan Switch". When HA does its entity discovery (light, fan, sensor, etc.) it is checking for Z-Wave Plus fans (match Generic/Specific node types with Generic "Multilevel Switch" and Specific "Fan Switch" and the Level value for Multilevel Switch CC v1).
The LZW36, which is Z-Wave Plus V2, identifies itself as Generic "Multilevel Switch" (0x11) and Specific "Not Used" (0x0).
So in either case, pre-Z-Wave Plus or now Z-Wave Plus V2, HA cannot not distinguish fan controllers from light switches by using the Generic & Specific types alone.
You can also see zwave2mqtt has it's own "quirks" database, the same as HA, so it would be nice to get rid of that duplication.
Here are the cache files. Node 24 is the GE non-Plus fan controller. Node 11 is a Plus fan controller, which HA can detect.
Okay from what you wrote, zwave-js cannot detect the devices as fan controllers - they don't tell us. The cache files don't contain any additional info.
Right, which is why it needs to go into a DB somewhere. Either that's zwave-js, which would provide the info somehow to a client application, or you close this and we continue with the status-quo and have applications handle it individually.
I'll leave it open for now. That's something that might be worth talking about with an expert.
@AlCalzone Building a database of fan controllers wouldn’t be that tough. The one posted has the word fan in about 15 places in the zwave alliance xml. A little regex? You could add a flag to the device file?
@AlCalzone What about a compat flag to override the device type? We already have a device database, we should use that
Another use case besides fans, HA now has valve entities (currently both water and gas types). The Binary Switch CC value for a device like the Zooz ZAC36, which currently is represented as a switch, could instead be treated as a "valve" if some kind of hinting were provided. There's not much difference in functionality, but it's a more accurate representation.
The DB say Binary Switch. The Alarm.com ADC-SWV100 is an actual Valve type. Looks like Valve is a type they dropped in Z-Wave + V2.