¶ Hub Variables
The Settings > Hub Variables page allows you to create and manage hub variables and hub variable connectors.
¶ Creating a Hub Variable
To create a hub variable, select the + (plus sign) icon below the table of variables:
Then fill in the required information:
-
Provide a name for the variable. This is how you will reference the variable later in apps (e.g., rules, Hubitat® Dashboard, etc.). It can contain letters, numbers, or spaces but may not contain an of the following characters:
' " \ ~ [ ] < >. In this example, we will call the variableMyNumberVariable.
-
Select a Variable Type for the new variable. In this example, we will use Number:
-
Provide an initial value for the variable (all variables must be initialized with a valid value for the specified type):
¶ Hub Variable Types
Available types of hub variables are:
- Number: an integer, positive or negative
- Decimal: a number including a decimal point, positive or negative
- String: text, including letters, numbers, spaces, etc. (maximum length: 1024 characters, previously 256)
- Boolean: true or false
- DateTime: a specific date, time of day, or both
¶ Managing Hub Variables
The table at the top of the Hub Variables page displays the current hub variables (if any have been created) and their current values. Note that current values are current as of page load but may not reflect current values if they were changed elsewhere afterwards (until the page is reloaded)
The table also provides ways to manage these variables:
¶ Creating Connectors
To create a hub variable connector, select the Create link (B) in the Connector column. If a connector has already been created, the type of the connector will appear in the Connector column with the type of connector that was created (A), and selecting the link will take you to the device detail page for that connector.
It is not necessary to create a connector unless you have a specific use case (many apps can simply use the hub variable directly). See below for more information on hub variable connectors.
¶ Setting Values Manually
While variable values will generally be set by an app (e.g., a rule), the value can be set manually by selecting the current value under the Value column and providing a new value.
¶ Finding Variables in Use By Apps
If a variable is in use by an app, the variable name in the Name column will appear in orange-colored text, and selecting the variable name will pop up a list of apps that have registered their use of this variable. Select Done to dismiss this list and return to the hub variables table.
Note that this will not show apps that use a variable connector instead of the variable directly. (This is, of course, only possible if a connector has been created; see below. Connectors are no longer necessary for most uses.) Connectors act like regular devices, and their use can be checked by navigating to the device detail page for the connector and checking the In use by section.
¶ Renaming Hub Variables
Hub variables in use by apps can be renamed by selecting the name of the variable in the table, selecting Rename, providing a new name, then clicking/tapping outside the field and selecting Done to save changes. Variables that are not in use by any apps cannot be renamed in this way, but you can simply create a new variable with the desired name and remove the old variable.
See below for information on hub variable connector names (for the most part, connectors can be renamed directly like regular devices).
¶ Deleting a Variable
To delete a hub variable, select the trash can icon (delete) under the Delete column (C). This will delete the hub variable and, if created, the associated connector. It is recommended to remove a variable from app apps by which it or an associated connector are in use (see above) before deleting a variable.
¶ Connectors
A connector is a device that is tied to the value of its corresponding hub variable. These devices can be used in apps that cannot work directly with hub variables — a relatively new feature that was not always available to apps, with connectors providing this functionality in the past. Connectors continue to remain available, and if you are already using a connector in an app, there is no reason to change. However, now that direct access is available, the direct use of a variable is preferred over a connector if the app offers direct use. For example, there is no reason to create a connector to use a variable with Hubitat Dashboard, Rule 5.0 or newer rules, and an increasing variety of other apps.
¶ Connector Types
Most types of connectors offer the ability for a variable to "pretend" to be a more common type of device that many apps are likely to provide a way to work with if they cannot work with variables directly. Supported connector types vary by variable type, and the behavior of the connector (and variable — the value of one will always reflect in the other) is usually straightforward to assume from the type of connector. The following is a list of variable types, the connector types they support, and the behavior of those connector devices:
- Supported connector types for Boolean variables:
- Acceleration: active when true, inactive when false
- Contact: open when true, closed when false
- Lock: locked when true, unlocked when false
- Motion: active when true, inactive when false
- Presence: present when true, not present when false
- Switch: on when true, off when false
- Water: wet when true, dry when false
- Variable: see below
- Supported connector types for DateTime variables:
- DateTime: see below
- Supported connector types for Decimal variables:
- Temperature: temperature corresponding to variable value
- Variable: see below
- Supported connector types for Number variables:
- ColorTemp: color temperature corresponding to variable value
- Dimmer: level corresponding to variable value
- Humidity: humidity corresponding to variable value
- Illuminance: illuminance corresponding to variable value
- Volume: volume corresponding to variable value
- Variable: see below
For example, creating a Switch connector for Boolean variable will allow you to set the value of that variable in apps that only support switches by turning the switch on to set the variable to true or off to set it to false. The value can also be read in such apps: if the switch is on, the variable is true, and vice versa.
The Variable type of connector creates a device with an attribute variable that represents the current value and a command setVariable() that takes one parameter, the new value to set. (This type of connector is rarely needed now that any app can support direct access to variables instead; connectors pre-date this functionality, and this was once a generic workaround for that.)
The DateTime variable offers a single type of connector, DateTime. This connector offers three commands, setDate(), setDateTime(), and setTime(). All of these commands accept one parameter, which must be a full date/time string in the format YYYY-MM-DDThh:mm:ss.000-0Z00, e.g., 2023-09-15T09:30:00.000-0600. To set only a date or only a time, fill in any missing part with nines (9) to make a complete string, e.g., 2023-09-16T99:99:99.999-0600 for only a date. (The user interface on the device detail page will offer a date-only or time-only picker and does not require this effort; this will be necessary to know if calling the command directly from an app. This includes a custom app, Maker API, or when setting the hub variable directly using the hub variable API.)
¶ Renaming Variable Connectors
The name of a hub variable connector can be updated independently of the hub variable name. This is done on the device detail page for that variable connector, just like any other device. However, if the hub variable itself renamed (see above), the variable connector name will be overwritten to match the updated hub variable name at that time.
¶ Uses for Hub Variables
Hub variables have many possible uses. Any time you need to store a value and share it among multiple apps, a hub variable may be useful. In certain apps like Rule Machine, hub variables can also be used to store the result of a computation (or as an operand in these computations), as can the Rule-Machine–specific "local variables" feature (which may be preferred if apps outside that rule do not need access to this variable).
Many apps also offer the ability to use hub variables for some function, from being able to use a boolean variable to enable or disable app behavior or using a number or decimal variable as an alternative to specifying a literal numeric value in the app (thus allowing to to automate the changing of this value by other means). For example, Room Lighting can use a variable for color temperature or level values, among other possibilities.
Possible uses are limited only by your imagination. The Community forum is full of fellow users who can give you ideas or help find solutions for your problems if you're looking for more help.
¶ Hub Variables API
For developers looking to use hub variables inside a custom app, see the hub variable API documentation.