Tcl ZWave extension

zwave - Tcl library for interacting with openzwave

Synopsis

package require Tcl 8.5
package require zwave 0.4

zwave controller subcommand ?arg ...?
zwave driver subcommand ?arg ...?
zwave group subcommand ?arg ...?
zwave init ?name value ...? ?prefix?
zwave node subcommand ?arg ...?
zwave release
zwave value subcommand ?arg ...?
zwave version

Description

The zwave package is designed to add support for Z-Wave devices to Tcl applications. The package uses the OpenZWave library for the low level communication.

The zwave package introduces a new zwave command with several subcommands described below.

zwave controller subcommand ?arg ...?

Provides access to a ZWave controller. The subcommands are described in Controller commands below.

zwave driver subcommand ?arg ...?

Provides access to a ZWave driver. The subcommands are described in Driver commands below.

zwave group subcommand ?arg ...?

Provides access to a ZWave group. The subcommands are described in Group commands below.

zwave init ?name value ...? ?prefix?

Initialize the OpenZWave library. This command must be executed before most of the other subcommands can be used. The following options are available:

-appendlogfile boolean: Append new session logs to existing log file (false = overwrite)
-associate boolean: Enable automatic association of the controller with group one of every device.
-assumeawake boolean: Assume Devices that Support the Wakeup CC are awake when they are first queried.
-configpath path: Path to the OpenZWave config folder.
-consoleoutput boolean: Display log information on console (as well as save to disk).
-drivermaxattempts value: Maximum number of attempts to load a driver.
-dumptriggerlevel level: Default is to never dump RAM-stored log messages
-enablesis boolean: Automatically become a SUC if there is no SUC on the network.
-exclude classes: Remove support for the specified command classes. The classes argument should be a list of class names, such as COMMAND_CLASS_BASIC, COMMAND_CLASS_NO_OPERATION, etc.
-include classes: Only handle the specified command classes. The Exclude option is ignored if anything is listed here. The classes argument should be a list of class names, such as COMMAND_CLASS_BASIC, COMMAND_CLASS_NO_OPERATION, etc.
-intervalbetweenpolls boolean: if false, try to execute the entire poll list within the PollInterval time frame.
-logfilename filename: Name of the log file.
-logging boolean: Enable logging of library activity.
-networkkey key: The network key to use for secure communication with nodes. A network key must be a list of 16 integers between 0 and 255.
-notifytransactions boolean: Notifications when transaction complete is reported.
-performreturnroutes boolean: If true, return routes will be updated.
-pollinterval milliseconds: Poll interval.
-queueloglevel level: Save (in RAM) log messages equal to or above LogLevel_Debug
-refreshallusercodes boolean: if true, during startup, we refresh all the UserCodes the device reports it supports. If False, we stop after we get the first "Available" slot (Some devices have 250+ usercode slots! - That makes our Session Stage Very Long)
-retrytimeout milliseconds: How long do we wait to timeout messages sent
-saveconfiguration boolean: Save the XML configuration upon driver close.
-saveloglevel level: Save (to file) log messages equal to or above LogLevel_Detail
-suppressvaluerefresh boolean: if true, notifications for refreshed (but unchanged) values will not be sent
-userpath path: Path to the user's data folder.

The prefix argument specifies a command to be executed (with additional arguments) whenever an event is generated by the OpenZWave library. For each OpenZWave event a number of arguments are appended to prefix so that the actual command is as folows:

prefix event data The data argument is a dict containing information relevant to the event. Possible events are: allnodesqueried, allnodesqueriedsomedead, awakenodesqueried, buttonoff, buttonon, controllercommand, createbutton, deletebutton, driverfailed, driverready, driverremoved, driverreset, essentialnodequeriescomplete, group, manufacturerspecificdbready, nodeadded, nodeevent, nodenaming, nodenew, nodeprotocolinfo, nodequeriescomplete, noderemoved, nodereset, notification, pollingdisabled, pollingenabled, useralerts, valueadded, valuechanged, valuerefreshed, valueremoved

zwave node subcommand ?arg ...?

Provides access to a ZWave node. The subcommands are described in Node commands below.

zwave release

Release the OpenZWave association. This will clean up any resources used in the OpenZWave library. Depending on some options, the library will save its configuration.

zwave value subcommand ?arg ...?

Provides access to a ZWave value. The subcommands are described in Value commands below.

zwave version

Report the version of the OpenZWave library. This is the only command that may be used before the OpenZWave library is initialized.

Driver commands

zwave driver add path: Set up a driver for a Z-Wave controller.
zwave driver remove path: Remove the driver for a Z-Wave controller, and close the controller.

Controller commands

zwave controller exclude homeid

Prepare to exclude a node from the network. Read the instructions of the device to be excluded on how to put it into exclusion mode.

zwave controller heal homeid ?init?

Heal a network by requesting all nodes to rediscover their neighbors. This may take a while on larger networks. The init argument controls whether return routes initialization will be performed. It defaults to true.

zwave controller include homeid ?secure?

Prepare to include a node into the network. Read the instructions of the device to be included on how to put it into inclusion mode. The secure argument controls whether the Network Key is initialized on devices that support the Security command class.

zwave controller info homeid ?name?

Retrieve one or all controller options. Available options are:

bridge

Flag indicating if the controller is using the bridge controller library. A bridge controller is able to create virtual nodes that can be associated with other controllers to enable events to be passed on.

interface

Reports the controller interface type. Possible values are: serial, hid, and unknown.

nodeid

The node ID of the Z-Wave controller.

path

The controller interface path.

primary

Flag indicating if the controller is a primary controller. The primary controller is the main device used to configure and control a Z-Wave network. There can only be one primary controller - all other controllers are secondary controllers.

queue

Count of messages in the outgoing send queue.

suc

The node ID of the Static Update Controller.

type

A string containing the Z-Wave API library type used by a controller. The possible library types are:

Static Controller
Controller
Enhanced Slave
Slave
Installer
Routing Slave
Bridge Controller
Device Under Test

version

The version of the Z-Wave API library used by the controller.

zwave controller reset homeid ?mode?

Reset the Z-Wave controller. Two modes are available:

soft: Reset the controller without erasing its network configuration settings. This is the default.
hard: A hard reset erases all network configuration settings of the controller. The controller becomes a primary controller ready to add devices to a new network.

Node commands

zwave node configure homeid nodeid ?parameter? ?value? ?size?

Set or retrieve node configuration parameters. With no arguments the values of all known parameters are requested. With one argument, the value of a single parameter is requested. With two or three arguments, the value of a parameter is set. The size argument should normally be 1, 2, or 4. If no size is specified, it defaults to 2.

zwave node heal homeid nodeid ?init?

Heal a network node by requesting the node to rediscover its neighbors. The init argument controls whether return routes initialization will be performed. It defaults to true.

zwave node info homeid nodeid ??name? value? ?name value ...?

Set or retrieve node options. Not all options can be set. Available options are:

awake: Flag indicating whether the node is awake or asleep. This is a readonly option.
basic: The basic type of a node. This is a readonly option.
baudrate: The maximum baud rate of a node's communications. This is a readonly option.
beaming: Flag indicating if the node is a beam capable device. This is a readonly option.
devicetype: The node device type as reported in the Z-Wave+ Info report, both in numerical form and as a string. This is a readonly option.
failed: Flag indicating whether the node is working or has failed. This is a readonly option.
frequent: Flag indicating whether the node is a frequent listening device that goes to sleep but can be woken up by a beam. This is a readonly option.
generic: The generic type of a node. This is a readonly option.
inforeceived: Flag indicating that the node information has been received. This is a readonly option.
listening: Flag indicating whether the node is a listening device that does not go to sleep. This is a readonly option.
location: The location of a node.
manufacturer: The manufacturer name of a device.
manufacturerid: The manufacturer ID of a device. This is a readonly option.
name: The name of a node.
neighbors: A list containing the node's neighbors. This is a readonly option.
nodetype: A human-readable label describing the node. This is a readonly option.
plustype: The node PlusType as reported in the Z-Wave+ Info report. This is a readonly option.
product: The product name of a device.
productid: The product ID of a device. This is a readonly option.
querystage: The node's query stage. This is a readonly option.
role: The node role as reported in the Z-Wave+ Info report. This is a readonly option.
routing: Flag indicating whether the node is a routing device that passes messages to other nodes. This is a readonly option.
security: Flag indicating whether the node supports security features. This is a readonly option.
specific: The specific type of a node. This is a readonly option.
version: The version number of a node. This is a readonly option.
zwaveplus: Flag indicating whether the node supports ZWave+. This is a readonly option.

zwave node refresh homeid nodeid ?mode?

Trigger the fetching of data for a node. The three possible modes are, in order of increasing depth: dynamic, state, full.

zwave node remove homeid nodeid

Remove a Failed Device from the Z-Wave Network.

zwave node replace homeid nodeid

Replace a failed device with another.

zwave node raw messagetype homeid nodeid data ?secure?

Send a raw message to a node. The messagetype can be either "request" or "response". The data argument should be a binary string representing the message content. For example, to make the Zipato PSE02 siren play the police car sound, the following comand can be used:

zwave node raw request \
  $homeid $nodeid [binary format ccx4ccx2 0x71 0x05 0x0A 0x01]

Group commands

zwave group add homeid nodeid group target ?instance?

Add a node to an association group.

zwave group info homeid nodeid ?groupid? ?option?

Retrieve information about groups of a node. Without any arguments, this command returns the number of groups present. Group numbers count from 1 up. With one argument, all attributes of a group a returned as a dict. With two arguments, the specific attribute value is returned. Possible attributes are:

associations: A list of node IDs associated with the group.
label: A description of the group.
maxassoc: The maximum number of nodes that can be associated with the group.

zwave group remove homeid nodeid group target ?instance?

Remove a node from an association group.

Value commands

zwave value id nodeid genre class instance index type: Build a valueid for use in one of the other subcommands.
zwave value info homeid valueid ?option? ?value?: Set or retrieve value options. Not all options can be set.
zwave value refresh homeid valueid: Refresh the specified value from the Z-Wave network.
zwave value set homeid valueid ?value?: Get or set a value.