Building Context-Aware Heating Automation: From Rule-Based to fully Autonomous LLM Control using AI assisted design

Share your Projects!
, , ,
3

The Blueprint (and the AI “Save File”)

Below is the full project specification I developed before writing any code. I didn’t just want to hack away at YAML; I wanted a robust logic model. I worked with an AI to “interview” me about my home’s setup, heating setup, and lifestyle, resulting in this document.

Crucially, this document serves a dual purpose:

  1. For a HA forum reader: It’s the design documentation and logic guide.
  2. For the AI: It acts as the “Context Prompt.” Since AI chat windows have limited memory, I can feed this entire block back into a fresh AI session to instantly restore the project’s “state.” It ensures the AI never forgets that my North Office needs wind protection or that my boiler has a specific dead-head risk, even 6 months from now. And we all know that sinking feeling when you find out that you are out of prompts or please start a new conversation.

It is essentially the “System Constitution” that keeps the project consistent across different coding sessions. Or even different AI’s.

The key thing is that the AI wrote the doc below, as this is the information the AI needs – and that was my starting point. If I start a new prompt, what do you Mr AI need to know to carry on. Write it to your needs.

Section 1: System Topology & Environmental Context

1.1 Physical Layout & Environmental Physics

  • Construction: New build, full concrete construction. High thermal mass, high insulation.
  • Zone A: Ground Floor (The “Greenhouse”)
    • Room: Open plan Lounge/Kitchen.
    • Orientation: South (Wall-to-wall glass).
    • Physics: Dominant Solar Gain (Risk of overshoot) + High Inertia (Slow cool down).
  • Zone B: 2nd Floor (The Mixed Zone)
    • Office: North Facing. Susceptible to wind chill and lower ambient light. requires higher heat input during storms.
    • Bedroom: South-West Facing. Subject to afternoon solar gain, though currently mitigated by privacy blinds.
    • Physics: Standard Radiator heating (Low Inertia).
  • 3rd Floor: Unheated Attic (Boiler location).

1.2 Hydraulic Topology (The Boiler)

  • Unit: Intergas HRE Combi Boiler.
  • Configuration: Single Flame, Dual Trigger.
    • Trigger 1 (OpenTherm): Modulating demand from Plugwise Adam.
    • Trigger 2 (On/Off): Binary demand from Tuya Relay (Wired to boiler ‘On/Off’ terminals).
  • The “Software Bypass” Constraint:
    • There is no physical bypass valve or always-open radiator on the 2nd floor.
    • Critical Safety Logic: The automation MUST ensure specific TRVs are fully open before engaging the Tuya Relay to prevent “dead-heading” the pump. (Current “holding” automation handles this, but final logic must enforce a “Valve Travel Time” delay).

1.3 Control Architecture

Zone A: Ground Floor (OpenTherm)

  • Controller: Plugwise Adam (Zigbee).
  • Sensing: Honeywell Round (Wired to Adam) + Lounge PIR.
  • Logic: Adam manages the OpenTherm modulation curve based on the setpoint sent from HA.

Zone B: 2nd Floor (Binary Relay)

  • Controller: Home Assistant (Virtual Brain).
  • Actuation:
    • Boiler Trigger: Tuya Thermostat (configured as a dumb relay).
    • Room Valves: Sonoff/Moes Zigbee TRVs.
  • Sensing:
    • Digital Thermometers (Sonoff/Tuya) in every room.
    • Feedback Loop: Plugwise Adam acts as a “System Monitor.” It detects Flame State: On even when Intended boiler temperature is 0.0, confirming that Zone B (or Hot Water) is active.

1.3.1 Inter-Zonal Thermal Coupling (The “Heat Rise” Effect)

The Physics: The zones are not hermetically sealed. In a modern, insulated home, heat transfer occurs vertically from Zone A (Ground) to Zone B (Upstairs) via:

  1. Conduction: Through the concrete ceiling/floor slab.
  2. Convection: Warm air rising through the open stairwell (Stack Effect).

The Logic Implication:

  • The “Parasitic Gain” Factor: The System must recognize that high demand in Zone A acts as a “Base Load” heater for Zone B.
  • Optimization: If Zone A is Active and > 20°C, Zone B radiators can potentially reduce their output (or delay their start time) because the room will naturally drift upwards.
  • Modeling: The AI must learn that Bedroom_Temp_Rise is correlated with Lounge_Temp.
    • Equation: Bedroom_Target_Power = Calculated_Load - (Lounge_Temp * Coupling_Coefficient).

1.4 Device Registry (Baseline)

Floor Room Device Type Function Critical Note
Ground Lounge Plugwise Adam Boiler Master Monitors total system state (Flame/Temps)
Ground Lounge Honeywell Round Interface Dumb dial, feeds data to Adam
2nd Hallway Tuya Thermostat Boiler Relay “Dummy” thermostat. High setpoint used to force relay closure.
2nd Office Sonoff TRV Actuator North Facing (Wind logic required)
2nd Bedroom Sonoff TRV Actuator South-West Facing (Solar logic required)
2nd Bathroom Moes TRV Actuator Priority zone for morning/evening

Section 1.5: Zigbee Sensor Configuration Standard

To ensure the logic layer receives granular data for predictive control, all Digital Thermometers (Sonoff SNZB-02D) are flashed/configured with the following Reporting Configuration:

Temperature (msTemperatureMeasurement)

  • Min Interval: 10 seconds (Throttle cap).
  • Max Interval: 300 seconds (Heartbeat every 5 mins if stable).
  • Min Change: 5 (0.05°C).
  • Impact: High-frequency updates allow for “Rate of Change” calculation, enabling predictive shut-off (coasting to target).

Humidity (msRelativeHumidity)

  • Min Interval: 30 seconds.
  • Max Interval: 900 seconds (15 mins).
  • Min Change: 100 (1%).
  • Impact: Sufficient for bathroom fan automation and dampness monitoring without excessive battery drain.

Section 1.6: Environmental Logic (The Haarlem Factor)

The automation logic moves beyond simple “Outdoor Temperature” to calculate a dynamic “Heat Loss Score” based on the specific coastal micro-climate of Haarlem.

Data Source Strategy:

  • Primary Source (The Truth): KNMI Integration.
    • Used for: Current Wind Speed (Safety), Gusts, Humidity (Dampness), and Official Weather Alarms (Code Yellow/Red).
    • Rationale: Direct feed from local Schiphol/IJmuiden stations ensures accurate “Wind Chill” calculation for the North-facing office.
  • Secondary Source (The Forecast): Met.no (Default).
    • Used for: Hourly forecasts (Solar prediction) if KNMI data is blocky or less granular for “Cloud Cover %”.
Factor Logic Source Action
Wind sensor.knmi_wind_speed If > 20km/h, boost Flow Temp.
Solar weather.knmi (Forecast) If “Sunny” predicted, block morning UFH run.
Alarm binary_sensor.knmi_alarm If “Code Red/Orange” (Storm), force pre-heat House to build buffer before power/grid risk.
Factor Environmental Reality Automation Logic Impact
Wind Chill Dominant Factor. Strong North Sea winds (often 20km/h+) strike the building envelope. Wind Compensation: If Wind Speed > 20km/h, the “Target Flow Temperature” for the UFH is boosted +2°C to counteract stripping of heat from walls. North Office Priority: The North-facing office TRV opens earlier during storms.
Solar Gain High efficiency glazing creates a “Greenhouse Effect” in the South-facing Lounge and SW Bedroom. Solar Blocking: If Forecast = Sunny AND Season = Spring/Autumn, heating is suppressed in Zone A (Ground) from 08:00 to avoid overshoot. The sun is trusted to bridge the gap.
Humidity/Rain Coastal dampness. High humidity (80%+) increases the specific heat capacity of the air, making it harder to heat. Comfort Boost: If Humidity > 85%, the target indoor temperature is virtually boosted by +0.5°C to combat the “damp cold” feeling.
Thermal Inertia Concrete construction retains heat (and cold) for hours. Predictive Coasting: The boiler cuts off before the target is reached (using the 0.05°C sensor reporting rate), allowing the concrete thermal mass to release stored energy and “land” on the target temp without overshoot.

Section 1.7: Occupancy & Geofencing (Single Occupancy)

The system uses a Multi-Stage Presence Model based on the User’s distance from home. This eliminates the lag time of standard heating systems by predicting arrival.

Zone Definition Heating State Logic Description
Zone 1: Home Inside house + 700m radius (Supermarket). COMFORT System maintains active schedules. Short trips to the local shop (10-20 mins) do not trigger “Away” mode, preventing unnecessary boiler cycling.
Zone 2: Town Outside 700m but inside Haarlem limits. STANDBY Duration: ~1 hour.

System enters “Light Setback” (e.g., -1.0°C). UFH pump continues to circulate to prevent floor cooling, but boiler firing is minimized. Fast recovery possible upon return.|
|Zone 3: Commute|Amsterdam / Regional.|ECO|Duration: 8+ hours.

System enters “Deep Setback” (e.g., -3.0°C or 17°C floor).

Recovery: Logic monitors travel time. Heating ramps up when user crosses back into Zone 2 (Haarlem).|
|Zone 4: Global|International / Vacation.|FROST|Duration: 48h+.

System enters “Vacation Mode.”

  • UFH: Off (or min 15°C for structure protection).

  • Water: Hot water tank pre-heat disabled.

  • Exercise: Valves/Pumps cycle once every 24h to prevent seizing.|

Section 1.8: Data Strategy for AI (LLM) Transition

Objective: To generate a structured, semantic dataset that captures not just the state of the home, but the decision logic behind state changes. This dataset will serve as the “Training Manual” for future LLM control.

1.8.1 The “Chain of Thought” Logging Standard

Standard Home Assistant logs record events (Boiler turned on). This project will implement a parallel “Context Log” that records the logic stack (Boiler turned on BECAUSE Office is Occupied AND Temp < Target AND User is Home).

The Logging Schema: Every major automation action will append a JSON-structured entry to a local log file (/config/logs/heating_decisions.log) containing:

  1. Timestamp: ISO format.
  2. Global Context: [User_Zone: Home], [Season: Winter], [Solar_Mode: Active/Inactive].
  3. Environmental Snapshot: [Outside: 5°C], [Wind: 25km/h], [Wind_Chill_Factor: High].
  4. Trigger Source: [Entity: binary_sensor.office_pir], [State: Detected].
  5. The Decision: [Action: Heating_Zone_B_Boost], [Reason: Comfort_Priority].

1.8.2 Hierarchical Data Labeling

To ensure the LLM understands the physical relationships between devices, all entities and log entries will adhere to a strict semantic hierarchy:

  • Level 1 (System): House
  • Level 2 (Zone): Zone_A_Ground (OpenTherm) vs Zone_B_Upstairs (Relay).
  • Level 3 (Room): Room_Office, Room_Kitchen.
  • Level 4 (Device Function): _Sensor_Temp, _Actuator_TRV, _Input_PIR.

Example of “LLM-Ready” Naming:

  • Bad: sensor.sonoff_temp_2 (The LLM has to guess where this is).
  • Good: sensor.z2_office_temp (The LLM knows: Zone 2, Office, Temperature).

1.8.3 The Feedback Loop (Outcome Logging)

We will not just log the start of an event, but the result.

  • Event: “Heating turned on at 09:00.”
  • Outcome Log (1 hour later): “Heating ran for 45 mins. Temperature rose by 1.2°C. Efficiency Rating: High.”
  • Purpose: This allows the LLM to learn Thermal Inertia (e.g., “Last time I ran the boiler for 45 mins in these wind conditions, it was too much. Next time I will suggest 30 mins.”).

Technical Implementation Note (For later)

When we get to the coding phase, we will create a simple Notify Service in HA called notify.llm_logger. Inside every automation, we will add a final action:

YAML

action: notify.llm_logger

data:

message: “ACTION: Boiler_On | REASON: Office_Occupied | WIND: {{ states(‘sensor.wind_speed’) }}”

This builds your dataset automatically in the background while I sleep.

Section 1.9: Supportability, Diagnostics & “The Human Manual”

Objective: To ensure the system is maintainable, transparent, and fails safely. The user must be able to answer “Why is the heating on?” instantly, without digging into code.

1.9.1 The “Why” Dashboard (Human Readability)

We will not rely solely on YAML comments. The Home Assistant frontend will feature a dedicated “Logic Inspector” card that translates code decisions into plain English.

  • The “State of the Nation” Text Helper:
    • We will create a text entity input_text.heating_status_message.
    • Function: Every automation updates this text.
    • Example Value: “Heating Zone B (Office) because Occupancy Detected and Temp (18°C) < Target (21°C). Wind Compensation Active (+2°C).”
  • The “Manual” Tab:
    • A Markdown card in HA containing the “Theory of Operation” (a condensed version of this Build Log).
    • Purpose: If you (or a future owner) forget why the North Office heats up during a storm, the dashboard explains the “Haarlem Wind Logic” right there.

1.9.2 Watchdog Logic (Failure Notifications)

The system will self-monitor for physical and logical failures using “Watchdog Automations.” These trigger high-priority alerts to my phone.

Priority 1: Safety & Hardware Protection

  • Dead-Head Prevention: If binary_sensor.boiler_flame is ON for > 1 min BUT all valve_position < 10%.
    • Action: Emergency Stop (Turn off Tuya Relay/Adam) + Critical Notification (“PUMP RISK: Boiler firing against closed valves”).
  • Runaway Heating: If sensor.indoor_temp > 25°C.
    • Action: Force Kill All Heating + Notification.

Priority 2: Logic Drift (Intent vs. Reality)

  • The “Ghost Flame” Alert: If binary_sensor.boiler_flame is ON but heating_demand_global is OFF.
    • Meaning: The boiler is firing without permission (stuck relay? manual override?).
  • The “Cold Radiator” Alert: If Zone B Heating is ON for > 30 mins but temp_rate_of_change is < 0.1°C.
    • Meaning: The boiler is running, but the room isn’t getting hotter (Air lock? Valve stuck closed?).

1.9.3 Debugging Tools

To facilitate “Crawling before we Run,” we will create a Traceability View:

  • Graphing: A History Graph stacking Boiler State, Outdoor Wind, Target Temp, and Valve Position on one timeline. This allows visual correlation (“Ah, the boiler fired exactly when the wind gusted”).
  • Toggle Overrides: “Maintenance Mode” booleans for every zone.
    • Function: input_boolean.maintenance_mode_zone_b. If ON, all logic for Zone B is bypassed, allowing manual testing of the Tuya relay without the automation fighting back.

Section 1.10: Failure Modes & Disaster Recovery (DR)

Objective: To define the system’s behaviour when components fail, ensuring the home remains habitable and physically safe without manual code intervention.

1.10.1 The “Brain Death” Scenario (Home Assistant Offline)

Scenario: The server crashes, drive fails, or Home Assistant hangs.

  • Impact: The “Virtual Logic” (Zone B Aggregation, Weather Compensation, Schedule Management) ceases immediately.
  • Zone A (Ground) Behavior: Fail-Safe.
    • Plugwise Adam and Honeywell Round are physically wired and paired independently of HA.
    • Result: They revert to their internal schedule (stored on Adam) or manual control via the Honeywell dial. The ground floor remains heatable.
  • Zone B (Upstairs) Behavior: Fail-Static (Risk).
    • The Tuya Relay and Sonoff TRVs will remain in their last known state (e.g., if HA crashes while Heating is ON, the Relay stays ON).
    • Hydraulic Risk: If the Relay stays ON but TRVs satisfy their local temp and close, the pump may dead-head.
    • The DR Protocol (Manual Override):
      1. Boiler Control: The Tuya Wall Thermostat (Stairwell) is physically wired. The user must manually walk to the unit and adjust the setpoint (Set high to fire boiler, Set low to stop).
      2. Room Control: Sonoff TRVs have physical dials/buttons. The user manually sets the target temp on each radiator.
      3. Summary: The system degrades to a standard 1990s manual heating system.

1.10.2 The “Nervous System” Failure (Zigbee Network Down)

Scenario: The Zigbee Coordinator fails (stick failure) or severe interference blocks signals.

  • Impact: HA is running, but cannot see sensors or control valves.
  • Detection: HA “Watchdog” automation detects sensor.last_updated > 1 hour for critical nodes.
  • Automated Response:
    • Notification: Critical Alert sent to User Phone: “ZIGBEE DOWN - HEATING IN MANUAL MODE.”
    • Adam Isolation: HA stops sending “Setpoints” to Adam (to prevent sending zeros or errors). Adam reverts to internal logic.
  • Zone B Fallback:
    • If the Tuya Relay is Zigbee: It isolates. User must manually toggle the wall unit.
    • TRVs: Revert to the last setpoint received. They will act as standard non-smart thermostatic valves (maintain temp locally).

1.10.3 The “Blindness” Scenario (Internet/Cloud Outage)

Scenario: ISP failure or Weather API down.

  • Impact: Loss of “Haarlem Factor” data (Wind, Solar Forecast, Outside Temp).
  • Degraded Logic Mode:
    • The system detects weather.haarlem is unavailable.
    • Action: The “Calculated Target Temp” logic bypasses the specific environmental modifiers.
      • Wind Boost: Disabled (Default to 0).
      • Solar Block: Disabled (Default to heating allowed).
    • Result: House may slightly overheat (sunny day) or underheat (windy day), but basic thermal functionality is preserved.

1.10.4 The “Dead-Head” Hydraulic Safety Net

Scenario: Zone B logic fails, Tuya Relay is stuck “ON”, but all TRVs close because rooms are hot.

  • Hardware Protection: The Intergas HRE boiler has an internal bypass (or relies on the installed system bypass).
  • Software Watchdog (If Zigbee is alive):
    • Logic checks: If Tuya_Relay = ON AND All_TRVs_Position < 10%.
    • Action: Force Tuya_Relay OFF via HA.
    • Fail-safe: If Zigbee is dead, we rely on the Boiler’s internal pressure relief/bypass valve.

Section 1.11: Energy Telemetry & Efficiency Feedback (P1 Meter)

Hardware: SmartGateways.nl P1 WiFi Gateway. Integration: MQTT/API to Home Assistant. Economic Context:

  • Gas: Single flat rate (Month-fixed). Primary optimization target.
  • Electricity: Peak/Off-Peak tariffs exist but the differential is negligible for heating components (pumps/valves). Secondary monitoring only.
  • Water: NOT monitored by P1. Water usage must be inferred via Boiler State (DHW active status from Plugwise Adam).

1.11.1 The “Gas Watchdog” (Safety & Validation)

Since we lack a physical water flow sensor, we rely on the Boiler’s digital status (via Adam) to explain gas spikes.

  • The “Ghost Flame” Detection (Leak/Stuck Relay):
    • Trigger: IF Gas_Usage > 0 (sustained for > 1 min).
    • Check 1: Is Heating Demand Active? (Zone A or Zone B).
    • Check 2: Is Domestic Hot Water (DHW) Active? (Verified via binary_sensor.adam_dhw_state).
    • Logic: IF Gas > 0 AND Heating = OFF AND DHW = OFF.
    • Diagnosis: Gas is flowing, but the boiler claims it is idle.
    • Action: Critical Alert: “Unexplained Gas Usage! (Boiler reports Idle).” Indicates potential gas leak or a Stuck Relay forcing the boiler to fire unmonitored.
  • Validation of Firing (Ignition Check):
    • Logic: IF Heating_Demand is ON (Zone B Sprint) AND Gas_Usage_Rate == 0 (for > 15 mins).
    • Diagnosis: Boiler Fault (Lockout code?), Valve Closed, or Pilot light failure.
    • Action: Alert User: “Heating demanded but no Gas flow detected.”

1.11.2 The Efficiency Algorithm (Volume vs. Comfort)

Since the gas price is flat, the automation prioritizes Volume Efficiency (using the least fuel to achieve the result) rather than Time-of-Use cost.

  • Metric: We will create a derived sensor: “Thermal Efficiency Score.”
  • The Formula: (Gas_Consumed_m3) / (Indoor_Temp_Rise_Delta).
  • Application:
    • Benchmarking: The system tracks the “Gas Cost” of heating rooms under different weather conditions.
    • Optimization: Determines the most efficient strategy (e.g., Is it cheaper to maintain 19°C constant, or setback to 15°C and sprint to 21°C?).

1.11.3 Electrical Monitoring (Passive)

  • Role: Passive observation only.
  • Logic: The heating system components (Pumps/Valves/Adam) ignore Peak/Off-Peak status. Comfort and Freeze Protection always override electrical cost saving.
  • Dashboarding: Current electrical usage is displayed on the “Heating Dashboard” purely to provide context for total household load.

1.11.4 The Cost Function (LLM Training Data)

Objective: To transform raw P1 energy data into a “Performance Grade” for the automation logic. This allows future AI models to optimize for Gas Efficiency rather than just Temperature Accuracy.

  • The “Session Cost” Logic:
    • We will log “Gas Usage per Heating Event” rather than just usage over time.
    • Trigger Start: When a heating cycle starts → Record input_number.gas_meter_start_value.
    • Trigger End: When the heating cycle ends (Target Temp reached) → Calculate (Current_Gas - Start_Gas).
  • The Data Structure for LLM Ingestion:
    • The final log entry for any heating event will append the cost delta:

JSON

{

“Event”: “Heating_Cycle_Zone_B”,

“Duration_Minutes”: 45,

“Outdoor_Conditions”: “Windy, 5C”,

“Result”: “Target_Reached”,

“Cost_Gas_m3”: 0.35,

“Efficiency_Rating”: “Standard”

}

  • Impact: This enables the LLM to learn correlations such as: “High wind increases the gas cost of ‘Sprinting’ by 40%; prefer ‘Coasting’ strategy during storms.”

Section 1.12: Micro-Occupancy & Predictive Presence (PIR Logic)

Objective: To transition from “Whole House” heating to “Follow-Me” heating. The system must distinguish between Transient Motion (walking through) and Sustained Presence (working/relaxing) to target heat only where it is needed.

1.12.1 Hardware Topology

  • Lounge (Zone A): PIR Sensor (Zigbee) + MMWave (Future consideration for stationary detection).
  • Office (Zone B): PIR Sensor (Zigbee)
  • Bedroom (Zone B): PIR Sensor (Zigbee) + MMWave (Future consideration for stationary detection).
  • Bathroom (Zone B): No PIR – can infer from time and DWH, or just not bother.

1.12.2 The “Wasp in a Box” Logic (State Machine)

Raw PIR data is too twitchy (“Motion Detected” → “Clear”). We will implement a Room State Machine in Home Assistant for each zone:

  1. State: EMPTY
  • Trigger: No motion for 30 minutes.
  • Action: Set TRV to “Eco/Setback” (e.g., 18°C).
  1. State: TRANSIENT (Just Passing Through)
  • Trigger: PIR detects motion.
  • Action: Lighting activates (if dark). Heating holds at current state (do not boost yet).
  • Logic: Prevents the boiler firing just because you walked into the office to grab my phone.
  1. State: OCCUPIED (Sustained)
  • Trigger: Motion detected repeatedly within a 5-minute window OR Motion > 2 mins continuous.
  • Action: Set TRV to “Comfort” (e.g., 21°C).
  • Action: Log this “Start Time” for the LLM.

1.12.3 The Learning Layer (LLM Training Data)

This is where the AI becomes powerful. We do not want to program hard-coded schedules (“Heat Office Mon-Fri 9-5”). We want the AI to deduce the schedule.

Data Logging Strategy: We will record “Occupancy Sessions” to the training log:

JSON

{

“Room”: “Office”,

“Day”: “Tuesday”,

“Session_Start”: “08:55”,

“Session_End”: “17:30”,

“Breaks”: “3”,

“Context”: “Work_Day”

}

The Predictive Model:

  • Phase 1 (Logging): The system passively watches your movement for 2 weeks.
  • Phase 2 (Prediction):
    • The Logic observes: “On Mondays, the user enters the Office at 09:00 with 95% confidence.”
    • Action: The system automatically schedules a Pre-Heat event for the Office at 08:30 on Mondays.
  • Phase 3 (Anomaly Detection):
    • Scenario: It is Monday 09:30 and the Office is empty.
    • Action: The system assumes “Day Off” or “Sick Day” and cancels the heat for the rest of the day to save energy.

1.12.4 The “Follow-Me” Comfort Logic

  • Logic: If Room_State changes to OCCUPIED and Current_Temp < Target.
  • Action: Boost Mode.
    • The specific TRV opens 100%.
    • The Boiler fires (Zone B demand).
    • Note: This is reactive. The goal of Section 1.12.3 (Prediction) is to eliminate the need for this reactive boost by having the room ready before you enter.

1.12.5 The Negative Reinforcement Loop (The “I Felt Cold” Marker)

Objective: To explicitly log instances where the automation failed to provide comfort, serving as “Error Correction” data for the AI model.

  • The Logic: If the user physically touches a TRV or manually adjusts the dashboard, the Automation has failed.
  • Trigger: Any state change on climate.* where context.user_id is present (Human) AND new_temp != old_temp.
  • The Data Structure:
    • Event: Manual_Override
    • Type: Comfort_Failure (if temp increased) OR Efficiency_Failure (if temp decreased).
    • Delta: +2.0°C (The magnitude of the error).
    • Context: “Windy, Evening, Sedentary.”
  • Impact: This tells the AI: “Your prediction for this Tuesday evening was wrong by 2 degrees. Adjust the weightings for next week.”

Section 1.13: Implementation Strategy (The Phased Rollout)

Objective: To mitigate risk and ensure system stability by deploying logic in distinct, testable layers. The project will follow a “Crawl, Walk, Run” Software Development Lifecycle (SDLC).

Phase 1: The Foundation (Observability)

Focus: “The Eyes.” Standardization of inputs and creation of the Passive Dashboard.

  • Goal: To see the “Truth” of the home’s thermal state before attempting to control it.
  • Deliverables:
    • Entity Ingestion: Map all Zigbee/WiFi devices to standardized HA entities (e.g., sensor.z2_office_temp).
    • Calibration: Execute Action 1 (Sonoff vs. TRV offset).
    • Telemetry: Build the “Heating Dashboard” graphing Temperature, Valve Position, and Gas Usage.
  • Exit Criteria: System can accurately visualize the house’s behaviour over 24 hours without gaps.

Phase 2: The Safety Net (Risk Mitigation)

Focus: “The Shield.” Protecting hardware from logic errors.

  • Goal: To ensure that no matter what the future automation does, it cannot damage the Boiler or Pumps.
  • Deliverables:
    • Dead-Head Protection: Logic to kill the Relay if valves are closed.
    • Watchdogs: Alerts for Zigbee offline or Sensor timeout.
    • Gas Auditing: “Ghost Flame” detection (Gas flow vs. Boiler State).
  • Exit Criteria: Simulating a “Stuck Relay” or “Closed Valve” triggers an immediate Kill Switch and Critical Notification.

Phase 3: The “Dumb” Arbiter (Basic Control)

Focus: “The Muscle.” Connecting Inputs to Outputs.

  • Goal: To achieve reliable heating control equivalent to a standard thermostat (On/Off logic), establishing the hydraulic handshake between Zone A and Zone B.
  • Deliverables:
    • Zone B Logic: Simple “If Temp < Target then Fire” loop.
    • Conflict Resolution: Managing the Adam (Zone A) when Zone B sprints.
    • Manual Overrides: Working booleans to disable automation for maintenance.
  • Exit Criteria: The house heats reliably on demand. Zone B fires the boiler without overheating Zone A.

Phase 4: The “Haarlem Factor” (Weather Intelligence)

Focus: “The Brain.” Injecting environmental variables.

  • Goal: To move from “Reactive” to “Predictive.”
  • Deliverables:
    • Wind Logic: Linking KNMI data to Flow Temperature targets.
    • Solar Logic: Solar forecast blocking for Zone A.
    • Dampness Logic: Humidity compensation.
  • Exit Criteria: The system correctly identifies a “Storm Day” and pre-heats the North Office earlier than usual.

Phase 5: The “Ghost” (AI Logging & Prediction)

Focus: “The Future.” Learning User Habits.

  • Goal: To capture the data needed for LLM training and Micro-Occupancy tracking.
  • Deliverables:
    • PIR State Machines: “Wasp in a Box” logic (Transient vs. Occupied).
    • Context Logger: The JSON logging engine (Section 1.8).
    • Feedback Loop: Writing “Gas Cost” back to the logs.
  • Exit Criteria: A rich, structured dataset is being generated daily, ready for future AI ingestion.

Section 2.0: Logic Hardening & Safety Protocols (The “Gap Analysis” Patch)

Source: Post-Review Gap Analysis. Objective: To resolve race conditions, hydraulic lag, and sensor drift before they occur, ensuring resilience against partial hardware failure.

2.1 The “Zone Arbiter” (Conflict Resolution)

Problem: Zone B (Radiators) requesting “Sprint” heat while Zone A (UFH) is in “Low & Slow” modulation causes hydraulic conflict and efficiency loss. The Fix: The Permit Matrix

  • Rule 1 (The UFH Shield): IF Zone A is Active AND Flow_Temp < 35°C (Modulating), THEN Queue Zone B request.
    • Dashboard: Display status “Zone B: QUEUED (Awaiting UFH Cooldown).”
    • Retry: Re-evaluate queue every 3 minutes.
  • Rule 2 (The Anti-Short-Cycle): Global Timer input_number.boiler_min_off (5 mins).
    • Dashboard: Show countdown timer “Boiler Locked: 3:20 remaining.”

2.2 Valve Sequencing (Hydraulic Lag)

Problem: A relay clicks instantly (ms). A Valve takes 60 seconds to open. Firing the relay before the valve opens = Dead Head Pressure Spike. The Fix: The “Travel Certified” Sequence

  1. Trigger: Room requests heat.
  2. Action: Open TRV to 100%.
  3. Wait: Wait_Template until valve_position > 70% OR timeout > 60 seconds.
  4. Verification:
  • Success: If sum(valve_open_area) > 70% → Fire Relay.
  • Partial Success: If sum is 20-70% → Fire Relay, but Log Warning: “Partial flow check. Check valves: [List].”
  • Failure: If sum < 20% → ABORT & CRITICAL ALERT.

2.3 The “Three Belts” Dead-Head Protection

Problem: Relying on one check is risky. We need redundancy. The Fix:

  1. Belt 1 (Software): IF Relay=ON AND All_TRVs < 15% → KILL.
  2. Belt 2 (Thermal Plausibility - Delta T): IF Flow_Temp rises > 1°C/sec AND Return_Temp remains flat → KILL. (Indicates water is not circulating).
  3. Belt 3 (Watchdog): “Ghost Command” check. IF Relay=ON but Logic_Demand=OFF → KILL (Stuck automation).

2.4 Environmental Logic Refinements

  • Wind Step-Logic (with Hysteresis):
    • Levels: 0°C (Calm), +1°C (Breezy), +2°C (Storm).
    • Hysteresis: Wind speed must remain below threshold for >15 mins to drop a level (prevents toggling).
  • Solar Escape Hatch: If “Solar Block” is active but Room Temp drops > 1°C below target → Override & Fire.
    • Logging: Record event as “Forecast Error” to tune future solar trust levels.

2.5 Data Integrity & Drift

  • Calibration Check: Weekly automation to compare TRV_Temp vs Sonoff_Temp.
    • Action: If delta > 2.5°C → Quarantine the TRV (Exclude from logic) and Notify User.
  • Battery Budget: binary_sensor.room_ready. Logic: IF Battery > 10% AND Last_Seen < 60 mins.
  • Test Mode: Create a script.test_watchdogs to simulate a “Dead Head” event and verify the Kill Switch activates.