Events reference
Home Keeper fires a Home Assistant bus event for every state change: a task is created, edited, completed, deleted, or becomes overdue or due soon. It also fires on spare-part stock changes (low stock, out of stock, restocked) and appliance changes (added, changed, removed). Automations and other integrations use these events.
You can react to the events in 3 ways:
- Home Keeper triggers (visual automation editor). Add trigger lists 1 Home Keeper trigger for each event, such as "Task became overdue" or "Spare part out of stock", by target, by type and in its search. A task, part or appliance trigger takes a target: an entity, device, area, floor or label. It works on every kind of device, also on a device that another integration owns. See the guide.
- Event trigger (any automation). For global automations ("any part low → add to
1 shopping list"), use a
platform: eventtrigger on the event name. - Events entity. The Home Keeper Events entity gets every event with a payload. Use it with the Event received trigger, or read its history.
The device triggers (platform: device) on Home Keeper's own devices are the older
path. Automations that use them keep working.
The API reference lists each event with its payload and triggers. Home Keeper generates that page from the integration. This page tells what each event means and what a restart does.
Integrators that push tasks into Home Keeper must also read INTEGRATING.md.
What the events mean
All event names use the pattern home_keeper_<noun>_<verb>. Task events share a common
spine. Stock events share 1 shape, and asset events share another.
Task lifecycle
A snooze moves only next_due. The recurrence does not change. "Due today" is the
opposite: next_due moves to now, and the recurrence does not change.
A skip starts a new interval from now on a floating task, and moves a fixed task to its next scheduled occurrence. After a skip, a one-off, triggered or sensor task goes dormant.
A snooze, a due-today, and a skip all re-arm the overdue and due-soon events for the new date.
move_occurrence moves 1 date of a fixed task and fires home_keeper_task_occurrence_moved
with occurrence (the rule date), to and previous_to. An undo sets to to occurrence.
Home Keeper records a skip in a skips list, next to the completions list. A skip
never sets last_completed, and nothing that uses the completion log counts it.
home_keeper_task_skipped includes the ts of the new entry. update_skip,
move_skip, and delete_skip use ts to find the entry, and the _skip_updated and
_skip_removed events include it.
A skip on a usage task resets its meter, as a completion does. The next interval
starts from the reading at the skip. The time backstop, also_every, starts from the
same point. The default combinator is "any", so the meter or the backstop can re-arm
the task. If the backstop stays at its old point, it can re-arm the task soon after a
skip. When a user edits the reading on the completion or skip that anchors the meter,
Home Keeper re-anchors the meter, and the _completion_updated and _skip_updated
events can add a meter_baseline.
Completion origins
Many paths complete a task through the ordinary home_keeper_task_completed event. The
origin tells you which path. No path adds a new event type.
origin | Path |
|---|---|
home_keeper_tag_scan | A scan of the NFC/RFID tag linked to the task. |
home_keeper_sensor_recover | A threshold or state binding with clear_on_recover sees its condition go away. |
home_keeper_shopping_list | A user ticks off a "Buy {part}" line on the synced shopping list. |
home_keeper_todo_sync | A user ticks off an item on a to-do list that a Profile syncs to. |
home_keeper_problem_sensor_sync | A synced device_class: problem sensor clears. |
To complete a task whose Require tag scan toggle blocks every UI surface, an
automation can pass origin: home_keeper_tag_scan to complete_task.
Sensor tasks use the triggered lifecycle. The watcher fires home_keeper_task_triggered
when a bound entity meets the condition of the task. A usage meter that passes its target
is one case. A state entity that enters its state is another. The task then becomes
home_keeper_task_overdue as any due task does. A user completion clears it and resets
the baseline of a usage meter. A usage meter with a time backstop (also_every in its
sensor block) arms on the first half that is due, also while the entity is unavailable.
With clear_on_recover, the task completes itself. A task that a declarative companion with
clear_on_recover made cannot be completed by hand: home_keeper.complete_task refuses it,
and its device page has no Mark done button. If the task is linked to a consumable, the
auto-completion uses 1 spare. It can then fire home_keeper_part_low_stock or
home_keeper_part_out_of_stock. An unavailable or unknown entity is not a recovery. It
counts as no reading and fires no event. A device that goes off the network never completes
a task.
The baseline bookkeeping of the watcher (a new meter anchor, a re-anchor after a meter
reset) fires no event, because it is internal state. A baseline that a user moves
with the set_task_meter service fires home_keeper_task_updated with
changed_fields: ["sensor"].
Task photos. A photo change is a task change. When a user adds a photo, removes a
photo or makes a photo the cover, Home Keeper fires home_keeper_task_updated with
changed_fields: ["photos"]. There is no separate photo event.
New appliance device. If an appliance gets a new device, each moved task and appliance fires
an _updated event with device_id, source or related_device_ids in changed_fields.
Shopping list. When Settings → Shopping list names a to-do list, each automatic
"Buy {part}" reminder goes on it. The completion has
source: {"buy": {"asset_id": …, "part_id": …}}. It restocks the part by its restock
quantity, which usually fires home_keeper_part_restocked. Home Keeper then deletes the
reminder with home_keeper_task_deleted.
To-do sync. When a Profile in Settings → Profiles names an external to-do list, its tasks go on that list while they qualify. An item that disappears from a list whose provider removes completed items also completes the task, while the treat removed items as completed toggle is on. A completion in Home Keeper ticks off the synced item and keeps it as the record. When a recurring task is due again, a new item goes next to it.
Problem sensors. When Sync problem sensors is on, Home Keeper creates a task for
each device_class: problem sensor. The task is triggered when the sensor reports a
problem and completed when it clears. The completion has
source: {"problem_sensor": {"entity_id": …}}. A user cannot complete these tasks by
hand.
The bookkeeping of each sync (which list item stands for which task) fires no event.
Time-based transitions (edge-triggered)
home_keeper_task_overdue fires when a task first passes its due date (now ≥ next_due).
home_keeper_task_due_soon fires when it enters the 3-day window before that date. The
coordinator finds these on its refresh (every 5 minutes). Each fires at most once per
next_due value. A completion or a new date re-arms the next event.
home_keeper_task_overdue_resolved fires once when a task that fired overdue stops being
overdue: its new date is in the future, or it is dormant or disabled. A deleted task fires
only home_keeper_task_deleted. The context is that of the change that ended the period.
Restart. At startup Home Keeper records the current state with no events, so a restart
never replays "overdue". The per-task overdue binary_sensor always shows the current state.
Stock transitions (edge-triggered)
When spare stock falls to ≤ reorder_at, home_keeper_part_low_stock fires. At
0, home_keeper_part_out_of_stock fires instead. When stock goes back above the
threshold, home_keeper_part_restocked fires.
Each crossing fires 1 event, not 1 event for each step while the part is low. A part must
track both stock and reorder_at to fire anything. If 1 change takes a low part to
0, only out_of_stock fires. Each part of a task that takes several parts fires its own.
Stock goes down, and these events fire, when a user completes a task linked to that
part. This includes an automatic wear-part replacement task and a task linked by hand
with home_keeper.set_task_consumable. Each completion removes the Used per
completion amount of the part (1 spare if unset). With 0.33, a bottle lasts 3 refills.
A deleted completion gives the stock back. The completion records the amount that it
really took: if it found 1 of the 2 spares it needed, it gives back 1. The return fires
home_keeper_part_restocked when it lifts the part above its reorder point.
With Auto-create buy task on, a part that crosses the reorder threshold gets a
one-off "Buy {part}" task (home_keeper_task_created). A restock removes the task
(home_keeper_task_deleted). A completion of the buy task restocks the part by its
restock_quantity and fires home_keeper_part_restocked. A deleted completion takes the
restock back and fires home_keeper_part_low_stock or home_keeper_part_out_of_stock
if the count crosses the threshold again.
Asset (appliance) lifecycle
A change to an appliance document (a manual, warranty, or receipt link, or an
uploaded file) fires home_keeper_asset_updated with changed_fields: ["documents"].
There is no separate document event. A change to the file of a part fires the same
event with changed_fields: ["parts"].
A deleted entry in the archived task history of an appliance
(home_keeper.delete_archived_completion) fires home_keeper_asset_updated with
changed_fields: ["archived_history"].
Archive (home_keeper.archive_asset) and restore (home_keeper.restore_asset) fire
their own events, not home_keeper_asset_updated. An archive only hides the appliance
from the default list in the panel. Its device, entities, and tasks continue to operate,
and home_keeper_asset_deleted does not fire.
Companion discovery (edge-triggered)
Home Keeper shows integrations that work with it in Settings → Companions (see
INTEGRATING.md §9).
As with time-based transitions, Home Keeper records the state at startup with no events.
An event fires only when a companion changes state at run time, as when it registers
itself or when a user installs a glue. Home Keeper checks the state on each coordinator
refresh (about 5 minutes). A read (the panel, or list_companions) fires nothing.
A suggestion names the glue in domain and the upstream that Home Keeper found in
upstream_domain.
At setup and on reload, Home Keeper fires home_keeper_register_companions with empty
data. It asks companions to announce themselves again. A companion answers with a call
to home_keeper.register_companion.
Declarative companion CRUD
A declarative companion is a spec that Home Keeper owns. It names a target integration
and entity filters, with a Jinja template for the task name and notes (see
INTEGRATING.md §9). It makes 1 managed
sensor task for each matching entity. Changes to a spec fire their own events. The
sensor tasks fire the ordinary task events, so an automation on
home_keeper_task_completed works with no change. To filter to declarative tasks, read
managed_by.integration == "home_keeper" and source.declarative_companion.spec_id.
| Event | Fires when |
|---|---|
home_keeper_declarative_companion_added | a spec was created (via the panel, home_keeper.add_declarative_companion, or the matching WS command); payload adds spec_id, name, enabled, preset_id |
home_keeper_declarative_companion_updated | any field of a stored spec was changed; same payload |
home_keeper_declarative_companion_removed | a spec was deleted (also fires home_keeper_task_deleted once per materialized task the spec had); same payload |
Payloads
The API reference lists every field of every payload. Home Keeper generates it from the builders that make the payloads.
stock and reorder_at can be fractional: a bottle topped up a third at a time reports
0.67. unit is the unit of the part ("ml", "bottles"), or "" for whole spares.
A notification can use {{ trigger.event.data.stock }} {{ trigger.event.data.unit }}
for both. Like the asset events, a stock event holds the source and managed_by of the
appliance. An integration that manages an appliance uses them to find its stock events.
Example automations
Notify when anything becomes overdue (event trigger)
automation:
- alias: "Maintenance overdue → notify"
trigger:
- platform: event
event_type: home_keeper_task_overdue
action:
- service: notify.mobile_app_phone
data:
message: >-
{{ trigger.event.data.name }} is overdue
({{ trigger.event.data.days_overdue }} day(s)).
Add a spare to the shopping list when it runs out (event trigger)
automation:
- alias: "Spare out of stock → shopping list"
trigger:
- platform: event
event_type: home_keeper_part_out_of_stock
action:
- service: todo.add_item
target:
entity_id: todo.shopping_list
data:
item: >-
{{ trigger.event.data.part_name }}
{{ trigger.event.data.part_number }} ({{ trigger.event.data.vendor }})
React only to a specific appliance
In the automation editor, select Add trigger, then the device of the appliance under By target, then the "Spare part low on stock" trigger. The same automation in YAML:
automation:
- alias: "Furnace filter low"
triggers:
- trigger: home_keeper.part_low_stock
target:
device_id: <furnace device id>
actions: ...
Home Keeper reads the target when the event fires. A device target matches the
device_id of the event, and each Home Keeper entity on the device adds its task,
part or appliance. A self-owned task device matches through its entities. The event
trigger variable holds the bus event, the same as for a platform: event trigger.
Notes for integrators
- The
home_keeper_task_completedpayload has the full task spine and thecompleted_atandoriginfields. - Home Keeper never reads
source. Use it, and theoriginon completions, to find your own tasks and remove duplicates. See INTEGRATING.md. - An import fires 1 event per record, not 1 per completion. A document that
home_keeper.import_datareads holds old history, from before the import. A backfilled completion fires nohome_keeper_task_completed. The record arrives as 1home_keeper_task_createdorhome_keeper_task_updated. An update that only adds history still fires, withcompletionsin itschanged_fields. To mirror completions, read the task history on that event. Do not count completion events. - Context.
context.user_idis the user who caused the event. The clock has no user.