Device Object

For developers: methods and properties available on device objects (DeviceWrapper, etc.)

Device Object

The device object (technically com.hubitat.app.DeviceWrapper, com.hubitat.app.ChildDeviceWrapper, and com.hubitat.app.ParentDeviceWrapper) is composed of methods that allow you to interact with the settings and values of a device. This object is available to apps that have been given access via a device selection input, as well as child devices of apps and parent devices. The device driver itself also has access via the device object.

Methods

currentValue

Retrieve the current value of an attribute. (Note: If you are looking to set the value of an attribute, use sendEvent() or equivalent.)

Signature

  • Object currentValue(String attributeName)
  • Object currentValue(String attributeName, boolean skipCache)

Parameters

  • attributeName - The attribute to get the current value of.
  • skipCache - Optional; defaults to false. If true, do not use the cached value of the attribute (values are cached during a single execution of the driver); instead force the system to read the latest from the database.

Returns

The current value of an attribute.

deleteCurrentState

Deletes the value of an attribute. (Not recommended for attributes required by any capabilities or custom attributes defined in the driver.)

Signature

  • void deleteCurrentState(String attributeName)

Parameters

  • attributeName - The attribute to remove the current value of

Returns

none

events

Retrieve a list of events for the device. By default the maximum number of events returned in the list is 10 which can be overridden by the max option.

Signature

  • List<Event> events()
  • List<Event> events(Map options)

Parameters

  • options - Optional values for getting the list of events. Possible values:
    • max - The maximum number of events to retrieve.

Returns

List of Event objects for the device

eventsSince

Retrieve a list of events since a date/time.

Signature

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

Parameters

  • startDate - The date/time to list events since.
  • options - Optional values for getting the list of events. Possible values:
    • max The maximum number of events to retrieve.

Returns

A list of Events (defaults to 10 events unless otherwise specified in options)

Examples

// Get events since 8:00 am today
def events = eventsSince(timeToday("08:00"))

// Get a maximum of 5 events
def events = eventsSince(timeToday("08:00"), [max:5])

getName

Retrieve the name of the device.

Signature

String getName()

Parameters

none

Returns

String - The name of the device

setName

Update the name of the device.

Signature

void setName(String name)

Parameters

name - the new name for the device.

Returns

none

getLabel

Retrieve the label of the device.

Signature

String getLabel()

Parameters

none

Returns

String - The label of the device

setLabel

Update the label of the device.

Signature

void setLabel(String label)

Parameters

label - the new label for the device.

Returns

none

hasAttribute

Determines if the device has the specified attribute. This works for both built-in and custom attributes.

Signature

Boolean hasAttribute(String attribute)

Parameters

attribute - The attribute to check for.

Returns

True if the attribute exists, false otherwise.

hasCapability

Determines if the device has the specified capability.

Signature

Boolean hasCapability(String capability)

parameters

capability - The capability to check for.

Returns

True if the capability exists, false otherwise.

hasCommand

Determines if the device has the specified command. This works for both built-in and custom commands.

Signature

Boolean hasCommand(String command)

Parameters

command - The command to check for.

Returns

True if the command exists, false otherwise.

getSetting

Signature

Object getSetting(String name)

Parameters

  • String name: name of setting

Returns

Value of the setting with the specified name

updateSetting

Updates the value of a setting (preference) to the specified value. If the setting does not exist, this method will create it.

Signature

  • void updateSetting(String name, Map options)

Parameters

  • options - Map with keys type and value, e.g.,
    [type: "number", value: 5]

Other Signatures

  • void updateSetting(String name, Long value)
  • void updateSetting(String name, Boolean value)
  • void updateSetting(String name, String value)
  • void updateSetting(String name, Double value)
  • void updateSetting(String name, Date value)
  • void updateSetting(String name, List value)

Parameters

  • name - The name of the setting to update
  • value - The value to store in the setting

Returns

None

removeSetting

Removes specified setting from saved settings (device preferences)

Signature

  • void removeSetting(String name)

Parameters

  • String name - name of setting to remove

Returns

None

getData

Get all data values for this device.

Signature

Map getData()

Parameters

None

Returns

Map - All data values.

getDataValue

Get a data value that was set for this device.

Signature

String getDataValue(String name)

Parameters

  • name - The String value of the data item.

Returns

  • String - The value of the data.

getDeviceDataByName

DEPRECATED: See getDataValue; this method is a wrapper for getDataValue.

updateDataValue

Update or create a data value for this device.

Signature

void updateDataValue(String name, String value)

Parameters

  • name - The name of the data item to store.
  • value - The value of the data item to store.

Returns

None.

removeDataValue

Remove a data value from a device.

Signature

void removeDataValue(String name) (Since 2.2.1)

Parameters

name - The name of the data item to remove.

Returns

None.

Additional to be documented

  • List<Event> eventsBetween(Date startDate, Date endDate)
  • List<Event> eventsBetween(Date startDate, Date endDate, Map options = null)
  • List<State> statesSince(String attributeName, Date startDate)
  • List<State> statesSince(String attributeName, Date startDate, Map options = null)
  • void sendEvent(Map properties)
  • void clearSetting(String name)
  • Long getIdAsLong()
  • String getId()
  • String getEndpointId()
  • String getZigbeeId()
  • Hub getHub()
  • String getStatus()
  • String getDisplayName()
  • void setDisplayName(String displayName)
  • String getDeviceNetworkId()
  • void setDeviceNetworkId(String dni)
  • State currentState(String attributeName) - same as currentValue()
  • State currentState(String attributeName, boolean skipCache)
  • Object latestValue(String attributeName)
  • Object latestValue(String attributeName, boolean skipCache)
  • State latestState(String attributeName)
  • State latestState(String attributeName, boolean skipCache)
  • List<State> getCurrentStates()
  • List<Command> getSupportedCommands()
  • List<Attribute> getSupportedAttributes()
  • List<Capability> getCapabilities()
  • Date getLastActivity()
  • Long getParentDeviceId()
  • Long getParentAppId()
  • Boolean getIsComponent()
  • boolean isDisabled()