Other features

These are some Spook-specific features that don’t fit in any of the other categories. They are not particularly useful, but they are fun to play with (and maybe you actually have a use case for them).

They originally served as the proof of concept for Spook and left them in for the fun of it.

Actions¶

Spook offers the following useless actions:

Boo!¶

This acti will just always scare Home Assistant, causing this action call to fail. Calling this action in any of your automations will thus cause your automation to stop and error.

1
action: homeassistant.boo

Random fail¶

This action call will randomly fail (and thus randomly stop your automation or script).

1
action: homeassistant.random_fail

Wait for a condition¶

Waits until a condition is true, and carries on straight away if it already is.

Home Assistant can wait for a template to turn true, and it can wait for a trigger. It cannot wait for a condition, so anything you can express with the condition building blocks has to be rewritten as a template before you can wait on it.

Takes one condition or a list of them, and a list means all of them, the same as anywhere else. Which is also what the visual editor sends, so both shapes have to work.

The other half of what this fixes is that it looks first. wait_for_trigger always waits for something to happen, so if the thing you are waiting for has already happened you wait forever, which is why people wrap it in an if. This checks the condition before waiting, so an automation that arrives late still carries on.

Returns completed when it is given a response_variable, which says whether the condition arrived or the timeout did.

1
2
3
4
5
6
action: spook.wait_for_condition
data:
  condition:
    condition: state
    entity_id: binary_sensor.back_door
    state: "off"

1
2
3
4
5
6
7
8
9
10
11
12
13
- action: spook.wait_for_condition
  data:
    timeout: "00:05:00"
    condition:
      condition: state
      entity_id: binary_sensor.back_door
      state: "off"
  response_variable: waited
- if: "{{ not waited.completed }}"
  then:
    - action: notify.persistent_notification
      data:
        message: The back door is still open.

Triggers¶

Spook offers the following triggers that are not tied to a specific integration:

Automation turned off¶

Fires when an automation is turned off.

This trigger has no options.

An automation that is off does nothing, and does not say so either. Turning one off while chasing a problem and forgetting to turn it back on is how a house quietly stops doing things. This trigger tells you the moment it happens, whoever or whatever did it: somebody in the editor, an automation, or a snooze.

Leave the target out to hear about every automation in the house. That is usually the question, and it saves labelling all of them just to be able to ask it.

When it fires, trigger.entity_id names the automation, and trigger.from_state and trigger.to_state hold its state just before and after. Whoever turned it off is on the context, so spook.triggered_by_user and spook.not_triggered_by_user can tell a person from an automation.

1
trigger: spook.automation_turned_off

1
2
3
4
5
6
7
8
9
10
triggers:
  - trigger: spook.automation_turned_off
conditions:
  - condition: spook.triggered_by_user
actions:
  - action: notify.notify
    data:
      message: >-
        {{ state_attr(trigger.entity_id, 'friendly_name') }} was turned off.
        Remember to turn it back on.

Cron schedule¶

Fires on a crontab schedule.

Home Assistant’s own time triggers cover a time of day and a time pattern. Between them they cannot say “every weekday at seven” or “the last Friday of the month”. A crontab expression says either in one line, and anybody who has written a crontab already knows the syntax.

Five fields, in the usual order: minute, hour, day of month, month, day of week. Ranges and steps work, and so do the day-of-week extensions, so MON#2 is the second Monday of the month and 5L the last Friday.

When it fires, trigger.schedule holds the expression and trigger.now the local time it fired at.

One crontab rule catches people out, and it is not ours. Give both a day of the month and a day of the week, and cron combines them with “or”, not “and”. So 0 7 15 * 1 runs at seven on the 15th of the month, and at seven every Monday as well. Leave one of the two as * if you only mean the other.

That “or” holds only while both fields are plain lists of days. Let either one start with a *, a step like */2 included, and the two combine with “and” instead: 0 7 15 * */2 is the 15th, but only when it falls on a Sunday, Tuesday, Thursday or Saturday.

1
2
3
trigger: spook.cron
options:
  schedule: "0 7 * * 1-5"

1
2
3
trigger: spook.cron
options:
  schedule: "0 15 * * 5L"

Device discovered¶

Fires when Home Assistant discovers something new it could set up.

This trigger has no options.

Home Assistant finds devices and services on its own: on your network, over Bluetooth, on a USB port, or announced by another integration. What it finds ends up in the Discovered list under Settings > Devices & services, and there it waits for somebody to look. Nothing in Home Assistant tells you that something new turned up today. This trigger does.

When it fires, trigger.domain is the integration that could set it up, trigger.name what it calls itself, if it says, trigger.source how it was found (zeroconf, dhcp, bluetooth, usb, ssdp and so on), trigger.unique_id the identifier the integration gave it, trigger.title_placeholders everything the integration shows about it in the list, and trigger.flow_id the discovery itself.

1
trigger: spook.device_discovered

Entity came back¶

Fires when an entity returns after having been unavailable for a while.

Home Assistant will tell you the moment something goes unavailable and the moment it returns, but not the difference between a blink and an outage. A router rebooting takes every device in the house through unavailable and back inside seconds, which is why an automation on the plain return is usually more trouble than it is worth.

This one only counts a return worth hearing about. The entity has to have been away for at least as long as you asked before coming back says anything, so the freezer that dropped off the network overnight reaches you and the reload of an integration does not.

The absence starts when the entity goes unavailable and ends when it reaches a state that is neither unavailable nor unknown. A device that reconnects before it has a reading passes through unknown on the way, and that neither ends the absence nor restarts it. An entity that only ever sits at unknown has not been away at all: that is the entity answering rather than the entity missing.

When it fires, trigger.entity_id names the entity that came back, trigger.gone_since is when it went, trigger.gone_for is how long it was away, and trigger.for is the minimum you configured.

1
2
3
4
5
trigger: spook.recovered
target:
  area_id: garage
options:
  for: "00:15:00"

1
2
3
4
5
trigger: spook.recovered
target:
  entity_id: sensor.freezer_temperature
options:
  for: "02:00:00"

Device added¶

Fires when a new device is added to Home Assistant.

This trigger has no options.

Home Assistant announces a new device on its event bus and nowhere else. A plug paired by somebody else in the house, or a Zigbee device that joined the network on its own, goes unnoticed until somebody browses the device list. This trigger tells you right away.

When it fires, trigger.device_id is the new device’s identifier, trigger.name its name, trigger.manufacturer and trigger.model what it is, trigger.area_id the area it was put in, if any, and trigger.integration the integration it belongs to. A device that is part of another one, like one outlet of a power strip, has no make or model of its own, so those are empty for it.

1
trigger: spook.device_added

1
2
3
4
5
triggers:
  - trigger: spook.device_added
conditions:
  - condition: template
    value_template: "{{ trigger.integration == 'zha' }}"

Entity fell silent¶

Fires when nothing has written to an entity for a while.

Home Assistant will tell you an entity went unavailable. Plenty of things die without ever saying so: an integration that quietly stopped polling, a battery device that dropped off the network, an MQTT topic nobody publishes to any more. The state sits there looking perfectly healthy, holding a reading from last Tuesday.

This watches for silence rather than for a value. A sensor that keeps reporting the same 21.5 every minute is alive and is left alone; one that stops reporting altogether fires after the duration you set. Point it at whole areas, floors or labels and the entities underneath are watched one at a time, each firing separately when it falls silent.

When it fires, trigger.entity_id names the entity that went quiet, trigger.last_reported is when it last spoke, and trigger.for is the duration you configured.

1
2
3
4
5
trigger: spook.stale
target:
  area_id: attic
options:
  for: "01:00:00"

1
2
3
4
5
trigger: spook.stale
target:
  entity_id: sensor.greenhouse_temperature
options:
  for: "00:15:00"

Integration added¶

Fires when an integration is added to Home Assistant.

This trigger has no options.

Fires for every integration added to Home Assistant, whether you added it, another admin did, or Home Assistant set one up by itself, like when a configuration in YAML is imported for the first time. Integrations that were already there when Home Assistant started are not added, so a restart stays quiet.

When it fires, trigger.domain is the integration, trigger.title the name of the new entry, trigger.entry_id its identifier, and trigger.source how it came to be: user for somebody adding it by hand, zeroconf or dhcp or another discovery for one that was found on the network, import for one from YAML.

1
trigger: spook.integration_added

Integration failed to set up¶

Fires when a configuration entry has been unable to set itself up for a while.

An integration that cannot reach its hardware fails to set up, and Home Assistant keeps retrying it on a backoff that tops out at ten minutes. A device switched off overnight therefore fails dozens of times before morning, which is why this trigger waits rather than firing on each attempt. Set for to how long you are willing to let something be broken before you want to hear about it, and the ordinary hiccups at start-up sort themselves out well inside it.

Every configuration entry is watched unless you name some in entry_id. Each one is reported on its own, and only once per spell of trouble: an entry has to come back before it can be reported again.

When it fires, trigger.domain is the integration, trigger.title the name of the entry, trigger.entry_id its identifier, trigger.state the state it is stuck in, trigger.reason whatever Home Assistant recorded about why, and trigger.for the duration you configured.

1
2
3
trigger: spook.integration_failed
options:
  for: "00:15:00"

1
2
3
4
trigger: spook.integration_failed
options:
  for: "00:05:00"
  entry_id: 01JQ8XW3M4YPKZ7N2VRTGH6BDC

Position reached¶

Fires when a cover or valve gets to a position, or moves past it.

Home Assistant tells you a cover opened or closed. Everything in between, the blinds at a third or the valve half open, is a position it reports but never announces.

It fires when the reported position gets to the one you asked for, from either side. Moving past it counts too: a cover moving quickly can report 20 and then 40 without ever reporting the 30 in between. Already being there is not reaching it, and it does not fire again until the cover has left and come back. The position is a whole percentage, from 0 (closed) to 100 (fully open).

When it fires, trigger.entity_id names the cover or valve, trigger.position is the position you asked for, and trigger.from_state and trigger.to_state hold its state just before and after.

1
2
3
4
5
trigger: spook.position_reached
target:
  entity_id: cover.blinds
options:
  position: 30

Repair issue created¶

Fires when a new repair issue turns up.

Home Assistant collects repair issues on the repairs page and waits to be visited. This is for the ones you would rather hear about: an integration reporting it needs attention, or Spook finding a reference to something that no longer exists.

Only genuinely new issues fire it. An integration re-reporting an issue that is already there counts as an update rather than a creation, which is what keeps a repair checked on a schedule from firing on every pass.

When it fires, trigger.domain is the integration that reported it, trigger.issue_id names the issue, and trigger.severity, trigger.is_fixable, trigger.breaks_in_ha_version, trigger.learn_more_url and trigger.translation_key carry the rest of what the registry knows.

1
trigger: spook.repair_issue_created

1
2
3
4
5
6
7
8
trigger: spook.repair_issue_created
options:
  domain:
    - hue
    - zwave_js
  severity:
    - critical
    - error

Repair issue resolved¶

Fires when a repair issue goes away.

Something got fixed, or whatever was complaining stopped complaining. Handy for closing a notification you opened when the issue turned up.

When it fires, trigger.domain and trigger.issue_id say which issue it was.

1
2
3
trigger: spook.repair_issue_removed
options:
  domain: hue

Target temperature reached¶

Fires when the temperature of a thermostat or water heater reaches its target.

A thermostat or water heater knows where it is heading and where it is. Home Assistant tells you when either one changes, but not when the one arrives at the other, which is the moment that matters.

It fires when the measured temperature gets to the target, coming from either side. Jumping past it counts too: a sensor that reports in whole degrees can go from below the target to above it without ever reporting the target itself. Once there, it does not fire again until the temperature has left and come back.

Heating and cooling to a band, in heat_cool, is there anywhere inside the band. A thermostat that can do both reports a setpoint and a band whatever mode it is in; in heat_cool the band counts, in any other mode the setpoint.

The tolerance is how close still counts as there, in the device’s own unit. Some thermostats settle just short of their setpoint and stay there; a tolerance of half a degree catches those. Zero, the default, means the target itself.

When it fires, trigger.entity_id names the device, and trigger.from_state and trigger.to_state hold its state just before and after.

1
2
3
trigger: spook.target_temperature_reached
target:
  entity_id: climate.bathroom

1
2
3
4
5
trigger: spook.target_temperature_reached
target:
  floor_id: upstairs
options:
  tolerance: 0.5

Update installed¶

Fires when an update entity reports a different installed version.

This trigger has no options.

Home Assistant tells you when an update is available, but not when one went in. This one fires when it did, and it does not care how: somebody pressed install, the device updated itself overnight, or it was updated with the app of whoever made it. A rollback is a different version too, and fires the same way.

The installed version is the only thing it reads. Whether an install is in progress says little: plenty of integrations never report it, and a device that reboots into its new firmware drops off before it can say it is done. The last version seen is remembered while the entity is unavailable, so a device that goes away mid-install and comes back on the new version is reported when it comes back.

When it fires, trigger.entity_id names the update entity, trigger.from_version is the version it was on, and trigger.to_version the version it is on now. trigger.from_state and trigger.to_state hold the entity’s state just before and after the change. On a device that went away mid-install, trigger.from_state is that of it being unavailable, which is why the versions are given separately.

1
2
3
trigger: spook.update_installed
target:
  area_id: garage

1
2
3
4
5
6
7
8
9
10
triggers:
  - trigger: spook.update_installed
    target:
      entity_id: update.plug_firmware
actions:
  - action: notify.notify
    data:
      message: >-
        The plug went from {{ trigger.from_version }}
        to {{ trigger.to_version }}.

Script started¶

Fires when a script starts a run.

This trigger has no options.

Home Assistant does announce every script run, as a script_started event. Using it means knowing that event exists, and typing its name and the script into an event trigger by hand: no picker, no area or label, nothing in the list of triggers. It also announces runs the script refuses straight after, like a second one for a script that may only run once at a time.

This one sits in the list of triggers with a target picker, and only fires for a run that is let through. Leave the target out to hear about every script.

When it fires, trigger.entity_id names the script, and trigger.from_state and trigger.to_state hold its state just before and after. Whoever started it is on the context, so spook.triggered_by_user and spook.not_triggered_by_user work with it.

1
2
3
trigger: spook.script_started
target:
  area_id: kitchen

1
2
3
trigger: spook.script_started
target:
  entity_id: script.movie_night

Spook’s state trigger¶

Fires when an entity changes state, for everything a target covers.

Home Assistant’s state trigger takes entities, one by one. This one takes a target: a label, an area, a floor, a device, or a mix. Put a label on every outside door and one trigger covers all of them, including the door you add next year.

Which entities. Everything the target covers, kept to the domains, integrations, integration entries and device classes you list. Leave the target out and those lists pick the entities from everything Home Assistant has instead: device_class: door alone is every door in the house. Without a target, at least one of them is needed. Picked this way, only primary entities count, and entities without a registry entry can only be picked by domain. Within one list any match will do; across lists, all of them must hold: a door sensor from ZHA is a binary_sensor, from zha, of class door. Through a device, area or floor, or a label on one of those, only the primary entities count, the way Home Assistant does it, so the battery and signal strength sensors of a device stay out of it. A label put on an entity itself names that entity, so it counts whatever it is. Then the same again, but to leave things out: exclude_target and the exclude_ lists. Without an exclude_target, or with one that names nothing, the exclude_ lists apply to everything the target covers. Leaving out an area leaves out everything in it, the diagnostic entities too. The target is followed as it changes: a new entity with the label joins straight away.

Which changes. A different state, from any state to any state, unless you narrow it down with from or not_from, and to or not_to. An attribute that changes while the state stays the same does not count, unless you turn on attribute_changes. With attribute, it follows that attribute instead of the state, and attribute_changes has nothing to add. Values are compared as text, so a brightness of 255 and a "255" typed into the editor are the same thing.

Unavailable and unknown are ignored on both sides: a router rebooting does not take every door through a change. Turn off ignore_unavailable to trigger on them. Naming them in from or to while they are ignored is refused, since that trigger could never fire. Following an attribute, from and to are its values, so an attribute that says unknown is fine to ask for.

How many. behavior works like it does on Home Assistant’s own entity triggers. each fires for every entity on its own. first fires when the first one of the target gets there, and not again until none of them are. all fires the moment the last one gets there. Both are about getting to a state, so they need to or not_to. While unavailable and unknown are ignored, entities in those states do not take part: a door that is not answering does not keep all from firing.

When. for waits until the change has held for that long. Held means that value: changing again in between calls it off, even to another value that would pass to. For first and all it is the target that has to hold, not one entity. blip_tolerance lets something drop to unavailable or unknown for a moment while for is running without starting the wait over: it counts as still there until it is back, as it was, or the tolerance runs out. Coming back as anything else calls the wait off. If the time runs out during the blip, it fires as soon as the blip is over. delay waits before firing, whatever happens in between, like a delay at the start of your actions. With both, delay starts once for is done.

When it fires, trigger.entity_id names the entity, trigger.from_state and trigger.to_state hold its state just before and after the change, and trigger.for and trigger.delay the durations you asked for. With delay, those are still the states of the moment it changed.

1
2
3
4
5
6
7
8
9
10
11
trigger: spook.state_changed
target:
  label_id: outside_door
options:
  domain: binary_sensor
  device_class: door
  exclude_target:
    area_id: garage
  to: "on"
  for: "00:05:00"
  blip_tolerance: "00:00:30"

User added¶

Fires when somebody is given a login to Home Assistant.

This trigger has no options.

A new person able to log in to your house is something you would rather hear about than stumble upon. Home Assistant does announce it, but only as an event on its bus: no notification, nothing on a page you visit.

When it fires, trigger.user_id is the new user’s identifier, trigger.name their name, and trigger.is_admin whether they were made an administrator.

1
trigger: spook.user_added

1
2
3
4
5
triggers:
  - trigger: spook.user_added
conditions:
  - condition: template
    value_template: "{{ trigger.is_admin }}"

Conditions¶

Spook offers the following conditions that are not tied to a specific integration:

Triggered by a user¶

Passes when a person set this run going.

What this can see is the person behind the trigger. Somebody flipping a switch, tapping something in the app, or calling an action from the API leaves their user account on the state change or event that follows, so an automation reacting to it finds them. A template trigger inherits it too, when the change that made the template true was theirs. A schedule, the sun, or an integration acting on its own leaves nobody.

If the person attribute is not provided, the condition passes for anybody. Name one or more people to narrow it, and Spook matches against the user account each of them is linked to.

1
condition: spook.triggered_by_user

1
2
3
4
5
condition: spook.triggered_by_user
options:
  person:
    - person.frenck
    - person.joe

Not triggered by a user¶

Passes when nobody set this run going.

This condition has no options. It passes for anything Spook cannot pin on a person: a schedule, the sun, an integration acting on its own, or a run forced with the Run button.

“Nobody started this” is a different question from “not this particular person”, which is why this condition takes no options. To exclude specific people, wrap Triggered by a user in Home Assistant’s own Not condition:

1
2
3
4
5
condition: not
conditions:
  - condition: spook.triggered_by_user
    options:
      person: person.frenck

That passes for anybody who is not Frenck, and also when nobody was behind it at all, which is what “not Frenck” means.

1
condition: spook.not_triggered_by_user

Cooldown¶

Passes when this automation or script has not run within a given time.

A built-in cooldown, so an automation does not re-fire more often than you want it to. An automation that has never run passes, because there is no last run to be too close to.

It replaces the most copy-pasted template condition there is:

{{ now() - this.attributes.last_triggered >= timedelta(minutes=5) }}

1
2
3
condition: spook.cooldown
options:
  duration: "00:05:00"

Chance¶

Passes a set percentage of the time, chosen at random on every check.

For when you want a bit of variation rather than the same thing every evening.

1
2
3
condition: spook.chance
options:
  percentage: 20

Triggered by an automation¶

Passes when another automation set this run going.

Home Assistant gives every automation run its own context, and everything that run writes carries it along. So an automation reacting to a change another automation made can find out who did it, and it keeps working when there is a script in between, because the script runs under the automation’s context rather than making one of its own.

What Home Assistant does not do is turn a context back into the automation it belongs to, so Spook listens for automations announcing themselves and remembers the mapping for the last few hundred runs. That is far more than enough: the run being asked about happened a fraction of a second earlier.

If the automation attribute is not provided, the condition passes for any automation. Name one or more to narrow it.

1
condition: spook.triggered_by_automation

1
2
3
4
5
condition: spook.triggered_by_automation
options:
  automation:
    - automation.goodnight
    - automation.leaving_home

Repair issue outstanding¶

Passes while a repair issue is outstanding.

For holding something back until the house is in order: not running a nightly job while an integration is complaining, or nagging once a day for as long as anything is wrong.

Leave the options out and any outstanding issue passes it. Name integrations, severities, or both, and all the named parts have to match the same issue.

1
condition: spook.repair_issue_present

1
2
3
4
5
6
7
condition: spook.repair_issue_present
options:
  domain:
    - hue
    - zwave_js
  severity:
    - critical

Temperature at its target¶

Passes when the temperature of a thermostat or water heater is at its target.

The question spook.target_temperature_reached answers once, asked whenever you like: is the bathroom warm yet, is the water hot. It reads the devices the same way the trigger does, so the two never disagree.

With several devices, any passes when one of them is there and all when every one is. A band, in heat_cool, counts anywhere inside it, and the tolerance is how close still counts as there, in the device’s own unit.

1
2
3
condition: spook.is_at_target_temperature
target:
  entity_id: climate.bathroom

1
2
3
4
5
6
condition: spook.is_at_target_temperature
target:
  floor_id: upstairs
options:
  behavior: all
  tolerance: 0.5

Run allowance left¶

Passes while this automation has runs to spare.

The counterpart to Cooldown: that one spaces runs out, this one caps how many there are. Handy for something that is fine now and then but not fifty times a day, like a notification about a door that keeps being opened.

The window rolls. A limit of five over a day means no more than five runs in any twenty-four hours, not five between midnights, so the allowance comes back gradually as the oldest run drops out of the window rather than all at once.

Runs are counted from what actually ran. Home Assistant does not announce an automation whose conditions turned the run down, so an attempt something else held back costs nothing.

1
2
3
4
condition: spook.quota
options:
  limit: 5
  period: "24:00:00"

1
2
3
4
condition: spook.quota
options:
  limit: 2
  period: "01:00:00"

Entity is available¶

Passes when an entity is there to talk to.

A speaker that is not always powered, a smart plug that comes and goes: before asking them to do anything, you want to know they are there. Any state counts, off included, except unavailable and unknown. Written by hand, that is a not around a state condition listing both, every time.

With several entities, any passes when one of them is there and all when every one is.

1
2
3
condition: spook.is_available
target:
  entity_id: media_player.bathroom

1
2
3
4
5
condition: spook.is_available
target:
  area_id: living_room
options:
  behavior: all

All of these happened¶

Fires when every one of several triggers has fired inside the same window of time, in any order.

Home Assistant cannot say “and” over time. The triggers on an automation are a list where any one of them is enough to set it off, and for covers a single state holding still. “These three things have all happened in the last five minutes, in whatever order” is not expressible, and written out by hand it takes a helper entity for each thing and an automation to set each one.

Triggers in order already covers the case where the order matters. The difference here is that it does not.

The window slides. Each trigger’s most recent turn is remembered, anything that happened longer ago than the window is forgotten as time passes, and the trigger fires the moment what is left covers all of them. That means a member going stale does not throw away the others: two things that happened a minute ago still count towards a set that a third completes later.

It fires once per set. After it goes off, every trigger has to have its turn again, or the next turn of any one member would complete the same set over and over.

When it fires, trigger.triggers holds each member’s own payload in the order you configured them, trigger.span is how far apart the oldest and newest actually were, and trigger.within is the window you set. The trigger that completed the set is lifted to the top as well, so trigger.entity_id, trigger.to_state and trigger.event mean what they mean in any other trigger, and a condition asking who set the run going still gets an answer.

1
2
3
4
5
6
7
8
9
10
trigger: spook.all_of
options:
  within: "00:02:00"
  triggers:
    - trigger: state
      entity_id: device_tracker.phone
      to: home
    - trigger: state
      entity_id: binary_sensor.front_door
      to: "on"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
trigger: spook.all_of
options:
  within: "01:00:00"
  triggers:
    - trigger: spook.stale
      target:
        entity_id: sensor.kitchen_temperature
      options:
        for: "00:30:00"
    - trigger: spook.stale
      target:
        entity_id: sensor.hallway_temperature
      options:
        for: "00:30:00"

Once it settles¶

Fires once a trigger has stopped firing for a while, so a burst of them arrives as one.

A motion sensor in a hallway does not report motion, it reports motion twenty times. A power meter crossing a threshold crosses it back and forth for a minute. Acting on the first of those is usually wrong and acting on every one of them is always wrong, and what you wanted was to hear about it once, after it settled.

Written out by hand that takes a helper entity and a second automation to turn it off again, which is the most rebuilt pattern on the forum.

Every firing starts the quiet period over. When it finally runs out, the trigger fires once for the whole burst. It is not Watchdog, which is about something that never happened at all.

Give it more than one trigger and they are waited out together: any of them starts a burst, any of them keeps it going, and the lot arrives as a single report.

When it fires, trigger.count is how many firings were collapsed, trigger.span is how long the burst lasted from its first firing to its last, not counting the quiet after it, and trigger.for is the quiet period you set. The last firing of the burst is lifted to the top, all of it: trigger.entity_id and trigger.to_state mean what they mean in any other trigger, an MQTT trigger’s trigger.payload or a calendar trigger’s trigger.calendar_event are there too, and a condition asking who set the run going still gets an answer. What stays the automation’s own is trigger.id, trigger.platform and the description, and trigger.for is always the quiet period, not the for of a nested state trigger.

1
2
3
4
5
6
7
trigger: spook.debounce
options:
  for: "00:00:30"
  triggers:
    - trigger: state
      entity_id: binary_sensor.hallway_motion
      to: "on"

1
2
3
4
5
6
7
8
trigger: spook.debounce
options:
  for: "00:01:00"
  triggers:
    - trigger: state
      entity_id: binary_sensor.front_door
    - trigger: state
      entity_id: lock.front_door

Triggers in order¶

Fires when several triggers happen one after another, in the order given.

Home Assistant fires on one thing happening. It does not fire on one thing happening after another, which is most of what a house actually does: the door opened and then somebody moved in the hall, the washing machine started and then went quiet, the alarm armed and then a window opened. Written by hand that needs a helper entity per step and an automation to set each one.

Only the step being waited for is listening. So a later step firing before an earlier one is not a match, and neither is the same step firing twice. Two steps is the minimum, because one trigger in order is just a trigger.

Once the last step lands the trigger fires and goes back to waiting for the first, so it works as many times as you like.

When it fires, trigger.steps holds what each step reported, in order, and trigger.duration is how long the whole thing took. The step that completed the sequence is also lifted to the top, so trigger.entity_id, trigger.from_state and trigger.to_state describe the thing that finished it, and spook.triggered_by_user and friends find the person behind it there.

1
2
3
4
5
6
7
8
9
10
trigger: spook.sequence
options:
  timeout: "00:02:00"
  steps:
    - trigger: state
      entity_id: binary_sensor.front_door
      to: "on"
    - trigger: state
      entity_id: binary_sensor.hallway_motion
      to: "on"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
trigger: spook.sequence
options:
  timeout: "00:02:00"
  steps:
    - trigger: state
      entity_id: binary_sensor.front_door
      to: "on"
    - trigger: state
      entity_id: binary_sensor.hallway_motion
      to: "on"
  reset:
    - trigger: state
      entity_id: alarm_control_panel.home
      to: disarmed

While a condition holds¶

Fires when a condition turns true, and keeps firing on an interval for as long as it stays true.

The nagging trigger. The garage is open and you want to hear about it again in ten minutes, and ten minutes after that, until somebody closes it.

Home Assistant can already do this inside a script, with a repeat holding a while and a delay. What that costs is a script run held open for as long as the garage is open: the automation’s mode has to allow for it, a reload ends it, and core stops a loop that has gone round ten thousand times. As a trigger none of that applies, because nothing is being held open between one firing and the next.

It fires the moment the condition arrives, not while it already holds, so loading an automation whose condition happens to be true does not set it off. Counting starts again at one each time the condition comes back.

When it fires, trigger.times is how many times it has fired this spell, starting at one, and trigger.every is the interval. The first firing also carries the state change that made the condition turn, in the same way Condition turned true does, so spook.triggered_by_user finds the person who caused it there. The firings after that carry nobody, because nobody makes a clock come round.

1
2
3
4
5
6
7
8
9
10
11
trigger: spook.while
options:
  every: "00:10:00"
  condition:
    - condition: state
      entity_id: cover.garage
      state: open
      for: "00:10:00"
    - condition: numeric_state
      entity_id: zone.home
      below: 1

Watchdog¶

Fires when something that was expected to happen does not happen in time.

Every trigger Home Assistant has fires because something happened. The interesting failures are the other kind: the back door opened and nobody walked into the hall, the washing machine started and never finished, the nightly backup began and never reported in. Written by hand that is a helper entity, a timer, and two automations to keep them in step.

Arming starts a clock. The expected trigger arriving before it runs out calls the watch off and nothing fires. The clock running out is what fires it.

Arming again while already waiting starts the wait over rather than running a second one, because the wait is measured from the arming and the latest one is the one that counts. The expected trigger arriving while nothing is being waited for does nothing at all.

When it fires, trigger.armed_by is what the arming trigger reported and trigger.within is the wait it was given. Nothing else is carried, and no user: a watchdog fires because nothing happened, at a moment a clock came round, and nobody makes a clock come round. An automation that wants to name the person can read trigger.armed_by.

1
2
3
4
5
6
7
8
9
10
11
trigger: spook.watchdog
options:
  within: "00:02:00"
  arm:
    - trigger: state
      entity_id: binary_sensor.back_door
      to: "on"
  expect:
    - trigger: state
      entity_id: binary_sensor.hallway_motion
      to: "on"

Entity will not settle¶

Fires when an entity changes state more often than it should within a stretch of time.

A sensor that goes on and off and on again, a device that drops off the network and comes back, a binary sensor sitting right on its threshold. Each change on its own looks perfectly fine, and Home Assistant has no way to say “this one has changed five times in five minutes and something is wrong with it”.

Changes of state, not writes. An entity reporting the same value over and over is chatty, not unsettled, so attribute changes do not count. Going to unavailable and back does count, which is the case this exists for. An entity appearing or disappearing does not: that is not it going back and forth.

The window slides, so this is always about the most recent changes rather than a fresh count every five minutes.

It reports once per spell. Once it has said an entity will not settle it stays quiet until that entity does settle, because a storm of alerts about a storm helps nobody. Settling means the last few changes no longer fall inside the window, and the next time it starts up is news again. A change that still leaves the last few inside the window is the same spell carrying on, however long it has been since the one before it.

When it fires, trigger.entity_id names the entity, trigger.from_state and trigger.to_state are the change that tipped it over, and trigger.changes and trigger.within are what was asked for.

1
2
3
4
5
6
trigger: spook.flapping
target:
  entity_id: binary_sensor.back_door
options:
  changes: 5
  within: "00:05:00"

1
2
3
4
5
6
trigger: spook.flapping
target:
  label_id: battery_powered
options:
  changes: 10
  within: "00:15:00"

Condition turned true¶

Fires when a condition goes from false to true.

A condition is true or false, and the moment it turns is worth reacting to. Home Assistant has a trigger for a template turning true and one for a state arriving, but nothing that takes the condition building blocks, so anything more involved than a single state has to be rewritten as a template.

Takes one condition or a list of them, and a list means all of them, the same as anywhere else. Which is also what the visual editor sends, so both shapes have to work.

Only the turn counts. A condition that is already true when the automation loads is not a change, so this does not fire for it, the same as the template trigger. And going back to false is not a turn either.

When it can tell which change turned the condition, trigger.entity_id names that entity and trigger.from_state and trigger.to_state are what it moved between, the same three the template trigger hands over. Which is also what carries the user through: an automation starts a fresh context, so spook.triggered_by_user and friends read the person off trigger.to_state.

It can tell only when every part of the condition announces its own turns, which means state, numeric_state and zone conditions without a for: and without a value_template, plus any and, or or not built out of those. Anything else and all three are empty, because a condition with a part that turns quietly gets discovered by the next unrelated change, and naming that change would be naming the wrong one.

1
2
3
4
5
6
7
8
9
10
11
trigger: spook.condition_met
options:
  condition:
    condition: and
    conditions:
      - condition: state
        entity_id: binary_sensor.back_door
        state: "on"
      - condition: numeric_state
        entity_id: sensor.outside_temperature
        below: 5