Offset Calculation

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

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.

{
  "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.

{
  "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.

{
  "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.

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

"off" - Trigger when entity turns OFF

Counts down from when the entity changes to OFF state.

{
  "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.

{
  "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:

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

Automation:

- 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:

{
  "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:

{
  "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:

{
  "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:

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:

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

---

Next: Learn about Datetime Offset →

Previous: Back to Timespan →