Skip to content

enkama/hass-variables

 
 

Repository files navigation

Variables+History

aka. variable

Variable Logo

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

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.