Variables+History

aka. variable

A Home Assistant Integration to declare and set/update variables.

Forked and updated from initial integration developed by rogro82

Home Assistant versions starting with v2024.7.2 will prevent Variables+History versions earlier than v3.4.5 from working. Be sure to upgrade.

Upgrading from v2 to v3

Existing variables will remain as yaml variables but instead of starting with variable., they will now start with sensor. If you would like to manage the variable using the UI configuration, you will need to delete the entity from your yaml and recreate it in the UI. This is also the only change needed when migrating from rogro82's version to this one

Installation

HACS (recommended)

1. Ensure that HACS is installed
2. Click Here to directly open Variables+History in HACS or
     a. Navigate to HACS
     b. Click + Explore & Download Repositories
     c. Find the Variables+History integration
   
3. Click Download
4. Restart Home Assistant
5. See Configuration below

Manual

You probably do not want to do this! Use the HACS method above unless you know what you are doing and have a good reason as to why you are installing manually

1. Using the tool of choice open the directory (folder) for your HA configuration (where you find configuration.yaml)
2. If you do not have a custom_components directory there, you need to create it
3. In the custom_components directory create a new folder called variable
4. Download all the files from the custom_components/variable/ directory in this repository
5. Place the files you downloaded in the new directory you created
6. Restart Home Assistant
7. See Configuration below

Preferred Configuration

1. Click Here to directly add a Variables+History sensor or
     a. In Home Assistant, go to Settings -> Integrations
     b. Click + Add Integrations and select Variables+History
   
2. Add your configuration (see Configuration Options below)
3. Click Submit

• Repeat as needed to create additional Variables+History sensors
• Options can be changed for existing Variables+History sensors in Home Assistant Integrations by selecting Configure under the desired Variables+History sensor.

Configuration Options

First choose the variable type.

Sensor

Name	Required	Default	Description
Variable ID	Yes		The desired id of the new sensor (ex. test_variable would create an entity_id of sensor.test_variable)
Name	No		Friendly name of the variable sensor
Icon	No	mdi:variable	Icon of the Variable
Initial Value	No		Initial value/state of the variable. If Restore on Restart is False, the variable will reset to this value on every restart
Initial Attributes	No		Initial attributes of the variable. If Restore on Restart is False, the variable will reset to this value on every restart
Restore on Restart	No	True	If True will restore previous value on restart. If False, will reset to Initial Value and Initial Attributes on restart
Force Update	No	False	Variable's last_updated time will change with any service calls to update the variable even if the value does not change
Exclude from Recorder	No	False	For Variables with large attributes (>16 kB), enable this to prevent Recorder Errors.

Binary Sensor

Name	Required	Default	Description
Variable ID	Yes		The desired id of the new binary sensor (ex. test_variable would create an entity_id of binary_sensor.test_variable)
Name	No		Friendly name of the variable binary sensor
Icon	No	mdi:variable	Icon of the Variable
Initial Value	No	False	Initial True/False value/state of the variable. If Restore on Restart is False, the variable will reset to this value on every restart
Initial Attributes	No		Initial attributes of the variable. If Restore on Restart is False, the variable will reset to this value on every restart
Restore on Restart	No	True	If True will restore previous value on restart. If False, will reset to Initial Value and Initial Attributes on restart
Force Update	No	False	Variable's last_updated time will change with any service calls to update the variable even if the value does not change
Exclude from Recorder	No	False	For Variables with large attributes (>16 kB), enable this to prevent Recorder Errors.

Device Tracker

Name	Required	Default	Description
Variable ID	Yes		The desired id of the new device tracker (ex. test_variable would create an entity_id of device_tracker.test_variable)
Name	No		Friendly name of the variable device tracker
Icon	No	mdi:variable	Icon of the Variable
Initial Latitude	Yes		Latitude
Initial Longitude	Yes		Longitude
Initial Location Name	No		If set, will show this as the state
Initial GPS Accuracy	No		Accuracy in meters
Initial Battery Level	No		Battery level from 0-100%
Initial Attributes	No		Initial attributes of the variable
Restore on Restart	No	True	If True will restore previous value on restart. If False, will reset to Initial Latitude, Initial Longitude, Initial Location Name, Initial GPS Accuracy, Initial Battery Level, and Initial Attributes on restart
Force Update	No	False	Variable's last_updated time will change with any service calls to update the variable even if the value does not change
Exclude from Recorder	No	False	For Variables with large attributes (>16 kB), enable this to prevent Recorder Errors.

Alternate YAML Configuration

Variables created via YAML will all start with sensor. and cannot be edited in the UI.

You can have a combination of Variables created via the UI and via YAML.

Add the component variable to your configuration and declare the variables you want.

Name	yaml	Required	Default	Description
Variable ID	<key>:	Yes		The desired id of the new sensor (ex. test_variable would create an entity_id of sensor.test_variable)
Name	name	No		Friendly name of the variable sensor
Initial Value	value	No		Initial value/state of the variable. If Restore on Restart is False, the variable will reset to this value on every restart
Initial Attributes	attributes	No		Initial attributes of the variable. If Restore on Restart is False, the variable will reset to this value on every restart
Restore on Restart	restore	No	True	If True will restore previous value on restart. If False, will reset to Initial Value and Initial Attributes on restart
Force Update	force_update	No	False	Variable's last_updated time will change with any service calls to update the variable even if the value does not change
Exclude from Recorder	exclude_from_recorder	No	False	For Variables with large attributes (>16 kB), set to True to prevent Recorder Errors.

Example:

variable:
  countdown_timer:
    value: 30
    attributes:
      friendly_name: 'Countdown'
      icon: mdi:alarm
  countdown_trigger:
    name: Countdown
    value: False
  light_scene:
    value: 'normal'
    attributes:
      previous: ''
    restore: true
  current_power_usage:
    force_update: true

  daily_download:
    value: 0
    restore: true
    attributes:
      state_class: measurement
      unit_of_measurement: GB
      icon: mdi:download

Services

There are instructions and selectors when the service is called from the Developer Tools or within a Script or Automation.

variable.update_sensor

Used to update the value or attributes of a Sensor Variable

Name	Key	Required	Default	Description
Targets	target:   entity_id:	Yes		The entity_ids of one or more sensor variables to update (ex. sensor.test_variable)
New Value	value	No		Value/state to change the variable to
New Attributes	attributes	No		What to update the attributes to
Replace Attributes	replace_attributes	No	False	Replace or merge current attributes (False = merge)

variable.update_binary_sensor

Used to update the value or attributes of a Binary Sensor Variable

Name	Key	Required	Default	Description
Targets	target:   entity_id:	Yes		The entity_ids of one or more binary sensor variables to update (ex. binary_sensor.test_variable)
New Value	value	No		Value/state to change the variable to
New Attributes	attributes	No		What to update the attributes to
Replace Attributes	replace_attributes	No	False	Replace or merge current attributes (False = merge)

variable.update_device_tracker

Used to update the value or attributes of a Device Tracker Variable

Name	Key	Required	Default	Description
Targets	target:   entity_id:	Yes		The entity_ids of one or more device tracker variables to update (ex. device_tracker.test_variable)
Latitude	latitude	No		Latitude
Longitude	longitude	No		Longitude
Location Name	location_name	No		If set, will show this as the state
Delete Location Name	delete_location_name	No		Remove the Location Name so state will be based on Lat/Long (boolean)
GPS Accuracy	gps_accuracy	No		Accuracy in meters
Battery Level	battery_level	No		Battery level from 0-100%

variable.toggle_binary_sensor

Used to toggle the state or update attributes of a Binary Sensor Variable. If the binary_sensor state is None, the toggle service will not change the state.

Name	Key	Required	Default	Description
Targets	target:   entity_id:	Yes		The entity_ids of one or more binary sensor variables to toggle (ex. binary_sensor.test_variable)
New Attributes	attributes	No		What to update the attributes to
Replace Attributes	replace_attributes	No	False	Replace or merge current attributes (False = merge)

Legacy Services

These will only work for Sensor Variables

These services are from the previous version of the integration and are being kept for pre-existing automations and scripts. In general, the new variable.update_ and variable.toggle_ services above should be used going forward.

Both services are similar and used to update the value or attributes of a Sensor Variable. variable.set_variable uses just the variable_id and variable.set_entity uses the full entity_id. There are instructions and selectors when the service is called from the Developer Tools or within a Script or Automation.

variable.set_variable

Name	Key	Required	Default	Description
Variable ID	variable	Yes		The id of the sensor variable to update (ex. test_variable for a sensor variable of sensor.test_variable)
Value	value	No		Value/state to change the variable to
Attributes	attributes	No		What to update the attributes to
Replace Attributes	replace_attributes	No	False	Replace or merge current attributes (False = merge)

variable.set_entity

Name	Key	Required	Default	Description
Entity ID	entity	Yes		The entity_id of the sensor variable to update (ex. sensor.test_variable)
Value	value	No		Value/state to change the variable to
Attributes	attributes	No		What to update the attributes to
Replace Attributes	replace_attributes	No	False	Replace or merge current attributes (False = merge)

Example service calls

action:
  - service: variable.update_sensor
    data:
      value: 30
    target:
      entity_id: sensor.test_timer

action:
  - service: variable.update_sensor
    data:
      value: >-
        {{trigger.to_state.name|replace('Motion Sensor','')}}
      attributes:
        history_1: "{{states('sensor.last_motion')}}"
        history_2: "{{state_attr('sensor.last_motion','history_1')}}"
        history_3: "{{state_attr('sensor.last_motion','history_2')}}"
    target:
      entity_id: sensor.last_motion

action:
  - service: variable.update_binary_sensor
    data:
      value: true
      replace_attributes: true
      attributes:
        country: USA
    target:
      entity_id: binary_sensor.test_binary_var

Example timer automation

• Create a sensor variable with the Variable ID of test_timer and Initial Value of 0

script:
  schedule_test_timer:
    sequence:
      - service: variable.update_sensor
        data:
          value: 30
        target:
          entity_id: sensor.test_timer
      - service: automation.turn_on
        data:
          entity_id: automation.test_timer_countdown

automation:
  - alias: test_timer_countdown
    initial_state: 'off'
    trigger:
      - platform: time_pattern
        seconds: '/1'
    action:
      - service: variable.update_sensor
        data:
          value: >
            {{ [((states('sensor.test_timer') | int(default=0)) - 1), 0] | max }}
        target:
          entity_id: sensor.test_timer
  - alias: test_timer_trigger
    trigger:
      platform: state
      entity_id: sensor.test_timer
      to: '0'
    action:
      - service: automation.turn_off
        data:
          entity_id: automation.test_timer_countdown

Examples

Play and Save TTS Messages + Message History - Made by jazzyisj

https://github.com/jazzyisj/save-tts-messages

This is more or less an answering machine (remember those?) for your TTS messages. When you play a TTS message that you want saved under certain conditions (i.e. nobody is home), you will call the script Play or Save TTS Message script.play_or_save_message instead of calling your tts service (or Alexa notify) directly. The script will decide whether to play the message immediately, or save it based on the conditions you specify. If a saved tts message is repeated another message is not saved, only the timestamp is updated to the most recent instance.

Messages are played back using the Play Saved TTS Messages script "script.play_saved_tts_messages". Set an appropriate trigger (for example when you arrive home) in the automation Play Saved Messages automation.play_saved_messages automation to call this script automatically.

Saved messages will survive restarts.

BONUS - OPTIONAL TTS MESSAGE HISTORY

You can find the full documentation on how to do this and adjust this to your needs in here.

More examples can be found in the examples folder.

Removing variables safely

This project implements safeguards to avoid orphaned variables and entity registry entries. If you need to remove a variable created via YAML or via the UI, follow the steps below.

Removing YAML-created variables

• Remove the variable entry from your configuration.yaml (under the variable: section).
• Reload or restart Home Assistant.
• The integration will detect YAML-imported variables that are no longer present and automatically remove their corresponding config entries. If an entry remains, you can remove it from Settings → Integrations → Variables+History → ... → Delete.

Removing UI-created variables

• In Home Assistant go to Settings → Integrations → Variables+History and select the variable to configure.
• Use the integration's UI to remove or delete the variable. This will delete the Config Entry and the integration now also cleans up entity registry entries during unload so the entity should disappear from the Entities list.

If an entity remains without a unique_id (orphaned entity)

1. Open Settings → Devices & Services → Entities and search for the orphaned entity.
2. If the entity has no unique ID and cannot be removed via the UI, go to Settings → Devices & Services → Entities → three-dot menu → Delete (if available). If that is not available, you can remove the entity registry entry manually by editing the .storage/core.entity_registry file in your Home Assistant config (advanced — backup first) or use the UI or entity_registry service from a local script.
3. After removing the registry entry, restart Home Assistant. The entity should no longer appear.

Note: Manual edits to .storage are advanced and should be done carefully with a backup. The integration now tries to prevent these situations by removing YAML-missing entries and cleaning up entity registry entries when a config entry unloads.