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())

getDate()

The date and time the State object was created.

Signature:
Date getDate()
Returns:
Date - the Date this State object was created.

Example:

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

getDateValue()

The value of the underlying attribute as a Date.

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

getDoubleValue()

The value of the underlying Attribute as a Double.

Signature:
Double getDoubleValue()
Returns:
Double - the value of the underlying attribute as a Double.

Warning

getDoubleValue() 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"
}

getFloatValue()

The value of the underlying Attribute as a Float.

Signature:
Float getFloatValue()
Returns:
Float - the value of the underlying Attribute as a Float.

Warning

getFloatValue() 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"
}

getId()

The unique system identifier for the State object.

Signature:
String getId()
Returns:
String - the unique system identifer for the State object.

Example:

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

getIntegerValue()

The value of the underlying Attribute as an Integer.

Signature:
Integer getIntegerValue()
Returns:
Integer - the value of the underlying Attribute as a Integer.

Warning

getIntegerValue() 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"
}

getIsoDate()

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

Signature:
String getIsoDate()
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}"

getJsonValue()

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

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

Warning

getJsonValue() 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"
}

getLongValue()

The value of the underlying Attribute as a Long.

Signature:
Long getLongValue()
Returns:
Long - the value if the underlying Attribute as a Long.

Warning

getLongValue() 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"
}

getName()

The name of the underlying Attribute.

Signature:
String getName()
Returns:
String - the name of the underlying Attribute.

Example:

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

getNumberValue()

The value of the underlying Attribute as a BigDecimal.

Signature:
BigDecimal getNumberValue()
Returns:
Number - the value if the underlying Attribute as a Number.

Warning

getNumberValue() throws an Exception of the underlying attribute value cannot be parsed into a getNumberValue().

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"
}

getNumericValue()

The value of the underlying Attribute as a Number.

Signature:
Number getNumericValue()
Returns:
Number - the value if the underlying Attribute as a Number.

Warning

getNumericValue() throws an Exception of the underlying attribute value cannot be parsed into a Number.

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"
}

getStringValue()

The value of the underlying Attribute as a String

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

Example:

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

getUnit()

The unit of measure for the underlying Attribute.

Signature:
String getUnit()
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}"

getValue()

The value of the underlying Attribute as a String

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

Example:

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

getXyzValue()

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> getXyzValue()
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"
}