Add value notification event for Multilevel Switch CC

[binzhou]

Is your feature request related to a problem? Please describe.
The Aeotec ZW111 is an in-wall dimmer with a single output but wiring for 2 external switches. It can be configured such that the second switch only sends zwave commands to an association group rather than controlling local load. It supports sending 2 sets of commands: basic and multilevel switch CC.

Currently, we can take advantage of this by associating the device with the controller node and setting it to send only basic commands - these are received by zwave-js and converted to value notifications. However, this doesn't work when set to multievel switch CC.

If this were supported, then not only could you program automations (eg. in Home Assistant) for on/off events, but also for multilevel start/stop commands which correspond to holding and releasing the external switch.

Describe the solution you'd like

1. Support parsing of MultilevelSwitchCCSet and MultilevelSwitchCCStartLevelChange (MultilevelSwitchCCStop already supported as there are no options)
2. Support generating value notifications when the controller receives these commands.

Describe alternatives you've considered
N/A

Additional context
Log from when I toggled then held-and-released external switch that had direct association with the controller and was set to send Multilevel Switch CCs

Subscribed to Z-Wave JS Log Messages…
2022-01-08T22:45:32.030Z SERIAL « 0x010c0004000d042601ff01da00fd (14 bytes)
2022-01-08T22:45:32.030Z DRIVER Dropping message because it could not be deserialized: MultilevelSwitchCCSet: 
                                  deserialization not implemented (ZW0320)
2022-01-08T22:45:32.031Z SERIAL » [ACK] (0x06)
2022-01-08T22:45:34.329Z SERIAL « 0x010c0004000d0426010001da0002 (14 bytes)
2022-01-08T22:45:34.330Z DRIVER Dropping message because it could not be deserialized: MultilevelSwitchCCSet: 
                                  deserialization not implemented (ZW0320)
2022-01-08T22:45:34.331Z SERIAL » [ACK] (0x06)
2022-01-08T22:45:37.229Z SERIAL « 0x010d0004000d052604200001d80025 (15 bytes)
2022-01-08T22:45:37.230Z DRIVER Dropping message because it could not be deserialized: MultilevelSwitchCCStart
                                  LevelChange: deserialization not implemented (ZW0320)
2022-01-08T22:45:37.231Z SERIAL » [ACK] (0x06)
2022-01-08T22:45:37.829Z SERIAL « 0x010a0004000d022605d80005 (12 bytes)
2022-01-08T22:45:37.830Z SERIAL » [ACK] (0x06)
2022-01-08T22:45:37.831Z DRIVER « [Node 013] [REQ] [ApplicationCommand]
                                  └─[MultilevelSwitchCCStopLevelChange]
2022-01-08T22:45:37.833Z CNTRLR « [Node 013] TODO: no handler for application command

[AlCalzone]

Interesting use case, but I can see the value in having this.
Note that Start/Stop would need to be under the notification event (not value notification), because they are a bit more complex (start/stop, direction and potentially startLevel).

I'll put this on the todo list - if anyone wants to help out, go for it!

[AlCalzone]

Some pointers:

1. The deserialization must be implemented in the MultilevelSwitchCCSet command here:
   

   node-zwave-js/packages/zwave-js/src/lib/commandclass/MultilevelSwitchCC.ts

   Lines 584 to 589 in 27bb4ee

   	// TODO: Deserialize payload
   	throw new ZWaveError(
   	`${this.constructor.name}: deserialization not implemented`,
   	ZWaveErrorCodes.Deserialization_NotImplemented,
   	);
   	} else {

   
   similar to

   node-zwave-js/packages/zwave-js/src/lib/commandclass/BasicCC.ts

   Lines 284 to 285 in 3a7251d

   	validatePayload(this.payload.length >= 1);
   	this.targetValue = this.payload[0];

2. An event value needs to be defined like for the Basic CC here
   

   node-zwave-js/packages/zwave-js/src/lib/commandclass/BasicCC.ts

   Lines 61 to 67 in 3a7251d

   	export function getCompatEventValueId(endpoint?: number): ValueID {
   	return {
   	commandClass: CommandClasses.Basic,
   	endpoint,
   	property: "event",
   	};
   	}

   
   and created during the interview:
   

   node-zwave-js/packages/zwave-js/src/lib/commandclass/BasicCC.ts

   Lines 213 to 221 in 3a7251d

   	if (node.deviceConfig?.compat?.treatBasicSetAsEvent) {
   	const valueId = getCompatEventValueId(this.endpointIndex);
   	if (!node.valueDB.hasMetadata(valueId)) {
   	node.valueDB.setMetadata(valueId, {
   	...ValueMetadata.ReadOnlyUInt8,
   	label: "Event value",
   	});
   	}
   	} else if (

   
   I'd gate it behind a compat flag like we do for Basic CC, so this needs to be defined here and here

3. The Start/Stop level change commands need to implement parsing too (see 1.) and new notifications must be defined for them here and emitted like here.

[reubenbijl]

I've just started having a look at this and have made the changes that you've suggested to the MultilevelSwitchCCSet command, but I'm getting an error where at node-zwave-js/packages/zwave-js/src/lib/node/Node.ts the command isn't recognised, so I've added a category for the Multilevel Switch but just wanted to check that this was expected?

[reubenbijl]

@binzhou I've added support for the Start and Stop Level Change Commands now as well, let me know if you get a chance to test it out.

@AlCalzone Where's the best place to get feedback on the commits?

 2022-02-25 20:55:10.710 INFO ZWAVE: Node 6: value notification: 38-0-event 0
 2022-02-25 20:55:12.100 INFO ZWAVE: Node 6: value notification: 38-0-event 99
 2022-02-25 20:55:14.802 INFO ZWAVE: Node 6: value notification: 38-0-event down
 2022-02-25 20:55:15.401 INFO ZWAVE: Node 6: value notification: 38-0-event stop
 2022-02-25 20:55:17.601 INFO ZWAVE: Node 6: value notification: 38-0-event up
 2022-02-25 20:55:18.799 INFO ZWAVE: Node 6: value notification: 38-0-event stop

[AlCalzone]

Where's the best place to get feedback on the commits?

Just open a PR here, this makes it easiest for me to check out what you did.

[j9brown]

FWIW, I believe this proposed change will also address a need for Leviton VRCS4 and Leviton VRCZ4 devices (and perhaps others too). These devices have a rocker switch that functions as a dimmer by sending Multilevel Switch messages to the associated load (or the hub). The rocker can be pressed to adjust the associated load's level incrementally or held to adjust the level continually until released.

In my previous integration with OpenZwave, I reported these events as "up" / "down" / "stop" similar to what is being proposed here (and I was just investigating how to do it with zwave-js). So I'm excited about this change. ;)