Skip to content

Home Information - Your home, your data, organized.

Python
7.4 KB
Raw Blame
"""
Event-system models.

Lifecycle note (Issue #288): EventDefinition is integration-attached
(inherits IntegrationDetailsModel). Integration-owned rows
(``integration_id IS NOT NULL``) are cleaned up at the integration
disconnect / sync-removal boundary by
``hi.integrations.event_definition_operations.EventDefinitionOperations``,
not by a generalized "EntityState delete cascades to parent" rule.
User-owned rows are not touched by integration cleanup; the existing
``on_delete=CASCADE`` on ``EventClause.entity_state`` and
``ControlAction.controller`` continues to apply, which can leave a
user-owned EventDefinition silently semantically changed (clauseless,
or with reduced clauses) — that broader UX is deferred to a separate
redesign.
"""

from django.db import models

from hi.apps.alert.enums import AlarmLevel
from hi.apps.control.models import Controller
from hi.apps.entity.models import EntityState
from hi.apps.security.enums import SecurityLevel

from hi.integrations.models import IntegrationDetailsModel

from .enums import EventClauseOperator, EventType


class EventDefinition( IntegrationDetailsModel ):

    name = models.CharField(
        'Name',
        max_length = 64,
    )
    event_type_str = models.CharField(
        'Match Type',
        max_length = 32,
        null = False, blank = False,
    )

    # For multi-clause event definitions, the span in which all clauses
    # need to satisfied.
    #
    event_window_secs = models.PositiveIntegerField(
        'Match Window Secs',
    )

    # Rate limits how many events will be generated for this
    # EventDefinition by ensuring at least this time elapsed before a new
    # event would be generated.
    #
    dedupe_window_secs = models.PositiveIntegerField(
        'Dedupe Window Secs',
    )
    
    enabled = models.BooleanField(
        default = True,
    )
    created_datetime = models.DateTimeField(
        'Created',
        auto_now_add = True,
        blank = True,
    )
    updated_datetime = models.DateTimeField(
        'Updated',
        auto_now = True,
        blank = True,
    )
    
    class Meta:
        verbose_name = 'Rule'
        verbose_name_plural = 'Rules'

    @property
    def event_type(self):
        return EventType.from_name_safe( self.event_type_str )

    @event_type.setter
    def event_type( self, event_type : EventType ):
        self.event_type_str = str(event_type)
        return


class EventClause( models.Model ):

    event_definition = models.ForeignKey(
        EventDefinition,
        related_name = 'event_clauses',
        verbose_name = 'Rule',
        on_delete = models.CASCADE,
    )
    entity_state = models.ForeignKey(
        EntityState,
        related_name = '+',
        verbose_name = 'Item State',
        on_delete = models.CASCADE,
    )
    value = models.CharField(
        'Value',
        max_length = 255
    )
    # How ``value`` is compared against the live wire reading.
    # Default ``'EQ'`` keeps every pre-threshold clause matching by
    # exact string equality (the historical behavior). Numeric
    # operators (LT / LTE / GT / GTE) enable threshold-based alarms
    # on continuous EntityStateTypes such as BATTERY_LEVEL.
    value_operator_str = models.CharField(
        'Operator',
        max_length = 8,
        default = str(EventClauseOperator.default()),
        null = False, blank = False,
    )
    created_datetime = models.DateTimeField(
        'Created',
        auto_now_add = True,
        blank = True,
    )
    updated_datetime = models.DateTimeField(
        'Updated',
        auto_now = True,
        blank = True,
    )

    class Meta:
        verbose_name = 'Rule Condition'
        verbose_name_plural = 'Rule Conditions'

    IN_VALUE_DELIMITER = ','

    @property
    def value_operator(self) -> EventClauseOperator:
        return EventClauseOperator.from_name_safe( self.value_operator_str )

    @value_operator.setter
    def value_operator( self, value_operator : EventClauseOperator ):
        self.value_operator_str = str(value_operator)
        return

    def in_value_members(self) -> set:
        """Members of the comma-delimited ``value`` used by the IN
        operator. Returns an empty set when ``value`` is empty or
        only contains delimiters / whitespace."""
        return {
            m.strip() for m in ( self.value or '' ).split(
                self.IN_VALUE_DELIMITER,
            )
            if m.strip()
        }

    @classmethod
    def serialize_in_members(cls, values) -> str:
        """Inverse of :meth:`in_value_members` — joins an iterable of
        member strings into the comma-delimited storage shape.
        Whitespace-tolerant, deduplicated, sorted for determinism."""
        return cls.IN_VALUE_DELIMITER.join( sorted({
            v.strip() for v in ( values or [] ) if v and v.strip()
        }))


class AlarmAction( models.Model ):

    event_definition = models.ForeignKey(
        EventDefinition,
        related_name = 'alarm_actions',
        verbose_name = 'Rule',
        on_delete = models.CASCADE,
    )
    security_level_str = models.CharField(
        'Security Level',
        max_length = 32,
        null = False, blank = False,
    )
    alarm_level_str = models.CharField(
        'Alarm Level',
        max_length = 32,
        null = False, blank = False,
    )
    alarm_lifetime_secs = models.PositiveIntegerField(
        'Lifetime Secs',
    )
    created_datetime = models.DateTimeField(
        'Created',
        auto_now_add = True,
        blank = True,
    )
    updated_datetime = models.DateTimeField(
        'Updated',
        auto_now = True,
        blank = True,
    )
    
    class Meta:
        verbose_name = 'Alarm Actions'
        verbose_name_plural = 'Alarm Actions'

    @property
    def security_level(self):
        return SecurityLevel.from_name_safe( self.security_level_str )

    @security_level.setter
    def security_level( self, security_level : SecurityLevel ):
        self.security_level_str = str(security_level)
        return

    @property
    def alarm_level(self):
        return AlarmLevel.from_name_safe( self.alarm_level_str )

    @alarm_level.setter
    def alarm_level( self, alarm_level : AlarmLevel ):
        self.alarm_level_str = str(alarm_level)
        return

        
class ControlAction( models.Model ):

    event_definition = models.ForeignKey(
        EventDefinition,
        related_name = 'control_actions',
        verbose_name = 'Rule',
        on_delete = models.CASCADE,
    )
    controller = models.ForeignKey(
        Controller,
        related_name = 'control_actions',
        verbose_name = 'Controller',
        on_delete = models.CASCADE,
    )
    value = models.CharField(
        'Value',
        max_length = 255
    )
    created_datetime = models.DateTimeField(
        'Created',
        auto_now_add = True,
        blank = True,
    )
    updated_datetime = models.DateTimeField(
        'Updated',
        auto_now = True,
        blank = True,
    )

    class Meta:
        verbose_name = 'Control Action'
        verbose_name_plural = 'Control Actions'

        
class EventHistory( models.Model ):

    event_definition = models.ForeignKey(
        EventDefinition,
        related_name = 'history',
        verbose_name = 'Rule',
        on_delete = models.CASCADE,
    )
    event_datetime = models.DateTimeField(
        'Timestamp',
        db_index = True,
    )
    
    class Meta:
        verbose_name = 'Rule Match'
        verbose_name_plural = 'Rule Matches'
        ordering = [ '-event_datetime' ]