Help and user guide
Finding your way around
- Home: whether everything is all right, how far learning has got, and each room now.
- Forecast: the next day's weather, sunlight and modelled heat need. Open-Meteo can supply weather without solar panels or weather sensors.
- Plan: what Warmcast would do in each half hour, and why.
- Rooms: each room against the comfort range you set for it.
- Insights: what Warmcast has learned, every reading it takes, and the charts.
- The cog at the top opens Settings, and the question mark opens this guide.
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, add expected use times, mixed litres and days. Litres mean water at your configured mixed outlet temperature. These are your estimates, not learned usage. Save and restart applies them. A tank plan also needs fresh tank and ambient readings, capacity, paired limits, 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. Current manufacturer and hygiene cycles are outside this scenario and continue independently.
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 remain unknown until the view can establish meter units and counter provenance.
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.
- App & house: what heats your home, your location, the heating-off periods already set, the outdoor temperature sensor and the list of rooms, where you add or remove a room.
- Rooms: one section per room, with its name, heating type, comfort range, the two sun settings and its own sensors. Every room needs a thermostat sensor. Tick Has a floor sensor or Has door or window sensors to choose those; a room can have several door or window sensors. Unticking a box tells you which sensor will no longer be logged. A room whose heating ceiling your install already logs shows it under the room's sensors. The ceiling is the setpoint your Home Assistant automation sets, which tells the room when to stop taking heat.
- Hot water: the hot water valve, the immersion heater's electricity, and any other hot water readings your install already logs, such as the tank temperature and setpoint.
- Energy: optional heat-pump electricity and solar-panel meters, live weather readings, the tariff name, and (where available) the Octopus or EDF UK current-day and next-day rate-event entities. The PV meter is only for homes with panels; it is not needed for a sunlight forecast. Heat-pump electricity usually comes from an integration energy sensor in kWh; solar generation comes from your inverter's cumulative energy sensor. Cloud, wind and irradiance sensors come from a weather station or weather integration and can be left blank.
- Heat pump: heat output, heating mode, and the readings your heat pump gives about how it is running, such as the leaving and return water temperatures, flow rate, compressor speed, defrost, the leaving water setpoint and offset, and its own mode.
- Other sensors: any reading that fits none of the tabs above. This tab appears only when there is one.
- Save: what you have changed on each tab.
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 hanging time and drying duration for a typical, well-spun cotton load. It uses weather only, stops a drying window at forecast rain and shows a broad heuristic range; it 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.
- The first chart has one line per room, plus a dashed line for the outdoor temperature. Rooms with underfloor heating warm slowly and keep warming for a while after the heat pump stops. Rooms with radiators respond faster.
- The second chart is the heat pump's heat output in kilowatts. The sensor measures all the heat the heat pump makes. When the hot water valve reading is available, heat for the hot water tank is shown as its own line, apart from space heating. Older readings, from before the valve was logged, cannot be split, so they show as a dashed line labelled total heat, hot water not separated.
- Heat can read low, or below zero, for a few minutes at a time. This happens during defrost, when the heat pump briefly reverses to clear ice from the outdoor unit, and it is expected. If a defrost reading is bound, those times are shaded light grey on the heat chart.
- A gap in a line means there was no reading then, for example because a sensor was unavailable. Warmcast never fills a gap with a made-up number.
- Hover over or tap a chart to see the exact readings at that time.
If something looks wrong
- Home says “Warmcast has stopped logging”. Check that Home Assistant is running, then open the app's log in Home Assistant for the reason.
- A reading shows “Missing” on Home or under Insights, System. The entity had no reading at the last sample. Check the entity in Home Assistant, and check which entity is chosen for it on the Settings page.
- The charts are empty. There are no readings from the last 24 hours yet. The charts need no internet access: the chart library comes with the app.
Hot-water estimates
Forecast shows the tank's current temperature and estimates of usable mixed water, thermal energy to the configured maximum 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.