Help and user guide

Finding your way around

Warmcast takes its colours from your Home Assistant theme, so it changes when your theme does.

What Warmcast does

Warmcast learns how your home gains and loses heat: how fast each room cools, how much heat the floors and walls hold, and how much the sun warms each room. Its Shadow planner uses a validated model to share half-hour slots between room heating and expected hot-water use. It checks stored warmth and forecast sunlight before adding heat. Cost and electricity estimates need relevant measured efficiency and complete prices.

Comfort always comes first. Your own thermostats and automations stay in charge and keep the house warm if Warmcast stops.

What this version does

It reads your sensors and keeps local records. Every minute it adds one row to its own reading log. Each night at 22:00 it tries to learn a model of your house from that log. Home shows whether the log is being written, and Insights shows what the last nightly refit said.

Forecast and tariff estimates are read-only. They do not change your heating controls.

Heating mode is what your heat pump is set to, for example Night Only or Continuous. Warmcast only reads it. It does not change it.

The common Shadow plan

Plan shows the next 24 hours in half-hour slots, or the last 48 complete hours of observations. The heat pump serves rooms or the tank in each planned slot. Times use your house time zone, with UTC offsets for clock changes. The Forecast overnight card reads this same plan.

In Settings → Hot water, you can add expected use times, mixed litres and days. Litres mean water at your configured mixed outlet temperature. These estimates take priority. If you leave them blank, Warmcast can learn recurring tank-heating finish times and temperatures from at least three complete, consistent valve-on runs spanning 14 days. The evidence must include tank temperature and heat, with other heat sources known off. It is an inferred pattern, not proof of the heat pump's configured schedule or household demand. Save and restart applies entered uses. A tank plan also needs fresh tank and ambient readings, capacity, a lower tank planning limit and a fresh controller setpoint, cold/outlet temperatures, standing loss, measured tank heat rate and auxiliary heat known off. Missing tank inputs leave a conditional room-only scenario.

Combined planning currently minimises thermal heat. Tank efficiency has not been learned, so it cannot give whole-plan electricity or cost. Space-heating COP is not a tank COP. Existing manufacturer and hygiene controls continue independently. A learned reservation may reflect one of those cycles, but Warmcast cannot identify its purpose or change it.

Actuals compare only a saved plan issued before a half-hour began. Shadow mode never executes that plan, so differences are prediction checks, not realised savings. Gaps stay blank. Room temperatures are endpoint readings. Electricity actuals use the configured heat-pump cumulative kWh sensor; gaps, counter resets and incomplete half-hours stay unknown.

Comfort feedback and the heating curve

Use Too cold, Just right or Too warm on Home or Rooms to record how a room feels. A report saves the readings available at that time. It changes no settings. You can add a note, correct the time or undo the report. Quiet hours mean no discomfort reported.

Open Insights → Heating curve to record the settings shown on your controller. Temperature settings use whole degrees in your selected display unit (°C or °F). Choose the rooms each circuit serves, and confirm whether the main heat-pump readings apply to that circuit. A separate or mixed circuit without readings stays unconnected. Native slope values can be recorded, but manufacturer conventions differ, so Warmcast does not invent a curve line from them.

The graph separates your recorded baseline, measured flow, reported target and any calculated target with its temporary offset. Missing readings stay unknown. The journal retains earlier curve versions and corrected reports. This version records manual changes only.

A cold report can prompt investigation of heating timing, a room fault or moisture. High humidity alone does not establish the cause. You can record a drying trial and follow-up observations without starting a device. A dehumidifier can warm the room; AC dry mode can cool it. Record the actual start and stop in the journal. Only confirmed running periods are left out of nightly fitting; their readings stay intact. A planned duration never implies the device stopped. The trial compares temperature and absolute humidity as well as RH. A lower RH caused by warming alone does not establish moisture removal.

Numeric curve corrections and integration writes need further validation. The curve page explains its evidence limits. Feedback and curve records are stored separately from your readings, so using them does not reset learning or change the CSV layout.

What shadow mode means

Shadow mode means Warmcast works out what it would do but does not act on it. You can watch what it would have done and compare it with what happened, with no risk to your comfort. Warmcast always starts in shadow mode. It only acts once you switch it to Autonomous yourself. In between sits Recommendations, where Warmcast shows the settings it would choose and you copy across the ones you want.

Until its model passes Gate 2, Warmcast has no tested model to work out what it would do, so for now it reads your sensors and learns. Passing Gate 2 does not switch anything on: it then starts working out what it would do, still without acting on it.

Gate 1 and Gate 2

Warmcast moves forward only when it has passed a check, called a gate, so it never plans with a model that has not been tested.

Gate 1: enough data

At least 14 days with the heating on, including 3 cold-weather samples and 3 sunny days, with every sensor recording. Until then the nightly refit may say there is not enough data yet. That is normal.

Home counts the days received so far under "Learning your home". A day counts only once it has ended and at least 80% of its readings were logged with the outdoor temperature, the heat output and every room's temperature. A heating-on day is one with no part in a heating-off period from house.toml. Learning also needs 7 days to learn from and 3 more to test what it learned. Cold and sunny days are not counted until what counts as a sunny day has been set. Cold-weather samples are the 3 coldest eligible heating-on days with a daily mean below 8 °C (46.4 °F). Warmcast also shows how many reached 5 °C (41 °F) or below. Predictions colder than the coldest sample remain unvalidated; rare cold weather does not block the model from progressing.

Plan's Last 48 hours view shows observed history as soon as readings exist. Missing periods stay unknown. A live scenario needs the current model's Gate 2 pass and usable current inputs; it is not promised for the next day. Existing history is retained when optional inputs change.

Gate 2: accurate forecasts

For a week, the model forecasts the warmest part of each day in every room to within about 0.5 °C (0.9 °F). The forecast is made the evening before, so it is a fair test. Once Gate 2 is passed, shadow-mode forecasts and plans appear on the Home, Forecast and Plan screens.

Your home's location

Warmcast needs your home's latitude and longitude to work out where the sun is, so it can tell morning sun from afternoon sun. Enter them on the App & house tab of the Settings page, or put them in house.toml as latitude and longitude; the app will not start without them. Find your home's latitude and longitude at https://www.itilog.com/ (search for your address, then copy the two numbers shown). West and south are negative.

The Settings page

The Settings page has these tabs.

Choosing sensors

Each reading shows the sensor behind it: its name in Home Assistant in bold, then its entity id. Choose Change to search your own entities for another one; the list shows only entities of the right kind. Picking one puts it in place of the old one and says it is not saved yet. Undo puts the earlier sensor back. An optional reading also has Clear, for when you have no such sensor.

Saving

Your changes on every tab are kept while you move between tabs. Nothing is saved until you choose Save, at the bottom of the page. Weather and tariff choices save straight away; house and sensor settings save together. If a house or sensor setting is wrong, those settings are left as they were and the message at the top says what to fix and which tab it is on. A room's sensors are saved with the room, so a box ticked without a sensor chosen is refused. House and sensor changes apply when you restart Warmcast. Weather and tariff choices take effect as soon as you save them.

Weather and solar forecasts

Choose Open-Meteo in Settings → App → Weather forecast and save. Warmcast uses the latitude and longitude on the House tab to request hourly outdoor temperature, humidity, wind, sunlight and rain. It sends no room readings or history. A PV meter measures the electricity your panels actually make; it is optional and is not needed to forecast sunlight. Cloud cover, wind and irradiance sensors on Energy are optional live readings for future model improvements, not prerequisites for the Open-Meteo forecast.

The tariff connector supports Octopus Energy and EDF Energy UK's current-day and next-day rate-event entities. Select both in Settings → Energy. Their entity names include current_day_rates and next_day_rates. Costs appear only when their prices cover the forecast and, for heat pumps, Warmcast has enough measured efficiency data. Any result is a Shadow estimate, not a control plan or a bill forecast.

The Forecast screen's Outdoor laundry card estimates a good time to hang a typical, well-spun cotton load, its drying duration and how long the dry weather window lasts. If the window is too short, it shows how long the window lasts, how long the load may need and says Not enough time. It uses weather only and stops a drying window at forecast rain. This broad heuristic is not calibrated to your clothes or washing machine. The separate Indoor moisture outlook compares outdoor air with room humidity to help with ventilation. Full indoor, dehumidifier and tumble-dryer advice is still planned.

Set an optional Maximum heating output in Settings → Energy, in thermal kW rather than electrical input. Use a conservative figure from your installer or equipment data. House settings apply after restarting Warmcast. Forecast checks the proposed heat profile against expected weather, 2 °C (3.6 °F) colder with half the sunlight, and 2 °C (3.6 °F) warmer with 1.5 times the sunlight. It includes the model error band and withholds tariff shifting if a room leaves its comfort range. These are sensitivity checks, not probabilities. Tank minimum and maximum on Hot water bound the tank scenario; they change no tank settings or hygiene cycle.

Insights → House shows completed forecast checks and their reading coverage, even when weather forecasts are switched off. Weather error and room replay error describe different things.

Warmcast also records a steady-heating baseline: continuous space heat without using the sunlight forecast, compared with its solar-aware tariff estimate. Cost differences stay hidden until Gate 2 passes. The comparison is an estimate, not a replay of your old thermostat schedule; it excludes hot water and fixed charges.

How to read the charts

The Charts section of Insights shows the last 24 hours of readings from the log. Every time on the dashboard is in the house time zone from your house settings (Europe/London unless you changed it), not the time zone of the device you are using, so the times match your heating.

If something looks wrong

Hot-water estimates

Forecast shows the tank's current temperature and estimates of usable mixed water, thermal energy to the current hot-water setpoint and the shortest charging time supported by measured output. These describe the tank now; they are not daily energy totals.

Choose the tank readings and calculation inputs in Settings → Hot water. Cold-supply and outlet temperatures are needed for usable litres. Charging time needs measured tank-side heat; unknown auxiliary heaters, defrost and gaps are excluded. Standing loss also needs measured air temperature beside the tank and evidence that no hot water was drawn. A quiet temperature trace alone does not establish that.

Insights → System shows the fit evidence and a twelve-hour cooling scenario with no heating or water use. It holds ambient temperature steady. One probe only approximates the average temperature of the water; no household usage pattern is assumed. Missing readings leave dependent estimates unavailable while other learning carries on. Hygiene cycles stay unchanged.

In Settings → Hot water, choose Immersion electrical power from the tank heater's meter channel. Both W and kW are accepted. Above the activity threshold (10 W by default) the immersion is Active; at or below it, Idle within that threshold. Unknown and stale readings stay Unknown. The power input identifies immersion activity separately from heat-pump heat output. Keep the cumulative electricity meter selected too if you have one.

Temperature display and colours

Settings → App offers Celsius, Fahrenheit or Auto. Auto follows Home Assistant and falls back to Celsius when opened on its own. Absolute temperatures convert with the freezing-point offset: 20 °C is 68 °F. Temperature changes and error bands scale only: a rise of 1 °C is a rise of 1.8 °F. A heat-loss figure of 1.8 W per °C is 1 W per °F.

The display choice does not set sensor source units. Home Assistant metadata supplies those; legacy readings without units use Celsius, and offline imports can declare source units. Saved history stays in Celsius. Outdoor and tank colour thresholds are display preferences; room colours follow the comfort ranges in Rooms settings.