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.
Retrieve the current value of an attribute. (Note: If you are looking to set the value of an attribute, use sendEvent() or equivalent.)
Object currentValue(String attributeName)Object currentValue(String attributeName, boolean skipCache)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.The current value of an attribute.
Retrieve the current state record (a State object, not just the value) of an attribute.
State currentState(String attributeName)State currentState(String attributeName, boolean skipCache)attributeName - The attribute to get the current state of.skipCache - Optional; defaults to false. If true, do not use the cached state; instead read the latest from the database.A State object for the attribute, or null if the attribute has no current state.
Retrieve the current value of an attribute. Same as currentValue().
Object latestValue(String attributeName)Object latestValue(String attributeName, boolean skipCache)attributeName - The attribute to get the current value of.skipCache - Optional; defaults to false. If true, do not use the cached value; instead read the latest from the database.The current value of the attribute, or null if the attribute has no current value.
Retrieve the current state record of an attribute. Same as currentState().
State latestState(String attributeName)State latestState(String attributeName, boolean skipCache)attributeName - The attribute to get the current state of.skipCache - Optional; defaults to false. If true, do not use the cached state; instead read the latest from the database.A State object for the attribute, or null if the attribute has no current state.
Retrieve the current state records for all of the device's attributes.
List<State> getCurrentStates()None
A list of State objects, one for each attribute with a current state.
Retrieve a list of state records for one attribute since a date/time.
List<State> statesSince(String attributeName, Date startDate)List<State> statesSince(String attributeName, Date startDate, Map options)attributeName - The attribute to list states for.startDate - The date/time to list states since (inclusive).options - Optional values for getting the list of states. Possible values:
max - Optional; the maximum number of results to return (defaults to 10). The value is expected to be an integer and is not validated.A list of State objects, in the order returned by the state store (defaults to 10 unless otherwise specified in options).
Deletes the value of an attribute. (Not recommended for attributes required by any capabilities or custom attributes defined in the driver.)
void deleteCurrentState(String attributeName)attributeName - The attribute to remove the current value ofnone
Create and process an event for this device, i.e., set the value of an attribute based on the values in the provided map.
void sendEvent(Map properties)properties - A Map of properties for the event, using the same keys as described for sendEvent() in the driver object (e.g., name, value, unit, descriptionText, isStateChange).none
device.sendEvent(name: "switch", value: "on")
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.
List<Event> events()List<Event> events(Map options)options - Optional values for getting the list of events. Possible values:
max - The maximum number of events to retrieve (defaults to 10).name - Only return events with this name. Characters other than letters and digits are removed before matching.List of Event objects for the device, newest first
// Get the 5 most recent "switch" events
def events = device.events(max: 5, name: "switch")
Retrieve a list of events since a date/time.
List<Event> eventsSince(Date startDate)List<Event> eventsSince(Date startDate, Map options)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.A list of Events (defaults to 10 events unless otherwise specified in options)
// 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])
Retrieve a list of events for the device between two dates/times.
List<Event> eventsBetween(Date startDate, Date endDate)List<Event> eventsBetween(Date startDate, Date endDate, Map options)startDate - The lower date/time bound.endDate - The upper date/time bound.options - Optional values for getting the list of events. Possible values:
max - Optional; the maximum number of results to return (defaults to 10). The value is expected to be an integer and is not validated.A list of Event objects, in the order returned by the event store (defaults to 10 events unless otherwise specified in options).
// Get events from the last hour
def events = device.eventsBetween(new Date(now() - 3600000), new Date())
Retrieve the most recent event for the device as a Map.
Map fetchLastEvent()None
A Map describing the latest event, or null if the device has no events. The map contains these keys (values other than id, date, physical, and digital may be null):
id - Long event IDdate - Date of the eventsource - String source typename - String event namedisplayName - String source labelvalue - String event valueunit - String unitdeviceId - Long device IDdescriptionText - String descriptionisStateChange - Boolean state-change flagphysical - Boolean physical-event flagdigital - Boolean digital-event flagtype - String event typeRetrieve the name of the device.
String getName()
none
String - The name of the device
Update the name of the device.
void setName(String name)
name - the new name for the device.
none
Retrieve the label of the device.
String getLabel()
none
String - The label of the device
Update the label of the device.
void setLabel(String label)
label - the new label for the device.
none
Retrieve the display name of the device.
String getDisplayName()None
String - The display name of the device
Update the display name of the device. The value is stored as the device label.
void setDisplayName(String displayName)displayName - The new display name for the device.none
Determines if the device has the specified attribute. This works for both built-in and custom attributes.
Boolean hasAttribute(String attribute)
attribute - The attribute to check for.
True if the attribute exists, false otherwise.
Determines if the device has the specified capability.
Boolean hasCapability(String capability)
capability - The capability to check for.
True if the capability exists, false otherwise.
Determines if the device has the specified command. This works for both built-in and custom commands.
Boolean hasCommand(String command)
command - The command to check for.
True if the command exists, false otherwise.
Retrieve the attributes declared by the device's type.
List<Attribute> getSupportedAttributes()None
A list of Attribute objects
Retrieve the commands declared by the device's type.
List<Command> getSupportedCommands()None
A list of Command objects
Retrieve the capabilities declared by the device's type.
List<Capability> getCapabilities()None
A list of Capability objects
Object getSetting(String name)
String name: name of settingValue of the setting with the specified name
Updates the value of a setting (preference) to the specified value. If the setting does not exist, this method will create it.
void updateSetting(String name, Map options)options - Map with keys type and value, e.g.,[type: "number", value: 5]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)name - The name of the setting to updatevalue - The value to store in the settingNone
Removes specified setting from saved settings (device preferences)
void removeSetting(String name)String name - name of setting to removeNone
Clear the stored value of a setting.
void clearSetting(String name)name - The name of the setting whose stored value should be cleared.none
Retrieve the type of a setting.
String getSettingType(String name)name - The name of the setting.String - The setting type, or null if the name is null or unknown.
Get all data values for this device.
Map getData()
None
Map - All data values.
Get a data value that was set for this device.
String getDataValue(String name)
DEPRECATED: See getDataValue; this method is a wrapper for getDataValue.
Update or create a data value for this device.
void updateDataValue(String name, String value)
name - The name of the data item to store.value - The value of the data item to store.None.
Remove a data value from a device.
void removeDataValue(String name) (Since 2.2.1)
name - The name of the data item to remove.
None.
Retrieve the internal ID of the device as a String.
String getId()None
String - The device ID
Retrieve the internal ID of the device as a Long.
Long getIdAsLong()None
Long - The device ID
Retrieve the device network ID (DNI) of the device.
String getDeviceNetworkId()None
String - The device network ID
Change the device network ID (DNI) and save the updated device.
void setDeviceNetworkId(String dni)dni - The new device network ID.none
Retrieve the LAN ID of the device.
String getLanId()None
String - The LAN ID
Change the LAN ID and save the updated device.
void setLanId(String lanId)lanId - The new LAN ID.none
Retrieve the endpoint ID of the device.
String getEndpointId()None
String - The endpoint ID, or null if the device has none
Retrieve the Zigbee identifier of the device.
String getZigbeeId()None
String - The Zigbee ID, or null if the device has none
Retrieve the current status text of the device.
String getStatus()None
String - The current device status
Retrieve the name of the device's type.
String getTypeName()None
String - The device type name
Retrieve the notes saved for the device.
String getNotes()None
String - The device notes, or null if none are set
Retrieve the date/time of the device's last event or activity.
Date getLastActivity()None
Date - The time of the last activity, or null if the device has had none
Retrieve the hub that owns the device.
Hub getHub()None
The Hub object
Retrieve the ID of the room the device is assigned to.
Long getRoomId()None
Long - The room ID, or null if the device is not in a room
Retrieve the name of the room the device is assigned to.
String getRoomName()None
String - The room name, or null if the device is not in a room
Retrieve the ID of the device's parent device.
Long getParentDeviceId()None
Long - The parent device ID, or null if the device has no parent device
Retrieve the ID of the device's parent app.
Long getParentAppId()None
Long - The parent app ID, or null if the device has no parent app
Determines whether the device is a component device.
Boolean getIsComponent()None
true if the device is a component device; null if unknown
Determines whether the device is displayed as a child device.
Boolean getDisplayAsChild()None
true if the device is displayed as a child; null if unknown
Determines whether the device is disabled.
boolean isDisabled()None
true if the device is disabled, false otherwise.
Determines whether the device is a linked device.
boolean isLinkedDevice()None
true if the device is a linked device, false otherwise.
Determines whether command retry is enabled for the device.
boolean isRetryEnabled()None
true if command retry is enabled, false otherwise.
Determines whether commands for the device's type run on a single executor thread.
boolean isSingleThreaded()None
true if the device type is single-threaded, false otherwise.
Retrieve the controller type recorded for the device.
String getControllerType()None
String - The controller type
Determines whether the device uses a Matter controller.
boolean isControllerMatter()None
true if the device uses a Matter controller, false otherwise.
Determines whether the device uses a Z-Wave controller.
boolean isControllerZWave()None
true if the device uses a Z-Wave controller, false otherwise.
Determines whether the device uses a Zigbee controller.
boolean isControllerZigbee()None
true if the device uses a Zigbee controller, false otherwise.
Retrieve the database ID of the driver (device type) used by the device.
Long getDriverId()None
Long - The driver ID
Retrieve the implementation type of the device's driver.
String getDriverType()None
String - The driver type