Installation and Setup

Installation and Setup

At the heat pump

Modbus TCP has to be switched on in the controller's menu: User → Settings → Modbus TCP.

• Parameter: On
• Network: either the address of your Home Assistant host (only that host may connect) or your network address, e.g. 192.168.178.0, to allow every host in it. The first is the safer choice.
• Netmask: the netmask of your network, usually 255.255.255.0.
• Port 502, slave address 1.

Modbus TCP is unencrypted, and every host the network setting admits can read and write; Weishaupt asks for a direct connection between client and heat pump rather than a home network. At least keep the heat pump on a trusted local network and never expose port 502 to the internet.

Installation

Minimum Home Assistant version: 2026.9. The integration borrows its Modbus connection from Home Assistant's own modbus integration, which offers it from 2026.9 on.

Add the repository as a custom repository in HACS (category Integration) and install it, or copy custom_components/weishaupt_modbus/ into the custom_components/ directory of your Home Assistant configuration and restart. Then add it under Settings → Devices & services → Add integration → Weishaupt Modbus.

The setup dialog checks that the heat pump answers before it creates the entry; a device that answers but refuses register 30001 (outside temperature), which every Weishaupt heat pump serves, is refused as not the heat pump. Add one entry per heat pump.

Setup parameters

Parameter	Default	Meaning
Host	-	Name or IP address of the heat pump. Mandatory.
Port	502	Modbus TCP port, as set on the heat pump.
Prefix	weishaupt_wbb	Part of every entity's unique ID. Leave it alone unless you are migrating from another integration and want to keep the recorded history.
Device postfix	empty	Tells several heat pumps apart. Leave it empty for a single pump; every further pump needs a postfix of its own, the dialog refuses an empty or reused one. The postfix is appended to device names and IDs.
Operation map file	weishaupt_wbb_kennfeld.json	The power map of your model (see How Data Updates).
2nd - 5th heating circuit	off	Adds the entities of the additional heating circuit.
Name device prefix	off	Puts the prefix in front of the name of every register entity, e.g. weishaupt_wbb_Outside temperature, and of the web interface's values and its power limit. The write counters and the sensors about the web interface's polling keep their names.
Name topic prefix	off	Puts the device's short name in front of the name of every register entity, e.g. WP_ for the heat pump, WW_ for hot water, and of the web interface's values and its power limit.

Prefix and device postfix are part of every entity's unique ID and cannot be changed afterwards: a change would orphan the recorded history of every entity. To change them, remove the entry and add it again; that also starts the EEPROM write counters over.

Reconfigure

Reconfigure in the entry's menu changes host, port, power map, heating circuits and the two name options without losing history. The heat pump has to answer at the new address before the change is saved.

A heating circuit switched off here loses its device and entities at the next load; switched on again, they come back with their names, entity IDs and history. While it is off, Home Assistant lists its statistics under Developer tools › Statistics and offers to delete them - leave them if you may switch it on again.

Heating circuits: your choice against the controller's

A circuit switched off at the controller still answers with factory values (seen on a WBB), so its entities would look real. Each time the entry loads - at start, after a reconfigure or an options change - the integration therefore compares heating circuits 2-5 enabled here with the controller's own setup (registers 41201, 41301, 41401, 41501: 0 means no circuit) and raises a repair notice for each circuit where they differ.

• A notice goes once the two match; one you ignore stays ignored, and only for its own circuit.
• A circuit the controller does not tell about - a refused read, a value it does not document, a link that drops - is not judged: its notice stays as it was, unless the circuit's switch here now says otherwise.
• Circuit 1 is always read, so it has nothing to compare.

Options

The Options dialog holds the settings that can change at any time. A change reloads the integration.

Option	Default	Range	Meaning
Poll interval	30 s	5 - 600 s	How often all registers are read.
Warn at this many writes per day	50	0 - 100 000	Logs a warning once when reached; 0 never warns.
Refuse writes above this many per day	0 (no limit)	0 - 100 000	Writes beyond it are refused until the next day. Must not be below the warning threshold.

The web interface entry has options of its own (see Web Interface).

Removal

1. Settings → Devices & services → Weishaupt Modbus, open the entry's menu and choose Delete. This removes its devices and entities; what the recorder already stored stays in its database. A heat pump's web interface is an entry of its own: delete it as well, on its own it only stops.
2. Delete www/local/weishaupt_modbus_powermap*.svg from your configuration directory if you no longer want the preview picture; removing the entry leaves it.
3. To remove the integration itself, uninstall it in HACS (or delete custom_components/weishaupt_modbus/) and restart.

Optionally switch Modbus TCP off on the heat pump again.