Z-Wave

Make/Model	Device Version	Connection Type
Zen-Sys/Z-Wave	N/A	USB (Serial)

Description:

This driver interfaces CQC to the Zen-Sys Z-Wave wireless control network. Z-Wave is one of a number of technologies that are replacing the aging X-10 technology commonly used in the past, with many improvements. For one, it is wireless, so it doesn't depend on power lines to transmit commands and data, is considerably faster than X-10 (though still very slow by modern standards), and is a routing network much like a wireless LAN, so that messages can be dynamically routed to deal with interference and so forth. It is also far more secure, since each unit must be allowed to join the network before it can be controlled or will be listened to.
Like X-10, Z-Wave consists of a controller to which CQC talks, and the controller talks to one or more 'units' or 'modules' that are distributed around the home. A unit can be an on/off lighting or appliance unit, a dimmer, a thermostat, and so forth. The Z-Wave protocol defines a number of possible types of units, not all of which have actually been delivered by anyone yet, and not all of which are supported yet by this driver. The limitations of the driver are listed below in the Quirks and Limitations section.
The Z-Wave network is managed by a 'primary controller'. This will be a hand held 'remote control' type unit which you can carry around with you, and which you will use to add units to. or remove units from. the network. The PC-based controller cannot perform this function, it must be done via the remote control. In Z-Wave parlance, the PC-based controller is a 'secondary controller', which means it can do things like turn devices on and off and ask them for their state, but it cannot add or remove units or do other housekeeping chores.
It is important that you follow certain strict rules if you want your Z-Wave network to remain fast and reliable, so be sure to read the section below on Good Z-Wave Practice.

Joining the Network/Learning about Units
When you first get the USB controller it will not be part of the Z-Wave network. Just like a unit, it must be added to the network, at which time it will be given a unit id and be set to the home id of your Z-Wave network. Getting it into the network is accomplished by replicating the Z-Wave remote control to the USB controller. Actually the replication process accomplishes two things. If the USB controller is not yet in the network, it gets added. And, the USB controller will learn about any Z-Wave units that the remote control knows about, making them available for control by CQC via the USB controller.
The first time you replicate to a new USB controller, you will be doing both these jobs. But you can subsequently do the replication process again to make the USB controller (and hence CQC) aware of new units that have been added to the network. Replication is done via the driver's client interface, which looks like this:
The replication process is done by first putting the Z-Wave remote control into replication mode, which is done differently on various models, so see your remote control documentation. You only want to replicate system information, not user information. The former just adds the USB controller to the network and doesn't go through the extra overhead of transferring data that the CQC driver doesn't make use of.
Once the remote control is in replication mode, you press the "Learn Network..." button on the CQC driver client interface above to invoke the replication process. A dialog box will pop up that indicates CQC is waiting on replication data and showing the replication status, and which provides you a cancel button to cancel the operation if you wish. An LED will blink on the dialog as the replication process proceeds.
When the process completes, the remote control will indicate the data was sent and the replication dialog above will go away. At that point you should see the Z-Wave units now known to the controller show up in the driver interface in the right hand list. Any units that CQC hasn't seen before will be given default names, such as BinSwitch_02 or MLSwitch_A1 and so forth, which indicates their unit type and their Z-Wave address. You can then rename then as desired, as you see in the client interface example above.
During replication, you generally want the remote control to be not too far away from the USB controller but not right up against it either. Somewhere in the same room is generally fine, though if you have replication problems, you might want to move a little closer. The newer style controllers work better (see the Quirks and Limitations section below.)
Once the replication is complete, you can then rename any new units that have appeared to give them more meaningful names, and CQC can control them. Be sure to rename them before you start referring to them in your automation logic since the name you give the unit is the name of the field for that unit, so you will change the field name when you rename it.
You can also create Groups, which are collections of units that you can issue simple on/off and level setting commands to as a group. Think of them as 'scenes' more or less. The list on the left of the client interface shows the defined groups. You can edit a group or create new groups, which will show a new dialog box where you can add units to the group, or remove units from the group.
Of course there are limitations if you put units into a group that cannot react to the same basic commands. If you create a group of mixed binary and multi-level switches, and you send the group a 50% level command, only the multi-level switches will react to that since it only makes sense for them. They all react to On/Off commands so you can control that mixed set in terms of on/off via the group.
The CQC drivers does not use the All On/Off setting that can be set on each Z-Wave unit to tell it whether to respond to All On/Off messages. Instead, there is a special group in the CQC driver called AllOnOff that is always present (you cannot delete it) and that group is used when you send All On or All Off commands. So add any units to this group that you want to react to these commands.

Good Z-Wave Practice

Any time you change the Z-Wave network, you must use the remote control! You cannot just unplug a Z-Wave unit to remove it from the network. Nor can you just unplug it and go plug it in somewhere else. Doing these things will cause all kinds of problems. Any changes must be made via the remote control, and as soon as they are done, you must replicate again to CQC to keep it apprised of any changes.
As mentioned above, Z-Wave is a routing network, and each unit (including the USB controller) knows who its neighbors are and uses that information to route messages. If a unit is just removed, then that invalidates these routing tables that each unit maintains and causes delays that can ruin the performance of your network.
Adding Units
If you want to add a unit. Plug it in where it will live, connect it to the thing you are controlling, and optimally turn that device on, and then use the remote control to add the unit. Once added, you can then replicate to CQC again. The new units will show up with default configuration, which you can then modify.
Moving Units
If you want to move a unit, you must use the remote control to remove it from the network (while it's still in its old position and still working), take it to its new location, and re-add it using the remote control. Then replicate to CQC again. Any units that CQC sees during replication that have the same unit id and same type will be seen and any new name you gave it will be maintained. So you don't have to go back and re-enter all the units names if you do a new replication.
Removing Units
To remove a unit, use the remote control to remove from the network, then replicate to CQC. It will see that this unit no longer exists and will remote it from the configuration.
Unit Coverage
The Z-Wave network requires a certain 'density' of units to work optimally. Meaning that if there are too few units, and they are too far spread out, the ability to get a good signal between them, and therefore to route messages accurately and quickly, is reduced. This is not to say that having one particular unit way out at the end of the driveway won't work. But you generally don't want them too spread out. If each unit has multiple neighbors that it can route through, the ability to deal with varying types of interference will be improved.
Reset the Remote Control
Remote controls, if they are used in various experiments during the learning phase of Z-Wave adoption, and over time, can sometimes get infected with junk data about modules that no longer exist (but not correctly removed) and so forth. This can cause lots of problems. If you want to be completely safe and have a completely clean system, you may want to reset every unit, then reset the remote control to factory defaults, and then add the units back in. Then install the CQC Z-Wave driver, use the Reset button on the driver to reset the USB controller back to defaults, and then replicate the remote control to it. This will insure that you get rid of any bogus information, any possible clashing module ids and just any detritus that might have accumulated. Of course if you just got all new equipment and just set up your network cleanly, then this is not likely to be an issue for you.
Polling Speed
Most Z-Wave units will not report their status on their own and must be polled. The CQC Z-Wave driver allows you to set the polling speed of each unit, or to disable polling altogether. You should be conservative in how fast you try to poll units, or you will overwhelm the Z-Wave network and make it worse, not better. You will also make outgoing commands slower because the controller is more often in use for polling purposes and the outgoing commands have to wait for the current poll to complete.
So don't set your poll times too fast, and disable it altogether for those that you don't really need to have two way feedback on. If the unit is one that reports its status, then set the poll time on that unit for something like once a minute or once very two minutes, just so that the controller will check it periodically and make sure it's still alive, but otherwise will rely on reports.
A good rule of thumb is to set the poll period to about 3 or 4 seconds for the most important units, maybe 10 to 15 seconds for less important ones, and for the others just set it to a minute or so just so that the controller checks it periodically (and can therefore know if it stops responding.)
There is a PollingLoad field that you can use to see if you are overloading your network. See the fields list below.
As long as you follow these rules, the network (and CQC's use of it) should remain stable. It is always possible that performance could vary over time due to some form of interference, and you may need to install some routing nodes to insure good, solid coverage. Most non-battery powered units are also routing units, so most any wall switch or lamp/appliance module will provide this service.

Quirks and Limitations:

This driver supports the older style ACT USB/Serial controllers as well as the newer style Intermatic USB Stick controllers. The latter are far superior and we don't recommend the use of the ACT controllers. For that matter, we don't recommend the use of the ACT modules either, since the newer modules have benefited greatly from the improvements in technology and packaging of late. A system composed purely of newer hardware will likely be considerably more reliable and performant.
The driver currently only supports those module types that react to the basic on/off and multi-level command classes. This covers a lot of modules, basically all the light switches, dimmers, appliance modules, relays and so forth. But there are other types that have not been added to the driver yet. They will be added over time.
There are some unit types currently that cause the replication process to fail, so you cannot use them. These include the new Vizia type units. This is being investigated and will be fixed as soon as possible.

Connection Details

The connection for the controller is USB, but in effect this is misleading, because you must load a device driver that makes it look like a serial port. So once you load this driver, and plug in the USB controller, a new serial port will show up in your system. You should select this serial port when you load the driver into CQC.
For the older style ACT controllers, here is the driver you must load:
FTDI Z-Wave Controller Driver
For the newer style Intermatic USB Stick controllers, here is the driver you must load:
Intermatic Stick Driver
Right click on it, and select Save As, and then save it to your local disk. Unzip it, and then when you plug in the USB controller, it will ask you where the driver is, and you should point it at this driver. BE SURE that you don't let it go to the Microsoft site and download a driver, because it will not be correct.
NOTE: A serial version of the ACT controller is also available. This driver should work just fine with it. In that case, you do NOT need to use the above driver, you just plug the controller into an available (real) serial port and you are fine.
If you are converting from Homeseer to CQC, it appears that Homeseer uses the lower level FTDI driver, which cannot co-exist with the virtual serial port driver that CQC uses. So, you should be sure that Homeseer is removed, then uninstall the current driver, then unplug the device. You might want to be safe and cycle the computer that point. Then you should be able to plug the device in, and Windows will ask for a driver. Don't let it auto-select a driver or go to Windows Update to get one. Select the driver yourself, and point it at the one you downloaded above.

Driver Fields

This section lists the fields that the driver makes available, their types, minimum and maximum values, etc...
Name Type R/W Description/Limits
Command String W An open ended command field which allows you to send formatted strings to invoke more complex control. The syntax is described below.
groups * Bool W Boolean write-only fields, one for each group you define. These just provide a convenient way to turn the whole group on and off. For finer grained control see the Command field.
units * Card/Bool R/W Read/write fields, either Card or Boolean according to the type of unit, which allow the units to be controlled. See the notes below. For Card fields (multi-value units), the range is from 0 (off) to 99 (fully on.) The actual field names will be whatever you have named the units.
PollingLoad Card R An indicator of how hard the driver is working to poll the units as you have configured them. It is the ratio of the number of units that are available to poll to the number that are currently queued up to be polled (i.e. their poll time has arrived but they've not been polled yet.) So zero means you have no backlog at all. 100 means you are working it too hard. Ideally you want it to be zero or a low number, so you may need to lower the polling rate on some units or disable polling on some.
ZW_HomeId Card R A read-only value that indicates the home id of the controller, which will be that of the local network once the controller is added to the network.
ZW_CtrlVersion String R A string that contains the version information for the Z-Wave controller, such as "Z-Wave 1.91". This can be very helpful with problem diagnosis.
ZW_SerialAPIVer Card R Indicates the version of the serial API that the USB controller uses. This might be important for problem diagnosis.
ZW_UnitId Card R A read-only value that indicates the unit id of the controller. Until the controller is added to the network, it will have a default id. When added, the primary controller will assign it an id.
Command Format
The Command field in the table above allows you to send the driver more complex commands via a formatted string. The format of the string written to this field is:
command [[target] options]
Where command is the command to perform, target is the target group or unit to affect, and options are optional modifiers that provide extra info needed for some commands. Both the target and options may be optional for some commands.
The possibilities are listed below.
ALLON
ALLOFF
These commands don't need any target or options. Any units in the Z-Wave network configured to respond to these events will do so (assuming no communications errors.) You can use the Z-Wave remote to control whether particular units participate in either the ALLON or ALLOFF operations.

GROUP grpname ON|OFF
GROUP grpname RAMPUP|RAMPDN|RAMPEND

This command allows you to turn a group on or off, which will turn all of the units in that group on or off, or to ramp the units in that group up or down. Z-Wave uses a start/stop paradigm for ramping. So you tell it to start ramping up or down and it does that until you tell it to stop.
Note that the group name is case sensitive, but the other stuff is not. Note the quotes around any name that has spaces in it, so that it can be distinguished as a single value.
Examples would be:
GROUP BedRoom ON
GROUP "HT Lights" RAMPUP
group HTLights rampend
GROUPLEV grpname %lev

This command allows you set the level of a group to a given percent illumination, which will in turn set the level of all of the units in that group to that percent level.
Note that the group name is case sensitive, but the other stuff is not. Note the quotes around any name that has spaces in it, so that it can be distinguished as a single value.
Examples would be:
GROUPLEV Kitchen 50
GROUPLEV "HT Lights" 95
UNIT unitname ON|OFF
UNIT unitname RAMPUP|RAMPDN|RAMPEND

This command allows you to turn a unit on or off, or to ramp a units up or down. Z-Wave uses a start/stop paradigm for ramping. So you tell it to start ramping up or down and it does that until you tell it to stop.
Note that the unit name is case sensitive, but the other stuff is not. Note the quotes around any name that has spaces in it, so that it can be distinguished as a single value.
Examples would be:
unit "Fnt Porch1" off
UNIT KitchenOH RAMPDN
GROUP KitchenOH RampEnd

Name	Type	R/W	Description/Limits
Command	String	W	An open ended command field which allows you to send formatted strings to invoke more complex control. The syntax is described below.
groups *	Bool	W	Boolean write-only fields, one for each group you define. These just provide a convenient way to turn the whole group on and off. For finer grained control see the Command field.
units *	Card/Bool	R/W	Read/write fields, either Card or Boolean according to the type of unit, which allow the units to be controlled. See the notes below. For Card fields (multi-value units), the range is from 0 (off) to 99 (fully on.) The actual field names will be whatever you have named the units.
PollingLoad	Card	R	An indicator of how hard the driver is working to poll the units as you have configured them. It is the ratio of the number of units that are available to poll to the number that are currently queued up to be polled (i.e. their poll time has arrived but they've not been polled yet.) So zero means you have no backlog at all. 100 means you are working it too hard. Ideally you want it to be zero or a low number, so you may need to lower the polling rate on some units or disable polling on some.
ZW_HomeId	Card	R	A read-only value that indicates the home id of the controller, which will be that of the local network once the controller is added to the network.
ZW_CtrlVersion	String	R	A string that contains the version information for the Z-Wave controller, such as "Z-Wave 1.91". This can be very helpful with problem diagnosis.
ZW_SerialAPIVer	Card	R	Indicates the version of the serial API that the USB controller uses. This might be important for problem diagnosis.
ZW_UnitId	Card	R	A read-only value that indicates the unit id of the controller. Until the controller is added to the network, it will have a default id. When added, the primary controller will assign it an id.