Home Information - Your home, your data, organized.
Event Alert Systems
Event System Overview
SensorResponses can create events for a user-defined set of rules. EventDefinitions define rules and get triggered off changes in one or more EntityStates. Events may result in zero or more Alarms (can also trigger control actions).
- EventDefinition: Multi-clause triggers with time windows
- EventClause: Individual conditions for event triggering
- EventAction: Automated responses when events fire
Alert Management System
An Alarm defines which SecurityLevel it is applicable to and the importance via the AlarmLevel. If the Alarm matches the current system security level, it becomes an Alert with the defined AlarmLevel and unique Alarm signature.
Alerts are those Alarms that we want to get the user's attention for. An Alert may contain one or more Alarm instances since there is only ever one Alert active for a given alarm signature. A WeatherAlert can also create an alarm and system alert.
Alarm Signature System
Each alarm has a unique signature format: {alarm_source}.{alarm_type}.{alarm_level}
alarm_source: The source of the alarm (e.g., EVENT, WEATHER)alarm_type: The specific type of alarm within that sourcealarm_level: The severity level (INFO, WARNING, CRITICAL)
Multiple alarms with the same signature are grouped into a single Alert, preventing duplicate notifications for the same condition.
Alert Lifecycle Management
Creation
- Alarms are added to the system and become Alerts if they match the current SecurityLevel
- Each Alert starts with a
start_datetimeand calculates anend_datetimebased onalarm_lifetime_secs
Grouping
- When a new alarm arrives with the same signature as an existing Alert, it gets added to that Alert
- The Alert's
end_datetimeis extended based on the new alarm's lifetime - Alert titles show the count when multiple alarms are grouped: "Critical: Motion Detected (3)"
Acknowledgment
- Users can acknowledge Alerts to stop active notifications
- Acknowledged Alerts remain visible but don't trigger new notifications
Expiration and Removal
- Alerts are automatically removed when they expire (
end_datetimepasses) - Acknowledged Alerts are also automatically removed during periodic maintenance
- Maximum of 50 Alerts are kept in memory at any time
Audio Signal Integration
Each AlarmLevel maps to specific audio files for user notification:
INFO: Configurable info audio file (e.g., chime)WARNING: Configurable warning audio file (e.g., buzzer)CRITICAL: Configurable critical audio file (e.g., alarm siren)
Audio signals can be customized per installation and may eventually support alarm-specific sounds (e.g., tornado siren for weather alerts).
Notification Integration
- When an Alert is first created (single alarm), it automatically generates a notification item
- Notifications can be sent via email or other configured channels
- Notifications are only sent for the first alarm in an Alert to prevent spam
- Notifications respect the system's SecurityLevel settings
Security Level Filtering
- Each Alarm specifies which
SecurityLevelit applies to - Only Alarms matching the current system SecurityLevel become active Alerts
- This allows different alarm behaviors for different security contexts (e.g., home vs. away)
Priority System
Alerts are prioritized based on AlarmLevel priority values:
CRITICAL: 1000 (highest priority)WARNING: 100INFO: 10NONE: 0 (not alert-worthy, rejected)
Priority determines:
- Order of display in alert lists
- Which audio signal plays when multiple alerts are active
- Auto-switching behavior for console displays
Weather Alert Integration
Weather alerts from external sources (e.g., NWS) can be converted to system Alarms based on:
- Alert Type Filtering: Not all weather alerts should create alarms (e.g., informational vs. actionable)
- Severity Mapping: Weather alert severity levels map to system
AlarmLevel - Appropriate Lifetimes: Weather alerts have different duration characteristics than sensor-based events
- Security Level Application: Weather alarms typically apply to all security levels
Alert Processing Implementation
Queue-based system using deque with maxlen for memory efficiency:
class AlertManager(Singleton):
def __init_singleton__(self):
self._alert_queue = deque(maxlen=50)
self._lock = threading.Lock()
def add_alarm(self, alarm):
"""Add alarm and create/update alert"""
with self._lock:
signature = self._generate_signature(alarm)
existing_alert = self._find_alert_by_signature(signature)
if existing_alert:
self._group_alarm_to_alert(existing_alert, alarm)
else:
self._create_new_alert(alarm, signature)
def _generate_signature(self, alarm):
"""Generate unique signature for alarm grouping"""
return f"{alarm.source}.{alarm.type}.{alarm.level}"
Related Documentation
- Domain guidelines: Domain Guidelines
- Business logic: Business Logic
- Integration patterns: Integration Guidelines