🚀 Installation Guide

Contents

Requirements

Before installing, make sure you have:

  • Home Assistant 2023.12 or later
  • A Nordpool (or compatible) electricity price source with today / raw_today and tomorrow / raw_tomorrow price lists
  • An indoor temperature sensor
  • An outdoor temperature sensor
  • (Optional) A weather entity — required for forecast-based preheat and precool
  • (Optional) An Ohmigo WiFi controller for direct hardware push

New Installation

Step 1 — Install from HACS

Open HACS in your Home Assistant sidebar. Go to Integrations. Search for PumpSteer. Select PumpSteer and click Download.

PumpSteer is available directly in HACS. You no longer need to add it as a custom repository.

Step 2 — Restart Home Assistant

A full restart is required after installing a new custom integration.

Step 3 — Add the integration

Go to Settings → Devices & Services → Add Integration. Search for PumpSteer and select it. Fill in the required entities:

Field Description
Indoor temperature sensor Your indoor thermometer sensor
Outdoor temperature sensor The real outdoor temperature
Electricity price sensor Today’s price list (e.g. Nordpool)
Tomorrow price sensor Tomorrow’s price list
Weather entity (optional) Used for forecast-based preheat

Step 4 — Verify

After setup, check that:

  • sensor.pumpsteer is active and shows a temperature value
  • The status attribute reads ok
  • The mode attribute changes sensibly over time (normal → braking → normal)
  • The price_category attribute reflects current electricity prices

It can take a few minutes after HA startup before all entities report valid states. PumpSteer falls back to safe mode (passing through real outdoor temp) until all required sensors are available.

Manual Installation

If you prefer not to use HACS:

  1. Download the latest release from GitHub.
  2. Extract and copy the custom_components/pumpsteer/ folder to your HA config/custom_components/ directory.
  3. Restart Home Assistant.
  4. Continue from Step 3 above.

Upgrade from 2.1.x → 2.2.x

No migration is required. Existing PumpSteer 2.1.x configurations continue to work.

Important changes in 2.2.x:

  • ThermalOutlook now actively gates/scales preheat when available
  • preheat may use bounded saving-level headroom above target and tapers at the ceiling
  • pre-brake and active braking share the same comfort-floor protection
  • short price dips use bounded brake_hold behavior
  • DST price-slot indexing is hardened
  • ThermalModel fitting runs after completed brake phases with enough valid samples; it remains diagnostic
  • optional Ohmigo Relay Guard can recover a configured Active/Bypass relay
  • braking notifications can expose the exact current price used by the decision

The Relay Guard is opt-in and is created only when an Ohmigo Active/Bypass relay is configured. It starts off on first creation.

Upgrade from 2.0.x → 2.1.x

No migration required. Existing setups continue working without changes.

New in 2.1.x:

  • sensor.pumpsteer_thermal_outlook is automatically registered
  • switch.pumpsteer_preheat_boost replaces the options-flow toggle (your saved value is preserved via RestoreEntity)

Upgrade from 1.x → 2.x

PumpSteer 2.0 is a complete rewrite. Treat this as a new integration, not an update.

Breaking changes

What changed Action required
Price categories Old categories (very_cheap, extreme) are gone. New: cheap, normal, expensive
Entity IDs All entities have been renamed — update dashboards and automations
ML features Removed entirely
Options flow Rebuilt — reconfigure after upgrade
  1. Note your current settings (target temp, aggressiveness, etc.)
  2. Remove the old PumpSteer integration
  3. Install 2.x fresh via HACS
  4. Reconfigure with your saved settings
  5. Observe for 24–48 hours before migrating dashboards and automations

What PumpSteer creates

After setup, PumpSteer registers the following entities:

Sensors

| Entity | Description | |—|—| | sensor.pumpsteer | The fake outdoor temperature plus control diagnostics such as mode, current price, brake factor and ThermalModel state | | sensor.pumpsteer_thermal_outlook | Forecast analysis (preheat worthwhile, trend, etc.) |

Number sliders

| Entity | Description | Default | |—|—|—| | number.pumpsteer_target_temperature | Desired indoor temperature | 21 °C | | number.pumpsteer_summer_mode_threshold | Outdoor temp at which summer mode activates | 17 °C | | number.pumpsteer_saving_level | Aggressiveness 0–5 | 3 | | number.pumpsteer_brake_ramp_time | Ramp duration (house inertia) | 2.0 |

Switches

| Entity | Description | Default | |—|—|—| | switch.pumpsteer_preheat_boost | Enable/disable preheat boost | On | | switch.pumpsteer_notifications | Enable/disable price notifications | On | | switch.pumpsteer_holiday_mode | Enable holiday mode (16 °C target) | Off | | switch.pumpsteer_ohmigo_push | Enable/disable Ohmigo push | On | | switch.pumpsteer_ohmigo_relay_guard | Optional Active/Bypass relay recovery guard; created only when a relay is configured | Off on first creation |

Datetime helpers

| Entity | Description | |—|—| | datetime.pumpsteer_holiday_start | Holiday start time (auto-activates holiday mode) | | datetime.pumpsteer_holiday_end | Holiday end time (auto-deactivates holiday mode) |