OpenHAB binding for WundaSmart heating controllers
Go to file
Mike Jagdis aa1f24fc1c Fix typo in comment
Signed-off-by: Mike Jagdis <>
2024-04-15 09:33:07 +01:00
src/main Fix typo in comment 2024-04-15 09:33:07 +01:00
addons.patch Add some developers docs 2024-03-08 10:39:19 +00:00 Add some developers docs 2024-03-08 10:39:19 +00:00
NOTICE Initial version 2023-12-13 09:22:13 +00:00
pom.xml Correct a typo in pom.xml 2024-01-06 12:37:28 +00:00 Update README 2024-03-09 13:05:08 +00:00

Binding for WundaSmart (UK/PL/EU), Bero (PL) and AEA Energy (IE) Heating Systems

The WundaSmart, Bero and AEA Energy systems are basically the same. The devices are manufactured by Elektro-System s.c. in Poland. In the UK they are marketed under the WundaSmart brand by Wunda Group Plc, in Poland by Sander System, again under the WundaSmart brand, (through their online shop) and also (or perhaps previously?) by Bero under the myBero brand. AEA Energy, based in Ireland, appear to use slight variations of the devices as part of their AEA Multiroom and AEA Solar products.

It is not known if there are other suppliers elsewhere.

All three systems, WundaSmart, myBero and AEA Multiroom/Solar are based on the same hardware, firmware and app with minor variations.

All the Hubs also support connection boxes (also called wiring centres) to drive underfloor heating systems, thermostat/sensor devices, and separate relay devices that are used to turn heating/cooling devices on and off (although relay devices do not appear in the WundaSmart catalogue currently). Some of the Hubs also have one or more built-in relays removing the need for external relay devices in many cases and the latest WundaSmart HubSmart also supports OpenTherm.

Cloud Usage

Unlike pretty much all other similar smart heating systems currently in the market these systems, although they use cloud services, do not absolutely require them. As long as you have access to the network the Hub is on you can both operate and configure your system. Configuration is stored on the Hub and there are no additional subscriptions.

Cloud access is used obtain the credentials necessary to access your Hub directly (although the credentials are obtainable via other means), for remote access when you away (the Hub maintains an outgoing connection to the cloud service) and for geofencing.


If your Hub is connected to the same network as your openHAB instance it should be discovered automatically and appear in the inbox. If it doesn't you can manually add an Account, configure the "cloud user" and "cloud password" to use, and all the Hubs associated with that account will appear in the inbox (if they don't check the openHAB logs). Once you've accepted the Hubs the Account is no longer needed and can be deleted.

For Hubs discovered automatically you will need to configure their "cloud user" "cloud password". They will then obtain the necessary "Auth token" from the cloud and begin polling, at which point all the paired devices, thermostats, sensors, radiator heads, etc. will appear in the inbox.

Hubs discovered via an Account will inherit "cloud user" and "cloud password" from the Account and start working immediately.

Note: you would normally want to use an owner/root or admin cloud account or auth token but it is perfectly reasonable to use a user account if you only want openHAB to be able to control the basics.

If you do not want to use the cloud at all (or cannot for some reason) you can ignore the cloud credentials and configure the "Auth token" directly. You will need to obtain the auth token by using something like PcapDroid to capture traffic between the phone app and the Hub. The auth token you want is the string after "Authorization: Basic" in the requests going TO the Hub.

If all else fails you can add Hubs manually in which case you will also need to set the IP address in the config. They can be added either via the UI or using a *.thing file such as:

Bridge wundasmart:wunda:myid [ eth_ip_ro="...", cloud_user="...", cloud_password="..." ] {

Replace :wunda: with :bero:, :bero_lts: or :fusionelite: depending what type of Hub you have.

You could, in theory, put the paired devices in the *.thing file as well however you would need to specify the serial numbers of devices and the internal IDs of rooms both of which are probably best obtained from Things accepted from the inbox after being discovered by a Hub.

Tech note

The Hub discovery works by broadcasting on the local broadcast address (all ones) which is why WundaSmart say that your Hub should be on the same wifi network and frequency band as your phone/tablet. Not all wifi routers will copy packets between 2.4 GHz and 5 GHz networks, sometimes not even to their own ethernet interfaces. Strictly speaking wifi doesn't even support broadcast (or multicast). The traffic between an Access Point (AP) and a client is separately encrypted and it's up to the AP to retransmit any broadcast or multicast data received to every other connected client. If you have these sorts of problems you may find options in your AP's config relating to broadcast, multicast or IGMP "optimizations" that can be tweaked to improve the situation and allow you to use your phone on 5 GHz while the Hub is on 2.4 GHz.

Supported Things

Currently the binding does not support activating pairing mode and devices cannot be added via the binding. Devices added via the provider's app will be discovered at the next poll of the Hub (a maximum of 1 minute by default) and will appear in the inbox.


As noted in the discovery section above, Accounts are only used to discover Hubs that are not locally connected. Hubs have their own cloud credentials in their config so once they have been added the Account Things are no longer required and should be removed (otherwise they will just keep needlessly polling the cloud).


At least four types of Hub are known to exist. The original Bero Hub only supported ethernet and had no internal relays. The Hubs used by AEA Energy for their Multiroom and Solar installations are based on the Bero Hub but are believed to include at least one relay internally. The WundaSmart HubSmart is a newer iteration that only supports Wifi (no ethernet port) and has and has four internal relays that can be configured to work individually or in push-pull pairs. The HubSmart also supports OpenTherm and is designed to work with typical gas-fired boiler and three-port valve arrangements (S-plan, Y-plan, etc.)


Only the HubSmart supports OpenTherm. Although all Hub Things in openHAB have Channels for OpenTherm data they can be ignored on non-HubSmart Hubs (or if you don't have your HubSmart connected to an OpenTherm boiler).


Rooms are not physical devices themselves but are pseudo-devices taht are created on the Hub to provide control and coordination of other devices.

The configuration for a room specifies which relays and actuators the Hub should use to supply heat to the room. The room's channels specify the parameters that the Hub uses to determine when (the schedule channels) and how much heat is required (the setpoint channels).

The alarm channel value comprises a set of bit flags. Only the open window flag has been identified and split out so far.

Radiator Heads (TRVs)

Radiator heads control the valves on your radiators. No, the WundaSmart radiator heads do not have temperature displays. Nor do they measure room temperature. They do measure valve temperature (give by the vtemp channel value) and modulate the opening and closing of the valve under control of a PID algorithm.

The heads self-calibrate on install to determine the minimum (closed) position of the valve (the vpos_min channel value) and how far it moves to fully open (the vpos_range channel value). They recalibrate weekly at a time set in the Hub's config in order to adjust for aging valves, sludge build-up etc.

The current position of the valve is given by the vpos channel and is relative to vpos_min and vpos_range. Since it is not unlikely that a mixture of valves in different conditions are in use the binding normalises vpos to provide a Valve_open channel that gives the position of the valve as a percentage from 0% (fully closed) to 100% (fully open).

In some cases the value of vpos_min determined by calibration is insufficient to fully close the valve and radiators may become warm when they shouldn't. The vendor recommendation is to adjust the downforce setting for the head via the app in order to compensate. It is perhaps useful to note that doing so actually changes vpos_min and not downforce and that the values of 1 to 6 settable for downforce in the app correspond to vpos_min settings of 20 down to 0 in steps of 5. If you need to adjust "downforce" you can do so by setting vpos_min via openHAB to whatever integer value works best. Recalibration does not appear to undo vpos_min changes. It is unknown whether or not the downforce channel has any functionality.

The alarm channel value comprises a set of bit flags. Only the low battery flag has been identified and split out so far.

Thermostats and Sensors

Thermostats and sensors are effectively the same as far as openHAB is concerned, the only difference being that thermostats have a screen and buttons to adjust setpoints whereas sensors are entirely passive.

Both provide ambient temperature (the "temp" channel), atomspheric humidity (the "rh" channel) and have an optional temperature probe which is specifically intended to be used to measure the floor temperature of an underfloor heating installation and which the Hub will use to shutdown the UFH if the temperature threshold (the "tmax" channel value of a room) is exceeded.

A maximum of one thermostat or sensor can be paired to a room. It is not necessary to have a sensor for room but where one exists the Hub will use it to improve its accuracy when modulating the heating of the room.

The alarm channel value comprises a set of bit flags. Only the low battery flag has been identified and split out so far.

External Sensors

External sensors are functionally the same as the other screenless sensors except that they do not support an external probe for measuring floor temperature. They do not appear in any of the vendors' current catalogues.


Relay devices provide a single relay that is used to control a heat source such as a boiler, furnace, etc. They do not appear in any of the vendor's current catalogues. They would have been necessary with the original Bero Hub which did not have an internal relay at all however newer Hubs are more specifically targetted and include at least one relay internally.

The alarm channel value comprises a set of bit flags. Only the low battery flag has been identified and split out so far.

Connection Boxes / Wiring Centres

Connection boxes provide the interface to underfloor heating systems. They have pump and valve controls plus outputs for up to twelve underfloor heating loops.

Thing Configuration



Security and Risks

  • Direct communication with Hubs is via unencrypted HTTP


      • Anyone with access to your Wifi network can potentially obtain your Hub's authorization by snooping the network.
      • Anyone knowing your Hub's authorization can control your heating system.
      • Anyone knowing your Hub's authorization can potentially identify when your home is unoccupied (via the geofencing status).

      • Ensure you are using WPA2/WPA3 or better on your Wifi network to prevent snooping.
  • It is unknown if the RF between Hubs and devices is encrypted or not


      • It is potentially possible for an attacker to listen to the signals and/or modify the behaviour of your heating system.

      • The protocol does not appear to be publically documented.
  • Hubs make outbound connections to the vendor's cloud service to facilitate remote access


      • If the security of the vendor's cloud service is compromised third parties may gain access to your heating system.

      • If you do not require remote access or backups of your config to the cloud (in case a factory reset is needed) consider blocking outbound connections from your Hub (and define a static IP in DHCP) and/or do not provide it with a router address.
  • Internet access is required for only two reasons: (a) for remote access and (b) in order to obtain updated auth details for local access


      • If you lose Internet access you can potentially lose access to your heating system if the passwords are regenerated (unlikely).
      • If you lose Internet access you will have no remote monitoring or control of your heating system.

      • If remote access is important to you consider using a provider that provides fallback via a mobile device or implement your own fallback using a secondary provider.
      • Consider making any blocks you put on the Hub's connection to the cloud toggleable (possibly remotely with suitable security).
  • OpenHAB does not possess a fine-grained permissions system


      • Anyone with access to your openHAB instance will be able control whatever aspects of your heating system "admin" has exposed via Items and UI elements.
      • Anyone with access to your openHAB instance will be able to see whatever data "admin" has exposed via Items and UI elements. This could include your schedule, your geofence status, whether there is likely to be a window left open and possibly more.

      • Do not permit your openHAB instance to respond to requests from insecure networks.
      • Do not add Items and UI elements that you are not willing to expose to every user.