quilt-hp-python 0.1.1__py3-none-any.whl

quilt_hp/models/__init__.py

@@ -0,0 +1,85 @@
+"""Pythonic data models wrapping protobuf messages."""
+
+from quilt_hp.models.comfort import ComfortSetting
+from quilt_hp.models.controller import Controller
+from quilt_hp.models.energy import EnergyBucket, SpaceEnergyMetrics
+from quilt_hp.models.enums import (
+    BoostMode,
+    ComfortSettingOverride,
+    ComfortSettingType,
+    ConditionState,
+    FallbackControlCommand,
+    FanSpeed,
+    HvacControllerType,
+    HVACMode,
+    HVACState,
+    LedAnimation,
+    LightPreset,
+    LouverAngle,
+    LouverMode,
+    OccupancyMode,
+    OccupancyState,
+    RemoteSensorControlMode,
+    SafetyHeatingMode,
+)
+from quilt_hp.models.indoor_unit import (
+    IndoorUnit,
+    IndoorUnitCommands,
+    IndoorUnitControls,
+    IndoorUnitSettings,
+    IndoorUnitState,
+)
+from quilt_hp.models.outdoor_unit import OutdoorUnit
+from quilt_hp.models.schedule import ScheduleDay, ScheduleEvent, ScheduleWeek
+from quilt_hp.models.sensor import ControllerRemoteSensor, RemoteSensor
+from quilt_hp.models.software_update import SoftwareUpdateInfo
+from quilt_hp.models.space import (
+    Space,
+    SpaceControls,
+    SpaceSettings,
+    SpaceState,
+)
+from quilt_hp.models.system import Location, SystemInfo, SystemSnapshot
+
+__all__ = [
+    "BoostMode",
+    "ComfortSetting",
+    "ComfortSettingOverride",
+    "ComfortSettingType",
+    "ConditionState",
+    "Controller",
+    "ControllerRemoteSensor",
+    "EnergyBucket",
+    "FallbackControlCommand",
+    "FanSpeed",
+    "HVACMode",
+    "HVACState",
+    "HvacControllerType",
+    "IndoorUnit",
+    "IndoorUnitCommands",
+    "IndoorUnitControls",
+    "IndoorUnitSettings",
+    "IndoorUnitState",
+    "LedAnimation",
+    "LightPreset",
+    "Location",
+    "LouverAngle",
+    "LouverMode",
+    "OccupancyMode",
+    "OccupancyState",
+    "OutdoorUnit",
+    "RemoteSensor",
+    "RemoteSensorControlMode",
+    "SafetyHeatingMode",
+    "ScheduleDay",
+    "ScheduleEvent",
+    "ScheduleWeek",
+    "SoftwareUpdateInfo",
+    "Space",
+    "SpaceControls",
+    "SpaceEnergyMetrics",
+    "SpaceSettings",
+    "SpaceState",
+    "SystemInfo",
+    "SystemSnapshot",
+]

quilt_hp/models/comfort.py

@@ -0,0 +1,47 @@
+"""Comfort setting (named preset) model."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from quilt_hp.models.enums import (
+    ComfortSettingType,
+    FanSpeed,
+    HVACMode,
+    LouverMode,
+)
+
+
+@dataclass(slots=True)
+class ComfortSetting:
+    """A named comfort preset (Active, Sleep, Away, etc.)."""
+
+    id: str
+    system_id: str
+    space_id: str
+    name: str
+    type: ComfortSettingType
+    hvac_mode: HVACMode
+    heating_setpoint_c: float
+    cooling_setpoint_c: float
+    fan_speed: FanSpeed
+    louver_mode: LouverMode = LouverMode.UNSPECIFIED
+    louver_fixed_position: float = 0.0  # degrees, used when louver_mode=FIXED
+
+    @classmethod
+    def from_proto(cls, proto: object) -> ComfortSetting:
+        """Construct from a protobuf ComfortSetting message."""
+        a = proto.attributes  # type: ignore[attr-defined]
+        return cls(
+            id=proto.header.object_id,  # type: ignore[attr-defined]
+            system_id=proto.header.system_id,  # type: ignore[attr-defined]
+            space_id=proto.relationships.space_id,  # type: ignore[attr-defined]
+            name=a.name,
+            type=ComfortSettingType(a.type),
+            hvac_mode=HVACMode(a.hvac_mode),
+            heating_setpoint_c=a.heating_temperature_setpoint_c,
+            cooling_setpoint_c=a.cooling_temperature_setpoint_c,
+            fan_speed=FanSpeed.from_wire(a.fan_speed_mode, a.fan_speed_percent),
+            louver_mode=LouverMode(a.louver_mode) if a.louver_mode else LouverMode.UNSPECIFIED,
+            louver_fixed_position=a.louver_fixed_position,
+        )

quilt_hp/models/controller.py

@@ -0,0 +1,135 @@
+"""Controller (Quilt Dial thermostat) model."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any, cast
+
+from quilt_hp.models.enums import RemoteSensorControlMode
+from quilt_hp.models.qsm import WifiInfo
+
+_ONLINE_THRESHOLD_S = 5 * 60  # 5 minutes, matching KMP IS_ONLINE_THRESHOLD_MINUTES
+
+
+@dataclass(slots=True)
+class Controller:
+    """A Quilt controller (Dial thermostat)."""
+
+    id: str
+    system_id: str
+    space_id: str
+    name: str
+    raw_thermistor_c: float  # ambient_temperature_c from raw Dial thermistor
+    pcb_temperature_a_c: float  # temperature_f3 — PCB temp A (~30–50°C)
+    pcb_temperature_b_c: float  # temperature_f4 — PCB temp B (hotter component, ~45–52°C)
+    calibrated_ambient_c: float  # temperature_f5 — calibrated ext ambient sent to IDU
+    wifi_ssid: str | None
+    wifi_ip: str | None
+    wifi_signal_dbm: int | None
+    wifi_freq_mhz: int | None = None  # e.g. 5745 → 5 GHz; 2437 → 2.4 GHz
+    wifi_last_seen: datetime | None = (
+        None  # WifiState.updated_ts — when the dial last checked in over WiFi
+    )
+    ap_wifi: WifiInfo | None = None  # AP-mode interface (device provisioning)
+    p2p_wifi: WifiInfo | None = None  # peer-to-peer / Wi-Fi Direct
+    remote_sensor_mode: RemoteSensorControlMode = RemoteSensorControlMode.UNSPECIFIED
+    software_update_info_id: str | None = None
+    firmware_update_info_id: str | None = None
+    serial_number: str | None = None  # ControllerHardware.attributes.serial_number
+    model_sku: str | None = None  # ControllerHardware.attributes.model_sku
+    firmware_version: str | None = None  # ControllerHardware.attributes.firmware_version
+    state_updated_at: datetime | None = None  # ControllerState.updated_ts (field 1)
+
+    @property
+    def ambient_temperature_c(self) -> float:
+        """Calibrated ambient temperature used for system control.
+
+        Use this for display and logic.  See also ``raw_thermistor_c`` for the
+        uncorrected on-chip reading (biased high by self-heating).
+        """
+        return self.calibrated_ambient_c
+
+    @property
+    def wifi_band(self) -> str | None:
+        """'5 GHz' or '2.4 GHz' based on frequency, or None if unknown."""
+        if self.wifi_freq_mhz is None:
+            return None
+        return "5 GHz" if self.wifi_freq_mhz > 5000 else "2.4 GHz"
+
+    @property
+    def is_online(self) -> bool:
+        """True if the controller is known to be online.
+
+        Uses ``ControllerState.updated_ts`` if available, with a 5-minute
+        threshold matching KMP ``IS_ONLINE_THRESHOLD_MINUTES = 5``.
+
+        The server does not currently send ``ControllerState.updated_ts``
+        (confirmed from wire captures — field 1 always absent).  When no
+        timestamp is available we assume the controller is online; we only
+        report offline when we have positive evidence of a stale timestamp.
+        """
+        if self.state_updated_at is None:
+            return True  # no timestamp → unknown → assume online (fail-open)
+        age = (datetime.now(tz=UTC) - self.state_updated_at).total_seconds()
+        return age < _ONLINE_THRESHOLD_S
+
+    @classmethod
+    def from_proto(cls, proto: object, hw_map: dict[str, object] | None = None) -> Controller:
+        """Construct from a protobuf Controller message.
+
+        ``hw_map`` maps hardware_id → ControllerHardware proto, built once from
+        ``HomeDatastoreSystem.controller_hardware`` and passed in at snapshot
+        load time.  Stream diffs won't have it; fields default to None.
+        """
+        p = cast("Any", proto)
+        w = p.hosted_wifi_state
+        ts = p.state.updated_ts
+        updated_at: datetime | None = None
+        if ts.seconds != 0:
+            updated_at = datetime.fromtimestamp(ts.seconds, tz=UTC)
+
+        wifi_last_seen: datetime | None = None
+        if w.updated_ts.seconds != 0:
+            wifi_last_seen = datetime.fromtimestamp(w.updated_ts.seconds, tz=UTC)
+
+        def _wifi(wstate: object) -> WifiInfo | None:
+            info = WifiInfo.from_proto(wstate)
+            return info if info.connected else None
+
+        serial: str | None = None
+        model_sku: str | None = None
+        fw_ver: str | None = None
+        if hw_map:
+            hw_id = p.relationships.hardware_id
+            hw = hw_map.get(hw_id)
+            if hw is not None:
+                a = cast("Any", hw).attributes
+                serial = a.serial_number or None
+                model_sku = a.model_sku or None
+                fw_ver = a.firmware_version or None
+
+        return cls(
+            id=p.header.object_id,
+            system_id=p.header.system_id,
+            space_id=p.relationships.space_id,
+            name=p.settings.name,
+            raw_thermistor_c=p.state.ambient_temperature_c,
+            pcb_temperature_a_c=p.state.temperature_f3,
+            pcb_temperature_b_c=p.state.temperature_f4,
+            calibrated_ambient_c=p.state.temperature_f5,
+            wifi_ssid=w.ssid or None,
+            wifi_ip=w.ipv4_address or None,
+            wifi_signal_dbm=w.signal_level_dbm or None,
+            wifi_freq_mhz=w.frequency_mhz or None,
+            wifi_last_seen=wifi_last_seen,
+            ap_wifi=_wifi(p.ap_wifi_state),
+            p2p_wifi=_wifi(p.p2p_wifi_state),
+            remote_sensor_mode=RemoteSensorControlMode(p.controls.remote_sensor_control_mode),
+            software_update_info_id=p.relationships.software_update_info_id or None,
+            firmware_update_info_id=p.relationships.firmware_update_info_id or None,
+            serial_number=serial,
+            model_sku=model_sku,
+            firmware_version=fw_ver,
+            state_updated_at=updated_at,
+        )

quilt_hp/models/energy.py

@@ -0,0 +1,31 @@
+"""Energy metrics models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+
+@dataclass(slots=True)
+class EnergyBucket:
+    """One hourly energy measurement slot."""
+
+    start_time: datetime
+    energy_kwh: float
+    status: int  # 0=UNSPECIFIED, 1=COMPLETE, 2=INCOMPLETE
+
+
+@dataclass(slots=True)
+class SpaceEnergyMetrics:
+    """Hourly energy buckets for one space over a time range."""
+
+    space_id: str
+    buckets: list[EnergyBucket]
+
+    @property
+    def total_kwh(self) -> float:
+        """Sum of all bucket energy values."""
+        return sum(b.energy_kwh for b in self.buckets)

quilt_hp/models/enums.py

@@ -0,0 +1,298 @@
+"""Pythonic enums mirroring the Quilt protobuf enum values."""
+
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class HVACMode(IntEnum):
+    """HVAC operating mode."""
+
+    UNSPECIFIED = 0
+    STANDBY = 1
+    COOL = 2
+    HEAT = 3
+    AUTO = 4
+    FAN = 5
+    FALLBACK_AUTO = 6
+    FALLBACK_OFF = 7
+
+    def __str__(self) -> str:
+        return self.name
+
+
+class HVACState(IntEnum):
+    """Current HVAC state (what the system is actually doing)."""
+
+    UNSPECIFIED = 0
+    STANDBY = 1
+    COOL = 2
+    HEAT = 3
+    DRIFT = 4
+    FAN = 5
+    COOL_DEFERRED = 6
+    HEAT_DEFERRED = 7
+    FAN_DEFERRED = 8
+    COOL_PREPARING = 9
+    HEAT_PREPARING = 10
+
+    def __str__(self) -> str:
+        return self.name
+
+
+class FanSpeed(IntEnum):
+    """Discrete fan speed labels (maps to mode + percent on the wire)."""
+
+    AUTO = 0
+    QUIET = 1
+    LOW = 2
+    MEDIUM = 3
+    HIGH = 4
+    BLAST = 5
+
+    def __str__(self) -> str:
+        return self.name
+
+    def to_wire(self) -> tuple[int, float]:
+        """Return (fan_speed_mode, fan_speed_percent) for the wire protocol."""
+        _MAP: dict[FanSpeed, tuple[int, float]] = {
+            FanSpeed.AUTO: (1, 0.0),  # FAN_SPEED_MODE_AUTO
+            FanSpeed.QUIET: (2, 0.20),  # FAN_SPEED_MODE_SETPOINT
+            FanSpeed.LOW: (2, 0.40),
+            FanSpeed.MEDIUM: (2, 0.60),
+            FanSpeed.HIGH: (2, 0.80),
+            FanSpeed.BLAST: (2, 1.00),
+        }
+        return _MAP[self]
+
+    @classmethod
+    def from_wire(cls, mode: int, percent: float) -> FanSpeed:
+        """Decode wire fan_speed_mode/fan_speed_percent to FanSpeed label."""
+        if mode != 2:  # FAN_SPEED_MODE_SETPOINT
+            return cls.AUTO
+        if percent <= 0.21:
+            return cls.QUIET
+        if percent <= 0.41:
+            return cls.LOW
+        if percent <= 0.61:
+            return cls.MEDIUM
+        if percent <= 0.81:
+            return cls.HIGH
+        return cls.BLAST
+
+
+class LouverMode(IntEnum):
+    """Indoor unit louver mode."""
+
+    UNSPECIFIED = 0
+    CLOSED = 1
+    SWEEP = 2
+    FIXED = 3
+    AUTO = 4
+
+    def __str__(self) -> str:
+        return self.name
+
+
+class LouverAngle(IntEnum):
+    """Discrete louver angle positions (when mode=FIXED)."""
+
+    ANGLE1 = 1
+    ANGLE2 = 2
+    ANGLE3 = 3
+    ANGLE4 = 4
+    ANGLE5 = 5
+
+    def to_wire(self) -> float:
+        """Return the louver_fixed_position float for the wire."""
+        return {1: 0.20, 2: 0.40, 3: 0.60, 4: 0.80, 5: 1.00}[self.value]
+
+    @classmethod
+    def from_wire(cls, position: float) -> LouverAngle:
+        """Decode a wire louver_fixed_position to a LouverAngle."""
+        if position <= 0.21:
+            return cls.ANGLE1
+        if position <= 0.41:
+            return cls.ANGLE2
+        if position <= 0.61:
+            return cls.ANGLE3
+        if position <= 0.81:
+            return cls.ANGLE4
+        return cls.ANGLE5
+
+
+class LightPreset(IntEnum):
+    """Built-in LED color presets (RGBW packed int32)."""
+
+    DAYLIGHT = 0x000000FF
+    WARM = 0xFF460064
+    SUNSET = 0xFF460024
+    SKY = 0x009CFF54
+
+    def __str__(self) -> str:
+        return self.name
+
+
+class LedAnimation(IntEnum):
+    """Indoor unit LED animation modes.
+
+    Note: NONE = 1 (not 0).  UNSPECIFIED = 0 means the field was absent from
+    the wire diff; NONE means the server explicitly set "no animation" (solid
+    colour).  Callers should treat UNSPECIFIED the same as NONE for display.
+    """
+
+    UNSPECIFIED = 0
+    NONE = 1
+    SPARKLE_FADE = 2
+    TWINKLE_FADE = 3
+    DANCE = 4
+    CHASE = 5
+
+    def __str__(self) -> str:
+        return self.name
+
+
+class ComfortSettingType(IntEnum):
+    """Type of comfort preset."""
+
+    UNSPECIFIED = 0
+    ACTIVE = 1
+    SLEEP = 2
+    AWAY = 3
+    STANDBY = 4
+    CUSTOM = 5
+
+    def __str__(self) -> str:
+        return self.name
+
+
+class OccupancyMode(IntEnum):
+    """Space-level auto-away/return occupancy mode."""
+
+    UNSPECIFIED = 0
+    DISABLED = 1
+    ENABLED = 2
+
+    def __str__(self) -> str:
+        return self.name
+
+
+class SafetyHeatingMode(IntEnum):
+    """Freeze protection mode for a space."""
+
+    UNSPECIFIED = 0  # treated as ENABLED by the device
+    DISABLED = 1
+    ENABLED = 2
+
+    def __str__(self) -> str:
+        return self.name
+
+
+class OccupancyState(IntEnum):
+    """Occupancy detection state."""
+
+    UNSPECIFIED = 0
+    UNDETECTED = 1
+    DETECTED = 2
+
+    def __str__(self) -> str:
+        return self.name
+
+
+class Presence(IntEnum):
+    """Raw radar sensor presence detection."""
+
+    UNSPECIFIED = 0
+    UNDETECTED = 1
+    DETECTED = 2
+
+    def __str__(self) -> str:
+        return self.name
+
+
+class LightState(IntEnum):
+    """Explicit LED on/off state (field 13 of IndoorUnitControls).
+
+    Sent when the ``mobile_led_scheduling_enabled`` Statsig gate is on.
+    When state=OFF, brightness is **preserved** server-side (not zeroed) so
+    toggling back on restores the prior brightness.  When UNSPECIFIED, fall
+    back to brightness-based detection.
+    """
+
+    UNSPECIFIED = 0
+    ON = 1
+    OFF = 2
+
+    def __str__(self) -> str:
+        return self.name
+
+
+class ConditionState(IntEnum):
+    """Fault condition state."""
+
+    UNSPECIFIED = 0
+    INACTIVE = 1
+    ACTIVE = 2
+
+    def __str__(self) -> str:
+        return self.name
+
+
+class HvacControllerType(IntEnum):
+    """Algorithm variant used by the controller to drive the IDU."""
+
+    UNSPECIFIED = 0
+    PASS_THROUGH_TEMPERATURE = 1
+    INTEGRAL_TEMPERATURE_V1 = 2
+    INTEGRAL_TEMPERATURE_V2 = 3
+
+    def __str__(self) -> str:
+        return self.name
+
+
+class BoostMode(IntEnum):
+    """Boost (turbo) mode override for a space."""
+
+    UNSPECIFIED = 0
+    OFF = 1
+    ON = 2
+
+    def __str__(self) -> str:
+        return self.name
+
+
+class ComfortSettingOverride(IntEnum):
+    """Why the active comfort setting differs from the schedule."""
+
+    UNSPECIFIED = 0
+    NONE = 1
+    UNTIL_NEXT_SCHEDULE = 2
+    INDEFINITE = 3
+    SCHEDULE = 4
+    UNOCCUPIED = 5
+    OCCUPIED = 6
+
+    def __str__(self) -> str:
+        return self.name
+
+
+class FallbackControlCommand(IntEnum):
+    """Command sent when the Dial loses cloud connectivity."""
+
+    UNSPECIFIED = 0
+    COMPLETE = 1
+    EXIT = 2
+
+    def __str__(self) -> str:
+        return self.name
+
+
+class RemoteSensorControlMode(IntEnum):
+    """Whether the Dial acts as the zone temperature sensor."""
+
+    UNSPECIFIED = 0
+    DISABLED = 1
+    ENABLED = 2
+
+    def __str__(self) -> str:
+        return self.name