Z-Wave Driver Class

An st.zwave.Driver extends the Driver class with structures and methods specific to Z-Wave devices.

Drivers are instantiated by passing a driver template into the st.zwave.Driver constructor, and then executing the driver run method:

--- @type st.zwave.Driver
local ZwaveDriver = require "st.zwave.driver"
local driver_template = {}
local driver = ZwaveDriver("driver_name", driver_template)
driver:run()

Subsequently, the framework passes the driver instance back to methods executed on the driver object.

zwave_handlers

The zwave_handlers field in the driver template defines callbacks to be executed on receipt of Z-Wave commands from the driver’s Z-Wave devices. These typically perform translation to SmartThings Capability events.

The zwave_handlers table is nested and indexed by [command class][command id]. Inclusion of zwave_handlers in the driver template and passage to the driver constructor registers callbacks for the Z-Wave command keys in the table:

local capabilities = require "st.capabilities"
--- @type st.zwave.CommandClass
local cc = require "st.zwave.CommandClass"
--- @type st.zwave.CommandClass.SwitchBinary
local SwitchBinary = require "st.zwave.CommandClass.SwitchBinary"
--- @type st.zwave.Driver
local ZwaveDriver = require "st.zwave.driver"

--- Handle a Z-Wave Command Class Switch Binary report, translate this to
--- an equivalent SmartThings Capability event, and emit this to the
--- SmartThings infrastructure.
---
--- @param driver st.zwave.Driver
--- @param device st.zwave.Device
--- @param cmd st.zwave.CommandClass.SwitchBinary.Report
local function report_handler(driver, device, cmd)
  if cmd.args.value == SwitchBinary.value.OFF_DISABLE then
    device:emit_event(capabilities.switch.switch.off())
  else
    device:emit_event(capabilities.switch.switch.on())
  end
end

local driver_template = {
  [cc.SWITCH_BINARY] = {
    [SwitchBinary.REPORT] = report_handler,
  },
}

local driver = ZwaveDriver("driver_name", driver_template)

In addition there are 2 extra keys that can be added to the zwave_handlers table. The fallback and error fields can be set to be used as the special handlers for the Dispatchers to be handlers that get called in the case of no other matching handler or an error is encountered respectively.

capability_handlers

SmartThings Capability handlers are supported across all driver types, with support in the st.zwave.Driver class inherited from Driver. Registration is by inclusion of a capability_handlers table in the Z-Wave driver template. Capability handlers typically perform translation to Z-Wave commands for transmission to a Z-Wave device.

local capabilities = require "st.capabilities"
--- @type st.zwave.CommandClass.SwitchMultilevel
local SwitchMultilevel = (require "st.zwave.CommandClass.SwitchMultilevel")({ version = 1 })
--- @type st.zwave.Driver
local ZwaveDriver = require "st.zwave.driver"

--- Handle a SmartThings switch capability level-set command, translate to
--- an equivalent Z-Wave command, and send this to the device.
---
--- @param driver st.zwave.Driver
--- @param device st.zwave.Device
--- @param cmd table ST level capability command
function level_set_handler(driver, device, cmd)
  device:send(SwitchMultilevel:Set({ value = cmd.args.level })
end

local driver_template = {
  capability_handlers = {
    [capabilities.switchLevel.ID] = {
      [capabilities.switchLevel.commands.setLevel.NAME] = level_set_handler
    }
  }
}

local driver = ZwaveDriver("driver_name", driver_template)

Class Documentation

class st.zwave.Driver: Driver
zwave_channel: message_channel

the communication channel for Z-Wave devices

zwave_dispatcher: st.zwave.Dispatcher
static extend_wakeup_handler(driver)

Wrap wake up notification handler to call a devices update_preferences function if there is one set on the device.

This function will be given a table of the previous preference values

This is used by sleepy device drivers when preferences are updated when the device is asleep.

Parameters

driver (st.zwave.Driver) –

build_child_device(raw_device_table)
Parameters

raw_device_table (any) –

static init(cls, name, driver_template)

  • set Z-Wave command version overrides

  • set Z-Wave receive channel override

  • execute base Driver init

  • parse zwave_handlers callback table

  • set Z-Wave default handler override

  • register RX on the Z-Wave socket

  • register lifecycle callbacks

Parameters
Returns

driver instance on which :run() method may be called

Return type

st.zwave.Driver

class st.zwave.Driver.Template
supported_capabilities: table

flat list of SmartThings capabilities supported by the driver

zwave_handlers: table

Z-Wave command handlers, indexed by [cmd_class][cmd_id]

capability_handlers: table

capability handlers, indexed by capability ID

lifecycle_handlers: table

device-configure and device-added lifecycle event callbacks

sub_drivers: table

device-specific sub-drivers