Qube heat pump

The Qube heat pump integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] allows you to monitor and control Qube heat pumps via the Modbus TCP protocol.

Use cases

• Monitor the heat pump’s temperatures, power, energy use, and coefficient of performance (COP), and add the electric consumption to the energy dashboard.
• Use surplus solar power: switch the smart grid ready mode to Plus or Max when your solar panels export to the grid, so the heat pump stores the energy as heat.
• Heat domestic hot water when electricity is cheap, by boosting the water heater during low dynamic tariff hours.
• Switch between summer and winter mode, or block the heat pump during peak hours, from automations instead of the heat pump’s panel.

Supported devices

The following devices are known to be supported by the integration:

• Qube heat pump

Unsupported devices

The following devices are not supported by the integration:

• Qbooster heat pump (the predecessor of the Qube heat pump)

Configuration

To add the Qube heat pump hub to your Home Assistant instance, use this My button:

Qube heat pump can be auto-discovered by Home Assistant. If an instance was found, it will be shown as Discovered. You can then set it up right away.

Home Assistant discovers the Qube heat pump automatically when it is on the same network, using the controller’s mDNS (Bonjour) advertisement. If the heat pump is on a separate network or VLAN, add it manually with its IP address or hostname, or allow mDNS between the networks on your router.

Reconfiguration

If the IP address or hostname of your heat pump changes, you can update it without removing and re-adding the integration:

1. Go to Settings > Devices & services.
2. On the Qube heat pump integration, select the three-dot menu and choose Reconfigure.
3. Enter the new IP address or hostname.
4. Select Submit to save the new settings.

Home Assistant checks that the new address belongs to a Qube heat pump and, when it can read the heat pump’s mDNS announcement, that it is the same heat pump as before.

Supported functionality

Binary sensors

• Source pump
  • Description: Indicates whether the source pump is running.
• User pump
  • Description: Indicates whether the user pump is running.
• Buffer pump
  • Description: Indicates whether the buffer pump is running.
• Four-way valve
  • Description: Indicates the state of the four-way valve.
• Three-way valve
  • Description: Indicates the state of the three-way valve.
• Cooling output
  • Description: Indicates whether the cooling output is active.
• Heater step 1 / 2 / 3
  • Description: Indicates whether the electric heater step is active.
• Keypad
  • Description: Indicates whether the keypad is enabled.
• Day mode
  • Description: Indicates whether day mode is active.
• Summer mode
  • Description: Indicates whether summer mode (cooling) is active.
• Anti-legionella
  • Description: Indicates whether an anti-legionella cycle is running.
• Dewpoint
  • Description: Indicates whether the dewpoint input is active.
• Booster security
  • Description: Indicates whether the booster security input is active.
• Source flow
  • Description: Indicates whether source flow is detected.
• PV surplus
  • Description: Indicates whether photovoltaic surplus energy is available.
• Thermostat demand
  • Description: Indicates whether the thermostat is requesting heating or cooling.
• Plant demand
  • Description: Indicates whether the plant controller is requesting heating or cooling.
• External demand
  • Description: Indicates whether an external demand signal is active.
• Anti-legionella timeout alarm
  • Description: Indicates whether the anti-legionella cycle exceeded its maximum time.
• DHW timeout alarm
  • Description: Indicates whether the domestic hot water cycle exceeded its maximum time.
• Dewpoint alarm
  • Description: Indicates a dewpoint-related alarm condition.
• Supply too hot alarm
  • Description: Indicates the supply temperature exceeded the safety limit.
• Flow alarm
  • Description: Indicates a flow-related alarm condition.
• Central heating alarm
  • Description: Indicates a central heating alarm condition.
• Cooling alarm
  • Description: Indicates a cooling-related alarm condition.
• Heating alarm
  • Description: Indicates a heating-related alarm condition.
• Working hours alarm
  • Description: Indicates a working hours alarm condition.
• Source alarm
  • Description: Indicates a source-related alarm condition.
• Global alarm
  • Description: Indicates any active alarm on the heat pump.
• Compressor alarm
  • Description: Indicates a compressor-related alarm condition.
• Room sensor enabled
  • Description: Indicates whether the room temperature sensor is enabled. Disabled by default.
• Plant sensor enabled
  • Description: Indicates whether the plant temperature sensor is enabled. Disabled by default.
• Buffer sensor enabled
  • Description: Indicates whether the buffer temperature sensor is enabled. Disabled by default.
• DHW controller enabled
  • Description: Indicates whether the domestic hot water controller is enabled. Disabled by default.

Selects

• SG Ready mode
  • Description: Controls the Smart Grid Ready (SG Ready) mode for load shifting based on grid conditions or solar surplus.
  • Options:
    • Off: Normal operation.
    • Block: Block heat pump operation (grid requests reduced consumption).
    • Plus: Regular heating curve with room setpoint +1K and DHW day mode (grid has surplus energy).
    • Max: Run anti-legionella cycle once, use surplus curve with room setpoint +1K (maximum energy absorption).

Sensors

• Supply temperature CH
  • Description: Current supply temperature for central heating.
• Return temperature
  • Description: Current return temperature.
• Source temperature in
  • Description: Temperature of the source fluid entering the heat pump.
• Source temperature out
  • Description: Temperature of the source fluid leaving the heat pump.
• Room temperature
  • Description: Current room temperature as measured by the heat pump.
• DHW temperature
  • Description: Current domestic hot water temperature.
• Outside temperature
  • Description: Current outside temperature.
• Thermal power
  • Description: Current thermal power output.
• Electric power
  • Description: Current electric power consumption.
• Total electric consumption
  • Description: Cumulative electric energy consumed.
• Total thermal yield
  • Description: Cumulative thermal energy produced.
• COP
  • Description: Current coefficient of performance.
• Compressor speed
  • Description: Current compressor speed in revolutions per minute.
• Measured PVT flow
  • Description: Current photovoltaic-thermal flow rate.
• Room setpoint heating (day)
  • Description: Target room temperature for heating during daytime.
• Room setpoint heating (night)
  • Description: Target room temperature for heating during nighttime.
• Room setpoint cooling (day)
  • Description: Target room temperature for cooling during daytime.
• Room setpoint cooling (night)
  • Description: Target room temperature for cooling during nighttime.
• Heat pump status
  • Description: Current operational status of the heat pump.

Switches

• Summer mode
  • Description: Toggle between heating and cooling mode.
• Anti-legionella cycle
  • Description: Manually start an anti-legionella prevention cycle.
• Heating curve
  • Description: Enable or disable dynamic heating curve compensation.
• Heating demand
  • Description: Activate or deactivate heating demand via Modbus.

Water heater

• Domestic hot water
  • Description: Controls domestic hot water temperature and operation mode.
  • Current temperature: The measured DHW temperature.
  • Target temperature: The user-defined DHW setpoint (adjustable).
  • Operation modes: Heat pump (normal operation) and performance (DHW boost, forces an immediate heating cycle).

Qube heat pump automation examples

Automation: Store surplus solar power as heat

When your solar panels export more power than the heat pump needs, raise the smart grid ready mode to Plus so the heat pump uses the surplus. Switch back to Off when the export drops.

• Trigger: The grid export sensor is above 1500 W for 5 minutes, or below 500 W for 5 minutes.
• Action: Select Plus or Off in the smart grid ready mode select.

alias: "Qube: use surplus solar power"
triggers:
  - trigger: numeric_state
    entity_id: sensor.grid_export_power
    above: 1500
    for:
      minutes: 5
    id: surplus
  - trigger: numeric_state
    entity_id: sensor.grid_export_power
    below: 500
    for:
      minutes: 5
    id: no_surplus
actions:
  - action: select.select_option
    target:
      entity_id: select.qube_heat_pump_smart_grid_ready_mode
    data:
      option: "{{ 'plus' if trigger.id == 'surplus' else 'off' }}"

Automation: Heat hot water when electricity is cheap

Boost the domestic hot water when the electricity price is low, and return to normal operation afterwards.

• Trigger: The electricity price changes.
• Action: Set the water heater operation mode to Performance when the price is below 0.10 per kWh, otherwise to Heat pump.

alias: "Qube: heat hot water at low prices"
triggers:
  - trigger: state
    entity_id: sensor.electricity_price
actions:
  - action: water_heater.set_operation_mode
    target:
      entity_id: water_heater.qube_heat_pump_domestic_hot_water
    data:
      operation_mode: >-
        {{ 'performance' if trigger.to_state.state | float(1) < 0.10
           else 'heat_pump' }}

Replace sensor.grid_export_power and sensor.electricity_price with the sensors of your energy meter and energy provider, and adjust the thresholds to their units. The examples assume an export power in watts that is positive while exporting, and a price per kWh.

Data updates

The integration polls the heat pump every 15 seconds via Modbus TCP.

Diagnostics

The diagnostics download contains:

• The values the integration last read from the heat pump.
• The state of the switches.
• The smart grid ready mode.
• The software version of the heat pump.

The host address is redacted. Attach the downloaded file when reporting an issue. For more information, see Download diagnostics.

Known limitations

• The integration communicates with the heat pump over Modbus TCP on your local network only. Settings that are not listed under Supported functionality, such as the heating curve parameters, are configured on the heat pump’s panel.
• Changes made on the heat pump’s panel appear in Home Assistant after the next poll, within 15 seconds.
• Automatic discovery uses mDNS, which does not cross network or VLAN boundaries unless your router forwards it. Without it, add the heat pump manually.
• On some firmware versions the heat pump does not report its software version over Modbus. The device page then does not show a meaningful software version.
• When the heat pump’s energy counters briefly report a lower value, the energy sensors keep the previous value until the counter passes it again, so the energy dashboard does not count the difference twice. A drop of more than 1 kWh that persists for three polls is treated as a counter reset.
• The heat pump cannot be restarted from Home Assistant. To restart it, power cycle the heat pump.

Troubleshooting

Removing the integration

This integration follows standard integration removal.

To remove an integration instance from Home Assistant

1. Go to Settings > Devices & services and select the integration card.
2. Next to the entry you want to remove, select the three dots menu. Then, select Delete.
   • Depending on the integration, the entries are listed under one of the following headings:
     • Devices
     • Hubs
     • Services
     • Integration entries
3. To confirm, select Delete.
   • Home Assistant also deletes the devices and entities of the entry.
4. If Home Assistant asks you to restart, restart Home Assistant.
5. If Home Assistant asks whether to also delete the application credentials, select Remove or Keep.
   • If you keep them, Home Assistant uses them automatically when you add the integration again.
   • To delete them later, refer to Deleting application credentials.