Home

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.