Skip to content

Custom Automation Conditions

Jump to bottom
Scott Gusler edited this page Feb 16, 2026 · 2 revisions

Custom Automation Conditions

Clockwork provides custom automation conditions that allow you to use time-based logic directly in your Home Assistant automations without creating intermediate sensors.

Timespan Condition: clockwork.timespan

Compare how long it's been since an entity last changed state.

Configuration

Using the Visual Editor

  1. Open Settings > Automations & Scenes > Create Automation
  2. Click Create new automation
  3. Add a Trigger (e.g., Time pattern, State change)
  4. Click Add condition
  5. Search for and select "Clockwork Last Changed"
  6. Select the entity to monitor in the Entity ID field
  7. Configure one of the comparison operators:
    • Above (seconds): Returns True if time since last change is greater than this value
    • Below (seconds): Returns True if time since last change is less than this value
    • Equal to (seconds): Returns True if time since last change equals this value
  8. Save the automation

The visual editor generates YAML with an options section. This is the correct format and will look like:

condition: clockwork.timespan
options:
  entity_id: binary_sensor.driveway_motion
  above: 300

Parameters

Condition Parameters:

  • entity_id (required): The entity to monitor
  • above: Return True if seconds since last change is greater than this value
  • below: Return True if seconds since last change is less than this value
  • equal_to: Return True if seconds since last change equals this value

At least one comparison operator (above, below, or equal_to) must be specified.

Standard Automation Fields:

  • alias (optional): A friendly name for this condition (useful for organizing complex automations)
  • enabled (optional): Whether this condition is enabled (true or false)

Example with Alias

condition: clockwork.timespan
options:
  entity_id: binary_sensor.driveway_motion
  below: 120
alias: Mailbox checked in last 2 minutes

Troubleshooting

Condition Not Working in Automation

If the condition appears but isn't evaluating correctly:

1. Verify Entity ID

  • The entity must exist and have a valid last_changed timestamp
  • Check that the entity ID is correct (use the dropdown in the UI)
  • Binary sensors usually work best: binary_sensor.xxx

2. Check Entity State History

  • Go to the entity's page
  • Verify it shows "Last changed" with a recent timestamp
  • If "Last changed" is missing, the condition won't work

3. Test with Simple Threshold

condition: clockwork.timespan
options:
  entity_id: binary_sensor.driveway_motion
  above: 0  # Should always be True if entity has ever changed

4. Review Logs During Automation Execution

  • Enable debug logging for Clockwork
  • Check Settings > System > Logs while running the automation
  • Look for Clockwork timespan condition: debug messages
  • This shows the calculated seconds and comparison result

Enable Debug Logging

Add to your configuration.yaml to see detailed debugging:

logger:
  logs:
    custom_components.clockwork: debug
    custom_components.clockwork.conditions: debug

Then restart Home Assistant and check Settings > System > Logs for detailed output.

Last Triggered Condition: clockwork.last_triggered

Compare how long it's been since an automation was last triggered.

Configuration

Using the Visual Editor

  1. Open Settings > Automations & Scenes > Create Automation
  2. Click Create new automation
  3. Add a Trigger (e.g., Time pattern, State change)
  4. Click Add condition
  5. Search for and select "Clockwork Last Triggered"
  6. Select the automation entity to monitor in the Automation Entity field (only automation.* entities are shown)
  7. Configure one of the comparison operators:
    • Above (seconds): Returns True if time since last trigger is greater than this value
    • Below (seconds): Returns True if time since last trigger is less than this value
    • Equal to (seconds): Returns True if time since last trigger equals this value
  8. Save the automation

The visual editor generates YAML with an options section. This is the correct format and will look like:

condition: clockwork.last_triggered
options:
  entity_id: automation.lights_evening
  above: 3600

Parameters

Condition Parameters:

  • entity_id (required): The automation entity to monitor (must be automation.*)
  • above: Return True if seconds since last trigger is greater than this value
  • below: Return True if seconds since last trigger is less than this value
  • equal_to: Return True if seconds since last trigger equals this value

At least one comparison operator (above, below, or equal_to) must be specified.

Standard Automation Fields:

  • alias (optional): A friendly name for this condition (useful for organizing complex automations)
  • enabled (optional): Whether this condition is enabled (true or false)

Example with Alias

condition: clockwork.last_triggered
options:
  entity_id: automation.security_system
  below: 300
alias: Security system triggered in last 5 minutes

Examples

Example 1: Trigger if motion hasn't been detected for 5 minutes

- alias: "Long idle timeout"
  trigger:
    platform: time_pattern
    minutes: "/1"  # Check every minute
  condition:
    - condition: clockwork.timespan
      options:
        entity_id: binary_sensor.driveway_motion
        above: 300  # 5 minutes = 300 seconds
  action:
    - service: light.turn_off
      entity_id: light.driveway

Example 2: Conditional action if motion detected recently

- alias: "Send notification if motion detected recently"
  trigger:
    platform: time
    at: "08:00:00"
  condition:
    - condition: clockwork.timespan
      options:
        entity_id: binary_sensor.driveway_motion
        below: 600  # Motion detected in the last 10 minutes
  action:
    - service: notify.mobile_app
      data:
        message: "Motion was detected near the driveway recently"

Example 3: Check exact duration

- alias: "Specific duration check"
  trigger:
    platform: state
    entity_id: sensor.event
  condition:
    - condition: clockwork.timespan
      options:
        entity_id: sensor.event
        equal_to: 120  # Exactly 2 minutes
  action:
    - service: script.my_action

Example 4: Automation hasn't run recently

- alias: "Re-run automation if it hasn't triggered recently"
  trigger:
    platform: time_pattern
    hours: "/1"  # Check every hour
  condition:
    - condition: clockwork.last_triggered
      options:
        entity_id: automation.daily_backup
        above: 86400  # 24 hours = 86400 seconds
  action:
    - service: automation.trigger
      entity_id: automation.daily_backup

Example 5: Conditional action if automation triggered recently

- alias: "Send notification if security system triggered recently"
  trigger:
    platform: time
    at: "08:00:00"
  condition:
    - condition: clockwork.last_triggered
      options:
        entity_id: automation.security_alert
        below: 3600  # Triggered in the last hour
  action:
    - service: notify.mobile_app
      data:
        message: "Security system was triggered recently"

Example 6: Check exact trigger timing

- alias: "Specific trigger timing check"
  trigger:
    platform: state
    entity_id: sensor.system_status
  condition:
    - condition: clockwork.last_triggered
      options:
        entity_id: automation.system_monitor
        equal_to: 300  # Exactly 5 minutes ago
  action:
    - service: script.precise_timing_action

Comparison with Alternative Approaches

Before (Template Condition)

condition: template
value_template: "{{ (now() - states.binary_sensor.driveway_motion.last_changed).total_seconds() > 300 }}"

After (Clockwork Condition)

condition: clockwork.timespan
options:
  entity_id: binary_sensor.driveway_motion
  above: 300

Benefits:

  • ✅ Cleaner, more readable YAML
  • ✅ No template syntax needed
  • ✅ Easier to maintain and modify
  • ✅ Better error handling and logging
  • ✅ Calculates on-the-fly, no continuous sensor updates needed

Use Cases

  1. Long Idle Detection: Trigger actions when devices haven't changed state for extended periods
  2. Recent Activity Detection: Check if something happened recently without needing a separate sensor
  3. Time-based Cleanup: Turn off devices if no activity detected for X seconds
  4. Event Debouncing: Skip actions if an event happened too recently
  5. Automation Optimization: Reduce the number of sensors needed for time-based logic

Performance Considerations

Unlike timespan sensors which update continuously, this automation condition:

  • Calculates the timespan only when the automation is evaluated
  • Doesn't require persistent updating in the background
  • Has minimal performance impact
  • Perfect for low-frequency automation checks

Choose this condition when you don't need continuous monitoring of timespan values. Choose timespan sensors when you want to display or track the value continuously in the UI.

Related Features

Comparison with Alternative Approaches

Before (Template Condition)

condition: template
value_template: "{{ (now() - states.binary_sensor.driveway_motion.last_changed).total_seconds() > 300 }}"

After (Clockwork Condition)

condition: clockwork.timespan
options:
  entity_id: binary_sensor.driveway_motion
  above: 300

Benefits:

  • ✅ Cleaner, more readable YAML
  • ✅ No template syntax needed
  • ✅ Easier to maintain and modify
  • ✅ Better error handling and logging
  • ✅ Calculates on-the-fly, no continuous sensor updates needed

Use Cases

  1. Long Idle Detection: Trigger actions when devices haven't changed state for extended periods
  2. Recent Activity Detection: Check if something happened recently without needing a separate sensor
  3. Time-based Cleanup: Turn off devices if no activity detected for X seconds
  4. Event Debouncing: Skip actions if an event happened too recently
  5. Automation Optimization: Reduce the number of sensors needed for time-based logic

Error Handling

  • If the entity doesn't exist, the condition returns False and logs a warning
  • If the entity has no last_changed time, the condition returns False
  • If no comparison operator is specified (above, below, equal_to), the condition returns True if the entity exists

Performance Considerations

Unlike timespan sensors which update continuously, this automation condition:

  • Calculates the timespan only when the automation is evaluated
  • Doesn't require persistent updating in the background
  • Has minimal performance impact
  • Perfect for low-frequency automation checks

Choose this condition when you don't need continuous monitoring of timespan values. Choose timespan sensors when you want to display or track the value continuously in the UI.

Related Features

Clone this wiki locally