Disclaimer : This is not a Koolnova official integration and use at your own risk.
koolnova-BMS-Integration is an integration of koolnova system into Home Assistant using BMS (Building Management System) and Modbus RTU (RS485) protocol.
Warning
Koolnova 1.0 and Koolnova 2.0 do not expose all system features in the same way. This integration supports both versions with a version selector and automatic detection. Koolnova 2.0 advanced entities are exposed progressively and should still be considered advanced configuration until validated on more real installations.
With BMS, owners can monitor and manage systems, such as air conditioning, heating, ventilation, lighting or energy supply systems. Some objectives of building automation are improved occupant comfort, efficient operation of building systems, reduction in energy consumption, reduced operating and maintaining costs and increased security.
Most building automation networks consist of a primary and secondary bus which connect high-level controllers with low-level controllers, input/output devices and a user interface. Physical connectivity between devices waq historically provided by dedicated optical fiber, ethernet, ARCNET, RS-232, RS-485 or a low-bandwidth special purpose wireless network.
Modbus is a client/server data communications protocol in the application layer of the OSI model. Modbus was developped for industrial applications, is relatively easy to deploy and maintain compared to other standards, and places few restrictions on the format of the data to be transmitted.
Communication standards or buses which is deployed for Modbus communication are:
- TCP/IP over Ethernet
- Asynchronous serial communication in a wide range of standards, technologies : EIA/TIA-232-E, EIA-422, EIA/TIA-485-A, fiber, radio frequency.
- Modbus PLUS, a high speed token passing network
Modbus standard defines MODBUS over Serial Line, a protocol over the Data link layer of the OSI model for the Modbus application layer protocol to be communicated over a serial bus. Modbus Serial Line protocol is a master/slave protocol which supports one master and multiple slaves in the serial bus. A serial bus for Modbus over Serial Line can maximum 247 slaves to communicate with 1 master, those slaves then must their unique address range from 1 to 247. Modbus over Serial Line has two transmission modes RTU and ASCII which are corresponded to two versions of the protocol, known as Modbus RTU and Modbus ASCII.
Modbus RTU (Remote Terminal Unit), makes use of a compact, binary representation of the data for protocol communication. The RTU format follows the commands/data with a cyclic redundancy check checksum as an error check mecahnism to ensure the reliability of data.
Modbus TCP/IP (also Modbus-TCP) is simply the Modbus RTU protocol with a TCP interface that runs on Ethernet. Modbus TCP/IP uses TCP/IP and Ethernet to carry the data of the Modbus message structure between compatible devices. That is, Modbus TCP/IP combines a physical network (Ethernet), with a networking standard (TCP/IP), and a standard method of representing data (Modbus as the application protocol). Essentially, the Modbus TCP/IP message is simply a Modbus communication encapsulated in an Ethernet TCP/IP wrapper.
Two different architectures, a first wired one where the Koolnova system is connected to the Home Assistant server via a USB/RS485 dongle and a second one wirelessly, the Koolnova system is connected to the RS485/WIFI device which is connected to the same WIFI network as the Home Assistant server.
In IEEE 802.11 (Wi-Fi) terminology, a station (abbreviated as STA) is a device that has the capability to use the 802.11 protocol. For example, a station may be a laptop, a desktop PC, PDA, access point or Wi-Fi phone. An STA may be fixed, mobile or portable.
- An installation of Home Assistant with free USB port.
- A RS485 USB dongle (Example: DSD Tech SH-U11) for wired systems or a RS485/WIFI device (Example: Elfin EW11A or Elfin EW11-0, example of configuration) for wireless systems.
- A Koolnova air conditioning system (identifier: 100-CPNR00 or 100-CPND00) with areas defined.
- Enabling Modbus communication on the master radio thermostat (INT 49).
- A Koolnova system version selected during setup:
Auto detectKoolnova 1.0Koolnova 2.0
Warning
If you choose the RS485/WIFI device from Elfin, it must accept voltages between 5v and 36v.
- Controller D+ to USB dongle A+
- Controller D- to USB dongle B-
- Controller GND to USB dongle GND
- Controller D+ to USB dongle A+
- Controller D- to USB dongle B-
- Controller GND to USB dongle GND
- Controller D+ to RS485/WIFI module A+
- Controller D- to RS485/WIFI module B-
- Controller GND to RS485/WIFI module GND
- Controller +24 to RS485/WIFI module VCC
Install using HACS In HACS go to the three dots int the upper right corner choose add custom repository and add https://github.com/sinseman44/koolnova-BMS-Integration to the list.
Install manually Clone or copy this repository and copy the folder custom_components/koolnova_bms into /custom_components/koolnova_bms.
After plugging the USB dongle into the system, check that among the tty, it's recognized by Home Assistant.
Example : ttyUSB0 is the node added for the device. The absolute path of this node (eg: /dev/ttyUSB0) will be used in the component configuration.
The first page after installing the component is the choice of Modbus communication.
- Modbus TCP (for wireless system)
- Modbus RTU (for wired system)
Depending on the choice made, the next step is the Modbus RTU configuration or the Modbus TCP configuration.
All serial fields are filled with default values defined by Koolnova.
Adapt the fields according to your own configuration.
Important
The device name is important if you have multiple Koolnova controller to differentiate them and must be different for each instance of this integration.
Note
Each control unit has a specific address (default 49). Possible addresses are 1 to 247.
After validation of the serial configuation, the component will test if it can communicate with the koolnova system. If not, an error occur.
Warning
some users encountered a problem with the slave Modbus address. Enter address “1” instead of the default (49) and check if this validate this step.
All fields are filled with default values.
Adapt the fields according to your own configuration.
Important
The device name is important if you have multiple Koolnova controller to differentiate them and must be different for each instance of this integration.
During setup, the integration asks which Koolnova system version must be used.
Auto detect: the integration tries to identify the controller version automatically.Koolnova 1.0: use this when your controller is a Koolnova 1.0 system.Koolnova 2.0: use this when your controller is a Koolnova 2.0 system. This enables additional diagnostics and advanced configuration entities.
Important
If automatic detection does not work on your installation, choose the version that matches your Koolnova controller. Selecting the wrong version can make advanced controls behave incorrectly.
The next installation page is the area configuration.
This page appears for each area that must be configured.
The checkbox must be filled before validation if you want to configure a new area.
The area configuration ends with no new area.
- Local polling over Modbus RTU or Modbus TCP.
- Config flow setup from the Home Assistant UI.
- Multiple controller support when each controller has a unique device name and Modbus connection.
- Koolnova 1.0 and Koolnova 2.0 version selection, with automatic detection.
climateentities for configured areas.sensor,number,selectandswitchentities for diagnostics and configuration.- Advanced Koolnova 2.0 services to send and inspect zone opening-angle commands.
- Koolnova 2.0 system controls are routed through the correct version-specific communication model.
The following parameters can be controlled for the climate platform entities:
- Area power on/off.
- Target temperature (Celsius, Min: 15°C -> Max: 35°C).
- Fan mode:
- Auto
- Off
- Low
- Medium
- High
- Area HVAC mode follows the controller-wide
Global HVAC mode.
The Koolnova system uses a controller-wide heating/cooling mode. Area climate entities can turn a zone on or off and adjust the zone temperature and fan mode, but changing from cooling to heating is done from the Global HVAC mode select entity.
The following attributes are available for diagnostic sensor platform entities:
-
Modbus serial (Device, Address, port, ...)
-
Target temperature (celcius) and throughput for each engine (maximum 4):
- Target temperature: Min: 15°C -> Max: 35°C
- Troughput: int value between 0 (engine stopped) to 15 (maximum troughput)
-
Target temperature (celcius) for each area:
- 0°C to 50°C
The following attributes are available for diagnostic sensor platform entities:
-
Network settings (Address, port)
-
Target temperature (celcius) and throughput for each engine (maximum 4):
- Target temperature: Min: 15°C -> Max: 35°C
- Troughput: int value between 0 (engine stopped) to 15 (maximum troughput)
-
Target temperature (celcius) for each area:
- 0°C to 50°C
When Koolnova 2.0 is selected, additional diagnostic sensors are created:
- Control unit model/version.
- System time diagnostic fields.
- Floor water temperature.
- Outdoor temperature.
- Auxiliary NTC temperature.
- Radiant floor demand count.
- AC3 air demand count.
- Connected and active volume for AC1 to AC4.
- Requested temperature average for AC1 to AC4.
- Raw/reserved diagnostic values that are not safe to expose as user controls yet.
Some advanced or noisy diagnostic entities are disabled by default and can be enabled from the Home Assistant entity registry when needed.
The following parameters can be controlled for the select platform entities:
-
Global operation mode (HVAC mode)
- ventilation (Koolnova 2.0)
- cold
- heat
- dehumidification (Koolnova 2.0)
- heating floor (need a specific hardware module, identifier: 100-MSR002)
- refreshing floor and refreshing air (need a specific hardware module, identifier: 100-MSR002)
- heating floor and heating air (need a specific hardware module, identifier: 100-MSR002)
-
Global efficiency, when supported by the controller, defines the balance point between efficiency and speed of the area system.
- Lower: the set temperature is reached sooner
- Higher: better efficiency
-
Engine state: int value which represents the flow programming of the system engines
- 1: Manual minimum
- 2: Manual medium
- 3: Manual high
- 4: Automatic
When Koolnova 2.0 is selected, the integration also exposes advanced configuration selects:
- EFI setting.
- Automatic changeover target modes:
- mode to apply above the heating water threshold
- mode to apply below the cooling water threshold
- DIN1 and DIN2 external input function codes.
- Thermostat block level.
- Mixing valve safety factor.
- Mixing valve cooling and heating modes.
Some options are still numeric because the public documentation does not always provide a confirmed user-facing label.
The number platform is used for numeric configuration values. Koolnova 2.0 adds the following advanced number entities:
- Heating and cooling temperature limits.
- These limits use 0.5 C steps.
- Automatic changeover water thresholds.
- Automatic changeover humidity relay threshold.
- Pump delay.
- Valve origin adjustment.
- Immersion heater activation delay and activation temperature.
- Mixing valve ambient temperature limits.
- Mixing valve water temperature limits.
- Mixing valve fixed cooling/heating supply temperatures.
The Koolnova 2.0 automatic changeover settings combine water temperature thresholds with the modes to apply when those thresholds are reached:
- cooling / refreshing floor threshold, used when the measured water temperature is lower than or equal to the configured value.
- heating / radiant floor threshold, used when the measured water temperature is higher than or equal to the configured value.
- target mode above the heating water threshold.
- target mode below the cooling water threshold.
- humidity relay threshold.
In Home Assistant, these values are exposed as separate select and number entities, but they should be configured together. Changing only the thresholds without checking the target modes, or changing the target modes without checking the thresholds, can make the automatic mode behave unexpectedly.
The following parameters can be controlled for the switch platform entities:
- Global HVAC State (stopped or running)
- Modbus Debug (stopped or running)
When Koolnova 2.0 is selected, the integration also exposes:
- Mode availability switches used by the global HVAC mode selector:
- ventilation
- cooling
- heating
- dehumidification
- radiant floor
- radiant floor cooling
- radiant floor heating
- Electrovalve enable switches for each configured zone.
Note
The number of V2 Zx - Area X electrovalve enabled entities depends on the number of zones configured during the integration setup.
These entities write advanced Koolnova 2.0 configuration values. Use them only if you understand the corresponding controller behavior.
The integration provides advanced services for the Koolnova v2 opening-angle commands:
koolnova_bms.set_v2_opening_angle: send the opening-angle command for one zone.koolnova_bms.get_v2_last_opening_angle: return the last targeted zone and angle command.
These are exposed as services instead of per-zone state entities because the controller only reports the last opening-angle command, not a persistent angle value for each zone.
Service fields:
zone_id: Koolnova zone number, from 1 to 16.angle: opening angle, one of 45, 60, 75 or 90.entry_id: optional Home Assistant config entry ID, required only when multiple Koolnova v2 controllers are loaded.
For get_v2_last_opening_angle, zone_id is optional. When provided, the response indicates whether the last command currently targets that zone.
Whenever you write a bug report, it helps tremendously if you indicate sufficient debug logs directly (otherwise we will just ask for them and it will take longer). So please enable debug logs like this and include them in your issue:
logger:
default: warning
logs:
custom_components.koolnova_bms: debug