re-uploading work

2026-02-04 17:46:30 -06:00
commit 3b14c65998
1388 changed files with 381262 additions and 0 deletions
--- a/docs/QUICKREF-timer-types.md
+++ b/docs/QUICKREF-timer-types.md
@@ -0,0 +1,119 @@
+# Quick Reference: Timer Types
+
+## Overview
+The Attune timer sensor supports three timer types for flexible scheduling.
+
+## Interval Timers (core.intervaltimer)
+**Purpose**: Fire at regular intervals
+
+```yaml
+# Every 30 seconds
+trigger_ref: core.intervaltimer
+parameters:
+  unit: seconds
+  interval: 30
+
+# Every 5 minutes
+trigger_ref: core.intervaltimer
+parameters:
+  unit: minutes
+  interval: 5
+
+# Every 2 hours
+trigger_ref: core.intervaltimer
+parameters:
+  unit: hours
+  interval: 2
+
+# Daily
+trigger_ref: core.intervaltimer
+parameters:
+  unit: days
+  interval: 1
+```
+
+## Cron Timers (core.crontimer)
+**Purpose**: Fire based on cron expressions
+
+```yaml
+# Every hour at :00
+trigger_ref: core.crontimer
+parameters:
+  expression: "0 0 * * * *"
+
+# Every 15 minutes
+trigger_ref: core.crontimer
+parameters:
+  expression: "0 */15 * * * *"
+
+# Daily at midnight
+trigger_ref: core.crontimer
+parameters:
+  expression: "0 0 0 * * *"
+
+# Weekdays at 9 AM
+trigger_ref: core.crontimer
+parameters:
+  expression: "0 0 9 * * 1-5"
+
+# Every Monday at 8:30 AM
+trigger_ref: core.crontimer
+parameters:
+  expression: "0 30 8 * * 1"
+```
+
+### Cron Format
+```
+second minute hour day_of_month month day_of_week
+  |      |     |        |         |        |
+  0-59  0-59  0-23    1-31      1-12    0-6 (0=Sunday)
+```
+
+## DateTime Timers (core.datetimetimer)
+**Purpose**: Fire once at a specific time (one-shot)
+
+```yaml
+# New Year's Eve countdown
+trigger_ref: core.datetimetimer
+parameters:
+  fire_at: "2024-12-31T23:59:59Z"
+  timezone: "UTC"
+
+# Specific deployment time
+trigger_ref: core.datetimetimer
+parameters:
+  fire_at: "2024-06-15T14:00:00-05:00"
+  timezone: "America/New_York"
+  description: "Production deployment"
+```
+
+**Note**: DateTime timers automatically remove themselves after firing.
+
+## Choosing a Timer Type
+
+| Use Case | Recommended Type |
+|----------|------------------|
+| Regular health checks | Interval |
+| Periodic sync/backup | Interval |
+| Business hours only | Cron |
+| Complex schedules | Cron |
+| One-time events | DateTime |
+| Reminders/deadlines | DateTime |
+
+## Implementation Details
+
+- All timers managed by `tokio-cron-scheduler`
+- Efficient async scheduling
+- Low memory overhead
+- Automatic cleanup on rule deletion
+- Support for concurrent timers
+
+## Event Payloads
+
+Each timer type creates events with specific metadata:
+
+**Interval**: Includes `interval_seconds`, `execution_count`
+**Cron**: Includes `expression`, `next_fire_at`, `execution_count`
+**DateTime**: Includes `fire_at`, `fired_at`, `delay_ms`
+
+All events include `sensor_ref: "core.interval_timer_sensor"`