Helpers

A helper is an entityAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] that you create yourself, without a device behind it. For example, a toggle that pauses an automation, a timer that counts down, or a sensor that shows the average temperature of several rooms. Helpers appear like other entities, so you can use them in automations, scripts, and dashboards.

You create and manage helpers in Settings > Devices & services > Helpers.

About the kinds of helpers

There are three kinds of helpers:

• Helpers that store a value, such as a toggle or a timer
• Helpers that calculate a value from other entities, such as the average of several sensors
• Other helpers, which combine or control other entities, such as a group of lights

Helpers that store a value

These helpers keep what you or an automation set: a value, like the state of a toggle, or settings values, like the time blocks of a schedule.

• Toggle
  • An on/off switch. For example, use it to pause an automation or to show that a guest is staying over.
• Number
  • A number that you set with a slider or a box. For example, use it for a target temperature.
• Dropdown
  • One option from a list that you define. For example, use it for the mode of your home.
• Text
  • A short piece of text. For example, use it for a message to show on a dashboard.
• Date and/or time
  • A date, a time, or both. For example, use it for the time your alarm goes off.
• Button
  • A button that you press to start automations. It remembers when it was last pressed.
• Counter
  • A whole number that goes up, goes down, or starts again from its initial value. For example, use it to count how many times a door opened today.
• Timer
  • Counts down a time that you set. You can start, pause, cancel, finish, or change it.
• Schedule
  • Turns on during time blocks that you set for each day of the week. For example, use it for the hours when the heating should be on.

Helpers that calculate a value

These helpers calculate their value from other entities, and update it when those entities change. For example:

• Combine the state of several sensors: The minimum, maximum, average, or sum of several sensors.
• Derivative sensor: How fast a value changes, such as how fast the temperature rises.
• Integral sensor: A total over time. For example, it calculates the energy used from the power.
• Utility Meter: The use of energy, gas, or water per day, week, month, or another period.
• History Stats: How long or how often an entity was in a state, such as how long the heating was on today.
• Threshold Sensor: Whether a value is above or below a limit that you set.
• Template: An entity whose state comes from a template, a small piece of code.

For all helpers of this kind, refer to the list of helpers.

Other helpers

Some helpers do more than store or calculate a value. For example:

• Generic thermostat: Turns a heater or a cooler on and off, based on a temperature sensor.
• Group: Combines several entities into one, such as all lights in a room.
• Change device type of a switch: Shows a switch as another type of device, such as a light.

When do you need a helper?

Most automations don’t need a helper. You need one when Home Assistant has to remember something, when you want to set something yourself that an automation then uses, or when you want a sensor that calculates its value from other entities. For example:

• You want to pause an automation without editing it, such as while you’re on vacation.
  • Create a Toggle. The automation only runs while the toggle is on. To pause the automation, turn the toggle off on your dashboard.
• You want to choose a value on your dashboard, and let automations use it.
  • Create a Number for a value, such as the temperature the heating should reach.
  • Or create a Dropdown for a choice, such as the mode of your home: Home, Away, or Night.
• You want something to happen a while later, even if Home Assistant restarts in between.
  • Create a Timer, and turn on Restore state and time when Home Assistant starts. One automation starts the timer, and another one reacts when it finishes.
  • If the timer finishes while Home Assistant isn’t running, the automation that reacts to it doesn’t run. For details, refer to the known limitations of the timer.
• You want to count something, such as how often the doorbell rang today.
  • Create a Counter. An automation increases it each time.
• You want a sensor that combines other sensors, such as the average temperature of all rooms.
  • Create a Combine the state of several sensors helper.

If none of these sounds like your situation, you probably don’t need a helper yet.

Creating a helper

1. Go to Settings > Devices & services > Helpers.
2. Select Create helper.
3. Select the type of helper, such as Toggle.
4. Enter a name, and fill in the other options.
5. Select Create or Submit, depending on the type of helper.

Some places let you create a helper right where you need it. For example, if a field asks for a toggle, a number, or a dropdown, the list of entities offers to create a new helper of that type.

To change a helper later, select it in the list of helpers, and change its settings. Helpers that you set up in YAML can’t be changed in the UI. Their settings show The settings of this entity cannot be edited from the UI. Only entities set up from the UI are configurable from the UI.

What happens to a helper value after a restart?

Home Assistant restarts now and then, such as after an update or a power cut. If your automations depend on a helper, it matters whether the helper still has its value afterwards. For example, if a “Guests staying over” toggle turned itself off, an automation could turn down the heating in the guest room. And if a timer started idle again, the reminder it was counting down to would never come.

Most helpers keep their value after a restart, so usually you don’t need to do anything. Check these cases:

• A timer that should keep running
  • By default, a timer stops when Home Assistant restarts, and is idle afterwards. If an automation depends on the timer, turn on Restore state and time when Home Assistant starts in the settings of the timer. If the timer finishes while Home Assistant isn’t running, automations that react to it don’t run after the restart.
• A toggle that should always start on or off
  • By default, a toggle keeps its state. If it should always be On, or always Off, after a restart, change Each time Home Assistant starts in the settings of the toggle.
• A counter that should start again from its initial value
  • By default, a counter keeps its value. To start at its initial value after every restart, turn off Restore the last known value when Home Assistant starts in the settings of the counter.
• A number or a dropdown whose settings you changed
  • If you change the range of a number, its value moves to the nearest new limit. For example, if the value is 30 and you change the maximum to 25, the value becomes 25. If you change the range in YAML instead, and the last value is outside the new range, the number starts at its minimum after the restart.
  • If you remove the option that a dropdown is set to, the dropdown shows as Unknown until you select another option. After a restart, it starts at its first option.

In YAML, a number, dropdown, text, or date and time helper can have an initial value. It then starts with that value after every restart, instead of its last value.

Helpers that calculate a value calculate it again from their entities. A schedule works out from its time blocks whether it’s on.

Where can you use helpers?

You can use helpers in these places:

• In automations and scripts
  • An automation can start when the helper changes. For example, the Timer finished trigger starts an automation when a timer finishes.
  • An automation can check the helper in a condition. For example, the automation only continues if a toggle is on.
  • An automation or a script can change the helper in an action. For example, an automation can turn on a toggle or start a timer.
  • For more examples, refer to Which tool to use.
• On a dashboard
  • You can see and change the helper yourself. For example, use a toggle to pause an automation, or a number to set a target temperature. Add the helper to a card, like any other entity.
• With Assist
  • You can change the helper with your voice. For example, you can turn a toggle on or off. First, expose the helper to Assist.