# Offset Calculation

Offset calculations add a time delay to entity state changes, creating binary sensors that trigger after a specified duration.

## Overview

An offset sensor becomes ON when an entity reaches a specified state and a certain amount of time has passed. The behavior after that depends on the mode you choose.

## Configuration

### Basic Setup

1. Go to Clockwork configuration
2. Select "Add Calculation"
3. Choose "Offset Calculation"
4. Fill in the following:
   - **Calculation Name**: A friendly name (e.g., "Door Open Alarm")
   - **Entity to Monitor**: The entity to watch
   - **Time Offset**: How long to wait before triggering (e.g., "1 hour", "30 minutes")
   - **Behavior Mode**: How the sensor behaves after offset is reached
   - **Trigger Event**: Which state change triggers the offset
   - **Pulse Duration** (pulse mode only): How long the pulse stays ON
   - **Icon**: Optional custom icon

![Add Offset](img/AddOffset.png)

## Behavior Modes

Offset calculations support three different behavior modes:

### Mode: "latch"
The sensor turns ON when the offset time is reached and **stays ON indefinitely**.

**Use case**: Alarm triggers 2 hours after door opens and stays on until manually acknowledged.

```json
{
  "type": "offset",
  "name": "Long Door Open Alert",
  "entity_id": "binary_sensor.front_door",
  "offset": "2 hours",
  "offset_mode": "latch",
  "trigger_on": "on"
}
```

### Mode: "pulse"
The sensor turns ON when the offset is reached and stays ON for a specified duration, then automatically turns OFF.

**Use case**: Warning light blinks for 10 seconds after motion detected.

```json
{
  "type": "offset",
  "name": "Motion Alert Pulse",
  "entity_id": "binary_sensor.motion_sensor",
  "offset": "5 seconds",
  "offset_mode": "pulse",
  "pulse_duration": "10 seconds",
  "trigger_on": "on"
}
```

### Mode: "duration"
The sensor turns ON when the offset is reached and **stays ON while the trigger condition is met**, then turns OFF when the condition changes.

**Use case**: Warning light stays on for as long as the door has been open AND 30 minutes have passed.

```json
{
  "type": "offset",
  "name": "Prolonged Door Open",
  "entity_id": "binary_sensor.front_door",
  "offset": "30 minutes",
  "offset_mode": "duration",
  "trigger_on": "on"
}
```

## Trigger Event Options

The **Trigger Event** controls which state change initiates the offset countdown:

### "on" - Trigger when entity turns ON
Counts down from when the entity changes to ON state.

```json
{
  "name": "Light Off Warning",
  "trigger_on": "on"
}
```

### "off" - Trigger when entity turns OFF  
Counts down from when the entity changes to OFF state.

```json
{
  "name": "Device Offline Alert",
  "entity_id": "binary_sensor.device_online",
  "trigger_on": "off"
}
```

### "both" - Trigger on ANY state change
Counts down from whichever direction the state changed.

```json
{
  "name": "State Change Alert",
  "trigger_on": "both"
}
```

## Real-World Examples

### Example 1: Garage Door Left Open
Trigger an alert if the garage door stays open for more than 30 minutes:

```json
{
  "type": "offset",
  "name": "Garage Left Open Alert",
  "entity_id": "cover.garage_door",
  "offset": "30 minutes",
  "offset_mode": "duration",
  "trigger_on": "on"
}
```

![Add Offset Garage Door Left Open Example](img/AddOffsetGarageDoorLeftOpenExample.png)

**Automation**:
```yaml
- trigger:
    platform: state
    entity_id: binary_sensor.garage_left_open_alert
    to: "on"
  action:
    service: notify.mobile_app
    data:
      message: "Garage door has been open for 30+ minutes!"
```

### Example 2: Device Offline Notification
Alert after a device has been offline for 1 hour:

```json
{
  "type": "offset",
  "name": "Device Long Offline",
  "entity_id": "binary_sensor.device_online",
  "offset": "1 hour",
  "offset_mode": "latch",
  "trigger_on": "off"
}
```

### Example 3: Motion-Triggered Alert
Trigger a brief alert (5 seconds) after motion is detected:

```json
{
  "type": "offset",
  "name": "Motion Detected Chime",
  "entity_id": "binary_sensor.entryway_motion",
  "offset": "2 seconds",
  "offset_mode": "pulse",
  "pulse_duration": "5 seconds",
  "trigger_on": "on"
}
```

### Example 4: Bathroom Fan Auto-Off
Turn off the bathroom fan 30 minutes after no motion is detected:

```json
{
  "type": "offset",
  "name": "Bathroom Fan Off Trigger",
  "entity_id": "binary_sensor.bathroom_motion",
  "offset": "30 minutes",
  "offset_mode": "pulse",
  "pulse_duration": "1 second",
  "trigger_on": "off"
}
```

## Offset Format

Offset values use a friendly format. Supported units:
- **second(s)** - `"5 seconds"`, `"1 second"`
- **minute(s)** - `"30 minutes"`, `"1 minute"`
- **hour(s)** - `"2 hours"`, `"1 hour"`
- **day(s)** - `"7 days"`, `"1 day"`
- **week(s)** - `"2 weeks"`, `"1 week"`

Examples:
- `"5 minutes"` - 5 minutes
- `"2 hours"` - 2 hours
- `"1 day"` - 24 hours
- `"1 week"` - 7 days

## Mode Comparison Table

| Aspect | Latch | Pulse | Duration |
|--------|-------|-------|----------|
| Turns ON | After offset time | After offset time | After offset time |
| Stays ON | Forever | For pulse_duration | While condition met |
| Resets | Manual/restart | Automatic | Automatic |
| Best for | Persistent alarms | Notifications | Conditional logic |

## Tips & Tricks

### Combining with Automations

Create complex logic by combining multiple offset sensors:

```yaml
automation:
  - alias: "Complex door logic"
    trigger:
      platform: state
      entity_id:
        - binary_sensor.door_open_30min
        - binary_sensor.door_open_1hour
      to: "on"
    action:
      - service: notify.all
        data:
          message: "Door has been open too long!"
```

### Time-Based Conditions

Use offset sensors in automation conditions:

```yaml
- condition: state
  entity_id: binary_sensor.door_open_alarm
  state: "on"
```

---

**Next**: [Learn about Datetime Offset →](Datetime-Offset)

**Previous**: [Back to Timespan →](Timespan-Calculation)