Home

vrctl - Z-Wave VRC0P utility for Linux
--------------------------------------

vrctl is a command line utility that operates the Leviton VRC0P-1LW (+3)
Z-wave serial interface unit.  It provides the following capabilities:

 - Turning Z-Wave devices on or off
 - Setting dimmer levels
 - Listing all devices present on the network
 - Upgrading the VRC0P's firmware

The vrctl interface was designed to be at least somewhat familiar to
users of the X10 Bottlerocket (br) utility.

Getting started:

1) The VRC0P unit must be paired to an existing Z-wave network using the
primary controller.  This does not require any interaction with the
attached PC.  Typically it is done by holding down the green LED button on
the front of the VRC0P until it blinks amber, then telling your primary
controller to include (add) a secondary controller to the network.

2) Next, the VRC0P should be attached to the PC via RS232.  These
instructions will assume it is connected to /dev/ttyS0 .

3) Now build vrctl:

$ tar -jxf vrctl*.tar.bz2
$ cd vrctl
$ make

4) At this point you should be able to list all devices on the Z-wave
network:

$ vrctl -x /dev/ttyS0 --list
002 (unnamed): switch/appliance (generic class 16, instance 1)
003 (unnamed): switch/appliance (generic class 16, instance 2)
004 (unnamed): switch/appliance (generic class 16, instance 3)

5) You can change the device power states by doing something like:

$ vrctl -x /dev/ttyS0 003 on
$ vrctl -x /dev/ttyS0 002 toggle 004 off
$ vrctl -x /dev/ttyS0 005 level 50

6) Optionally, you may create $HOME/.vrctlrc and add settings that will
be read by vrctl each time it starts.  Example:

port /dev/ttyS0

alias kitchen 2
alias bedroom 3
alias bedroom2 4
alias fan 6

Aliases may reference prior aliases:

alias study bedroom2

Node IDs (002, 003, ...) are persistent until the module is unpaired.  If a
module is paired and then unpaired, it is likely to be assigned a new node
ID by the primary controller.  It is usually not possible to control the
node ID assigned to a module (unlike X10), so it is generally a good idea
to use vrctl aliases instead of trying to memorize node IDs.

Firmware upgrade (experimental):

Firmware packages available from Leviton generally contain two files, e.g.

"ST V0_30_U02.hex" - Main firmware for the ST Micro SoC that runs the
VRC0P.  This resides on the ST chip's internal flash.

"Zensys V0_30_U01.HEX" - Firmware for the low-level Zensys Z-wave
transceiver chip.  This resides on a serial EEPROM.

vrctl can upgrade either firmware image over the serial port, avoiding the
need for Leviton's Windows-based installer.

Upgrading the firmware may brick your device, so use this feature at your
own risk.

Usage:

$ vrctl -x /dev/ttyS0 -u zensys.hex

$ vrctl -x /dev/ttyS0 -u st.hex

The ST bootloader has an automatic "recovery mode" built in, which allows
reflashing the image through an alternative protocol if the last attempt
was not successful.  vrctl will attempt to use the recovery mode if the
VRC0P is not responsive to normal commands.  You may need to toggle power
to the unit prior to attempting a recovery flash.

Other random tips:

Some of the cheaper Z-Wave controllers have interoperability problems with
certain modules.  This can manifest itself in a failure to pair, or strange
behavior with respect to "ALL ON" / "ALL OFF" commands.

Some of the older VRC0P firmware images had problems with node enumeration.
It doesn't work "great" on current images (some devices don't show up, and
it sure is slow), but it mostly does what you expect.

The Leviton CTZUS-1US ControlThink ThinkStick makes a decent primary
controller.  But you will need to use the Leviton RF Installer tool
(Windows) to set up the network.  Be sure to upgrade the ThinkStick to the
latest firmware image as well.

Usage page:

$ vrctl -h
vrctl v0.1 - Z-Wave VRC0P utility
Copyright 2012 Kevin Cernekee.  License: GPLv2+
This is free software with ABSOLUTELY NO WARRANTY.

Usage:
  vrctl [<options>] <nodeid> <command> [ <nodeid> <command> ... ]
  vrctl [<options>] all { on | off }
  vrctl [<options>] --list

Options:
  -v, --verbose       add v's to increase verbosity
  -q, --quiet         only display errors
  -x, --port=PORT     set port to use (default: /dev/vrc0p)
  -l, --list          list all devices in the network
  -u, --upgrade=FILE  upgrade firmware from FILE
  -h, --help          this help

<nodeid> is one of the following:
  a decimal node number: 3 (use vrctl -l to list them)
  an alias from $HOME/.vrctlrc

<command> is one of the following (case-insensitive):
  on                  turn the device on
  off                 turn the device off
  bounce              turn the device off, then on again
  toggle              invert the device's on/off state
  level <n>           set brightness level
  status              display the current on/off/dimmer status
  lock                lock (door locks only)
  unlock              unlock (door locks only)
  scene <n>           Activate a previously stored scene

Contact:

Kevin Cernekee <cernekee@gmail.com>

License:

GPLv2+