Z-Wave Shared Methods

These methods are shared among non-controller Z-Wave Devices. For most systems, you won't need to use these methods, as the default configuration set up by the Virtual Wiring System works well. These methods are good for doing lower level device configuration, control and monitoring, and they are useful if you want to learn more about how Z-Wave devices work.

Z-Wave Command Methods

The following methods allow you to send low level Z-Wave commands to a device in the system.

do_cmd method:

The do_cmd method sends a Z-Wave command to a device. It takes 3 parameters: a command class number, a command number, and any numeric parameters required by the command.

As an example, here is how one asks a device implementing the Basic Command Class for its state. The number for the Basic Command Class is 0x20. Getting state is done by the "get" command, which, for the Basic Command Class, is command number 2. The get command takes no parameters. If we assume our Device has ID "zwave_device", type into the system Console:

poke "zwave_device", "do_cmd 0x20, 2"

You should get back a successful response, like:

[true,true]

Go to the Log screen and look at the bottom. You will see something like this:

status: "Unhandled device Z-Wave packet: FRAME(0x01): L=0x09 RQ_RSP=0x00 CMD_REQ=ACPT_RPT(0x04) ??=0x00 SRC_ID=0x06 L=0x03 BASIC(0x20): RPT_NUM=0x03 OFF_ON=0xFF CHK=0x2B" (from: user_name@, ZWAVE[zwave_device])

It is the result of your command. The log describes it as "Unhandled" because the system got a response it didn't ask for (you, the user, asked for it).

do_class_set method:

This method runs the set method on a device's command class. The do_class_set method is used only rarely as it adds no additional functionally over that provided by the do_cmd method. It has the single advantage that the do_class_set method is more Script friendly, whereas the do_cmd parameters generally conform to Z-Wave's 1 byte per parameter commands. Generally, users should use the do_cmd method instead of this one.

The do_class_set method takes 2 or more parameters. The first is the command class number. The second and any others are the parameters that the set command uses.

Z-Wave Informational Methods

The following commands are used to display and acquire information about Z-Wave devices.

get_zwave_info method:

This method asks a Z-Wave Device to acquire device information from its Z-Wave device. It is used when a device's runtime information (supported command classes, for example) is not yet known by the Device and one wishes the Device to learn it. This method is handy when the Z-Wave device is offline during initialization. This method takes no parameters.

zwave_info method:

This method returns the information available about a Z-Wave device in a human readable string.

Other Z-Wave Device Commands

associate method:

This associates the system controller with a Z-Wave device's groups. Associating the controller with a device allows the device to send the controller real time state changes. Not all devices support the Association Command Class, but when they do, associating a controller with a device's groups helps do away with the need to poll the device for state changes. This command is typically performed in a Device's installation Script, so there is usually no need to run it.

queue_command method:

The queue_command method puts a command into a Device's wakeup queue. When one needs to send a command to a Z-Wave device which sleeps (most battery powered devices sleep), one should use the queue_command method. The Device will queue the command and send it to the Z-Wave device the next time it wakes up. Though non-sleeping devices implement the queue_command method, they typically don't wakeup, so they will never take commands from their wakeup queue. For this reason, the queue_command method should only be used for devices which sleep.

The queue_command method takes a single parameter: a command string to enqueue. It is commonly used in Scripts when configuring devices which sleep. The following command enqueues an associate command for a sleeping device with ID "zwave_device":

poke "zwave_device", "queue_command(\"associate\")"