diff --git a/bundles/org.openhab.binding.modbus.kermi/README.md b/bundles/org.openhab.binding.modbus.kermi/README.md new file mode 100644 index 0000000000000..78f11cf7395e7 --- /dev/null +++ b/bundles/org.openhab.binding.modbus.kermi/README.md @@ -0,0 +1,194 @@ +# Kermi Heat pump + +Integrates the X-Center Device (x-center pro) of Kermi Heat pump. +Kermi X-Center & other attached devices (in progress) are integrated into the Modbus Binding. +Requirement is contacting Kermi Support to activate Modbus-TCP which can be connected directly by network. +Older devices (non-Pro ?) were connected by Modbus-RCP - maybe you can try to connect them here using a Modbus-TCP modulator (e.x. from waveshare or similar). +This binding was tested and developed with Kermi x-change dynamic pro heat pump (build 2023). + +See chapter [Thing Configuration](#thing-configuration) how to set them up. + +## Supported Things + +First you need a TCP-Bridge which establishes the basic connection towards your X-Center device + +| Name | Thing Type ID | Description | +|--------------------------|---------------|-----------------------------------------------------------------------------------------------------------------------------| +| Kermi Heat Pump X-Center | kermi-xcenter | Provides (electric) Power values, Flow-information, PV-States, Temperatures and general Information of your Kermi Heat Pump | +| StorageSystemModule | kermi-storage | Provides temperatures of your water-storage (drinking water), heating and cooling and details about your heating-circuit | + +## Discovery + +There's no discovery. +Modbus registers are available for all devices. + +## Device IDs + +| Device | device ID | Comment | +|---------------------|-----------|--------------------------------------------------| +| X-Center | 40 | on cascade-circuits: slave1: 41, slave2: 42, ... | +| StorageSystemModule | 50 or 51 | | + +## Thing Configuration + +The needed Things can be found in the **Modbus Binding** and have to be added manually without Discovery + +1. Create _Modbus TCP Bridge_ with matching Settings of your Kermi Device + +- IP Address +- Device ID +- Port ID + +1. Create _Kermi Heat Pump X-Center_ and attach it to the previous installed _Modbus TCP Bridge_. Configuration requires an approriate Data Refresh Interval with more than 2000 Milliseconds, default is 5000. If it's too fast, you may experience errors in openhab or your x-center ! (Reboot if x-center stops responding on network access). You can enable "PV Modulation" if you want to read the values (default: disabled) + +2. If you have a StorageSystemModule add _StorageSystemModule_ Thing, you have to create a separate _Modbus TCP Bridge_ because of the other device-id. (todo) + + +### Modbus TCP Slave + +| Parameter | Type | Description | +|-----------|---------|---------------------------------------------------------------| +| host | text | IP Address or reachable hostname of your device | +| port | integer | TCP Port of your Kermi device Modbus Settings. Default is 502 | +| deviceid | integer | Modbus ID of your Kermi device Modbus Settings. Default is 40 | + +### Kermi Heat Pump X-Center + +Select as Bridge your previously created Modbus TCP Slave. + +| Parameter | Type | Description | +|-----------------|---------|-------------------------------------------------------------------------| +| refresh | integer | Refresh Rate of x-center values in Milliseconds | + +### Kermi StorageSystemModule (todo) + +Select as Bridge a seperate (second) Modbus TCP Slave. + +| Parameter | Type | Description | +|-----------|---------|--------------------------------------------------------------------| +| host | text | IP Address or reachable hostname of your device (same as x-center) | +| port | integer | TCP Port of your Kermi device Modbus Settings. Default is 502 | +| deviceid | integer | Modbus ID of your Kermi device Modbus Settings. Default is 50 | + + +### Things + +```java +Bridge modbus:tcp:device "Kermi X-Center Modbus TCP" [ host="xcenter", port=502, id=40 ] { + Bridge kermi-xcenter "Kermi X-Center Heat Pump" [ refresh=5000 ] +} +``` + +### Channel-Groups + +The X-Center / StorageSystemModule device offers quite an amount of channels. +They are grouped into 7 channel-groups: + +- State +- EnergySource +- Charging Circuit +- Power & Efficiency +- Workhours +- Alarm +- PV Modulation + + +### Channels + +#### Status + +| Channel | Type | Description | +|------------------------|--------|----------------------------------------------------------------------------------------------| +| Global State | String | State of heat pump as String taken from Kermi Documentation (german wording) | +| Global State as Number | Number | State of heat pump as Number, better for checking / integration as the State as String above | + +Possible states: + +- Standby +- Alarm +- TWE +- Kuehlen +- Heizen +- Abtauung +- Vorbereitung +- Blockiert +- EVU Sperre +- Nicht verfuegbar + + +- Status unknown (if no valid state is received) + + +#### Energy-Source + +| Channel | Type | Description | +|----------------------|---------------------|-------------------------------------------------| +| Exit temperature | Number | in °C - Air temperature exiting heat pump | +| Incoming temperature | Number | in °C - Air temperature incoming into heat pump | +| Temperature Outside | Number | in °C - Outside Air Temperature (if connected) | + +#### Charging Circuit + +| Channel | Type | Description | +|--------------------|----------------------------|-----------------------------------------------------------------------------------| +| Flow temperature | Number | in °C - Water temperature **from** heat pump to drinking water or heating circuit | +| Return temperature | Number | in °C - Water temperature returning back **to** heat pump | +| Flow speed | Number | in l/min - Flow speed of the water | + +#### Power and efficiency + +| Channel | Type | Description | +|---------------------------------------|---------------|--------------------------------------------------| +| Current COP | Number | current cop overall (Coefficient Of Performance) | +| Current COP heating | Number | cop for heating | +| Current COP drinking water | Number | cop for drinking water | +| Current COP cooling | Number | cop for cooling | +| | | | +| Current power | Number | in W (Watt) - Power overall | +| Current power heating | Number | in W (Watt) - Power for heating | +| Current power drinking water | Number | in W (Watt) - Power for drinking water | +| Current power cooling | Number | in W (Watt) - Power for cooling | +| | | | +| Current electric power | Number | in W (Watt) - electric Power overall | +| Current electric power heating | Number | in W (Watt) - electric Power for heating | +| Current electric power drinking water | Number | in W (Watt) - electric Power for drinking water | +| Current electric power cooling | Number | in W (Watt) - electric Power for cooling | + +#### Workhours + +| Channel | Type | Description | +|--------------------------------|--------------|--------------------------------------------------------| +| Fan workhours | Number