State¶

A State object encapsulates information about a particular Attribute at a particular moment in time.

State objects are associated with a Device - a Device may have zero-to-many Attribute s, and an Attribute has zero-to-many associated State records.

Refer to the Devices section of the SmartApp Guide for more information about the relationship between Devices, Attributes, and State.

A few ways to get a State object instance from a device (See the Device API reference for detailed information):

preferences {
    section() {
        input "thecontact", "capability.contactSensor"
    }
}
...
// <device>.<attributeName>State
def latestState = thecontact.contactState

// <device>.currentState(<attributeName>)
def latestState2 = thecontact.currentState("contact")

// get a list of states between two dates
def recentStates = thecontact.statesBetween(new Date() - 5, new Date())

date¶

The date and time the State object was created.

Signature:: Date date
Returns:: Date - the Date this State object was created.

Example:

def stateDate = contactSensor?.currentState("contact").date

dateValue¶

The value of the underlying attribute as a Date.

Signature:: Date dateValue
Returns:: Date - the value if the underlying attribute as a Date. Returns null if the attribute value cannot be parsed into a Date.

doubleValue¶

The value of the underlying Attribute as a Double.

Signature:: Double doubleValue
Returns:: Double - the value of the underlying attribute as a Double.

Warning

doubleValue throws an Exception if the underlying attribute value cannot be parsed into a Double.

You should wrap calls in a try/catch block.

Example:

try {
    def latestStateAsDouble = someDevice.currentState("someAttribute").doubleValue
    log.debug "latestStateAsDouble: $latestStateAsDouble"
} catch (e) {
    log.debug "caught exception trying to get double for state record"
}

floatValue¶

The value of the underlying Attribute as a Float.

Signature:: Float floatValue
Returns:: Float - the value of the underlying Attribute as a Float.

Warning

doubleValue throws an Exception if the underlying attribute value cannot be parsed into a Double.

You should wrap calls in a try/catch block.

Example:

try {
    def latestStateAsFloat = someDevice.currentState("someAttribute").floatValue
    log.debug "latestStateAsFloat: $latestStateAsFloat"
} catch (e) {
    log.debug "caught exception trying to get floatValue for state record"
}

id¶

The unique system identifier for the State object.

Signature:: String id
Returns:: String - the unique system identifer for the State object.

Example:

def latestState = someDevice.currentState("someAttribute")
log.debug "latest state id: ${latestState.id}"

integerValue¶

The value of the underlying Attribute as an Integer.

Signature:: Integer floatValue
Returns:: Integer - the value of the underlying Attribute as a Integer.

Warning

integerValue throws an Exception if the underlying attribute value cannot be parsed into a Integer.

You should wrap calls in a try/catch block.

Example:

try {
    def latestStateAsInt = someDevice.currentState("someAttribute").integerValue
    log.debug "latestStateAsInt: $latestStateAsInt"
} catch (e) {
    log.debug "caught exception trying to get integerValue for state record"
}

isoDate¶

The acquisition time of this State object as an ISO-8601 String

Signature:: String isoDate
Returns:: String - the time this Sate object was created as an ISO-8601 Strring

Example:

def latestState = someDevice.currentState("someAttribute")
log.debug "latest state isoDate: ${latestState.isoDate}"

jsonValue¶

Value of the underlying Attribute parsed into a JSON data structure.

Signature:: Object jsonValue
Returns:: Object - the value if the underlying Attribute parsed into a JSON data structure.

Warning

jsonValue throws an Exception of the underlying attribute value cannot be parsed into a Integer.

You should wrap calls in a try/catch block.

Example:

try {
    def latestStateAsJSONValue = someDevice.currentState("someAttribute").jsonValue
    log.debug "latestStateAsJSONValue: $latestStateAsJSONValue"
} catch (e) {
    log.debug "caught exception trying to get jsonValue for state record"
}

longValue¶

The value of the underlying Attribute as a Long.

Signature:: Long longValue
Returns:: Long - the value if the underlying Attribute as a Long.

Warning

longValue throws an Exception of the underlying attribute value cannot be parsed into a Long.

You should wrap calls in a try/catch block.

Example:

try {
    def latestStateAsLong = someDevice.currentState("someAttribute").longValue
    log.debug "latestStateAsLong: $latestStateAsLong"
} catch (e) {
    log.debug "caught exception trying to get longValue for state record"
}

name¶

The name of the underlying Attribute.

Signature:: String name
Returns:: String - the name of the underlying Attribute.

Example:

def latest = contactSensor.currentState("contact")
log.debug "name: ${latest.name}"

numberValue¶

The value of the underlying Attribute as a BigDecimal.

Signature:: BigDecimal numberValue
Returns:: BigDecimal - the value if the underlying Attribute as a BigDecimal.

Warning

numberValue throws an Exception of the underlying attribute value cannot be parsed into a BigDecimal.

You should wrap calls in a try/catch block.

Example:

try {
    def latestStateAsNumber = someDevice.currentState("someAttribute").numberValue
    log.debug "latestStateAsNumber: $latestStateAsNumber"
} catch (e) {
    log.debug "caught exception trying to get numberValue for state record"
}

numericValue¶

The value of the underlying Attribute as a BigDecimal.

Signature:: BigDecimal numericValue
Returns:: BigDecimal - the value if the underlying Attribute as a BigDecimal.

Warning

numericValue throws an Exception of the underlying attribute value cannot be parsed into a BigDecimal.

You should wrap calls in a try/catch block.

Example:

try {
    def latestStateAsNumber = someDevice.currentState("someAttribute").numericValue
    log.debug "latestStateAsNumber: $latestStateAsNumber"
} catch (e) {
    log.debug "caught exception trying to get numericValue for state record"
}

stringValue¶

The value of the underlying Attribute as a String

Signature:: String stringValue
Returns:: String - the value of the underlying Attribute as a String.

Example:

def latest = contactSensor.currentState("contact")
log.debug "stringValue: ${latest.stringValue}"

unit¶

The unit of measure for the underlying Attribute.

Signature:: String unit
Returns:: String - the unit of measure for the underlying Attribute, if applicable, null otherwise.

Example:

def latest = tempSensor.currentState("temperature")
log.debug "unit: ${latest.unit}"

value¶

The value of the underlying Attribute as a String

Signature:: String value
Returns:: String - the value of the underlying Attribute as a String.

Example:

def latest = contactSensor.currentState("contact")
log.debug "stringValue: ${latest.value}"

xyzValue¶

Value of the underlying Attribute as a 3-entry Map with keys ‘x’, ‘y’, and ‘z’ with BigDecimal values. For example:

[x: 1001, y: -23, z: -1021]

Typically only useful for getting position data from the “Three Axis” Capability.

Signature:: Map<String, BigDecimal> xyzValue
Returns:: Map < String , BigDecimal > - A map representing the X, Y, and Z coordinates.

Warning

xyzValue throws an Exception if the value of the Event cannot be parsed to an X-Y-Z data structure.

You should wrap calls in a try/catch block.

Example:

def latest = threeAxisDevice.currentState("threeAxis")

// get the value of this event as a 3 entry map with keys
//'x', 'y', 'z', and BigDecimal values
// throws an exception if the value is not convertable to a Date
try {
    log.debug "The xyzValue of this event is ${latest.xyzValue}"
    log.debug "latest.xyzValue instanceof Map? ${latest.xyzValue instanceof Map}"
} catch (e) {
    log.debug "Trying to get the xyzValue threw an exception: $e"
}