Before you start
- A working Ampernova installation with assigned, online thermostats.
- Home Assistant and a broker reachable from the HeatingMain controller.
- Access to the controller in the Ampernova portal. It must be online to receive the broker settings.
Once configured, MQTT operates locally. Matter pairing and the thermostat’s Fabric menu are separate from this setup.
Set up MQTT
- In Home Assistant, open Settings → Devices & services → Add integration → MQTT. On Home Assistant OS, follow the offered Mosquitto broker setup. If already installed, use the existing broker.
- Create a dedicated broker login for Ampernova. With the official Mosquitto app, create a Home Assistant user under Settings → People → Users; enable Advanced Mode in your profile if the Users tab is hidden. Choose a unique password and leave administrator access off.
- For Home Assistant Container or an external broker, install Mosquitto separately and supply that broker’s address and login to the MQTT integration.
- Keep MQTT discovery enabled with the discovery prefix
homeassistant.
Official Home Assistant MQTT instructions · Mosquitto setup and users
Connect Ampernova
In the Ampernova portal, open your HeatingMain controller, then Settings → MQTT broker. Fill in all four fields:
| Field | What to enter |
|---|---|
host | The broker’s LAN address, for example 192.168.1.20. For the Mosquitto app, use the Home Assistant machine’s LAN address. Enter no scheme, path or port here. |
port | 1883 for the local MQTT TCP listener. |
user | The dedicated broker username you created. |
password | That user’s broker password. Enter it again whenever applying settings; a blank field sends an empty password. |
Select apply broker. The controller saves the settings and reconnects automatically; no manual reboot is needed. Repeat for each HeatingMain controller you want in Home Assistant.
A “settings sent” message confirms dispatch. Verify the connection by finding live readings in Home Assistant. The password is never displayed or filled back in.
Use a trusted local network: this controller setting uses plain MQTT TCP, not TLS or WebSockets. Keep the broker’s port private to your LAN.
Find your rooms
- Open Settings → Devices & services → MQTT in Home Assistant, then open its device list.
- Find your controller by its device ID. Thermostat entities are grouped under the controller and use circuit labels such as Thermostat A1 or Thermostat B4.
- Open a thermostat entity and check its room temperature and targets against the physical thermostat. Rename the entity for the room and assign an area if desired.
- Add the thermostat entity to a dashboard. Change a temperature target and confirm it reaches the physical thermostat; allow a bus round, about one minute.
No custom Ampernova integration or manual discovery YAML is required. Available entities depend on the connected circuits and firmware; a room with both floor and ceiling assignments can appear under both circuit addresses.
Room temperature targets are individual. Heating or cooling season is a plant-wide choice; use the global mode control in the Ampernova portal.
Troubleshooting
The controller does not appear
Check the broker address, credentials and LAN access from the controller. Use the broker machine’s LAN IP, not localhost or core-mosquitto. Check Mosquitto’s log for a connection or authentication error, then apply all four fields again.
MQTT is connected, but rooms are missing
Confirm the thermostats are online and assigned. In Home Assistant’s MQTT options, check that discovery is enabled with prefix homeassistant. After the rooms are online, apply the broker settings again to reconnect and resend discovery.
Entities appear but are unavailable
Discovery descriptions are retained by the broker and can outlive a connection. Check current controller and thermostat connectivity and wait for fresh readings. A retained device listing alone does not prove the system is online.
What does “use default broker” do?
It removes the portal override and restores the broker configured when the controller was provisioned. If there is no default, local MQTT stops. To connect to your own broker, enter its details and select apply broker.