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

quilt_hp/models/indoor_unit.py

@@ -0,0 +1,412 @@
+"""Indoor unit model — wall-mounted mini-split head."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+from quilt_hp.models.enums import (
+    FallbackControlCommand,
+    FanSpeed,
+    HvacControllerType,
+    HVACMode,
+    HVACState,
+    LedAnimation,
+    LightState,
+    LouverMode,
+    Presence,
+)
+
+_ONLINE_THRESHOLD_MINUTES = 5
+
+
+@dataclass(slots=True)
+class IndoorUnitControls:
+    """Controllable settings for an indoor unit."""
+
+    fan_speed: FanSpeed
+    louver_mode: LouverMode
+    louver_fixed_position: float
+    led_color_code: int
+    led_brightness: float  # stored brightness 0.0-1.0; preserved when led_state=OFF
+    led_animation: LedAnimation
+    led_state: LightState = LightState.UNSPECIFIED  # explicit ON/OFF (proto field 13)
+    # Raw wire FAN_SPEED_MODE value (0=absent/proto3-default, 1=AUTO,
+    # 2=SETPOINT). Needed because FanSpeed.from_wire(0, 0.0) and
+    # from_wire(1, 0.0) both return FanSpeed.AUTO.
+    fan_speed_mode_raw: int = 0
+
+    @property
+    def light_on(self) -> bool:
+        """True when the LED intent is ON.
+
+        When ``led_state`` is explicit (mobile_led_scheduling_enabled gate on):
+        - ON  → True
+        - OFF → False (brightness is preserved server-side, so > 0 does not
+          mean on)
+        Fallback when UNSPECIFIED: matches KMP ``Light.isOn`` logic:
+        isBlack = led_color_code == 0; isOn = !isBlack && brightness > 0.
+        """
+        if self.led_state == LightState.ON:
+            return True
+        if self.led_state == LightState.OFF:
+            return False
+        # UNSPECIFIED: legacy brightness-based detection
+        return self.led_color_code != 0 and self.led_brightness > 0.0
+
+
+@dataclass(slots=True)
+class IndoorUnitSettings:
+    """Configuration/calibration settings for an indoor unit."""
+
+    name: str
+    description: str
+    light_brightness_default_percent: float
+    presence_fence_left_m: float  # detection zone left boundary (0 = unconfigured/max range)
+    presence_fence_right_m: float  # detection zone right boundary
+    presence_fence_forward_m: float  # detection zone forward boundary (depth)
+    radar_sensor_distance_from_floor_m: float  # mounting height calibration
+
+
+@dataclass(slots=True)
+class IndoorUnitState:
+    """Read-only state for an indoor unit."""
+
+    hvac_mode: HVACMode
+    hvac_state: HVACState
+    ambient_temperature_c: float
+    ambient_humidity_percent: float
+    fan_speed_rpm: float
+    fan_speed_setpoint_rpm: float
+    presence_detection_level: float
+    # Additional state fields (proto fields 2, 7, 9, 10, 13, 14)
+    temperature_setpoint_c: float = 0.0
+    light_brightness_percent: float = 0.0  # device-reported actual LED brightness (field 7)
+    inlet_temperature_c: float = 0.0
+    outlet_temperature_c: float = 0.0
+    calculated_ambient_temperature_c: float = 0.0
+    louver_angle_up_down_degrees: float = 0.0
+    # proto field 1: timestamp of last state update (used for online detection)
+    updated_at: datetime | None = None
+
+
+@dataclass(slots=True)
+class IndoorUnitPerformanceData:
+    """Raw IDU sensor measurements (updated every ~5 seconds)."""
+
+    measurement_interval_s: float
+    energy_measurement_j: float
+    hvac_mode: HVACMode
+    hvac_state: HVACState
+    actual_fan_speed_rpm: float
+    outlet_temperature_c: float
+    inlet_temperature_c: float
+    inlet_humidity_pct: float
+    coil_temperature_c: float
+    gas_pipe_temperature_c: float
+    liquid_pipe_temperature_c: float
+
+    @property
+    def energy_kwh(self) -> float:
+        """Energy for this interval in kWh."""
+        return self.energy_measurement_j / 3_600_000
+
+
+@dataclass(slots=True)
+class IndoorUnitPerformanceMetrics:
+    """Computed efficiency metrics (only populated when unit is running)."""
+
+    capacity_w: float
+    coefficient_of_performance: float
+    hvac_power_w: float
+    led_power_w: float
+    hvac_mode: HVACMode
+    hvac_state: HVACState
+    measurement_duration_s: float = 0.0
+    energy_total_j: float = 0.0
+    hvac_energy_j: float = 0.0
+    led_energy_j: float = 0.0
+
+
+@dataclass(slots=True)
+class IndoorUnitHvacInputs:
+    """HVAC controller inputs — what the controller sends to the IDU."""
+
+    external_ambient_temperature_c: float
+    ambient_temperature_source: int
+    temperature_setpoint_c: float
+    hvac_mode: HVACMode
+    hvac_state: HVACState
+    hvac_controller_type: HvacControllerType = HvacControllerType.UNSPECIFIED
+
+
+@dataclass(slots=True)
+class IndoorUnitCommands:
+    """IDU fallback control command (sent during cloud connectivity loss)."""
+
+    fallback_control_command: FallbackControlCommand
+
+
+@dataclass(slots=True)
+class IndoorUnitConditions:
+    """IDU diagnostic conditions (ODU-linked conditions included)."""
+
+    mode_conflict: int
+    anti_cold_wind: int
+    abnormal_outdoor_air_temperature: int
+    hvac_mode_switching_delay: int
+    defrost_cycle: int
+    safety_heating: int
+    oil_return: int
+    modbus_communication_error: int
+    coil_preheat: int
+    mode_conflict_avoidance: int
+    outdoor_unit_communication_error: int
+
+    @property
+    def any_active(self) -> bool:
+        """True if any condition is ACTIVE (value 2)."""
+        return any(
+            getattr(self, f) == 2
+            for f in (
+                "mode_conflict",
+                "anti_cold_wind",
+                "abnormal_outdoor_air_temperature",
+                "hvac_mode_switching_delay",
+                "defrost_cycle",
+                "safety_heating",
+                "oil_return",
+                "modbus_communication_error",
+                "coil_preheat",
+                "mode_conflict_avoidance",
+                "outdoor_unit_communication_error",
+            )
+        )
+
+
+@dataclass(slots=True)
+class IndoorUnitPresence:
+    """Radar presence sensor data — binary DETECTED / UNDETECTED per sensor."""
+
+    sensor0_presence: Presence
+    sensor1_presence: Presence
+
+
+@dataclass(slots=True)
+class IndoorUnitOccupancy:
+    """Computed room occupancy state."""
+
+    occupancy_state: int
+
+
+@dataclass(slots=True)
+class IndoorUnit:
+    """A Quilt indoor unit (wall-mounted mini-split head)."""
+
+    id: str
+    system_id: str
+    space_id: str
+    outdoor_unit_id: str | None  # APK: IndoorUnitRelationships.outdoor_unit_id field 3
+    hardware_id: str
+    qsm_id: str | None  # QuiltSmartModule embedded in this unit
+    settings: IndoorUnitSettings
+    controls: IndoorUnitControls
+    state: IndoorUnitState
+    hvac_inputs: IndoorUnitHvacInputs | None
+    conditions: IndoorUnitConditions | None
+    performance_data: IndoorUnitPerformanceData | None
+    performance_metrics: IndoorUnitPerformanceMetrics | None
+    presence: IndoorUnitPresence | None
+    occupancy: IndoorUnitOccupancy | None
+    firmware_update_info_id: str | None = None
+    commands: IndoorUnitCommands | None = None
+
+    @classmethod
+    def from_proto(cls, proto: object) -> IndoorUnit:
+        """Construct from a protobuf IndoorUnit message."""
+        return _idu_from_proto(proto)
+
+    @property
+    def is_online(self) -> bool:
+        """True if the IDU has sent a state update within the last 5 minutes.
+
+        Matches KMP SpaceViewNode.isOnlineByUpdatedTimestamp.
+        An offline IDU may have stale controls data — treat LED as off.
+        """
+        ts = self.state.updated_at
+        if ts is None:
+            return False
+        now = datetime.now(tz=UTC)
+        delta_minutes = (now - ts).total_seconds() / 60
+        return delta_minutes < _ONLINE_THRESHOLD_MINUTES
+
+    @property
+    def led_on(self) -> bool:
+        """True if the LED is currently illuminated.
+
+        Applies the online gate: KMP's ``getLight()`` calls ``filterOnline()``
+        and returns ``Light.OFF`` for offline IDUs.  An offline IDU's controls
+        data is stale and must not be used for LED state.
+        """
+        return self.is_online and self.controls.light_on
+
+    @property
+    def effective_occupancy_state(self) -> int | None:
+        """Occupancy state proto value, or None if the IDU is offline.
+
+        KMP reads presence/occupancy only from online IDUs (``filterOnline()``).
+        An offline IDU's last-known ``occupancy_state`` is stale and must not
+        be displayed as current. Returns None when offline or no occupancy data.
+        """
+        if not self.is_online or self.occupancy is None:
+            return None
+        return self.occupancy.occupancy_state
+
+
+def _idu_from_proto(proto: object) -> IndoorUnit:
+    """Internal: convert a proto IndoorUnit to our model."""
+    from quilt_hp.models.enums import HVACMode, HVACState
+
+    c = proto.controls  # type: ignore[attr-defined]
+    s = proto.state  # type: ignore[attr-defined]
+    st = proto.settings  # type: ignore[attr-defined]
+    pd = proto.performance_data  # type: ignore[attr-defined]
+    pm = proto.performance_metrics  # type: ignore[attr-defined]
+
+    perf_data = None
+    if pd.updated_ts:
+        perf_data = IndoorUnitPerformanceData(
+            measurement_interval_s=pd.measurement_interval_s,
+            energy_measurement_j=pd.energy_measurement_j,
+            hvac_mode=HVACMode(pd.hvac_mode),
+            hvac_state=HVACState(pd.hvac_state),
+            actual_fan_speed_rpm=pd.actual_fan_speed_rpm,
+            outlet_temperature_c=pd.outlet_temperature_c,
+            inlet_temperature_c=pd.inlet_temperature_c,
+            inlet_humidity_pct=pd.inlet_humidity_pct,
+            coil_temperature_c=pd.coil_temperature_c,
+            gas_pipe_temperature_c=pd.gas_pipe_temperature_c,
+            liquid_pipe_temperature_c=pd.liquid_pipe_temperature_c,
+        )
+
+    perf_metrics = None
+    if pm.updated_ts:
+        perf_metrics = IndoorUnitPerformanceMetrics(
+            capacity_w=pm.capacity_w,
+            coefficient_of_performance=pm.coefficient_of_performance,
+            hvac_power_w=pm.hvac_power_w,
+            led_power_w=pm.led_power_w,
+            hvac_mode=HVACMode(pm.hvac_mode),
+            hvac_state=HVACState(pm.hvac_state),
+            measurement_duration_s=pm.measurement_duration_s,
+            energy_total_j=pm.energy_total_j,
+            hvac_energy_j=pm.hvac_energy_j,
+            led_energy_j=pm.led_energy_j,
+        )
+
+    hvac_inputs = None
+    hi = proto.hvac_inputs  # type: ignore[attr-defined]
+    if hi.updated_ts:
+        hvac_inputs = IndoorUnitHvacInputs(
+            external_ambient_temperature_c=hi.external_ambient_temperature_c,
+            ambient_temperature_source=hi.ambient_temperature_source,
+            temperature_setpoint_c=hi.temperature_setpoint_c,
+            hvac_mode=HVACMode(hi.hvac_mode),
+            hvac_state=HVACState(hi.hvac_state),
+            hvac_controller_type=HvacControllerType(hi.hvac_controller_type),
+        )
+
+    commands = None
+    cmd = proto.commands  # type: ignore[attr-defined]
+    if cmd.updated_ts:
+        commands = IndoorUnitCommands(
+            fallback_control_command=FallbackControlCommand(cmd.fallback_control_command),
+        )
+
+    conditions = None
+    co = proto.conditions  # type: ignore[attr-defined]
+    if co.updated_ts:
+        conditions = IndoorUnitConditions(
+            mode_conflict=co.mode_conflict,
+            anti_cold_wind=co.anti_cold_wind,
+            abnormal_outdoor_air_temperature=co.abnormal_outdoor_air_temperature,
+            hvac_mode_switching_delay=co.hvac_mode_switching_delay,
+            defrost_cycle=co.defrost_cycle,
+            safety_heating=co.safety_heating,
+            oil_return=co.oil_return,
+            modbus_communication_error=co.modbus_communication_error,
+            coil_preheat=co.coil_preheat,
+            mode_conflict_avoidance=co.mode_conflict_avoidance,
+            outdoor_unit_communication_error=co.outdoor_unit_communication_error,
+        )
+
+    presence_state = None
+    if hasattr(proto, "presence") and proto.presence.updated_ts:
+        presence_state = IndoorUnitPresence(
+            sensor0_presence=Presence(proto.presence.sensor0_presence),
+            sensor1_presence=Presence(proto.presence.sensor1_presence),
+        )
+
+    occupancy_state = None
+    if hasattr(proto, "occupancy") and proto.occupancy.updated_ts:
+        occupancy_state = IndoorUnitOccupancy(
+            occupancy_state=proto.occupancy.occupancy_state,
+        )
+
+    return IndoorUnit(
+        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]
+        outdoor_unit_id=proto.relationships.outdoor_unit_id or None,  # type: ignore[attr-defined]
+        hardware_id=proto.relationships.hardware_id,  # type: ignore[attr-defined]
+        qsm_id=proto.relationships.quilt_smart_module_id or None,  # type: ignore[attr-defined]
+        settings=IndoorUnitSettings(
+            name=st.name,
+            description=st.description,
+            light_brightness_default_percent=st.light_brightness_default_percent,
+            presence_fence_left_m=st.presence_fence_left_m,
+            presence_fence_right_m=st.presence_fence_right_m,
+            presence_fence_forward_m=st.presence_fence_forward_m,
+            radar_sensor_distance_from_floor_m=st.radar_sensor_distance_from_floor_m,
+        ),
+        controls=IndoorUnitControls(
+            fan_speed=FanSpeed.from_wire(c.fan_speed_mode, c.fan_speed_percent),
+            fan_speed_mode_raw=c.fan_speed_mode,
+            louver_mode=LouverMode(c.louver_mode) if c.louver_mode else LouverMode.UNSPECIFIED,
+            louver_fixed_position=c.louver_fixed_position,
+            led_color_code=c.led_color_code,
+            led_brightness=c.led_color_brightness_percent,
+            led_animation=LedAnimation(c.led_animation),
+            led_state=LightState(c.led_state),
+        ),
+        state=IndoorUnitState(
+            hvac_mode=HVACMode(s.hvac_mode),
+            hvac_state=HVACState(s.hvac_state),
+            ambient_temperature_c=s.ambient_temperature_c,
+            ambient_humidity_percent=s.ambient_humidity_percent,
+            fan_speed_rpm=s.fan_speed_rpm,
+            fan_speed_setpoint_rpm=s.fan_speed_setpoint_rpm,
+            presence_detection_level=s.presence_detection_level,
+            temperature_setpoint_c=s.temperature_setpoint_c,
+            light_brightness_percent=s.light_brightness_percent,
+            inlet_temperature_c=s.inlet_temperature_c,
+            outlet_temperature_c=s.outlet_temperature_c,
+            calculated_ambient_temperature_c=s.calculated_ambient_temperature_c,
+            louver_angle_up_down_degrees=s.louver_angle_up_down_degrees,
+            updated_at=(
+                datetime.fromtimestamp(s.updated_ts.seconds, tz=UTC)
+                if s.updated_ts and s.updated_ts.seconds
+                else None
+            ),
+        ),
+        hvac_inputs=hvac_inputs,
+        conditions=conditions,
+        performance_data=perf_data,
+        performance_metrics=perf_metrics,
+        presence=presence_state,
+        occupancy=occupancy_state,
+        firmware_update_info_id=(
+            proto.relationships.firmware_update_info_id or None  # type: ignore[attr-defined]
+        ),
+        commands=commands,
+    )

quilt_hp/models/outdoor_unit.py

@@ -0,0 +1,71 @@
+"""Outdoor unit model — compressor/condenser."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class OutdoorUnitPerformanceData:
+    """Raw ODU compressor telemetry."""
+
+    measurement_interval_s: float
+    energy_measurement_j: float
+    compressor_frequency_hz: float
+    ambient_temperature_c: float
+    coil_temperature_c: float
+    exhaust_temperature_c: float
+    high_pressure_kpa: float
+    low_pressure_kpa: float
+
+
+@dataclass(slots=True)
+class OutdoorUnit:
+    """A Quilt outdoor unit (compressor)."""
+
+    id: str
+    system_id: str
+    space_id: str
+    hvac_state: int
+    model_sku: str | None
+    serial_number: str | None
+    firmware_version: str | None
+    firmware_update_info_id: str | None
+    performance_data: OutdoorUnitPerformanceData | None
+
+    @classmethod
+    def from_proto(cls, proto: object, hw_map: dict[str, object] | None = None) -> OutdoorUnit:
+        """Construct from a protobuf OutdoorUnit message."""
+        hw_id = proto.relationships.hardware_id  # type: ignore[attr-defined]
+        hw = hw_map.get(hw_id) if hw_map else None
+
+        pd = None
+        if hasattr(proto, "performance_data"):
+            p = proto.performance_data
+            # Server does not reliably set updated_ts on
+            # OutdoorUnitPerformanceData. Gate on any non-zero value instead.
+            if p.ambient_temperature_c or p.compressor_frequency_hz or p.energy_measurement_j:
+                pd = OutdoorUnitPerformanceData(
+                    measurement_interval_s=p.measurement_interval_s,
+                    energy_measurement_j=p.energy_measurement_j,
+                    compressor_frequency_hz=p.compressor_frequency_hz,
+                    ambient_temperature_c=p.ambient_temperature_c,
+                    coil_temperature_c=p.coil_temperature_c,
+                    exhaust_temperature_c=p.exhaust_temperature_c,
+                    high_pressure_kpa=p.high_pressure_kpa,
+                    low_pressure_kpa=p.low_pressure_kpa,
+                )
+
+        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]
+            hvac_state=proto.state.hvac_state,  # type: ignore[attr-defined]
+            model_sku=hw.attributes.model_sku if hw else None,  # type: ignore[attr-defined]
+            serial_number=hw.attributes.serial_number if hw else None,  # type: ignore[attr-defined]
+            firmware_version=hw.attributes.firmware_version if hw else None,  # type: ignore[attr-defined]
+            firmware_update_info_id=(
+                proto.relationships.firmware_update_info_id or None  # type: ignore[attr-defined]
+            ),
+            performance_data=pd,
+        )

quilt_hp/models/qsm.py

@@ -0,0 +1,105 @@
+"""QuiltSmartModule (QSM) model — the WiFi compute module embedded in each IDU.
+
+Each indoor unit contains one QSM that handles:
+- Cloud/local NATS connectivity (three WiFi interfaces: hosted, AP, P2P)
+- Presence detection (phase + target radar channels)
+- Ambient light sensing (ALS: illuminance, IR, combined)
+- Accelerometer (X/Y/Z — detects unit tilt/movement)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class WifiInfo:
+    """WiFi interface snapshot (one of three on a QSM)."""
+
+    ssid: str | None
+    ip: str | None
+    signal_dbm: int | None
+
+    @property
+    def connected(self) -> bool:
+        return bool(self.ssid)
+
+    @classmethod
+    def from_proto(cls, proto: object) -> WifiInfo:
+        ssid = getattr(proto, "ssid", None) or None
+        ip = getattr(proto, "ipv4_address", None) or None
+        sig = getattr(proto, "signal_level_dbm", None) or None
+        return cls(ssid=ssid, ip=ip, signal_dbm=sig)
+
+
+@dataclass(slots=True)
+class QsmSensors:
+    """Raw sensor data from the QSM (updated every few seconds)."""
+
+    # Radar presence sensor (mm-wave)
+    phase_detected_raw: float  # phase-channel detection strength
+    target_detected_raw: float  # target-channel detection strength
+
+    # Ambient light sensor
+    als_illuminance_raw: int  # broadband illuminance
+    als_ir_raw: int  # IR channel
+    als_both_raw: int  # combined
+
+    # Accelerometer (detects unit orientation/tilt)
+    accel_x_raw: int
+    accel_y_raw: int
+    accel_z_raw: int
+
+
+@dataclass(slots=True)
+class QuiltSmartModule:
+    """A QSM — the WiFi compute module embedded in every Quilt indoor unit."""
+
+    id: str
+    system_id: str
+    led_color_code: int
+    sensors: QsmSensors | None
+    hosted_wifi: WifiInfo | None  # normal station mode (connects to home network)
+    ap_wifi: WifiInfo | None  # access-point mode (direct device provisioning)
+    p2p_wifi: WifiInfo | None  # peer-to-peer / Wi-Fi Direct (usually empty)
+    software_update_info_id: str | None = None
+    firmware_update_info_id: str | None = None
+
+    @classmethod
+    def from_proto(cls, proto: object) -> QuiltSmartModule:
+        """Construct from a protobuf QuiltSmartModule message."""
+        c = proto.controls  # type: ignore[attr-defined]
+        s = proto.state  # type: ignore[attr-defined]
+
+        sensors: QsmSensors | None = None
+        if s.updated_ts:
+            sensors = QsmSensors(
+                phase_detected_raw=s.phase_detected_raw,
+                target_detected_raw=s.target_detected_raw,
+                als_illuminance_raw=s.als_illuminance_raw,
+                als_ir_raw=s.als_ir_raw,
+                als_both_raw=s.als_both_raw,
+                accel_x_raw=s.accel_x_raw,
+                accel_y_raw=s.accel_y_raw,
+                accel_z_raw=s.accel_z_raw,
+            )
+
+        def _wifi(w: object) -> WifiInfo | None:
+            info = WifiInfo.from_proto(w)
+            return info if info.connected else None
+
+        return cls(
+            id=proto.header.object_id,  # type: ignore[attr-defined]
+            system_id=proto.header.system_id,  # type: ignore[attr-defined]
+            led_color_code=c.led_color_code,
+            sensors=sensors,
+            hosted_wifi=_wifi(proto.hosted_wifi_state),  # type: ignore[attr-defined]
+            ap_wifi=_wifi(proto.ap_wifi_state),  # type: ignore[attr-defined]
+            p2p_wifi=_wifi(proto.p2p_wifi_state),  # type: ignore[attr-defined]
+            software_update_info_id=(
+                proto.relationships.software_update_info_id or None  # type: ignore[attr-defined]
+            ),
+            firmware_update_info_id=(
+                proto.relationships.firmware_update_info_id or None  # type: ignore[attr-defined]
+            ),
+        )

quilt_hp/models/schedule.py

@@ -0,0 +1,98 @@
+"""Schedule models — week programs, day programs, schedule events."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+_WEEKDAY_NAMES = {
+    0: "?",
+    1: "Mon",
+    2: "Tue",
+    3: "Wed",
+    4: "Thu",
+    5: "Fri",
+    6: "Sat",
+    7: "Sun",
+}
+
+
+@dataclass(slots=True)
+class ScheduleEvent:
+    """A single time event within a schedule day."""
+
+    start_s: int  # seconds from midnight
+    comfort_setting_id: str
+    hvac_mode: int
+    heating_setpoint_c: float
+    cooling_setpoint_c: float
+    precondition: bool
+
+    @property
+    def start_time(self) -> str:
+        """Format start_s as HH:MM."""
+        return f"{self.start_s // 3600:02d}:{(self.start_s % 3600) // 60:02d}"
+
+
+@dataclass(slots=True)
+class ScheduleDay:
+    """A named day program with time events."""
+
+    id: str
+    name: str
+    space_id: str
+    events: list[ScheduleEvent]
+
+    @classmethod
+    def from_proto(cls, proto: object) -> ScheduleDay:
+        """Construct from a protobuf ScheduleDay message."""
+        events = [
+            ScheduleEvent(
+                start_s=ev.start_s,
+                comfort_setting_id=ev.comfort_setting_id,
+                hvac_mode=ev.hvac_mode,
+                heating_setpoint_c=ev.heating_temperature_setpoint_c,
+                cooling_setpoint_c=ev.cooling_temperature_setpoint_c,
+                precondition=ev.precondition,
+            )
+            for ev in sorted(proto.events, key=lambda e: e.start_s)  # type: ignore[attr-defined]
+        ]
+        return cls(
+            id=proto.header.object_id,  # type: ignore[attr-defined]
+            name=proto.attributes.name,  # type: ignore[attr-defined]
+            space_id=proto.relationships.space_id,  # type: ignore[attr-defined]
+            events=events,
+        )
+
+
+@dataclass(slots=True)
+class ScheduleWeekDay:
+    """A single weekday→day-program mapping."""
+
+    weekday: int
+    day_id: str
+
+    @property
+    def weekday_name(self) -> str:
+        return _WEEKDAY_NAMES.get(self.weekday, str(self.weekday))
+
+
+@dataclass(slots=True)
+class ScheduleWeek:
+    """A weekly schedule for a space, mapping weekdays to day programs."""
+
+    id: str
+    space_id: str
+    days: list[ScheduleWeekDay]
+
+    @classmethod
+    def from_proto(cls, proto: object) -> ScheduleWeek:
+        """Construct from a protobuf ScheduleWeek message."""
+        days = [
+            ScheduleWeekDay(weekday=wd.weekday, day_id=wd.day_id)
+            for wd in sorted(proto.days, key=lambda x: x.weekday)  # type: ignore[attr-defined]
+        ]
+        return cls(
+            id=proto.header.object_id,  # type: ignore[attr-defined]
+            space_id=proto.relationships.space_id,  # type: ignore[attr-defined]
+            days=days,
+        )