# 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](img/AddTimespan.png)

### Example Configuration

```json
{
  "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
```json
{
  "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
```json
{
  "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
```json
{
  "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)
```json
{
  "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)
```json
{
  "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

```jinja2
{% 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

```yaml
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 →](Offset-Calculation)

**Previous**: [Back to Home →](Home)