The var component is a Home Assistant integration for declaring and
setting generic variable entities. Variables can be set manually using
the var.set service or they can be set using templates or SQL queries
which will be run automatically whenever a specified event fires. The
var component depends on the recorder component for up-to-date SQL
queries and uses the same database setting.
- Installation
- Configuration
- Services
- Automatic Updates
- Templates
- SQL Queries
- Scenes
- Lovelace UI
- Reload
- Why?
- Useful Links
- Download the latest release.
- Unpack the release and copy the
custom_components/vardirectory into thecustom_componentsdirectory of your Home Assistant installation. - Add a
varentry to yourconfiguration.yaml. - Restart Home Assistant.
- Ensure that HACS is installed.
- Search for and install the "Variable" integration.
- Add a
varentry to yourconfiguration.yaml. - Restart Home Assistant.
To add a variable, include it under the var component in your
configuration.yaml. The following example adds two variable entities,
x and y:
# Example configuration.yaml entry
var:
x:
friendly_name: 'X'
initial_value: 0
icon: mdi:bug
y:
friendly_name: 'Y'
initial_value: 'Sleeping'
entity_picture: '/local/sleep.png'var (map) (Required)
-
unique_id (string)(Optional) Unique identifier for VAR entity, to enable overriding settings from within the UI, such as the entity name or room. Use with care, and only if explicitly required!
-
friendly_name (string)(Optional) Name to use in the frontend.
-
friendly_name_template (template)(Optional) Defines a template for the name to be used in the frontend (this overrides
friendly_name).Note:
friendly_name_templateis evaluated every time an update is triggered for the variable (i.e., viatracked_entity_id,tracked_event_type, orvar.update). To pass a template to be evaluated once byvar.set, use thefriendly_nameparameter in adata_template. -
initial_value (match_all)(Optional) Initial value when Home Assistant starts.
-
value_template (template)(Optional) Defines a template for the value (this overrides
initial_value).Note:
value_templateis evaluated every time an update is triggered for the variable (i.e., viatracked_entity_id,tracked_event_type, orvar.update). To pass a template to be evaluated once byvar.set, use thevalueparameter in adata_template. -
attributes (map)(Optional) Dictionary of attributes equivalent to that of HomeAssistant template sensor attributes.
Similar to value_template, attributes are evaluated on every update.
-
tracked_entity_id (string | list)(Optional) A list of entity IDs so the variable reacts to state changes of these entities.
-
tracked_event_type (string | list)(Optional) A list of event types so the variable reacts to these events firing.
-
query (string)(Optional) An SQL QUERY string, should return 1 result at most.
-
column (string)(Optional) The SQL COLUMN to select from the result of the SQL QUERY.
-
restore (boolean)(Optional) Restores the value of the variable whenever Home Assistant is restarted.
Default value: true
-
force_update (boolean)(Optional) Trigger a state change event every time the value of the variable is updated, even if the value hasn't changed. If false, state change events will only be triggered by distinct changes in value.
Default value: false
-
unit_of_measurement (string)(Optional) Defines the units of measurement of the variable, if any. This will also influence the graphical presentation in the history visualization as a continuous value. Variables with missing
unit_of_measurementare shown as discrete values.Default value: None
-
icon (string)(Optional) Icon to display for the component.
-
icon_template (template)(Optional) Defines a template for the icon to be used in the frontend (this overrides icon).
Note:
icon_templateis evaluated every time an update is triggered for the variable (i.e., viatracked_entity_id,tracked_event_type, orvar.update). To pass a template to be evaluated once byvar.set, use theiconparameter in adata_template. -
entity_picture (string)(Optional) Picture to display for the component.
-
entity_picture_template (template)(Optional) Defines a template for the
entity_pictureto be used in the frontend (this overridesentity_picture).Note:
entity_picture_templateis evaluated every time an update is triggered for the variable (i.e., viatracked_entity_id,tracked_event_type, orvar.update). To pass a template to be evaluated once byvar.set, use theentity_pictureparameter in adata_template.
The set service can be used to set the state or attributes of the
variable entity from an automation or a script. All config
parameters can also be set using var.set.
- entity_id
(string | list)(Required)
A list of
varentity IDs to be set by the service. - friendly_name (string)(Optional)
- friendly_name_template (template)(Optional)
- value (match_all)(Optional)
- value_template (template)(Optional)
- attributes (map)(Optional)
- tracked_entity_id (string | list)(Optional)
- tracked_event_type (string | list)(Optional)
- query (string)(Optional)
- column (string)(Optional)
- restore (boolean)(Optional)
- force_update (boolean)(Optional)
- unit_of_measurement (string)(Optional)
- icon (string)(Optional)
- icon_template (template)(Optional)
- entity_picture (string)(Optional)
- entity_picture_template (template)(Optional)
This example sets up an automation that resets the values of the variables at midnight.
var:
daily_diaper_count:
friendly_name: "Daily Diaper Count"
initial_value: 0
icon: mdi:toilet
daily_bottle_feed_volume_formula:
friendly_name: "Daily Formula Intake"
initial_value: 0
unit_of_measurement: 'ounces'
icon: mdi:baby-bottle-outline
automation:
- alias: "Reset Baby Counters"
trigger:
- platform: time
at: '00:00:00'
action:
- service: var.set
data:
entity_id:
- var.daily_diaper_count
- var.daily_bottle_feed_volume_formula
value: 0
icon: mdi:nullThe update service can be used to force the variable entity to update
from an automation or a script.
- entity_id
(string | list)(Required)
A list of
varentity IDs to be updated by the service.
This example sets up an automation that updates the variable every 5 minutes.
var:
temp_sensor_battery:
friendly_name: "Temp Sensor Battery"
value_template: "{{ state.attr('sensor.temperature', 'battery') }}"
automation:
- alias: "Update Temp Sensor Battery Var Every 5 Minutes"
trigger:
- platform: time_pattern
minutes: '/5'
action:
- service: var.update
data:
entity_id: var.temp_sensor_batteryNote: The homeassistant.update_entity service can be used more generally to update any entity, including var entities.
A variable can be set to update whenever the state of an entity changes.
This example counts the number of times the state changes for
input_boolean.foo and input_boolean.bar.
var:
toggle_count:
friendly_name: "Toggle Count"
initial_value: 0
value_template: "{{ (states('var.toggle_count') | int) + 1 }}"
tracked_entity_id:
- input_boolean.foo
- input_boolean.barA variable can be set to update whenever an event fires. This example
multiplies variables y and z whenever my_custom_event fires.
var:
x:
friendly_name: 'yz'
value_template: "{{ (states('var.y') | int) * ( states('var.z') | int) }}"
tracked_event_type: my_custom_event
attributes:
y: "{{ states('var.y') }}"
z: "{{ states('var.z') }}"The var component shares features with the
template sensor.
Many of a variable's attributes can be set using templates.
Templates can be used with the variable set service to select the
entity_id and to set any of the attributes of a variable entity. This
example shows entity_id and value being selected via template.
automation:
- alias: "Handle Bottle Feed Event"
trigger:
platform: event
event_type: bottle_feed_event
action:
service: var.set
data_template:
entity_id: >-
{% if trigger.event.data.contents == 'milk' %}
var.daily_bottle_feed_volume_milk
{% elif trigger.event.data.contents == 'formula' %}
var.daily_bottle_feed_volume_formula
{% endif %}
value: >-
{% if trigger.event.data.contents == 'milk' %}
{{ (states('var.daily_bottle_feed_volume_milk') | int) + (trigger.event.data.volume | int) }}
{% elif trigger.event.data.contents == 'formula' %}
{{ (states('var.daily_bottle_feed_volume_formula') | int) + (trigger.event.data.volume | int) }}
{% endif %}
attributes: >-
last_feed_volume: "{{ trigger.event.data.volume }}"
This example shows how the value, and other attributes of the variable,
can be set to update automatically based on the state of another entity.
Template values will be updated whenever the state changes for any of
the tracked entities listed below tracked_entity_id.
var:
waldo_location_status:
friendly_name: "Waldo Location Status"
value_template: >-
{% if states('device_tracker.waldo_phone_wifi') == 'home' and states('device_tracker.waldo_phone_bluetooth') == 'home' %}
Home
{% else %}
Unknown
{% endif %}
entity_picture_template: >-
{% if states('var.waldo_location_status') == 'Home' %}
/local/home.jpg
{% else %}
/local/question_mark.jpg
{% endif %}
tracked_entity_id:
- device_tracker.waldo_phone_wifi
- device_tracker.waldo_phone_bluetooth
- var.waldo_location_statusThe var component also shares features with the
SQL sensor. When a
variable updates, it will run the SQL query against the Home Assistant
database updating the variable with the value of the query.
This example shows how the value, and other attributes of the variable,
can be set to update automatically based on an SQL query. Template
values will be updated whenever the state changes for any of the tracked
entities listed below tracked_entity_id or when any event fires with
the same event type as any of the event types listed below
tracked_event_type.
var:
todays_diaper_count:
friendly_name: "Today's Diaper Count"
icon: mdi:toilet
query: "SELECT COUNT(*) AS diaper_count FROM events WHERE event_type = 'diaper_event' AND time_fired BETWEEN DATETIME('now', 'start of day') AND DATETIME('now');"
column: 'diaper_count'
tracked_event_type: diaper_eventThis example shows how to use an SQL query to filter events based on
their event_data. In the example, diaper_event contains an
event_data entry called type that is either wet, dirty, or
both.
var:
todays_wet_diaper_count:
friendly_name: "Today's Wet Diaper Count"
icon: mdi:water
query: "SELECT COUNT(*) AS diaper_count FROM events WHERE event_type = 'diaper_event' AND JSON_EXTRACT(event_data, '$.type') LIKE '%wet%' AND time_fired BETWEEN DATETIME('now', 'start of day') AND DATETIME('now');"
column: 'diaper_count'
tracked_event_type: diaper_eventThe result of a variable's SQL query can also be used within templates.
This example computes the average formula volume over the past week and
adds it to the variable z. In this example, bottle_event contains an
event_data entry called volume that contains the volume of formula.
var:
avg_formula_plus_z:
friendly_name: "Average Formula Plus z"
value_template: "{{ ( avg_formula | float) + ( states('var.z') | float) }}"
query: "SELECT COALESCE(SUM(CAST(JSON_EXTRACT(event_data, '$.volume') AS FLOAT))/7.0, 0) AS avg_formula FROM events WHERE event_type = 'bottle_event' AND time_fired BETWEEN DATETIME('now', 'start of day', '-7 days') AND DATETIME('now', 'start of day');"
column: 'avg_formula'
tracked_event_type: bottle_eventYou may set the values of variables with scenes:
- name: My Scene
entities:
var.my_var: 'New Value'Variables can be displayed in the Lovelace frontend like other entities.
cards:
- type: entities
title: "Baby Variables"
entities:
- entity: var.daily_diaper_count
- entity: var.daily_bottle_feed_volume_milk
- entity: var.daily_bottle_feed_volume_formulaSetting a unit_of_measurement will prompt Home Assistant to display a
two dimensional graph in its history panel and history-graph card.
cards:
- type: history-graph
title: "Baby Plots"
hours_to_show: 24
entities:
- entity: var.daily_bottle_feed_volume_milk
- entity: var.daily_bottle_feed_volume_formulaTip: Using a unit of ' ' can be useful if you want to group unit-less
variables together in a single 2D graph.
Variable configuration can be reloaded without restarting HA using the
YAML tab on the Developer Tools page. When the var component is loaded
an option will be added to the YAML configuration reloading section
named Variables. Clicking this option will reload all var
configuration.
Note: the component is only loaded by HA at startup when configuration
is defined for the component. This means that if the var component is
installed and HA is restarted without var configuration the reload
option is not available yet. You have to add some configuration first
and restart HA again before the reload option becomes available.
I assembled this component for a few reasons:
- It was tedious to create a corresponding separate template sensor for each entity in the UI.
- I wanted a single general-purpose component, with a generic name, that could be used to store, update, and display values using templates.
- I didn't like using named UI components to store first-class data
(e.g.
input_text). - I wanted to be able to work with data directly from the home assistant database (especially custom events) without having to create and flip-flop between a bunch of different entities.
- I wanted a custom component that I could extend with more features in the future.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent