TZWave Plugin

From Tallus LLC Wiki
Jump to: navigation, search

About[edit]

The Z-Wave device driver provides ZWave device control for MainLobby3 Server. It does not require the MLLighting Plugin Device Manager.

TZWave is a stand alone executable that works initially with MLServer from Cinemar. For use with MLServer, it requires that you have Tallus's MLComDevice. MLComDevice provides for one way TCP send capability free. Additionally, the free MLTCPSend plugin can be used as well, if it installed as a plugin in MLServer. TZWave will eventually work with MLComDevice using two way TCP connectivity. MLComDevice is available with preconfigured support for TZWave to ease setup.

TZWave has the capability to add ZWave connectivity for most PC based home automation systems.

Z-Wave Description[edit]

In a Z-Wave radio network, all nodes (devices) are wirelessly linked together through a communications network featuring the patented Z-Wave technology. The Z-Wave protocol defines various device classes (types) such as Lighting, Thermostat, Remote Controller, Static Controller, Repeater Slave, Binary Sensor, Multilevel Sensor, Pulse Meter, Entry Control, and more to come in the future.

More detailed information about the protocol and its devices can be found at: DDJ.com

Product Limitations[edit]

1. Leviton has acquired ControlThink and has subsequently eliminated support for the driver. You may not even be able to purchase a license. Please do NOT purchase TZWave unless you already have access to a ControlThink license.

2. Only Lighting Devices and HSM100 Motion Sensors are supported. There is absolutely no support for other types of Motion Detectors, Thermostats, Curtain Motors and the like. If these devices work, then you are lucky and we do not guarantee that it will work the same in future releases. These devices will not be supported until Version 4 (about 2 months from official release).

3. When you change an alias in the device tab of the plugin from one name to another, the old variables will not get deleted. Example: You have a device with the alias of "foyermainlights". You want to change this to "entrymainlights". New variables will be created in MLServer with the name of "entrymainlights", but the old variables with the name of "foyermainlights" will not be deleted. If you have not directed MLServer to save the variables, then simply restart MLServer in order to get rid of the old variables. Otherwise, you might have to manually delete each variable

Hardware Requirements[edit]

Although other controllers might work, the following ZWave Controllers have been tested with this driver. Any problems found in this driver for controllers not on this list will be fixed "at best effort".

HomeSeer ZTroller ZWave Controller (Serial Connection)
Intermatic HA22 USB Controller
ControlThink ThinkStick USB Controller (see availability information above!)
Wayne Dalton USB Controller

For the current product, the following ZWave Lighting Devices were tested. Any others should work, but we were not able to test every device that is available in the industry today. Please note that this device driver does not support Thermostats, Motion Detectors other than the HSM100 or other non-lighting device types. These are planned for the future, but are not in the current release.

Leviton Vizia Scene Capable On/Off Switch
Leviton Vizia Scene Capable On/Off Dimmer
Cooper Aspire Switch and Dimmer
Cooper Aspire Split Control Receptacle
Intermatic Switch and Dimmer

Software Requirements[edit]

Tested with Mainlobby3 Server 3.0.588 Mainlobby3 Server.

MLComDevice or MLTCPSend plugin installed.

MainLobby3 Client 3.0.107 (or newer)

[MDAC 2.8]

[Microsoft .NET Framework 3.5]

[Microsoft Visual C++ Package]

[TZWave] executable

ControlThink Z-Wave PC SDK 1.3 (or newer - see availability information above!)

Hardware Installation[edit]

General hardware setup for ZWave Lighting

Purchase a ZWave Controller and Devices.

There are several sources where you can purchase ZWave Controllers. Make sure that, in addition to, any handheld controllers, you also purchase a PC Controller. Often, these are called Static Controllers as they are supposed to remain in one location during their lifetime. Static Controllers, generally, act as Primary Controllers. A Primary controller (versus a Secondary Controller) contains the detailed routing table for all the devices within the ZWave mesh network.

There are many types of PC Controllers. Some of them are USB based and others work via a serial interface. There are also older models of controllers that don't support all of the latest features of the ZWave protocol and, additionally, don't have any way to update their onboard firmware in order to bring them up to date. We recommend that you steer clear of these controllers. If you have one of the older model controllers, we would recommend that you consider investing in a newer USB based controller with user-updatable firmware. The latest controller is the SmartStick branded controllers. We have tested the ThinkStick brand from ControlThink. It can be purchased online from ControlThink

Install the ZWave wall switches / plug in modules as per the instructions that they ship with; following all safety precautions.

Add the devices to the controller - There are a number of ways that this can be accomplished. You could use a handheld controller and walk around the house in order to add each device to the controller. Note that the ZWave protocol only allows you to add or delete a device when the controller is within 1 foot of the device. This is the only time that the controller needs to be in this close a proximity to the devices.

After you have added all of the devices to the controller, you can proceed to TZWave executable installation. In this section, you will make the ZWave PC Controller a secondary controller to the handheld controller. This can be done through the TZWave software. If you use this method, then the TZWave will be limited in some of its functionality. Things like optimizing the network will be limited to the handheld controller; since it contains the master routing table for the meshed ZWave network.

Alternative (and preferred method) to add devices to controller - In this method, you will make the PC Controller the primary controller. This is done by transferring the primary controller role from the handheld to the PC Controller used by TZWave. When the PC Controller is the primary, all of the group, scene and routing information are contained in the controller. This also means that the PC Controller must now be used to add any new devices or remove (delete) any old devices. There is only one problem with the PC Controller being the primary ZWave Controller. Adding or removing devices requires that the PC Controller be within one foot of the device being worked on. Since it is unlikely that you are going to carry your MLServer computer to the ZWave device, the functionality to add or remove devices has NOT been added to this plugin.

If you have a laptop, you can purchase the ZTools software from Homeseer for adding or removing devices. In this way, you can plug your ZWave USB stick into your laptop and use that for the several times that you might want to add the devices into your network.

If you don't have a laptop, TZWave does have the capability to "Receive Devices" from the primary controller. Use your handheld controller as a primary in order to add or remove any devices. Then either make the PC Controller a secondary controller or a primary controller. The "Receive Devices" button on the Controller Tab can make this happen. Whether you are a primary or secondary after the transfer is dependant upon what you did with the handheld controller.

Download Link[edit]

[TZWave Gateway Trial]

The plugin installs in a 30 day trial mode. Once you have decided to purchase it from [Tallus's shopping cart], just apply the software license you will receive from Tallus via email on purchase of the plugin. After the plugin is installed, the license is then applied to the TZWave Software Registration Menu (in TZWave: Help/Manage License Keys) which you must then Activate to that PC by sending your purchased license, your PC's Hardware ID (found at bottom of the Registration Menu window) to: info(at)talluscorp.com. You will soon receive an Activation code via email that is applied to the Registration Menu which makes that plugin permenant to that PC.

You should perform the above within the 30 day trial period to enjoy uninterrupted usage of the plugin with no rework needed between trial and licensed useage. Please allow up to two days for Tallus processing time for your requests. Most requests are processed within a few hours.

Software Installation[edit]

If you are installing to a pre Vista PC, you will need to have MDAC Version 2.8 installed on your MLServer PC prior to installation. You can check your current MDAC version by using:

MDAC Check Utility Download

If you have an earlier version you can get MDAC Version 2.8 at the following link:

MDAC Download

Install the ControlThink SDK on the computer where you would like to run TZWave. Make sure to license the ControlThink SDK as this plugin will not work until the SDK is licensed properly.

Please note that since TZWave is a standalone executable, it does not have to run on the same machine as MLServer. It will communicate with MLServer using TCP/IP and you only need to make sure that the computer running TZWave can communicate to the computer running MLServer.

During the installation, the installer will query whether you want to install .NET Version 3.5. If you are unsure whether the library is already installed, make sure that you check this box and allow the installation to occur. This library is required for the plugin to work properly.

Start the TZWave program. If the plugin is running in Trial or Expired licensing, the licensing menu page will appear so you can update the licensing. Once on Permanent licensing, the program will open directly to the configuration screen. You can also have MLSchedule (Tallus MLServer3 plugin) open the TZWave application in minimized mode, which is the typical implementation.


Licensing[edit]

The application will install with a 30 day trial. Once purchased, you will receive an email from Tallus with your license key that you should Copy / Paste into the applications's License field. If successful, you will see the Licensing Key Icon on the right side of that field go Green.

Copy the Machine ID value into an email that you should send to support (at) talluscorp (dot) com with a request for your TZWave Activation code. Once Tallus receives that request, you will be emailed back the Activation Key that you would Copy / Paste into the Activation Key field. Click the Activate button on the bottom left and you should see "This is a permanent license key" message at the top of the licensing window. TZWave application is then permanently licensed for that PC.


Configuration[edit]

Servers Tab

This tab deals with configuring which home automation server this software will communicate with. The two choices are the MainLobby Server from Cinemar or the Charmed Quark Controller from Charmed Quark Systems.

Zwave server.jpg


MainLobby Server Section

Server Name or IP Addr contains the IP address or name of the computer that MLServer is running. Even if MLServer is running on the same computer as TZWave, you must enter that computer name or IP address here. Next to Server Name or IP Addr, you will notice Port and the default value of 6246. Leave this value alone unless you receive instructions from support at Tallus to do otherwise. This is required to communicate with MLServer.

This program receives on contains the port number that TZWave receives its instructions from MLServer. The default is 9090 and, again, this should be left alone unless the support people from Tallus direct you to do otherwise.

Variable prefix allows you to preface the variables set from TZWave in MLServer. This gives you better control over the variables within MLServer by grouping them together. You can notice this within the following screenshot.


Zwave variables.jpg


CQC Section

This section is disabled at this time. This section is reserved for a future product enhancement to support the Charmed Quark Server.


ZWave Connection Tab

This tab deals with configuring the controller.

Zwave controller.JPG


Controller Information Section

This section is active when the ZWave Controller is connected. It will display information such as the HomeID of the controller, Controller Type, and Number of Devices.

The Number of Devices can be somewhat misleading as it is possible that it might be inaccurate under the following conditions. Initially, the Number of Devices reflects how many devices were read from the configuration database and not how many devices the controller has connected. This can only occur when the controller configuration does not match the configuration database because the controller was updated by an external ZWave configuration program.


Connection Section

Select the com port of the controller and click Connect (assuming the controller is physically connected). Within a few seconds, you should see the controllers HomeID, Controller Type and Number of Devices. Please note that the Serial Port and USB settings are mutually exclusive. You can select either one or the other, not both.

Once the controller is connected, then the Connect button becomes a Disconnect button.


Start Up Settings Section

Click Connect on Startup so that the controller connects when TZWave starts.

Click Reconnect on Failure if you want TZWave to attempt to reconnect to the controller when the link to the controller fails. This should never happen unless the controller has been physically unplugged from the back of the computer or it has failed. If this option is checked, then TZWave will attempt to reconnect to the controller once per minute.

Click Set Controller for Notify if you have Leviton Style Two-Way devices. Checking this option will add the controller to Group 1 of each device after controller has connected. This causes the controller to be notified whenever a device is turned on or off manually. Normally, ZWave has no notification mechanism for manual operation of devices. This feature is fairly new with the Leviton Two-Way devices. Do not select this option if you don't have Leviton switches. Selecting this option causes the controller connection to take quite a bit of time as each device has to be communicated with to set this option.


Controller Functions Section

These operations are only available when the controller is connected.

Create Secondary:

Clicking this button will start a transfer from the controller managed by TZWave to another controller. When the transfer is completed, the new controller will be a Secondary Controller within your mesh network. The controller managed by this plugin will still be a Primary Controller. This option is only available if the controller managed by TZWave is a Primary Controller.

Transfer Primary:

Clicking this button will start a transfer from the controller managed by TZWave to another controller. When the transfer is completed, the new controller will be the Primary Controller within your mesh network. The controller managed by this plugin will now assume a Secondary Controller role. This option is only available if the controller managed by TZWave is a Primary Controller.

Receive Configuration:

Clicking this button will start a transfer from a controller to the controller managed by TZWave. When the transfer is completed, the controller managed by TZWave may be a Primary or a Secondary Controller. The role of TZWave controller is directed based upon the type of transfer initiated by the sending controller. If the sending controller does a "Transfer Primary", then this controller will be a Primary Controller and the sending controller will become a Secondary Controller. If the sending controller does a "Create Secondary", then this controller will become a Secondary Controller and the sending controller will remain the Primary Controller.

Optimize or Repair:

Clicking this button will cause the controller to communicate with each and every device in order to optimize the mesh network. Generally, this option will not have to be selected. However, if you are getting an abundance of errors from the device (check the Events tab when in Verbose mode), then click this button. Optimizing the network is unique to ZWave. Each device is aware of its neighbor devices and this mesh is used by the device to determine how to communicate from the device to the controller and vice-versa. If a device becomes non-responsive, it could cause all of its neighbor devices to also become intermittantly non-responsive as they might request the non-responsive device to relay its status message.


Use With Caution! Section

These operations are only available when the controller is connected.

Hard Reset:

Clicking this button erase all of the information from the controller managed by TZWave. If the controller is a secondary, you will only have to relearn the devices from the Primary Controller using the "Receive Configuration" button. If this controller is a primary, then you will have erased the master devices information and routing table. This CANNOT be recreated from a secondary controller. Your only option will be to walk around the house and remove every device from the old mesh network and re-add each device to a new Primary Controller.

Initialize Device Table:

This button will ONLY be valid when the HomeID stored in the controller does not match the HomeID stored in the ZWave database. Clicking this button acknowledges that you wish to erase the database managed by TZWave and read the devices from the controller. The new devices read from the controller will be populated into the database managed by TZWave. Since all of the information about Aliases, Names and Locations are stored in the database, all of this information will be deleted and you will have to re-enter it.

Working with Devices[edit]

The Device tab deals with managing individual devices.


Zwave devices 1.JPG


This tab displays all of the devices contained within the ZWave mesh network. From this tab, you can control the devices and also change information such as the Alias, Name and Location of the device. Additionally, this tab contains settings for Polling, AllOn, AllOff, and the FastVar flags.

Device ID = The number of the device assigned by the controller when the device was added to the ZWave mesh network.

Alias = Your common name for the device. It must be a unique name.

Type = This is the type of device discovered by the controller. You can not change this.

Name = A name that will help you remember where the device is.

Location = A name that will help you remember where the device is.

Status = Last know status of the device. Can be updated when sending a command, or by the device updating the plugin (2-way devices only).

Level = Last known dim level. You can click on this field to select a new dim level.

Poll Enable = Check this if the device is not a Leviton two-way device. You do not need to have polling enabled if the device reports back its status on a manual activation. Test this by walking around the house, turn on a light and then look at the Devices Tab and see if the device status is showing the device in an ON state.

Poll Interval = This is an interval in minutes from 1 to 15. This field must be filled in BEFORE you can enable polling.


Zwave devices 2.JPG


All On = Check this option if the device can participate in an All On group. Only certain devices have this capability. If you check this option and the device does not support it, then nothing will happen when you issue the AllOn command.

All Off = Check this option if the device can participate in an All Off group. Only certain devices have this capability. If you check this option and the devices does not support it, then nothing will happen when you issue the AllOff command.

FastVar = Check this option if you want the plugin to update the variables for this device in MLServer without regard for Server Rules. When this option is checked, MLServer will not analyze the variables for this device when they change. This means that if the variables are used in Server Rules, nothing will happen.


Zwave devices 3.JPG


In this illustration, we will explore the buttons for the Device Tab. You will note that one of the devices is selected. Once a device is selected, the buttons become active.

Device Operations Section

These operations are only available when a device is selected.

On:

Clicking this button will turn on the selected device.

Off:

Clicking this button will turn off the selected device.

AllOn:

Clicking this button will turn on ALL devices with the AllOn flag set. You can select any device in order to perform this function. This can even be performed on a device without the AllOn flag set.

AllOff:

Clicking this button will turn off ALL devices with the AllOff flag set. You can select any device in order to perform this function. This can even be performed on a device without the AllOff flag set.

Ping Device:

Clicking this button will send a query to the device to determine if the device is responding. If you are having problems with the device, click this button to see if you can talk to the device. If you continue to have problems, then optimize the device (see next section).

Dim Level:

This slider is active whenever a Dimmer Type Device is selected. You can slide the handle to fine tune the dim level of the device.

Device Configuration Section

These operations are only available when a device is selected.

Optimize:

Clicking this button will cause the device to rediscover all of its closest neighbors. This is often done to attempt to heal a device that is starting to misbehave. This button will only be active if the ZWave controller is the primary controller. If the ZWave controller that TZWave is managing is a secondary controller, then this button will be grayed out (like the example in the illustration).

Controller Notify:

Clicking this button will register the controller within association 1 for this device. This is done so that the device will notify TZWave when a user manually turns on or off a light. Only certain devices support two-way operations. Currently, the only devices that support this new ZWave functionality are the Leviton devices.


Zwave devices 4.JPG


In this illustration, you will note that multiple devices are selected. Every function that you were able to perform by selecting a single device can be done after you have selected multiple devices. Hold the shift key in order to select a range of contiguous devices. Hold the control key in order to select devices that are not in contiguous order (as done in this illustration).

Working with Sensors[edit]

The Sensors tab deals with managing the HSM100 Multi-Sensor from Homeseer. This sensor will notify TZWave when motion is detected and additionally, inform the software of the amount of light in the room, the temperature in the room and the status of the sensor's battery.

The sensor will be triggered whenever any motion occurs within its maximum range of 30 feet. The sensor is also triggered when its timeout period of 60 minutes expires. The motion trigger can turn on lighting devices. The timeout trigger is mainly used to update the software with the temperature and ambient light within the room.

Please Note: The Sensors Tab will NOT appear if you do not have any HSM100 sensors.

Zwave sensor 1.JPG

This tab displays all of the HSM100 sensors contained within the ZWave mesh network. From this tab, you can control the sensors and also change information such as the Alias, Name and Location of the sensor.

Device ID = The number of the sensor assigned by the controller when the sensor was added to the ZWave mesh network.

Alias = Your common name for the sensor. This must be a unique name across all the devices, sensors, zones and scenes.

Type = This is the type of sensor discovered by the controller. You can not change this.

Name = A name that will help you remember where the sensor is.

Location = A name that will help you remember where the sensor is.

Status = Last know status of the device. This status can only have two states: Off or Triggered.

Temperature = The temperature of the room when the sensor is located. Temperature is only updated when the sensor is triggered.

Ambient Light = The amount of light in the room where the sensor is located. Ambient Light is only updated when the sensor is triggered.

Battery = The state of the battery on the sensor. Battery is only updated when the sensor is triggered.

Zwave sensor 2.JPG

Sensitivity = This is a field that you can set to change the sensitivity of the device. The default is 200. If you do not want the sensor to detect your pets, then set the sensitivity lower.

Wait Off = This is the time the device waits until it signals that the trigger event has ended. If no motion occurs within the "Wait Off" time period, then the sensor will inform the software that the trigger has ended. The default for this field is 20 minutes.

Enable LED = Uncheck this option if you do not want the LED on the sensor to flash when motion is detected. By default, this option is checked.

Sleep = Uncheck this option if you want the sensor to stay enabled. Normally, once the sensor has not detected motion, it will go to sleep until the next motion event is detected. The default is to have the sensor go to sleep between motion triggers. Unchecking this option will cause your batteries to drain in a very short time.

Light % = This is the percentage to turn on a light when the sensor triggers. This is only valid if you have registered devices with the sensor. Example: The sensor is located within a bathroom. You would like the lights to go on in the bathroom to 80% when motion is detected. Set this field to 80 and register the bathroom light with the sensor.

FastVar = Check this option if you want TZWave to update the variables for this sensor in MLServer without regard for Server Rules. When this option is checked, MLServer will not analyze the variables for this device when they change. This means that if the variables are used in Server Rules, nothing will happen.

Zwave sensor 3.JPG

Sensor Configuration Section

These operations are only available when some sensor has been selected. You will note that only one sensor can be selected at a time.

In order to use any of the buttons within the Sensor Configuration Section, you must first push the blue button on the side of the sensor. This will awaken the sensor for a period of 10 minutes. If you forget to push the blue button, any operation started with these buttons will fail.

Get Parameters

Clicking this button will retrieve from the sensor the values for "Sensitivity, Wait Off, Enable LED, Sleep and Light %"

Set Parameters

Clicking this button will set into the sensor the values for "Sensitivity, Wait Off, Enable LED, Sleep and Light %"

Controller Notify

Just like the two-way devices on the Device Tab, a sensor will only inform TZWave of a trigger event if the ZWave Controller for this software is registered with the sensor. This MUST be done manually since the sensor must be enabled by depressing the blue button on the side of the sensor before the controller can be registered.

Register Devices

The sensor can turn on up to three lighting devices when motion has been detected. In order to register these devices with the sensor, you will have to use this function. Before you depress the "Register Devices" button, go to the Devices Tab and select from one to three devices that you would like to register with the sensor. Then come back to this screen, highlight the sensor to register and push this button. Make sure the sensor has been turned on by pressing the blue button on the side of the sensor before you start this operation. Please NOTE that although this is a useful function, this software is NOT notified when a registered device is turned on by the sensor. If you want a notification for each light turned on by the sensor, then software like MLServer or CQC is the better choice to turn on the lights when the sensor is triggered.

Working with Zones[edit]

This tab deals with placing groups of devices into zones.


Zwave zones 1.JPG


Zones can be used to group like devices together so that all devices within a zone can be turned on or off with one command. Zones are not officially a part of the ZWave specification. However, it is sometimes nice to turn on or off groups of devices. The reasons why you would want to do that are entirely up to you. TZWave is simply providing a mechanism whereby it is possible.

Zone Create/Delete Section

New = Pushing this button will create a blank entry into the zones table. At this point, you MUST enter a valid Alias that will be used to turn on or off the devices within the zone. All Aliases in TZWave must be unique. This means that the Alias that you enter here cannot be a duplicate with another alias within the Zones OR Devices Tab.

Delete = If you highlight a zone in the zones table, then you can delete that zone with this button. Note that this operation is final and it will not ask you if you are sure. Once you hit this button, the zone will be deleted.

Zwave zones 2.JPG

Notice in the above example that the NEW button was pressed. This creates a blank entry in the zones table. You would now highlight that entry and type an alias into the field.

Zwave zones 3.JPG

As you can see here, we entered the alias of FrontEntrance. At this point, you would select the devices from the Device Members table that you want to be part of this zone. If you have multiple devices that will be part of zone (which is very likely), then you can use the Control key while clicking on an entry to select multiple non-contiguous rows. If you hold down the Shift key while clicking on an entry, you will be able to select multiple contiguous rows.

Confirm Section

Save = This button will save any new or modified zone into the database. At this point, the zone is capable of being used.

Cancel = This button will cancel any work in progress. Any work on a zone that was being created or modified at this point will be lost.

Zwave zones 4.JPG

Zone Operations Section

On = This button will turn on all devices in the highlighted zone.

Off = This button will turn off all devices in the highlighted zone.

Using the above example, you can also modify the zone highlighted. Notice that the GarageEntrance zone is highlighted. The members or devices that are in this zone are the LaundryMain and KitchenHall. This is a valid scenario within my house. When I open the garage door, I want the lights to go on in the Laundry Room (which is right off the garage) and also in the Hallway to the Kitchen. Maybe I also want to add GarageStairs device to this zone. I would then highlight the GarageStairs row in the Device Members table (remember to use the control key while selecting this device or you will lose the other members). After I have added the third device to the zone, I would hit the Save button to write my new zone to the database. After the zone is saved, it is free to use. (See this example in the next picture).

Zwave zones 5.JPG



Working with Scenes[edit]

The Scenes Tab deals with placing groups of devices into scenes.

Please Note: The Scenes tab will not appear if you do not have any scene capable devices. You can tell if you have scene capable devices by looking in the Device Tab and checking the Type field. The type of device will be either BinarySceneSwitch or MultilevelSceneSwitch.


Zwave scenes 1.JPG


Scenes are used to create lighting "moods". With a scene, it is possible to turn on or off up to 32 different devices simultaneously. Each light can be turned on or off to a different value and at a different rate. For instance, I may want to create a scene that will light the house when the garage door opens. In order to get to the kitchen from the garage, I have to pass through the laundry room. So, let's start with:

Turn on garage lights
Turn on laundry room lights
Slowly turn on hallway lights to kitchen
Turn on kitchen lights

Creating a Scene

Scenes are created by recording the current state of the lights that you want to include in the scene. So, before you start, go to the Devices Tab and turn on or off the lights that you wish to include in this scene. If you want the kitchen hallway light to be at 53% in the scene, make sure that you turn it on to 53% in the devices tab before you start!

In the example below, I am going to create a test scene with the four devices listed above: GarageMain, LaundryMain, KitchenHall and KitchenMain. I have turned on the lights to levels that I wish to attain in the scene.

Zwave scenes 2.JPG


Once the lights are turned on (or turned off) for the devices that you wish to include in the scene, you would navigate back to the Scenes Tab (as pictured below).


Zwave scenes 3.JPG


Highlight one of the entries in the Scene panel. You will note that there are already 255 different entries in this panel. They are numbered from 1 to 255. Note also that there is a column for an alias. This is NOT optional. You must include an alias or the scene will not become active. The alias in the scene panel must be unique across the devices, zones and scenes. There can be no duplicate alias names.

Once you have highlighted the scene entry, enter the alias that you wish to use. In the example below, I have used the name "ComingHome".


Zwave scenes 4.JPG


Now, using the Device Members Panel, select the devices that you wish to add into the scene. In our example, that would be the devices named: GarageMain, LaundryMain, KitchenHall and KitchenMain. You will also note that each device has a pull down called Ramp Rate. The ramp rate can be anywhere from 0 to 10. This number is the time in seconds that it takes for the device to reach the level that you specified. Only devices that are MultiLevel switches can have a ramp rate. You will note in the example below that every device has a ramp rate. However, you can only change the ramp rate for devices that are of the MultiLevel (dimmer) type.

In our example, I will change the ramp rate for KitchenHall to 8. This means that it will take 8 seconds to turn on the light to the level specified. The default is 4 seconds.

Once you have selected all the devices that you want to include into the scene, hit the Save button to register this scene with all the devices in the zwave network.


Zwave scenes 5.JPG


Scene Operations Section

Using the example that we have been working on, let's activate the scene and make sure it works. Remember, that a scene does NOT have an OFF. A scene just does what you have saved. In our example, we turned ON four devices. If we want to turn off those devices, then we MUST have a second scene that turns off the devices. An alternative would be to create a zone with the same devices and turn off the zone. Or we could turn off each of the devices individually. In order to test our example, go to the Device Tab and turn off each of the devices. Then, come back to the Scene Tab.

In the picture below, highlight the ComingHome scene. You will see that the four devices in the scene will be highlighted. At this point, you could modify the scene by adding or removing devices by simply selecting or deselecting the devices that you wish to add or remove and then hitting the Save button.

In this case, we will want to activate the scene in order to test it. So, hit the Activate button. You will see that the lights will come on to the correct level (as seen in the Device Tab) and the highlighted devices will be deselected.


Zwave scenes 5.JPG


Scene Delete Section

Delete = If you highlight a scene in the scenes table, then you can delete that scene with this button. Note that this operation is final and it will not ask you if you are sure. Once you hit this button, the scene will be deleted.


Confirm Section

Save = This button will save any new or modified scene into the database. At this point, the scene is capable of being used.

Cancel = This button will cancel any work in progress. Any work on a scene that was being created or modified at this point will be lost.

When a Device doesn't work[edit]

This tab deals with devices that are having some type of problem.


Zwave response.JPG


There are two types of failures that can occur for any individual device. The first is that the device becomes non-responsive. The second is that the device has timed out.

Non Responsive Devices are a problem and should be examined. This occurs when an order is issued to the device and the controller cannot contact the device.

Timed Out Devices are not really a problem, but should be monitored to make sure that it doesn't start to become a problem. This occurs when an order is issued to the device and the controller is actually able to talk to the device, but the device cannot perform the operation within a set period of time. The period of time is set by the ZWave Protocol and cannot be changed. You will note that sometimes the operation does really occur, but the response times out. So, your lights may turn on, but TZWave will get no confirmation that it occurred.

Since devices can time out at any time, based upon how busy the device is, we have provided a button to remove these entries.

Devices that have not responded can ONLY be removed from the "not responding" table when the device comes back online. They will stay in this table until we get a good response from the device.

Configuring MLServer to work with TZWave[edit]

TZWave will work with either Tallus's MLComDevice plugin (recommended) or Cinemar's MLTCPSend plugin.

MLComDevice

.....NOT TESTED YET.....

It is required that you have loaded the MLComDevice plugin for MLServer. This plugin is used to communicate with TZWave and pass it commands.

Mlserver mlcomdevice.jpg


Configuring MLComDevice

Double click on the MLComDevice plugin (Plugin Settings) and click on the Families tab for the MLComDevice plugin in MLServer. You should see a screen like this:

Mlserver mlcomdevice 1.jpg

MLComDevice doesn't require any Header / CheckSum / End Cmd or EndTrig settings as commands are sent using MLComDevice's Send method.


Go into the Settings tab for the MLComDevice plugin in MLServer. You should see a screen like this:

Mlserver mlcomdevice 2.jpg


In this screen, you need to create a Device with an IP and a Port. The Device is used in your commands within MLServer to send commands to TZWave. When you send a command from MLServer like MLComDevice|Send~ZWave1~KitchenLights.SwitchPower_On.50, the component in this example that says ZWave1 is the Device used in MLComDevice.

Select "'TZWave'" from the Family drop down list. Type a name like "ZWave1" in the Name: field.

The IP address is the computer that is running TZWave application.

The Port is the address that TZWave is listening on to receive commands from MLServer. The Port must match what is configured in the Connection page of the TZWave application.

Note that this Port has to be open on all Firewall / Antivirus protections on the TZWave PC.

Select "'ASCII"' in the Encoding drop down.

Make sure TCP is checked in the Control box. Uncheck "Disable" to make the ZWave1 Device active.

Click "'Save as New'" button.

You should now see the ZWave1 in your Devices tab.

Mlserver mlcomdevice 3.jpg

In the Families tab, click on the Commands tab. Here, you should be able to edit the commands to send the TZWave application for your needs. The Triggers tab will be used in a future release of TZWave to receive the commands from TZWave application. There should be no Triggers configured until this update is available.

Mlserver mlcomdevice 5.jpg
When the TZWave.exe is running and configured properly, and the MLComDevice Zwave device is enabled, you should see this type of connection message in the MLComDevice log: Mlserver mlcomdevice 6.jpg




MLTCPSend

If you choose to use MLTCPSend instead of MLComDevice, it is required that you have loaded the MLTCPSend plugin for MLServer. This plugin is used to communicate with TZWave and pass it commands.

Mlserver mltcpsend.jpg


Configuring MLTCPSend

Go into the Settings mode for the MLTCPSend plugin in MLServer. You should see a screen like this:

Mlserver mltcpsend 2.jpg


In this screen, you need to create a Device with an IP and a Port. The Device is used in your commands within MLServer to send commands to TZWave. When you send a command from MLServer like MLTCPSend|Send~ZWave~KitchenLights.SwitchPower_On.50, the component in this example that says ZWave is the Device used in MLTCPSend.

The IP address is the computer that is running TZWave.

The Port is the address that TZWave is listening on to receive commands from MLServer. The Port is configured in the Connection page of the TZWave application.


TZWave Startup Options

The normal means to launch TZWave is to have MLServer launch it during MLServer startup.

TZWave launch command syntax:
tzwave.exe /minimize

This is best triggered using Tallus's MLSchedule plugin that has a "Frequency: MLServer launch" setting. This will "schedule" for a "MLFileOpen|C:\Program Files\Tallus\bin\TZWave.exe~/minimize" command to occur which launches TZwave minimized to the Windows system tray. You can set an "offset" of 1 minute to have MLSchedule launch TZWave one minute after MLServer has finished it's startup.

Mlserver tzwave 1.jpg


For additional flexibility, TZWave application can also be installed on a non MLServer PC. This is especially helpful if your MLServer PC is not located near the ZWave USB hardware adapter.

To automatically launch TZWave on a remote PC: Install the ClientSvc Agent on the remote TZWave PC. Install MLClientSvc plugin on the MLServer PC. Follow the instructions in MLClientSvc Wiki to configure it's networking.
Configure MLSchedule to run on MLServer launch this command:
Sys.PCAliasName|Send~Run~C:\Program Files\Tallus\bin\TZWave.exe /minimize
When you launch MLServer, MLSchedule will send the MLClientSvc plugin the command to tell the ClientSvc Agent to startup TZWave minimized on the "PCAliasName" defined PC.

Supported MainLobby3 Server Commands[edit]

TZWave receives all of its commands from MLServer using either MLComDevice or MLTCPSend. Please see the MLComDevice or MLTCPSend configuration section for more detail.

MLComDevice|Send~MLComDevice-Device~Command.ID/Alias.OptionalParameter
or
MLTCPSend|Send~MLTCPSend-Device~Command.ID/Alias.OptionalParameter

where:

MLComDevice-Device and MLTCPSend-Device = The name of the Device in either the MLComDevice or MLTCPSend plugin.

Command = The command that you wish to send to TZWave. The valid commands are:

On <optional: Level = lighting level>
Off
Toggle
AllOn
AllOff
Bright
Dim
ZoneOn
ZoneOff
SceneActivate
Shutdown

Specific Commands

MLComDevice|Send~ZWave1~On.ID/Alias.<optional level>
or
MLTCPSend|Send~ZWave~On.ID/Alias.<optional level>

Turns the specified light on. If the optional level is included in the command the switch will go on to that level. If the level is not included the switch will turn on to the level it was at the last time the light was on.

MLComDevice|Send~ZWave1~Off.ID/Alias
or
MLTCPSend|Send~ZWave~Off.ID/Alias

Turns the specified light off.

MLComDevice|Send~ZWave1~Toggle.ID/Alias
or
MLTCPSend|Send~ZWave~Toggle.ID/Alias

Toggles the light on or off based on its current status.
ex: MLComDevice|Send~ZWave1~Toggle.2

MLComDevice|Send~ZWave1~AllOn
or
MLTCPSend|Send~ZWave~AllOn

Turns on all of the lights that are selected to participate in the AllOn group. AllOn must be selected on each device in the Devices Tab in order to be affected by this command. Please note that the AllOn function is device specific. If your device does not support this function, then this command will function much like a simple Power On.

MLComDevice|Send~ZWave1~AllOff
or
MLTCPSend|Send~ZWave~AllOff

Turns off all of the lights that are selected to participate in the AllOff group. AllOff must be selected on each device in the Devices Tab in order to be affected by this command. Please note that the AllOff function is device specific. If your devices does not support this function, then this command will function much like a simple Power Off.

MLComDevice|Sendw~ZWave1~Bright.ID/Alias.<optional amount>
or
MLTCPSend|Send~ZWave~Bright.ID/Alias.<optional amount>

Brightens the specified light by the amount listed in the optional amount argument. If you don't specify an optional amount, then the default amount will be 3%.

MLComDevice|Send~ZWave1~Dim.ID/Alias.<optional amount>
or
MLTCPSend|Send~ZWave~Dim.ID/Alias.<optional amount>

Dims the specified light by the amount listed in the optional amount argument. If you don't specify an optional amount, then the default amount will be 3%.

MLComDevice|Send~ZWave1~ZoneOn.Alias
or
MLTCPSend|Send~ZWave~ZoneOn.Alias

This command will turn on a zone specified by the alias. Please note that unlike a device which can have both a device ID and/or Alias, a zone can ONLY have an Alias.

MLComDevice|Send~ZWave1~ZoneOff.Alias
or
MLTCPSend|Send~ZWave~ZoneOff.Alias

This command will turn off a zone specified by the alias. Please note that unlike a device which can have both a device ID and/or Alias, a zone can ONLY have an Alias.

MLComDevice|Send~ZWave1~SceneActivate.Alias
or
MLTCPSend|Send~ZWave~SceneActivate.Alias

This command will activate a scene specified by the alias. Please note that unlike a device which can have both a device ID and/or Alias, a scene can ONLY have an Alias.

MLComDevice|Send~ZWave1~Shutdown
or
MLTCPSend|Send~ZWave~Shutdown

This command will shutdown the TZWave application.


ID/Alias = The Alias or ID# of the device that you wish to manipulate.

You can use both the ID# (see the TZWave Device Tab - the leftmost column has the ID#) or the Alias. The Alias is a unique name for the ZWave device (example: MasterBedroomRecessedLights). The default scenes provided use ID# so that the scenes can be used with minimal adjustment. You can later change this to Alias name, so that the device is easier to remember and specific to your setup. Please note that ALL aliases in TZWave must be unique. Aliases are used by Devices, Zones and Scenes. You cannot use the same alias in a Zone or Scene that has already been used somewhere else (like a Device). Also, Zones and Scenes do not have ID#'s. In order to use a Zone or Scene, you must create the Zone or Scene by giving it a valid Alias.


Variables Created[edit]

Two sets of variables are created for each lighting device. The first set is based upon the device id (NodeID) of the ZWave device. The second second is based upon the alias that you have assigned to that device. If you have not assigned an alias to a device, then the second set of varibles will not be created.

All variables created will use the prefix that you set during the configuration section. If the prefix is zwave, as is used in our example, then the variables that look like the example are created. We recommend that you use a prefix as this will help with grouping your variables within MLServer.

Please note that alias names can have spaces in them. KitchenLights could also be "Kitchen Lights" (with a space included).

Lighting Device Variables

zwave_32_alias=KitchenLights

zwave_32_device_type=MultiLevelSceneSwitch

zwave_32_id=32

zwave_32_last_status_change=3/6/2008 7:58:52 AM

zwave_32_numeric_value=0

zwave_32_location=Kitchen

zwave_32_name=Main Lights

zwave_32_status=off

zwave_32_value=0%

zwave_kitchenlights_alias=KitchenLights

zwave_kitchenlights_device_type=MultiLevelSceneSwitch

zwave_kitchenlights_id=32

zwave_kitchenlights_last_status_change=3/6/2008 7:58:52 AM

zwave_kitchenlights_numeric_value=0

zwave_kitchenlights_location=Kitchen

zwave_kitchenlights_name=Main Lights

zwave_kitchenlights_status=off

zwave_kitchenlights_value=0%

HSM100 Multi-Function Sensor Variables

The HSM100 Multi-Function Sensor will set the following variables within the automation software. Many of the variables are the same as for a lighting device. Some have been removed (value and numeric_value) and three more have been added (battery, temperature and light). Battery and Temperature are self-explanatory. Light denotes the amount of ambient light where the sensor is located.

zwave_57_alias=HallbathSensor

zwave_57_device_type=RoutingMultilevelSensor

zwave_57_id=57

zwave_57_last_status_change=3/6/2008 7:58:52 AM

zwave_57_location=Hall Bathroom

zwave_57_name=Sensor

zwave_57_status=off

zwave_57_battery=100

zwave_57_temperature=72.4

zwave_57_light=20

zwave_hallbathsensor_alias=HallbathSensor

zwave_hallbathsensor_device_type=RoutingMultilevelSensor

zwave_hallbathsensor_id=57

zwave_hallbathsensor_last_status_change=3/6/2008 7:58:52 AM

zwave_hallbathsensor_location=Hall Bathroom

zwave_hallbathsensor_name=Sensor

zwave_hallbathsensor_status=off

zwave_hallbathsensor_battery=100

zwave_hallbathsensor_temperature=72.4

zwave_hallbathsensor_light=20

Glossary of Terms[edit]

Node (Unit) - A single module entity (device) within the Z-Wave network. It could be a plug-in dimmer module, appliance module, wall switch, dimmer switch, etc. There are 160 addressable Z-Wave unit nodes as described in the Z-Wave protocol.

Device - Please see Node.

Group - A set of one or more modules (devices) that are to be operated together as if they were one device. More specifically, every module included in a group will switch on or off together as that group is turned on or off. When a group is activated, each Light module in that group turns on, returning to its last dim level. This level will, in general, differ from module to module. Appliance Modules may also be included in groups. There are 64 Z-Wave groups in the Z-Wave protocol.

Scene - A scene is a pre-programmed custom lighting set-up. With scenes, you can turn specific lights on/off and dim individual or group lights. Scenes can turn on a select group of lights dimmed to your preference; perfect for watching movies. You can also use scenes to automatically turn on lights when you are not home, or wake up with a gradual brightening of your bedroom lights during the weekdays. There are 32 Z-Wave lighting scenes in the Z-Wave protocol. Each scene can have a maximum of 58 Nodes or individual devices assigned to it.

Replicate - To transfer or copy the setup and configuration information between any two controllers. Controllers can be stationary (known as Static Controllers) or handheld.

Route - If an obstacle or radio dead spot exists between two Z-Wave modules, Z-Wave automatically repeats or passes the signal from one device to the next, effectively going around obstacles and radio dead spots in a building. Likewise, if two devices are not within range of each other, a route will be created when the device is added to the network that will identify devices within range. Those devices will automatically retransmit any signals from the controller to a device that is not within range of the controller. This technology essentially enables devices to communicate at long ranges since the signal is repeated or bounced until it reaches the receiving device.

Status Reply - The process of a device transmitting its current state (on, off, dim, etc) in response to an individual node or unit change command from a controller. The original specification of the protocol only allowed for devices to respond with their status to the specific controller that commanded their change. So, if you use a handheld controller, then our device driver will not see the device status since it is not transmitted to us. As well, if a user manually turns on or off a light, this status will also not be transmitted to us. Newer devices can transmit their change status to any controller added to group one (1). Our device driver will attempt to always add our controller to each devices group one (1). Some older devices may reject this command. In that case, polling should be enabled.

Polling - Controllers can send periodic status request messages to devices. Each device will respond with its current status when it receives a poll request message. This was the only way in older devices to determine if a user had turned on or off a device manually or with a handheld controller. Newer devices do not have this problem as long as the PC controller used by your PC software is added to that devices group one (1).

Troubleshooting[edit]

Device will not report status when user turns on light

Only two-way devices like the Leviton series will report status when you manually turn on a light. If you have a two-way device, make sure that you have Set Controller for Notify on the Connection tab of the application. This registers the controller to notify when a device is initialized. This only happens during the startup of the application. You can highlight the device in the Devices tab and hit the Controller Notify button in order to register the device after the application has started. Try this and then walk over and turn on the light at the switch. Make sure that you have logging turned on and in Verbose mode before trying. This way you can see the status when you hit the Controller Notify button and when you turn on the light.

High number of Timeouts or Not Responding when talking to devices

Several things could be a problem.

1. The longest distance allowed between a device and a controller is about 30 feet. This distance can be reduced if you have walls or other obstructions between the controller and the device. Make sure that you don't have too long a distance between the controller and the device. If you think you do, then try to either move the controller closer (if possible) or add another device between the failing device and the controller.
2. You may have a device that has an incorrect routing table or the device is starting to fail. Try to Optimize the entire network in order to rebuild the routing tables within all the devices.

The device is not showing ON after I turn it on with a handheld controller

Handheld controllers CANNOT report status back to the PC when they turn on or off lights. If you do this often, you might want to turn on polling in the Devices tab for those devices that will be turned on with a handheld controller.

I have an defined a Server Rule in MLServer and it is not working properly

Variables that are used in Server Rules should not be set using the Fast option. Check to make sure that the Fast option is not checked in the Devices tab for those variables that you are using in your Server Rules.

I have a HSM100 sensor and I registered a light to turn on when the sensor is tripped. How come I do not see that light go on in the Devices Tab?

The reason that you do not see the light turn on or off is because the HSM100 turned on the device. The ZWave protocol only allows for a notification to the controller when a user manually turns on/off a light at the switch or the controller turns on/off a light. The HSM100 is not a user or the zwave controller, so when it turns on/off a device, the software will not get a notification. If you need to know if lights are turned on/off when a sensor trips, then you should not register any devices, but rather hit the controller notify button on the Sensors tab. Then, when you get a notification from the sensor, have the MLServer or CQC software issue a command to turn on/off the light.

Bugs[edit]

1. Currently, the AllOn and AllOff functions do not work correctly. When you issue an AllOn command, every light will go on. What is supposed to happen is that only the lights with the AllOnEnable flag checked are supposed to go on.

New Feature Requests[edit]

Release Notes[edit]

V 2.5.8.0 - Published 10/20/2010

1. Changed licensing components to allow for licensing on Win7 operating systems. Has had very limited testing.

V 2.5.6.0 - Published 6/26/2009

1. Allow users to set the controller notify function AFTER the software has already connected to the ZWave controller.

2. Added some more error checking on the IP address of the MLServer. It was possible previously to enter a blank for the address.

3. Added checking to make sure that the ZWave controller can talk to the motion sensors. There are certain controllers that cannot talk to the sensors using the SDK. If we discovered one of these controllers before, TZWave would abort. Now, it recovers gracefully. However, it will not talk to the motion sensor as this functionality only exists in the SDK for the ThinkStick controller.

4. Added new screens in order to support the CQC automation server. This feature is still not completely functional and is "grayed out" at this time.

5. Improved the performance of individual devices by about 75%.

V 2.1.7.0 - Published 3/31/2009

1. Fixed miscellaneous licensing bugs.

2. Fixed bug in sensor where the time to turn off the light was always reset to 20 seconds.

V 2.1.6.0 - Published 3/25/2009

1. Fixed bug where the Get Parameters function did not work properly for the HSM100 sensor.

2. Fixed bug where the software would occasionally get a "Index out of range" exception.

3. Fixed bug where the software was registering the controller before any devices for the HSM100 sensor. This caused the registered device to turn on slowly after the sensor was tripped because it was spending quite a bit of time to talk to the controller.

V 2.1.5.0 - Published 3/8/2009

1. Add functionality for HSM100 Multi-Function Sensors from Homeseer.

2. Fixed bug where sensors, scenes and zones did not load properly from the database file at startup.

3. Added capability where user can change Level field in Devices Tab to change the light level of the device.

V 2.1.4.0 - Published 3/2/2009

1. Fixed bug where a scene could be saved with no devices selected. This would cause an exception.

2. Fixed bug where a zone could be saved with no devices selected. This would cause an exception.

V 2.1.2.0 - Published 2/28/2009

1. Fixed bug where BRIGHT command from PC would not work above 89%.

2. Fixed bug where DIM command from PC would not work when above 98%

3. Fixed bug where the zwave controller would not restart after a manual disconnect.

4. Fixed bug where ALLON, ALLOFF, and SHUTDOWN commands from MLServer did not get processed correctly.

5. Fixed other miscellaneous bugs

V 2.1.0.0 - Published 2/18/2009

1. Changed command Format from Alias.Command.<Optional Parameter> to Command.Alias.<Optional Parameter>

2. Added Scene Capability

3. Added Shutdown Command sent from Home Automation Server

4. Fixed a bug where the ON command turned the light on to 100% if no optional level was specified. The light should turn on instead to the LAST level the light was at.

V 2.0.0.0 - Published 2/14/2009

1. First Beta Release