Z-Wave Device Class

The st.zwave.Device class inherits from Device, extending behavior with Z-Wave-specific functionality. Device objects are instantiated by the framework and passed to drivers as parameters for device-related methods.

Sleepy devices

Sleepy devices present unique use cases for a Z-Wave controller since communication can only occur when the device is awake. One particular case is when a sleepy device’s preferences are updated and it is asleep, any configuration commands for the device cannot be sent until the device wakes up. To allow for sending device configuration commands when the device wakes up, a driver can set an update_preferences function on a device which will get called when the device wakes up. The function is provided args which are similar to the args on the infoChanged lifecycle event and contain the old_st_store.preferences with the preferences that were present the last time the device woke up. Note that there will still be an infoChanged event for sleepy devices, and this automatic preference update mechanism only works for devices that support the WakeUp command class. The following is an example of how this functionality should be handled in a driver that supports both listening and sleepy devices:

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

local function update_preferences(self, device, args)
  if args.old_st_store.prefrences["my_pref"] ~= device.preferences["my_pref"] then
    -- send commands if you need
  end
end

local function device_init(self, device)
  device:set_update_preferences_fn(update_preferences)
end

local function info_changed(self, device, event, args)
  -- only update preferences for devices we know are awake
  -- if this driver only supports sleepy devices, an infoChanged handler may not be needed at all.
  if ~device:is_cc_supported(cc.WAKE_UP) then
    update_preferences(self, device, args)
  end
end

local zwave_contact_driver = {
  supported_capabilities = {
    capabilities.contactSensor,
    capabilities.battery
  },
  lifecycle_handlers = {
    init = device_init,
    infoChanged = info_changed,
  },
}

defaults.register_for_default_handlers(zwave_contact_driver, zwave_contact_driver.supported_capabilities)
--- @type st.zwave.Driver
local contact_sensor = ZwaveDriver("zwave_contact_sensor", zwave_contact_driver)
contact_sensor:run()
class st.zwave.Device: st.Device
zwave_endpoints: table

store Z-Wave endpoints

collect_default_refresh_commands(self)

Collect and return the list of refresh commands for self device as provided

by registered default modules, removing duplicates.

Parameters

self (st.zwave.Device) –

set_component_to_endpoint_fn(comp_ep_fn)

Set a function to map this devices SmartThings components to Zwave endpoints

Parameters

comp_ep_fn (CompToEp) – Component to Endpoint function to do the mapping for this device

set_endpoint_to_component_fn(ep_comp_fn)

Set a function to map this devices Zwave endpoints to SmartThings components

Parameters

ep_comp_fn (EpToComp) – function to do the mapping for this device

set_update_preferences_fn(update_pref_fn)

Set a function to be called with with previous preferences when this device wakes up. Should be used to update preferences on sleepy devices.

Parameters

update_pref_fn (UpdatePreference) – function to update preferences when a device wakes up.

default_refresh(self)

Collect device-specific refresh commands from registered default modules

and send these to the associated Z-Wave device.

Parameters

self (st.zwave.Device) –

refresh(self)

Use the capability dispatcher to execute refresh as appropriate for

the particular device instance.

Parameters

self (st.zwave.Device) –

default_configure(self)

Default device configure function. Execute refresh to bootstrap state

for all capability event listeners.

Parameters

self (st.zwave.Device) –

emit_event_for_endpoint(endpoint, event)

Emit event for Z-Wave endpoint(channel), mapped to component.

Parameters
  • endpoint (number) – the endpoint(Z-Wave channel) ID to find the component for

  • event (table) – the endpoint(Z-Wave channel) ID to find the component for

send(cmd)

Send a Z-Wave command to the associated Z-Wave device.

The command will be logged in the live logs when it is sent from the driver. There will also be logs to trace when the command is queued in the hub, and when the transmission has completed on the radio.

Parameters

cmd (st.zwave.Command) –

send_to_component(cmd, component_id)

Send a Z-Wave command to the specific component of associated Z-Wave device.

The command will be logged in the live logs when it is sent from the driver. There will also be logs to trace when the command is queued in the hub, and when the transmission has completed on the radio.

Parameters
component_to_endpoint(component_id)

Map component to end_points(channels)

e.g. {} - map component to un-encapsulated {2} - map to specific Z-Wave endpoint(channel) {1,2,3} - map to more then one Z-Wave endpoint (channels)

e.g. {2} for Z-Wave channel 2 or {} for unencapsulated

Parameters

component_id (str) – ID

Returns

dst_channels destination channels

Return type

table

endpoint_to_component(endpoint)

Map end_point(channel) to Z-Wave endpoint(channel)

Parameters

endpoint (number) – the endpoint(Z-Wave channel) ID to find the component for

Returns

the component ID the endpoint matches to

Return type

str

is_cc_supported(cc_value, endpoint)

Interrogate the device’s profile to determine whether a particular command class is supported.

Parameters
  • cc_value (number) – the command class id as defined in cc.lua, e.g cc.SWITCH_BINARY = 0x25

  • endpoint (number) – of the endpoint to check, if nil we check the first endpoint

Returns

true if the command class is supported, false if not

Return type

boolean

id_match(mfr_id, product_type, product_id)

Determine whether device self is a match to the passed manufacturer ID(s),

product ID(s) and product type(s). Filter arguments can be numerical literals or arrays of numerical literals.

In the case that a filter argument is an array, matching uses OR logic. Match against any single array item is considered a device match.

Parameters
  • mfr_id (number or table) – numerical manufacturer ID or array of IDs

  • product_type (number or table) – numerical product type ( aka product in DTH namespace) or array of types.

  • product_id (number or table) – numerical product ID ( aka model in DTH namespace) or array of IDs

Returns

true if device self matches the passed all filter arguments

Return type

boolean

static init(cls, driver, raw_device)

Initialize an st.zwave.Device instance

Parameters
pretty_print()

Get a string with the ID, DNI and label of the device.

Returns

a short string representation of the device

Return type

str