Device

In order for a driver to do its job it will need to know information about the devices that it is responsible for. This information is held in a Device object that provides many utility functions and abstractions that will simplify many normal use cases. It will also provide relevant caching and updating on changes that originate outside the driver. In addition a driver can provide a infoChanged lifecycle handler that can do additional processing after the provided processing. The Device object is provided to event handlers handling events for a specific device. A full list of all of these objects for every device the driver is responsible for can be fetched with the Driver:get_devices method.

Below is an example of a Device object.

device = {
  driver = {
    id = "9fbc3680-b9a9-4bd8-a574-9b03517032b2", name = "smartthings/Lua Zigbee Water", type = "DATAMGMT" },
  components = {
    main = {
      capabilities = {
        { id = "temperatureMeasurement", version = 1 },
        { id = "battery", version = 1 },
        { id = "waterSensor", version = 1 },
        { id = "sensor", version = 1 },
      },
      emit_event = function(capability_event, event_metadata) end,
      id = "main"
    }
  },
  preferences = {},
  zigbee_endpoints = {
     1 = {
      client_clusters = { 25 },
      device_id = 1026,
      id = 1,
      manufacturer = "CentraLite",
      model = "3315-S",
      profile_id = 260,
      server_clusters = { 0, 1, 3, 32, 1026, 1280, 2821 }
    }
  },
  id = "02703834-4ab9-46e0-80ed-789fbd481f63",
  fingerprinted_endpoint_id = 1,
  zigbee_eui = "\x00\x0D\x6F\x00\x03\x26\x8A\x5C",
  network_type = "DEVICE_ZIGBEE",
  label = "Water Leak Sensor",
  data = {
    deviceEUI = "000D6F0003268A5C",
    firmwareChecked = "2020-01-15T00:41:46.213Z",
    initialJoinTime = "2019-12-05T15:54:31.563Z",
    initialJoinType = "Unsecure Join",
    lastJoinTime = "2020-01-08T18:33:57.480Z",
    lastJoinType = "Secure Rejoin",
    parent = "0000",
    targetFirmwareVersion = "520573712",
    zigbeeNodeType = "SLEEPY_END_DEVICE"
  },
  profile = {
    components = {
      {
        capabilities = {
          { id = "temperatureMeasurement", version = 1 },
          { id = "battery", version = 1 },
          { id = "waterSensor", version = 1 },
          { id = "configuration", version = 1 },
          { id = "sensor", version = 1 },
          { id = "healthCheck", version = 1 }
        },
        id = "main"
      }
    },
    id = "b648f97a-ab00-4a92-a1f5-2d10bf9a5c7d"
  },
  device_network_id = "D836"
}

Device Class

The device class is the wrapper on top of the raw data provided by the device_api. The device class table will store information in a variety of different locations, and these locations will be protected with metatables. Following are the main pieces to the device object.

st_store:

This is used to store the above shown representation of the SmartThings device model. It is read only, and will be updated automatically if there are changes in the model from an external source (e.g. a change in the cloud). The top level values of this table are also “mirrored” onto the device object itself. That is device.st_store.id will give you the device’s UUID to refer to the device in the SmartThings platform, but you can also access this value simply through device.id. This is done for simplicity of access.

transient_store:

The transient_store is used for storing driver/device specific information. This information however, will only exist as long as the driver is running, and will need to be re-populated where necessary on restart of the hub. A good example of this would be storing the timestamp of the last time you read a given attribute. It’s something that is only useful within the context of the specific driver, but is easily re-constructed after a restart. It is suggested that most of your data can/should be stored this way. It is also recommended that most user/driver stored data be accessed/set using the device:set_field and device:get_field methods documented below.

persistent_store:

Similar to the transient_store, this is for use for driver specific information, however, unlike the transient_store, information written here will be stored and persisted through restarts. This carries with it a cost in wear, as well as time delays associated with the writing and reading. This should also be accessed through the device:set_field and device:get_field methods. A good example of a target for the persistent store would be something like the number of lock codes a lock can support. This is something that only needs to be read once when the device is first joined, and won’t change for the lifetime of the device. This could be read every time the driver restarts, but it is reasonable to read once and store for the lifetime of the device. In order to protect the longevity of your hub device, we limit how frequently values are actually written to flash. This does, however, come with a potential loss of information. When the persistent store for your driver is “written” it is cached in memory and will actually be written to flash on a schedule and on graceful shutdown. This means there is potential information loss in the case of a power loss.

state_cache:

The state cache is a persistent data cache that will store for each component, capability, attribute, the most recently generated state by the driver. For example device.state_cache.main.switch would contain { value = "on" }.

The set_field and get_field functions can be used to write and read from the persistent and transient stores. It is enforced that top level keys cannot be repeated between the two stores, as such get_field will always return the single value with the matching key. Consequently set_field will delete the value in the other store if it is written to the other.

There are also a variety of other utility methods documented below.

Device Class Documentation

class st.Device

A device object contains all of the information we have about a given device that is set to be managed by this driver. It also provides a number of utility functions that make normal operations for dealing with devices simpler.

transient_store: table

Used to store driver specific data about a device that will not persist through driver restart.

persistent_store: table

Used to store driver specific data about a device that will be persisted through restart. The actual flash writes are on a schedule so some data loss is possible if the hub experiences a power loss

st_store: table

Contains the SmartThings device model. Read only and can be updated as a result of changes made elsewhere in the system.

state_cache: table

Caches the most recent event state generated for each component/capability/attribute this is per run session, and is persisted through restart.

thread: st.thread.Thread

The handle to the cosock thread that executes events for this device. This can also be used directly to schedule your own events or use its register_socket function to handle a device-specific socket.

emit_event(capability_event)

Emit a capability event for this devices main component. Will log a warning and do nothing if there is no “main” component on the device

Parameters

capability_event (table) – the capability event to emit

emit_component_event(component, capability_event)

Generate a capability event for this device and component

Usage: device:emit_component_event(device.profile.components.main, capabilities.switch.switch.on())

Parameters
  • component (table) – The component to generate this event for

  • capability_event (table) – The event table generated from a capability

Returns

The converted SmartThings event generated by this device

Return type

table

set_field(field, value, addtional_params)

Set a device specific value to be stored and retrieved when needed. The key names are unique across both persistent and transient stores.

Parameters
  • field (str) – The field name for this value

  • value (value) – The value to set the field to. If setting to persistent store it must be serializable

  • addtional_params (table) – Optional: contains additional description of the field. Currently only usage is the persist field which, if true, will store the field to the persistent store instead of transient

get_parent_device()

Get the st.Device object that is the parent of this device. This _can_ result in a blocking request for the

parents device data, and can be subject to race conditions based on order of data sync. This should _NOT_ be used within an added or init lifecycle event to avoid race conditions and deadlocks.

Returns

the parent device object of this device

Return type

st.Device

set_find_child(find_child_fn)

Set a function used to find a child given an “endpoint” input specific to each protocol

Parameters

find_child_fn (function) – A function that takes a protocol specific endpoint identifier to find a child from

get_child_list()

Get a list of all the children of this device

Returns

a list of the child devices of this device. The type will be specific to the protocol

Return type

list[st.Device]

get_child_by_parent_assigned_key(parent_assigned_key)

Find a child of this device by the parent assigned child key given at creation

Parameters

parent_assigned_key (str) – the key assigned by the parent to identify a child at creation

Returns

the child device with this key

Return type

st.Device or st.zigbee.ChildDevice or st.zwave.ChildDevice or st.matter.ChildDevice or nil

get_field(field)

Retrieve the value a previously set field. nil if non-existent

Parameters

field (str) – The field name for this value

Returns

value The value the field was set to.

Return type

value

supports_capability(capability, component)

Check if this device has a capability in its profile

Parameters
  • capability (Capability) – The capability to check for existence

  • component (str) – Optional: The component id to check for capability support. If nil, any component match will return true

Returns

true if the capability is present in this devices profile

Return type

boolean

component_exists(component_id)

Check if this device has a component_id in its profile

Parameters

component_id (str) –

Returns

true if the component is present in this devices profile

Return type

boolean

get_latest_state(component_id, capability_id, attribute_name, default_value, default_state_table)

Get the latest state of this device for a given component, capability, attribute

table (e.g. it would include both the value and unit keys if both are present)

Parameters
  • component_id (str) – the component ID to get the state for

  • capability_id (str) – the capability ID to get the state for

  • attribute_name (str) – the capability attribute name to get the state for

  • default_value (any) – Optional value to return if the state_cache for the lookup is nil

  • default_state_table (any) – Optional value to return if the state_cache for the lookup is nil

Returns

The first return value is the state.value present for the attribute, the second return is the state

Return type

any or any

component_count()
Returns

count of components in device profile

Return type

number

supports_capability_by_id(capability_id, component)

Check if this device has a capability_id in its profile

Parameters
  • capability_id (str) – The capability ID to check for existence

  • component (str) – Optional: The component id to check for capability support. If nil, any component match will return true

Returns

true if the capability is present in this devices profile

Return type

boolean

try_update_metadata(metadata)

Send a request to update the metadata of a device.

Example usage: device:try_update_metadata({profile = "bulb.rgb.v1", vendor_provided_label = "My RGB Bulb"})

All metadata fields are type string. Valid metadata fields are:

For all network types (LAN/ZIGBEE/ZWAVE/MATTER): profile - profile name defined in the profile .yaml file. provisioning_state - the provisioning state of the device (TYPED/PROVISIONED)

LAN specific: manufacturer - device manufacturer model - model name of the device vendor_provided_label - device label provided by the manufacturer/vendor

Parameters

metadata (table) – A table of device metadata

static build(cls, driver, raw_device)

Build a device object from a raw st_store of the SmartThings device model

helper event generation functions

Parameters
  • cls (table) – The Device class

  • driver (Driver) – The driver context this device will run under

  • raw_device (table) – The SmartThings device model representation, used to populate the st_store and generate

Returns

The created device

Return type

Device

load_updated_data(new_device_data)

Update the st_store data with newly provided data from the cloud.

Parameters

new_device_data (any) –

extend_device(func_name, func)

Add a function to this device object, or override an existing function

Parameters
  • func_name (str) – the name of the function to add/overwrite

  • func (function) – the function to add to the device object

deleted()

This will do any necessary cleanup if the device is removed. The device object will not

be functional after this call.

pretty_print()

Get a string with the ID and label of the device

Returns

a short string representation of the device

Return type

str

online()

Mark device as being online

Only useable on LAN type devices and children of LAN type devices. Calls to this API for ZIGBEE, ZWAVE, or MATTER type devices are ignored as their online/offline status are automatically determined at the radio level. When a parent device is marked online, the online state of its children will be determined independently (i.e. they can be either online or offline).

Returns

boolean Status of whether the call was successful or not

Return type

status

Returns

string The error that occured if status was falsey

Return type

error

offline()

Mark device as being offline and unavailable

Only useable on LAN type devices and children of LAN type devices. Calls to this API for ZIGBEE, ZWAVE, or MATTER type devices are ignored as their online/offline status are automatically determined at the radio level. When a parent device is marked offline, its children will also be marked offline.

Returns

boolean Status of whether the call was successful or not

Return type

status

Returns

string The error that occured if status was falsey

Return type

error