Skip to content

Timespan Calculation

Jump to bottom
Scott Gusler edited this page Feb 26, 2026 · 3 revisions

Timespan Calculation

The timespan calculation measures how long an entity has been in a specific state.

Overview

A timespan sensor tracks the duration since an entity changed to a particular state. It continuously updates, showing how many seconds, minutes, or hours have elapsed.

Configuration

Basic Setup

  1. Go to Clockwork configuration
  2. Select "Add Calculation"
  3. Choose "Timespan Calculation"
  4. Fill in the following:
    • Calculation Name: A friendly name for your sensor (e.g., "Door Open Duration")
    • Entity to Monitor: The entity to watch for state changes
    • Track State: Which state change to track
      • any: Track time for any state change (regardless of specific state)
      • on or off: Track time since entity turned ON or OFF
      • Common states: cooling, heating, idle, active, armed, disarmed, unavailable
      • Custom value: Enter any other state value (e.g., standby, charging)
    • Update Interval: How often to update the value (in seconds, minimum 1, default 60)
    • Icon: Optional custom icon

Add Timespan

Example Configuration

{
  "type": "timespan",
  "name": "Front Door Open Duration",
  "entity_id": "binary_sensor.front_door",
  "track_state": "on",
  "update_interval": 30,
  "icon": "mdi:door-open"
}

Understanding Track State

Track State: "on" / "off"

Measures duration since the entity changed to a specific state.

  • "on": Shows how long the entity has been in the ON state
  • "off": Shows how long the entity has been in the OFF state

Example: If a door sensor is currently open, using track_state: "on" shows how long the door has been open.

Track State: "any"

Measures duration since the last state change (regardless of which state it changed to).

Example: Shows time elapsed since the door's state last changed, whether it went from open to closed or vice versa.

Track State: Custom States

For devices with specialized states, enter the exact state value you want to track.

Common states:

  • cooling - HVAC in cooling mode
  • heating - HVAC in heating mode
  • idle - Device in idle mode
  • active - Device actively running
  • armed - Security system armed
  • disarmed - Security system disarmed
  • unavailable - Entity unavailable
  • <custom> - Any other state value your entity has

Example: For a thermostat, use track_state: "cooling" to measure how long the AC has been running.

Use Cases

1. Garage Door Automation

{
  "name": "Garage Door Open Timer",
  "entity_id": "cover.garage_door",
  "track_state": "on",
  "update_interval": 10
}

Create an automation that closes the garage if it stays open longer than 30 minutes.

2. Motion-Based Lighting

{
  "name": "No Motion Duration",
  "entity_id": "binary_sensor.living_room_motion",
  "track_state": "off",
  "update_interval": 15
}

Turn lights off if there's been no motion for more than 5 minutes.

3. Device Availability Tracking

{
  "name": "Device Offline Time",
  "entity_id": "binary_sensor.device_available",
  "track_state": "off",
  "update_interval": 60
}

Alert if a device has been offline for more than 1 hour.

4. HVAC Cooling Duration (Custom State)

{
  "name": "AC Running Time",
  "entity_id": "climate.home_thermostat",
  "track_state": "cooling",
  "update_interval": 30
}

Track how long the AC has been running. Create automations to alert on excessive cooling duration or optimize HVAC cycles.

5. Thermostat State Changes (Any State)

{
  "name": "Last Thermostat Change",
  "entity_id": "climate.living_room",
  "track_state": "any",
  "update_interval": 60
}

Measure time since the thermostat's state was last changed, useful for debugging or monitoring system activity.

State Format

The sensor's state is represented as a number of seconds. You can display it in different formats:

In Templates

{% set seconds = states('sensor.front_door_open_duration') | int(0) %}
{% set minutes = (seconds / 60) | int %}
{% set hours = (seconds / 3600) | int %}

Door has been open for:
- {{ seconds }} seconds
- {{ minutes }} minutes  
- {{ hours }} hours

In Automations

condition:
  - condition: numeric_state
    entity_id: sensor.door_open_duration
    above: 1800  # 30 minutes

Advanced: Update Interval Considerations

The Update Interval determines how frequently the state is recalculated:

  • Fast Updates (1-10 seconds): More responsive but uses more resources
  • Standard (30-60 seconds): Good balance for most use cases
  • Slow (120+ seconds): Battery-friendly for less critical timers

Troubleshooting

Sensor not updating

  • Check that the entity ID is correct
  • Verify the entity is changing states
  • Review Home Assistant logs for errors

Values seem wrong

  • Ensure the Update Interval is set appropriately
  • Check that you're tracking the correct state (any, on, off, or a custom state value)
  • Restart Home Assistant if values seem stuck

Next: Learn about Offset Calculation →

Previous: Back to Home →

Clone this wiki locally