Device¶

The Device object represents a physical device in a SmartApp. When a user installs a SmartApp, they typically will select the devices to be used by the SmartApp. SmartApps can then interact with these Device objects to get device information, or send commands to the Device.

Device objects cannot be instantiated, but are created by the SmartThings platform and available via the name given in the preferences definition of a SmartApp:

preferences {
    section() {
        // prompt user to select a device that supports the switch capability.
        // assign the chosen device to a variable named "theswitch"
        input "theswitch", "capability.switch"
    }
}
...
// access Device instance using the input name:
def deviceDisplayName = theswitch.displayName
...

Note

Event history is limited to the last seven days. Methods that query devices for event history will only query the last seven days. This will be called out in those methods, but is good to be generally aware of.

<attribute name>State¶

The latest State instance for the specified Attribute.

The exact name will vary depending on the device and its available attributes.

For example, the Thermostat capability supports several attributes. To get the State for any of the attributes, simply use the attribute name to construct the call. Consider the case of the “temperature” and “heatingSetpoint” attributes:

somethermostat.temperatureState
somethermostat.heatingSetpointState

Signature:: State <attribute name>State
Returns:: State - The latest State instance for the specified Attribute.

Example:

preferences {
    section() {
        input "thetemp", "capability.temperatureMeasurement"
    }
}
...
// The Temperature Measurement has a "temperature" attribute.
// so the form is <attribute name>State = temperatureState
def tempState = thetemp.temperatureState
...

<command name>()¶

Executes the specified command on the Device.

The method name will vary on the Device and Command being called.

For example, a Device that supports the Switch capability has both the on() and off() commands.

Some commands may take parameters; you will pass those parameters to the command as well.

Signature:

void <command name>()

void <command name>([delay: Number])

void <command name>(arguments)

void <command name>(arguments, [delay: Number')])

Parameters:

arguments - The arguments to the command, if required.

Map options - A map of options to send to the command. Only the delay option is currently supported:

option	type	description
`delay`	Number	The number of milliseconds to wait before sending the command to the device.

Returns:

void

Example:

preferences {
    section() {
        input "theswitch", "capability.switch"
        input "thethermostat", "capability.thermostat"
    }
}
...
// call the "on" command on theswitch - no arguments
theswitch.on()

// call the "setHeatingSetpoint" command on thethermostat - takes an argument:
thethermostat.setHeatingSetpoint(72)

// A map specifiying command options can be specified as the last parameter.
// Only supported options are "delay":
theswitch.on([delay: 30000]) // send command after 30 seconds
thethermostat.setHeatingSetpoint(72, [delay: 30000])
...

current<Uppercase attribute name>¶

The latest reported values for the specified attribute.

The specific signature will vary depending on the attribute name. Follow the patter of current plus the attribute name, with the first letter capitalized.

For example, the Carbon Monoxide Detector capability has an attribute “carbonMonoxide”. To get the latest value for this attribute, you would call:

def currentCarbon = somedevice.currentCarbonMonoxide

Signature:: Object current<Uppercase attribute name>
Returns:: Object - the latest reported values for the specified attribute. The specific type of object returned will vary depending on the specific attribute.

Tip

The exact returned type for various attributes depends upon the underlying capability and Device Handler.

Example:

preferences {
    section() {
        input "theswitch", "capability.switch"
        input "thetemp", "capability.temperatureMeasurement"
    }
}
...
def switchattr = theswitch.currentSwitch
def tempattr = thetemp.currentTemperature

log.debug "current switch: $switchattr"
log.debug "current temp: $tempattr"

// switch attribute returned as a string
log.debug "switchattr instanceof String? ${switchattr instanceof String}"

// temperature attribute returned as a Number
log.debug "tempatt instanceof Number? ${tempattr instanceof Number}"

...

capabilities¶

The List of Capabilities provided by this Device.

Signature:: List<Capability> capabilities
Returns:: List <Capability> - a List of Capabilities supported by this Device.

Example:

def supportedCaps = somedevice.capabilites
supportedCaps.each {cap ->
    log.debug "This device supports the ${cap.name} capability"
}

currentState()¶

Gets the latest State for the specified attribute.

Signature:: State currentState(String attributeName)
Parameters:: String attributeName - The name of the attribute to get the State for.
Returns:: State - The latest State instance for the specified attribute.

Example:

preferences {
    section() {
        input "temp", "capability.temperatureMeasurement"
    }
}
...
def tempState = temp.currentState("temperature")
log.debug "state value: ${tempState.value}"
...

currentValue()¶

Gets the latest reported values of the specified attribute.

Signature:: Object currentValue(String attributeName)
Parameters:: String attributeName - The name of the attribute to get the latest values for.
Returns:: Object - The latest reported values of the specified attribute. The exact return type will vary depending upon the attribute.

Warning

The exact returned type for various attributes is not adequately documented at this time.

Until they are, we recommend that you save often and experiment, or even look at the specific Device Handler for the device you are working with.

Example:

preferences {
    section() {
        input "theswitch", "capability.switch"
        input "thetemp", "capability.temperatureMeasurement"
    }
}
...
def switchattr = theswitch.currentValue("switch")
def tempattr = thetemp.currentValue("temperature")

log.debug "current switch: $switchattr"
log.debug "current temp: $tempattr"

// switch attribute returned as a string
log.debug "switchattr instanceof String? ${switchattr instanceof String}"

// temperature attribute returned as a Number
log.debug "tempatt instanceof Number? ${tempattr instanceof Number}"

...

displayName¶

The label of the Device assigned by the user.

Signature:: String label
Returns:: String - the label of the Device assigned by the user, null if no label iset.

Example:

def devLabel = somedevice.displayName
if (devLabel) {
    log.debug "label set by user: $devLabel"
} else {
    log.debug "no label set by user for this device"
}

id¶

The unique system identifier for this Device.

Signature:: String id
Returns:: String - the unique system identifer for this Device.

events()¶

Get a list of Events for the Device in reverse chronological order (newest first).

Note

Only Events in the last seven days will be returned via the events() method.

Signature:

List<Event> events([max: N])

Parameters:

Map options (optional) - Options for the query. Supported options below:

option	Type	Description
`max`	Number	The maximum number of Events to return.

Returns:

List <Event> - A list of events in reverse chronological order (newest first).

Example:

def theEvents = somedevice.events()
def mostRecent20Events = somedevice.events(max: 20)

eventsBetween()¶

Get a list of Events between the specified start and end dates.

Note

Only Events from the last seven days is query-able. Using a date range that ends more than seven days ago will return zero events.

Signature:

List<Event> eventsBetween(Date startDate, Date endDate [, Map options])

Parameters:

Date startDate - the lower Date range for the query.

Date endDate - the upper Date range for the query.

Map options (optional) - Options for the query. Supported options below:

option	Type	Description
`max`	Number	The maximum number of Events to return.

Returns:

List <:ref:event_ref> - a list of Events between the specified start and end dates.

Example:

// 3 days ago
def startDate = new Date() - 3

// today
def endDate = new Date()

def theEvents = somedevice.eventsBetween(startDate, endDate)
log.debug "there were ${theEvents.size()} events in the last three days"

// events in the last 3 days - maximum of 5 events
def limitedEvents = somedevice.eventsBetween(startDate, endDate, [max: 5])

eventsSince()¶

Get a list of Events since the specified date.

Note

Only Events from the last seven days is query-able. Using a date range that ends more than seven days ago will return zero events.

Signature:

List<Event> eventsSince(Date startDate [, Map options])

Parameters:

Date startDate - the date to start the query from.

Map options (optional) - options for the query. Supported options below:

option	Type	Description
`max`	Number	The maximum number of Events to return.

Returns:

List <Event> - a list of Events since the specified date.

Example:

def eventsSinceYesterday = somedevice.eventsSince(new Date() - 1)
log.debug "there have been ${eventsSinceYesterday.size()} since yesterday"

hasAttribute()¶

Determine if this Device has the specified attribute.

Tip

Attribute names are case-sensitive.

Signature:: Boolean hasAttribute(String attributeName)
Parameters:: String attributeName - the name of the attribute to check if the Device supports.
Returns:: Boolean - true if this Device has the specified attribute. Returns a non-true value if not (may be null).

Example:

preferences {
    section() {
        input "theswitch", "capability.switch"
        input "thetemp", "capability.temperatureMeasurement"
    }
}
...
def hasTempAttr = thetemp.hasAttribute("temperature")
// true, since this device supports the 'temperature' capability
log.debug "${thetemp.displayName} has temperature attribute? $hasTempAttr"

def hasTempAttrCaseSensitive = thetemp.hasAttribute("Temperature")
if (hasTempAttrCaseSensitive) {
    log.debug "${thetemp.displayName} supports the Temperature attribute."
} else {
    // this block will execute, since attribute names are case sensitive
    log.debug "${thetemp.displayName} does NOT support the Temperature attribute."
}

...

hasCapability()¶

Determine if this Device supports the specified capability name.

Tip

Capability names are case-sensitive.

Signature:: Boolean hasCapability(String capabilityName)
Parameters:: String capabilityName - the name of the capability to check if the Device supports.
Returns:: Boolean - true if this Device has the specified capability. Returns a non-true value if not (may be null).

Example:

preferences {
    section() {
        input "theswitch", "capability.switch"
        input "thetemp", "capability.temperatureMeasurement"
    }
}
...
def hasSwitch = theswitch.hasCapability("Switch")
def hasSwitchCaseSensitive = theswitch.hasCapability("switch")
def hasPower = theswitch.hasCapability("Power")

// true
log.debug "${theswitch.displayName} has Switch capability? $hasSwitch"

if (!hasSwitchCaseSensitive) {
    // enters this block (names are case-sensitive!)
    log.debug "${theswitch.displayName} does not have the switch capability"
}

// true
log.debug "${theswitch.displayName} also has Power capability? $multiCapabilities"

...

hasCommand()¶

Determine if this Device has the specified command name.

Tip

Command names are case-sensitive.

Signature:: Boolean hasCommand(String commandName)
Parameters:: String commandName - the name of the command to check if the Device supports.
Returns:: Boolean - true if this Device has the specified command. Returns a non-true value if not (may be null).

Example:

preferences {
    section() {
        input "theswitch", "capability.switch"
        input "switchlevel", "capability.switchLevel"
    }
}
...

def hasOn = theswitch.hasCommand("on")
def hasOnCaseSensitive = theswitch.hasCommand("On")

// true
log.debug "${theswitch.displayName} has on command? $hasOn"

if (!hasOnCaseSensitive) {
    // enters this block - case-sensitive!
    log.debug "${theswitch.displayName} does not have On command"
}

def hasSetLevelCommand = switchlevel.hasCommand("setLevel")
// true
log.debug "${switchlevel.displayName} has command setLevel? $hasSetLevelCommand"
...

hub¶

The Hub associated with this Device.

Signature:: Hub hub
Returns:: Hub - the Hub for this Device.

Example:

log.debug "Hub: ${someDevice.hub.name}"

latestState()¶

Get the latest Device State record for the specified attribute.

Signature:: State latestState(String attributeName)
Parameters:: String attributeName - The name of the attribute to get the State record for.
Returns:: State - The latest State record for the attribute specified for this Device.

Example:

def latestDeviceState = somedevice.latestState("someAttribute")
log.debug "latest state value: ${latestDeviceState.value}"

latestValue()¶

Get the latest reported value for the specified attribute.

Signature:: Object latestValue(String attributeName)
Parameters:: String attributeName - the name of the attribute to get the latest value for.
Returns:: Object - the latest reported value. The exact type returned will vary depending upon the attribute.

Warning

The exact returned type for various attributes is not adequately documented at this time.

Until they are, we recommend that you save often and experiment, or even look at the specific Device Handler for the device you are working with.

Example:

preferences {
    section() {
        input "theswitch", "capability.switch"
        input "thetemp", "capability.temperatureMeasurement"
    }
}
...
def switchattr = theswitch.latestValue("switch")
def tempattr = thetemp.latestValue("temperature")

log.debug "current switch: $switchattr"
log.debug "current temp: $tempattr"

// switch attribute returned as a string
log.debug "switchattr instanceof String? ${switchattr instanceof String}"

// temperature attribute returned as a Number
log.debug "tempatt instanceof Number? ${tempattr instanceof Number}"

...

name¶

The internal name of the Device. Typically assigned by the system and editable only by a user in the IDE.

Signature:: String name
Returns:: String - the internal name of the Device.

label¶

The name of the Device set by the user in the mobile application or Web IDE.

Signature:: String label
Returns:: String - the name of the Device as configured by the user.

statesBetween()¶

Get a list of Device State objects for the specified attribute between the specified times in reverse chronological order (newest first).

Note

Only State instances from the last seven days is query-able. Using a date range that ends more than seven days ago will return zero State objects.

Signature:

List<State> statesBetween(String attributeName, Date startDate, Date endDate [, Map options])

Parameters:

String attributeName - The name of the attribute to get the States for.

Date startDate - The beginning date for the query.

Date endDate - The end date for the query.

Map options (optional) - options for the query. Supported options below:

option	Type	Description
`max`	Number	The maximum number of Events to return.

Returns:

List <State> - A list of State objects between the dates specified. A maximum of 1000 State objects will be returned.

Example:

preferences {
    section() {
        input "theswitch", "capability.switch"
    }
}
...
def start = new Date() - 5
def end = new Date() - 1

def theStates = theswitch.statesBetween("switch", start, end)
log.debug "There are ${theStates.size()} between five days ago and yesterday"
...

statesSince()¶

Get a list of Device State objects for the specified attribute since the date specified.

Note

Only State instances from the last seven days is query-able. Using a date range that ends more than seven days ago will return zero State objects.

Signature:

List<State> statesSince(String attributeName, Date startDate [, Map options])

Parameters:

String attributeName - The name of the attribute to get the States for.

Date startDate - The beginning date for the query.

Map options (optional) - options for the query. Supported options below:

option	Type	Description
`max`	Number	The maximum number of Events to return.

Returns:

List <State> - A list of State records since the specified start date. A maximum of 1000 State instances will be returned.

Example:

preferences {
    section() {
        input "theswitch", "capability.switch"
    }
}
...
def theStates = theswitch.statesBetween("switch", new Date() -3)
log.debug "There are ${theStates.size()} State records in the last 3 days"
...

supportedAttributes¶

The list of Attribute s for this Device.

Signature:: List<Attribute> supportedAttributes
Returns:: List <Attribute> - the list of Attributes for this Device. Includes both capability attributes as well as Device-specific attributes.

Example:

preferences {
    section() {
        input "theswitch", "capability.switch"
    }
}
...
def theAtts = theswitch.supportedAttributes
theAtts.each {att ->
    log.debug "Supported Attribute: ${att.name}"
}
...

supportedCommands¶

The list of Command s for this Device.

Signature:: List<Command> supportedCommands
Returns:: List <Command> - the list of Commands for this Device. Includes both capability commands as well as Device-specific commands.

Example:

preferences {
    section() {
        input "theswitch", "capability.switch"
    }
}
...
def theCommands = theswitch.supportedCommands
theCommands.each {com ->
    log.debug "Supported Command: ${com.name}"
}
...