TIP: See also Common Methods, which includes methods available to both apps and drivers.
Creates an OAuth access token that can be used as part of the OAuth functionality of a properly configured app. The function will return the token, but will also automatically set the state variable state.accessToken to the return value. This value can then be passed to any API Endpoint (for example those defined in the mappings section of an app) using a query string parameter called access_token.
String createAccessToken()None
The OAuth access token.
Returns the base URL of the Hubitat cloud API.
String getApiServerUrl()None
The base URL of the Hubitat cloud API, generally https://cloud.hubitat.com/api
Returns the full URL of the Hubitat cloud API for a specific App.
String getFullApiServerUrl()None
The URL of the Hubitat cloud API for the app, generally https://cloud.hubitat.com/api/hubid/apps/appid
Returns the base URL of the Hubitat local API.
String getLocalApiServerUrl()None
The base URL of the Hubitat local API, generally https://hubip/apps/api
Returns the base URL of the Hubitat local API for a specific App.
String getFullLocalApiServerUrl()None
The URL of the Hubitat local API for the app, generally https://hubip/apps/api/appid
Retrieves a unique identifier that represents your hub.
String getHubUID()None
A UUID that uniquely identifies your hub.
Returns a List of Rooms the user has configured on their hub along with select information for each.
List<Map> getRooms()None
A List of Maps. Each Map contains the following keys/values:
id - unique Long identifying this roomname - a String matching the name the user provided for this roomdeviceIds - a List of Long device IDs for devices the user has assigned to this room (note that this does not allow you to use these devices unless the user has already selected them from an input in your app, as normal)Example: [[id:1, name:"Bedroom", deviceIds:[5, 6]], [id:2, name:"Kitchen", deviceIds:[7]]
Subscribe to events sent from a device, app or location.
void subscribe(InstalledAppWrapper app, handlerMethod)
void subscribe(Location location, handlerMethod)
void subscribe(DeviceWrapper device, String handlerMethod, Map options = null) (Since 2.2.1)
void subscribe(DeviceWrapperList devices, String handlerMethod, Map options = null) (Since 2.2.1)
void subscribe(DeviceWrapper device, String attributeName, handlerMethod, Map options = null)
void subscribe(DeviceWrapperList devices, String attributeName, handlerMethod, Map options = null)
void subscribe(Location location, String attributeName, handlerMethod, Map options = null)
app - Installed App to subscribe tolocation - Location to subscribe todevice - Device to subscribe tohandlerMethod - The method to run when an event is receivedattributeName - The name of the attribute to subscribe tooptions - Optional values to configure the subscribe. Possible values:
Boolean filterEvents - Used for device subscriptions. Defaults to true, which ignores events where the value did not change (unless isStateChange is set to true on the event, in which case the event will still be handled). Set to false to receive all events.String subscriptionData - (as of platform 2.4.1) Can optionally be used to pass a subscriptionData field to the handler method with the specified data, e..g, [subscriptionData: "someValue"]Unsubscribe from events sent from a device or all event subscriptions.
void unsubscribe()
void unsubscribe(DeviceWrapper device)
void unsubscribe(List<DeviceWrapper> deviceList)
void unsubscribe(DeviceWrapper device, String attributeName) (Since 2.0.7)
void unsubscribe(List<DeviceWrapper> deviceList, String attributeName) (Since 2.1.0)
void unsubscribe(DeviceWrapper device, String attributeName, String handlerMethod) (Since 2.1.0)
void unsubscribe(List<DeviceWrapper> deviceList, String attributeName, String handlerMethod) (Since 2.1.0)
void unsubscribe(InstalledAppWrapper installedApp) (Since 2.1.2)
void unsubscribe(Location location) (Since 2.1.2)
void unsubscribe(Location location, String attributeName) (Since 2.1.2)
void unsubscribe(String handlerMethod) (Since 2.1.2)
device - The device to unsubscribe from.deviceList - A list of devices to unsubscribe from.attributeName - which attribute you want to unsubscribe from.handlerMethod - The name of a method which was subscribed to a device event.location - The location to unsubscribe from.installedApp - The installed app to unsubscribe from.None
Creates a new child device and returns that device from the method call.
ChildDeviceWrapper addChildDevice(String namespace, String typeName, String deviceNetworkId) (since 2.1.9)
ChildDeviceWrapper addChildDevice(String namespace, String typeName, String deviceNetworkId, Map properties) (since 2.1.9)
ChildDeviceWrapper addChildDevice(String namespace, String typeName, String deviceNetworkId, Long hubId) (deprecated)
ChildDeviceWrapper addChildDevice(String namespace, String typeName, String deviceNetworkId, Long hubId, Map properties) (deprecated)
namespace - The namespace of the child driver to add as a child device (optional, if not specified it will default to the namespace of the parent)
typeName - The name of the child driver to add as a child device
deviceNetworkId - unique identifier for this device
hubId - present for backwards compatibility, pass 1.
properties - optional parameters for this child device. Possible values listed below
Properties:
boolean isComponent - true or false, if true, device will still show up in device list but will not be able to be deleted or edited in the UI. If false, device can be modified/deleted on the UI.String name - name of child device, if not specified, driver name is used.String label - label of child device, if not specified it is left blank.ChildDeviceWrapper
Gets a list of all child devices for this device.
List<ChildDeviceWrapper> getChildDevices()
List<ChildDeviceWrapper> getAllChildDevices()
None
List<ChildDeviceWrapper>
Gets a specific child device with the device network id specified.
ChildDeviceWrapper getChildDevice(String deviceNetworkId)deviceNetworkId - The unique identifier for the deviceChildDeviceWrapper
Deletes a specific child device with the device network id specified.
void deleteChildDevice(String deviceNetworkId)deviceNetworkId - The unique identifier for the deviceNone
Generates an event for the app based on the values in the provided map. (NOTE: App events are rarely used. Only a few built-in apps, mostly older apps, utilize this feature. Writing to logs is often a better method of communicating information, debugging, etc. This method is more commonly used in drivers to generate events that apps may subscribe to.)
void sendEvent(Map properties)void sendEvent(DeviceWrapper device, Map properties)void sendEvent(String dni, Map properties)device - Optional; the device (DeviceWrapper) to generate the event for, instead of the app.dni - Optional; the device network ID of the device to generate the event for, instead of the app.properties - a Map of properties for the event. Valid keys are:
String name (required) - name of the eventvalue (required) - value of the eventString unit - units corresponding to the value, if appropriateString descriptionText - a human-friendly description of the event or additional informationBoolean isStateChange - typically omitted; if true, will generate event even if previous value is the same as new valuesendEvent(name: "myAppEvent", value: "theValue")none
Appends a path to the configured cloud API base URL.
String apiServerUrl(String url)url - Path appended to the API base URLThe cloud API base URL followed by / and the supplied path String.
Appends a path to this app’s cloud API base URL.
String fullApiServerUrl(String url)url - Path appended to the API base URLThis app’s cloud API base URL followed by / and the supplied path String.
Appends a path to the local apps API base URL.
String localApiServerUrl(String url)url - Path appended to the API base URLThe local apps API base URL followed by / and the supplied path String.
Appends a path to this app’s local API base URL.
String fullLocalApiServerUrl(String url)url - Path appended to the API base URLThis app’s local API base URL followed by / and the supplied path String.
Returns the map that stores this app's state, also available as the state property (e.g., state.lastRun = now()).
Map getState()None
The state Map. Keys and values are defined by the app.
Replaces the app's state with the supplied map.
void setState(Map value)value - The entries to store as the app's state.none
Pauses app script execution for the requested number of milliseconds and records that runtime as paused.
void pause(Long millisecs)millisecs - Pause duration in millisecondsnone
Retrieves this app's parent app, if it is a child app.
InstalledAppWrapper getParent()None
The parent InstalledAppWrapper, or null if there is no parent app.
Creates a child app under the current installed app.
InstalledAppWrapper addChildApp(String namespace, String name, String label, Map properties = null)namespace - Namespace containing the child app typename - Child app type namelabel - Display labelproperties - Optional; defaults to null. Properties assigned to the new child appThe InstalledAppWrapper for the new child app
Deletes the specified child app of the current installed app.
void deleteChildApp(Long childAppId)childAppId - Child app idnone
Retrieves this app's child apps.
def getChildApps()None
A list of the child apps (InstalledAppWrapper objects)
Retrieves this app's child apps. Same as getChildApps().
def getAllChildApps()None
A list of the child apps (InstalledAppWrapper objects)
Retrieves one of this app's child apps by its ID.
def getChildAppById(Long childAppId)childAppId - Child app idThe child app (InstalledAppWrapper), or null if there is no such child app
Retrieves one of this app's child apps by its label.
def getChildAppByLabel(String childAppLabel)childAppLabel - Child app label to matchThe child app (InstalledAppWrapper), or null if there is no such child app
Retrieves the child apps of the installed app with the specified ID.
List<InstalledAppWrapper> getChildAppsByParentId(Long parentAppId)parentAppId - Installed parent app idA list of the child apps (InstalledAppWrapper objects); empty if there are none
Changes the active location mode by its name.
void setLocationMode(String mode)mode - Location mode name to activatenone
Changes the active location mode when the supplied mode id exists.
void setLocationModeById(Long modeId)modeId - The ID of the mode to activate.none
Changes location mode unless the requested mode would replace Away.
void setModeUnlessAway(Long modeId)modeId - The ID of the mode to activate.none
Exits Away mode.
void exitAwayMode()None
none
Returns location events with the requested attribute at or after the supplied start date.
List<Event> getLocationEventsSince(String attributeName, Date startDate, Map options = null)attributeName - Event attribute namestartDate - Earliest event date to includeoptions - Optional; query options for the event lookup.A list of Event objects
Retrieves a device by ID, but only if this app is subscribed to it.
DeviceWrapper getSubscribedDeviceById(Long deviceId)deviceId - Device idThe DeviceWrapper, or null if the app is not subscribed to a matching device
Returns installed apps reported as using the supplied device.
List<InstalledApp> getAppsUsingDevice(Long deviceId)deviceId - Device idA list of InstalledApp objects for the apps using the device
Retrieves the devices with the specified IDs. IDs that do not match a device are omitted.
List<DeviceWrapper> getDevicesByIds(List<Long> deviceIds)deviceIds - Device idsA list of DeviceWrapper objects
Retrieves an installed app by its ID.
InstalledApp getAppByAppId(Long installedAppId)installedAppId - Installed app idThe InstalledApp for the ID, or null if it does not exist.
Finds app ids by namespace and name, optionally filtering by app type.
List<Long> getInstalledAppIds(String namespace, String name, String appTypeType = null)namespace - Namespace containing the app or device typename - App type nameappTypeType - Optional; defaults to null. App type filter; null leaves all app typesA List of app ids matching namespace and name, filtered by type when appTypeType is non-null; no matches produce an empty list.
Checks whether an app with the namespace and name is installed, optionally restricting its type.
boolean isAppInstalled(String namespace, String name, String type = "ANY")namespace - Namespace containing the app typename - App type nametype - Optional; app type filter; defaults to ANYTrue when an app matching namespace, name, and requested type is installed; otherwise false.
Checks whether an installed app with the namespace, name, and label exists, optionally restricting its type.
boolean isAppInstalledByLabel(String namespace, String name, String installedAppLabel, String type = "ANY")namespace - Namespace containing the app typename - App type nameinstalledAppLabel - Installed app label to matchtype - Optional; app type filter; defaults to ANYTrue when an app matching namespace, name, label, and requested type is installed; otherwise false.
Checks whether a library exists for the namespace and name.
boolean isLibraryPresent(String namespace, String name)namespace - Namespace containing the libraryname - Library nameTrue when a library exists for the namespace and name; otherwise false.
Returns bundle id, name, and namespace records for installed bundles.
List getInstalledBundlesList()None
A List of maps; each map contains:
id: Long bundle id.name: String bundle name.namespace: String bundle namespace.Returns discovered mDNS service records, optionally filtered by service type.
List<Map> getMdnsServiceTypes(String type = null)type - Optional; defaults to null. Service type filter; null includes all discovered typesA List of maps copied from the mDNS service entries. Each map contains:
type: String service type.name: String service instance name.ip: String IP address.mac: String MAC address.isInstalled: Boolean installed flag.deviceId: nullable Long associated device id.properties: Map<String,String> service properties.Compresses UTF-8 text with GZIP and returns the compressed bytes as Base64 text.
String gzipAndBase64(String s)s - The text to compress.A Base64 String containing the GZIP-compressed UTF-8 bytes of s.
Decodes Base64 text, decompresses the GZIP payload, and returns UTF-8 text.
String unzipBase64(String s)s - The Base64-encoded, GZIP-compressed text to expand.The UTF-8 text from the Base64-decoded GZIP payload.
Sends a HubAction or HubMultiAction immediately, without waiting for it to complete.
Future sendHubCommand(HubAction hubAction)Future sendHubCommand(HubMultiAction hubMultiAction)hubAction - The HubAction to send.hubMultiAction - The HubMultiAction to send.A Future for the submitted command. Its result is null, and failures are logged rather than reported through the Future.
Returns the number of queued hub commands for this app execution.
int getPendingHubCommandCount()None
Number of actions waiting in the app command queue.
Creates and stores an additional OAuth access token without replacing existing tokens.
String createAnotherAccessToken()None
The new access token (a String). Throws a RuntimeException if OAuth is not enabled for the app.
Returns the stored OAuth access tokens as a list when OAuth is enabled.
List<String> getAccessTokens()None
A List of the app's stored access tokens (empty if there are none). Throws a RuntimeException if OAuth is not enabled for the app.
Removes all of the app's stored access tokens.
void revokeAccessToken()None
none
Removes the specified access token from the app's stored access tokens.
void revokeSpecificAccessToken(String token)token - The access token to revoke.none
Replaces the specified access token with a newly generated one.
void resetSpecificAccessToken(String token)token - The access token to replace.none
Returns whether Hubitat UI security is enabled.
boolean isHubitatUISecurityEnabled()None
true if security is enabled for the Hubitat UI, false otherwise.
These methods should be defined in your app code and will be called as indicated below.
This method is called when the app is first installed.
void installed()This method is called when the preferences of an installed app are updated (e.g., user clicks "Done" button).
void updated()This method is called when the app is uninstalled. This method can be used to do any cleanup that is necessary.
void uninstalled()