HOWTO: Leviton Vizia rf+ Zone Controllers


#1

The following is a guide on how to use the Leviton Vizia rf+ zone controllers with Home Assistant, specifically:

VRCZ4-M0Z 4-Button Zone Controller (type=“0702” id="0261”)
VRCZ4-MRZ 4-Button Zone Controller with Switch (type=“1202” id="0243”)

The following applies to these two specific versions of the Leviton zone controllers. Although purchased separately, I only have three of them, and there may be different revisions where things are different. I’m also not claiming to be an expert in Z-Wave or Home Assistant. Any feedback or corrections are welcome, and perhaps we can get it into shape for inclusion in the official documentation.

Software Installation

When configuring Home Assistant, it is possible to specify a path to the device database. This allows using the latest database from OpenZWave. Putting it into .homeassistant/config allows it to be be shared with the OpenZWave control panel (which would then installed in into the .homeassistant directory):
zwave: config_path: /usr/local/homeassistant/.homeassistant/config
The OpenZWave control panel and Home Assistant will also access the same network configuration file (zwcfg_…xml).

Coming from Vera and Z-Way, I personally am still using the Z-Way software as the primary Z-Wave controller (even though Z-Way has many many other shortcomings). A second UZB1 USB stick is used for Home Assistant. The UZB1 has the advantage that it can be backed up and restored using the Z-Way software, even if the full feature set of the software is not licensed. The backup is a standard .tar.gz file, and before restoring, it is possible to manipulate its contents, including values that would otherwise be impossible to change (such as the Home ID or Node ID of the controller, or promoting a secondary to a primary controller). Note that it is necessary to perform a factory reset before the restore.

Network Design

Reportedly, some legacy devices cannot report state changes to a controller that is not at Node ID 1. Other devices have problems with Node IDs greater than 32. While I have not encountered this, it’s still a good idea to ensure that the USB stick connected to OpenZWave for Home Assistant is Node ID 1. A verified fact is that some battery operated devices will only ever report their status to one controller, so it may be necessary to pick the primary or secondary controller for the reporting target.

Including the Zone Controller

The VRZC4-M0Z is included by pressing and holding the left side of the first and third buttons (counting from the top) for about five seconds until the LED turns amber. Letting go of the buttons, the LED will blink and the zone controller can be included.

Including the Zone Controller with Switch

The VRZC4-MRZ is “two devices in one”. It will show up on the Z-Wave network with two Node IDs, but both of them will have an identical manufacturer, type and ID.
First, include the zone controller part (buttons 1 and 3) as described above.
Second, include the local switch (load control). The manufacturer’s instructions are confusing or wrong. I succeeded by pressing and holding the left side of buttons 2 and 4.

Buttons and Z-Wave Scenes

Associations

The zone controller can talk to OpenZWave, and “directly” to (some) devices. To talk directly to devices (which makes things faster), the target device’s Node ID must be “associated”. Supposing OpenZWave is Node ID 1, and the light bulbs to be controlled with buttons 1, 2, 3, and 4 are Node IDs 13, 14, 15, 16, then the Z-Wave “Association Groupings” for the zone controller would be:

Controller Button Association Group (Target) Node IDs
1 1 1, 13
2 2 1, 14
3 3 1, 15
4 4 1, 16

Set the associations first. Using the Home Assistant Z-Wave Configuration panel, select the Node ID of the zone controller, and change “Node group associations” (or use Z-Way).

It is possible to add multiple Node IDs for each association group. The key is that Group 1 is Button 1, Group 2 is Button 2, etc.
Note that not all devices support “direct” association. I have found it only works when the device supports the Z-Wave SCENE_ACTIVATION command class.

Scenes

Z-Wave scenes can be programmed to set a light to a certain dimming level, and to turn lights and switches on and off. Like many things in Z-Wave, scenes aren’t that useful when using a powerful controller such as Home Assistant, but they still have some advantages. Direct association is faster (otherwise, there can be an annoying noticeable delay), and works even when the controller is down.
Pressing a button on the zone controller sends out a Z-Wave SCENE_ACTIVATION command. The Scene ID numbers have nothing to do with Node IDs, and different buttons and different devices can send out the same scene number.
To reuse Scene ID numbers across buttons and devices is inviting trouble. Instead, create a scene number plan and define which device and button creates which scene. OpenZWave may have built-in scene management, but I have been unable to get it to work. It would be easier if software managed this.

For example:

Device Scene IDs
scene_controller_4 11, 12, 13, …
scene_controller_5 21, 22, 23, ...
scene_controller_6 31, 32, 33, …

As shipped, the Leviton zone controllers emit SCENE_ACTIVATION commands for the left sides of the buttons only, and use Scene IDs 1 through 4. The right (“off”) side of the buttons can turn directly associated devices off, but the only notification OpenZWave will see is a “node event” that does not specify which of the buttons was pressed, and so it is not terribly useful. It also does not allow triggering a button specific automation or script in Home Assistant.

Therefore, the next step is to change the Scene ID numbers that the buttons produce. This is done using the Z-Wave SCENE_CONTROLLER_CONF command class. Currently, this is not possible in Home Assistant’s Z-Wave Configuration panel. It might be possible in OpenZWave’s Control Panel, but I took the shortcut of using Z-Way.

Zone controller’s SCENE_CONTROLLER_CONF factory programming:

Group

Scene ID

Description

1

1

Button 1 Left (On)

2

2

Button 2 Left (On)

3

3

Button 3 Left (On)

4

4

Button 4 Left (On)

5

None


6

None


7

None


8

None




Zone controller’s SCENE_CONTROLLER_CONF modified programming:

Group

Scene ID

Description

1

21

Button 1 Left (On)

2

22

Button 2 Left (On)

3

23

Button 3 Left (On)

4

24

Button 4 Left (On)

5

25

Button 1 Right (Off)

6

26

Button 2 Right (Off)

7

27

Button 3 Right (Off)

8

28

Button 4 Right (Off)

9

None




Magically, the zone controller will now send out Scene IDs for the right side of the buttons. The “all off” is no longer emitted. The “off” side of the buttons can now be used for automation triggers in Home Assistant, for example:

    - action: []
      alias: Controller Button 4 Off
      condition: []
      id: controller_button_4_off
      trigger:
      - event_data:
          entity_id: zwave.scene_controller_5
          scene_id: 28
        event_type: zwave.scene_activated
        platform: event

The next step is to go into the configuration for each “directly” associated device and change the Z-Wave SCENE_ACTUATOR_CONF to do the right thing.
For example, to turn on the light with Node ID 15 when the left side of button 3 is pressed on controller 5:
For device node ID 15, change SCENE_ACTUATOR_CONF and set Scene ID 28, Level 255, Duration 0, Level used 128.
Note that not all devices support SCENE_ACTUATOR_CONF, and in those cases a Home Assistant action can be created such as the following:

- action:
  - data:
      entity_id: light.node004_level
    service: light.turn_on
  alias: Controller Button 3 On
  condition: []
  id: controller_button_3_on
  trigger:
  - event_data:
      entity_id: zwave.scene_controller_5
      scene_id: 23
    event_type: zwave.scene_activated
    platform: event

Using actions vs. directly controlled devices has the downside of potentially incurring a delay. The delay is small but may be noticeable enough to be irritating.

Troubleshooting

In an ideal world, all Z-Wave devices would interoperate. In the real world, devices are buggy, support different parts and revisions of the specification, and sometimes just don’t work well. For those who can afford it, using Z-Wave Plus devices exclusively helps. Z-Wave Plus is by no means perfect, but better. For those who have legacy devices (which may at some point have cost quite a bit), the following may help.

Symptom

Cause

Solution

Device does nothing when zone controller button pressed

Wrong Scene ID sent, or Scene ID not configured in device, or scene does not tell the device a light level

Program Scene IDs properly, and ensure the device knows what to do with the scene


Device does not support scenes

Use light.turn_on/off or switch.turn_on/off in automation action

Home Assistant state does not change when light or switch turns on/off

Device does not report changed state

For Aeon Labs dimmers and switches, enable the Z-Wave HAIL using COMMAND_CLASS_CONFIGURATION, parameter 80, value 1



Force a refresh in Home Assistant either by repeating the action from Home Assistant (issue service switch/light.turn_on/off) or by a call to service zwave.node_refresh

Zone controller LEDs do not indicate controlled device state

Lights must be set and cleared using manufacturer proprietary commands, currently not supported by Home Assistant

None - Contribute to or wait for software upgrade

Bonus: When toggling button on controlled outlet, Home Assistant state does not change

Device sends out a NIF (Node Information Frame), but OpenZWave/Home Assistant ignores it

None - Contribute to or wait for software upgrade (Z-Way has the user contributed NIFFLER)


Leviton Z-Wave Plus switches/Dimmers No configuration options
#2

Hi Robert,

I have two VRCZ4-M0Zs installed, and almost exclusively Zigbee (Philips Hue) bulbs in my network. I’ve already developed code to respond to “Manufacturer Proprietary” commands from my first VRCZ4, and it’s all working beautifully. On installing my second VRCZ4, though, I find that it’s behaving just like the first one except that it’s not generating of those Manufacturer Proprietary (command 9100, or 0x91) commands that include the button-press number.

Any chance you’ve come across how to enable/activate these messages? (I’m thinking perhaps I did it somehow inadvertently while discovering the first unit…)


#3

Hi All,

I just started with Home Assistant and Z-Wave recently and have my network setup with 34 devices and working decently. I wanted to add the 4 VRCZ4-M0Z I have to my network (they are currently connected to my Vera) and was expecting them to send zwave.scene_activated events just like my MiniMotes, but they don’t even just for the left side buttons. I’ve reset a controller multiple times and still get the same thing; none of the ZWave events generated help me. I don’t have access to ZWay so can’t reprogram the controller that way. I’m not versed in OpenZWave Control Panel or Zensys-tools, but anyone know if I could use either of those tools to send raw commands to the controller to get it to send scene activated events? Interestingly enough, my Vera works flawlessly with the controllers so I suspect they have some magic sauce.

Thanks!


#4

I hate to reply to myself, but I spent the last several days trying to figure this out. I did figure out how to reprogram the VRCZ4-M0Z using the Z-Wave PC Controller that is part of the Z-Wave SDK. I didn’t use the SCENE_ACTUATOR_CONF commands, just the SCENE_CONTROLLER_CONF commands and re-used the scene IDs across controller as I can distinguish between controllers in HA. For buttons that I want to control lights directly, I don’t set the SCENE_CONTROLLER_CONF, just set an ASSOCIATION to the device.

Full instructions can be found on my blog.