¶ Hub Variable API
Hubitat provides an interface for app developers to use hub variables in their own apps. (Many built-in apps use this feature, too!)
NOTE: This information is for developers wanting to use hub variables in their own apps. End users looking for information how to create or use hub variables (including in built-in apps, like Rule Machine), should consult the hub variables documentation.
This is a brief introduction to how to use Hub Variables in user apps.
¶ Hub Variables Methods
¶ Getting a Global Variable (by Name)
getGlobalVar(String name)- Returns:
GlobalVariableobject with properties:[name: xx, type: xx, value: xx, deviceId: xx, attribute: xx]for global variable with name matchingname(if none,null)- Note:
valueis already cast to data type corresponding to variable type,Integer || BigDecimal || Boolean || String || DateTime deviceIdandattributeapply to variables with connectors and will be deprecated as connectors are phased out
- Note:
- Returns:
¶ Setting a Global Varible
Boolean setGlobalVar(String name, Object value)
¶ Adding a Value to a Global Variable
Boolean addValueToGlobalVar(String name, Object value)- Note: global variable type must be Integer or BigDecimal
¶ Getting All Global Varibles or All by Type
-
Map getGlobalVarsByType(String type)- where
typeis:"integer" || "bigdecimal" || "boolean" || "string" || "datetime" - Returns: same format as
getAllGlobalVars(), below
- where
-
Map getAllGlobalVars()- Returns
Mapin format:[globalVarName:[type:xx, value:xx, deviceId,xx] ,... ](as above,deviceIdwill be phased out as connectors are)
- Returns
¶ Registering Use
Apps that use a hub variable should register it as in use. (This will display in the "(Variable name) is in use by these apps" popup on the Hub Variables settings page when the user selects the name of the variable and will warn the user before deleting such a variable. Users generally expect this behavior.)
From the app using the variable (the hub will register that app as the app using the variable), the below methods can be called:
Boolean addInUseGlobalVar(String variableName)(registersvariableName)Boolean addInUseGlobalVar(List variableNames)(registers all variable names in list)
To remove when your app is no longer using the variable(s):
Boolean removeInUseGlobalVar(String variableName) (un-registers variableName)
Boolean removeAllInUseGlobalVar() (un-registers all registered variables)
Developers may find it easiest to call removeAllInUseGlobalVar() and then re-register variables that they know are in use. Often, this will be done in the updated() method of your app.
The Boolean return value for all the add/remove methods above designates success or failure of those methods (true or false, respectively).
¶ Hub Variable Events
Changes in the value of a hub variable are sent via Location Events. These events are logged on the Location Events tab of the Logs page (see below for examples) with event names beginning with "variable:" followed by the variable name. These events can be subscribed to in two ways:
-
subscribe(location, "variable:variable-name", "myHandlerMethodName") -
subscribe(location, "variable:variable-name.value", "myHandlerMethodName")
The first example subscribes to all events for the variable names "variable-name". The second example subscribes to events for "variable-name" that have "value" as the event value.
Here are two log examples:
¶ Renamed Variables
When a hub variable is renamed (from the Hub Variables settings page, the hub will call the following method in an app:
void renameVariable(String oldName, String newName)
Apps that use hub variables should implement this method and respond appropriately (e.g, update the value of settings that refer to hub variable names).
¶ A Note on DateTime Variables
DateTime variables are strings in this date format: yyyy-MM-dd'T'HH:mm:ss.sssXX, for example: 2022-10-13T14:25:09.009-0700.
Hub variables can also use a DateTime variable to represent only a date or only a time. In such cases, the "missing" components should be substituted with the digit 9 (as many times as needed to ensure the format is still correct). For example, a time-only variable with a blank date could look like: 9999-99-99T14:25:09.009-0700. If the variable contains only a date with blank time, the string is like 2022-10-13T99:99:99:999-9999. Built-in app UIs would display these as only times or only dates, respectively. Your apps should also gracefully handle all three possibilities: date, time, or date and time and display appropriate presentation (and provide appropriate values back to the hub). Generally you can test for the two special cases above with startsWith("9999") or endsWith("9999").
¶ Connectors
When hub variables were first introduced, the above API was not available. Thus, custom apps had to rely on variable connectors, which are devices that apps can use via standard means (see the Hub Variables docs for more on the role of connectors). Direct use of hub variables, as above, is preferred wherever possible. (Variable connectors may be phased out in the future, though existing connectors will continue to work and the ability to create new ones may be removed.)