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. Later it will use that to plan your heat pump's heating ahead in half-hour slots. It will store heat in the house and the hot water tank when energy is cheapest or the heat pump runs most efficiently, and hold back before a sunny day so rooms do not overheat.

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 only reads. Every minute it reads the sensors you listed and 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.

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. Warmcast also shows how many reached 5 °C or below. Predictions colder than the coldest sample remain unvalidated; rare cold weather does not block the model from progressing.

Before the plan and history are available, Warmcast will show them the next day, based on the readings logged so far. It will be refined as more readings are captured.

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. 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 and sunlight. 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 first tariff connector uses Octopus Energy'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 Warmcast has enough measured efficiency data. Any result is a Shadow estimate, not a control plan or a bill forecast.

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