Skip to content

Timespan Calculation

Jump to bottom
Scott Gusler edited this page Feb 13, 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
      • on: Track time since entity turned ON
      • off: Track time since entity turned OFF
      • both: Track time for any state change
    • 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"

Measures duration since the entity turned ON.

Example: If a door sensor is currently open, the timespan shows how long the door has been open.

Track State: "off"

Measures duration since the entity turned OFF.

Example: If a door sensor is currently closed, the timespan shows how long the door has been closed.

Track State: "both"

Measures duration since the last state change (whether to ON or OFF).

Example: Shows time elapsed since the door's state last changed, regardless of direction.

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.

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 (on/off/both)
  • Restart Home Assistant if values seem stuck

Next: Learn about Offset Calculation →

Previous: Back to Home →

Clone this wiki locally