Do not set any values if the corresponding readings don't match the displayed data on the control unit itself or if any other readings are not correct! I'm not responsible for any damage!
This module is for the FHEM home automation server written in Perl. If you do not have a FHEM server you can use my project java-wtkcontrol, a standalone version for the same use case which includes a CLI and GUI interface. Thus, the protocol description in this README applies to the standalone project too.
This module will not work for your heat pump if the official one (by user StefanStrobel) works for you! - It uses different memory addresses! Successfully tested with a Resümat CD4 with software version 8011 (should work on 7000 and 8000 too) on a DS 5009.3 heat pump.
If it does not work for you, try to use the official module as seen in the FHEM wiki.
It should already be in the contrib/ folder of your FHEM installation.
Can be used to request/change settings from older Waterkotte heat pumps with the Resümat CD4 control unit via the RS232 port.
Based on 98_WKRCD4.pm.
Just copy 98_WKRCD4.pm into the FHEM/ folder of your FHEM installation.
Here's an example of the full path: /opt/fhem/FHEM/98_WKRCD4.pm
After that, make sure to enable the module by restarting FHEM with shutdown restart.
define <Name> WKRCD4 <Device>@<Speed> <Read-Interval>
You can use a USB-to-RS232-converter and plug it into your FHEM server. Most of these devices use /dev/ttyUSB0 as the device path but if you're unsure, just check the syslog with cat /var/log/syslog | grep tty after plugging it in.
The default speed/baud rate is 9600. The default read interval is 60 (poll every minute).
By the way, if your heat pump is too far away from your server:
Just use another Raspberry Pi and use ser2net to transfer the serial data over the network. More information about that is available at the end of the document.
Example command:
define Heating WKRCD4 /dev/ttyUSB0@9600 60
Most sets/gets are hidden by default because they usually don't have to be changed that often.
You can enable them by setting the attribute enableAdvancedMode to 1.
attr <name> enableAdvancedMode 1
To disable the adv. mode, just delete the attribute or set it to 0.
Check out examples.md to find some snippets for attributes and notifies.
Protocol description reverse engineered and found in docs for "MOS protocol" by "Mühlhaus Prozessleittechnik GmbH".
By sending hexadecimal strings (without the spaces) to the serial interface of the control unit you can receive a response with some hexadecimal data.
Please note: If the control unit doesn't respond, try sending "AT" and a carriage return:
41 54 0D
01 18 - Start logger/Show contents? (not compatible with FW 7000, 8000, 8011!)
01 15 - Read memory
01 14 - Write RTC (time/date) memory
01 13 - Write memory (Don't destroy your heat pump!)
00 17 - Read response
00 11 - Write response
00 03 - Logger response (?, maybe)
Example command to read data:
10 02 01 15 0000 0002 10 03 FE17
10 - DLE (Data Link Escape)
02 - STX (Start of Text)
01 15 - SLAVE ADDR (typically 01) / CMD (Heat pump command, 15 means "Read memory")
0000 - Start address
0002 - Bytes to read at start address (if you start at 0x00, the max value is 0x152 with SW-Version 8011)
10 - DLE (Data Link Escape)
03 - ETX (End of Text)
FE17 - CRC-16 checksum of CMD, start address and bytes to read (More information below)
Example command to write data:
10 02 01 13 00BC 0000C841 10 03 851C
10 02 - DLE / STX
01 13 - SLAVE ADDR (typically 01) / CMD (Heat pump command, 13 means "Write memory")
00BC - Start address
0000C841 - Bytes to write at start address (0000C841 is a float - 25.0)
10 03 - DLE / ETX
851C - CRC-16 checksum of CMD, start address and bytes to write (More information below)
Example command to sync the time/date:
10 02 01 14 0000 1B 1E 0C 16 02 13 1003 AF8D
10 02 - DLE / STX
01 14 - SLAVE ADDR (typically 01) / CMD (Heat pump command, 14 means "Write time/date memory")
0000 - Start address (maybe at RTC register?)
1B 1E 0C - SS:MM:HH (In that case: 27:30:12)
16 02 13 - DD.MM.YY (In that case: 22.02.19)
10 03 - DLE / ETX
AF8D - CRC-16 checksum of CMD, start address and time/date (More information below)
Example command to start the logger (or show the contents?):
10 02 01 18 0000 001A 10 03 7C1C
10 02 - DLE / STX
01 18 - SLAVE ADDR (typically 01) / CMD (Heat pump command, 01 18 means "Start logger" (?, or "Show logger contents"?)
0000 - Start address (?)
001A - Bytes to read at start address (?)
10 03 - DLE / ETX
AF8D - CRC-16 checksum of CMD, start address and bytes to read (More information below)
Response for command 10 02 01 15 00E9 0001 10 03 732A as an example:
16 10 02 00 17 00 10 03 7200 16
The bytes between 17 and 10 are the received data bytes.
In that case, it would be 00, because address 00E9 is the field "Ww-Abschaltung" (German for 'Warm water disabled'). At the time of the request, warm water was enabled, so the answer is 0, not 1.
7200 is the checksum once again.
Please note: If 10 appears in the data bytes, it is escaped using another 10. Due to that, you have to skip one 10 to get correct values.
The control unit acknowledges any write command with the following response:
16 10 02 00 11 00 10 03 6600 16
Response for command 10 02 01 18 0000 001A 10 03 7C1C (Start logger/Show contents?) resulted in the following response:
16 10 02 00 03 05 10 03 0A1E 16
Data to interpret might be between 03 and 10.
Please note: Feature not supported on versions 7000, 8000 and 8011.
Some people at the IP-Symcom forums already created two PHP scripts to calculate the CRC-16.
Alternatively, you can look on the web for scripts/pages that can calculate a CRC16_BUYPASS or a custom CRC-16. Here are the parameters:
CRC-Order: 16
Input type: Hex
Polynomial: 0x8005
Initial value: 0x0
LSB/Final Xor Value: 0x0
Input/data reflected/reversed: No
Result reflected/reversed: No
For me, crccalc.com worked well. Just enter the part of the command between 10 02 and 10 03 - that would be the CMD, the start address and the bytes to be read after the start address. Make sure to choose CRC-16, the correct result is CRC-16/BUYPASS.
- Floats -----> IEEE float notation (4 byte, little endian!)
- Integers ---> 1 or 2 bytes (8 or 16 bits)
- Binary -----> 1 byte
- Date -------> 3 bytes (DD MM YY)
- Time -------> 3 bytes (SS MM HH)
If you need more information about the protocol, visit https://www.symcon.de/forum/threads/2092-ComPort-und-Waterkotte-abfragen (German).
Install ser2net by opening a terminal/SSH session:
sudo apt-get install ser2net -y
After that, edit /etc/ser2net.conf with your favorite text editor.
sudo nano /etc/ser2net.conf
Go to the end of the file (Ctrl+W, Ctrl+V in nano) and make sure to comment out the BANNER line and the 4 default entries (2000:telnet, 2001:telnet, 3000:telnet, 3001:telnet) by prepending a # to each line.
At the end of the file, add the following line:
2000:raw:0:/dev/ttyUSB0:9600 NONE 1STOPBIT 8DATABITS
2000 is the used port, raw is the mode, /dev/ttyUSB0 the device (change it if you have to) and 9600 is the speed/baud rate.
Save the file and close the text editor. The last step: Restart ser2net.
sudo /etc/init.d/ser2net restart
define Heating WKRCD4 192.168.1.23:2000@9600 60
It's basically like a normal define, just change the device to IP:PORT. (The port is 2000 in our case!)
- Hz-KlSteilheit
- Hz-Temp-BasisSoll
- Hz-Temp-Einsatz
- Hz-Temp-RaumSoll
- Ww-Temp-Soll
- Hz-Abschaltung
- Ww-Abschaltung
- menuEntry (menu entry of a reading on the control unit, get only)
- menuEntryHidden (1 if hidden by default, 0 if not, get only)
- dateTimeSync (set only)
- statusRequest (set only)
- ... more available but disabled by default. (
attr <name> enableAdvancedMode 1) - Be careful!
- AnalogKorrFaktor
- Ausfaelle
- Ausfall-BetriebMode
- Ausfall-Datum
- Ausfall-Di-Buffer
- Ausfall-Do-Buffer
- Ausfall-FuehlAusfall
- Ausfall-FuehlKurzsch
- Ausfall-RaumAusfall
- Ausfall-RaumKurzsch
- Ausfall-Reset
- Ausfall-Temp-Aussen
- Ausfall-Temp-Kondensator
- Ausfall-Temp-Raum
- Ausfall-Temp-Ruecklf
- Ausfall-Temp-Verdampfer
- Ausfall-Temp-Vorlauf
- Ausfall-Temp-WQu-Aus
- Ausfall-Temp-WQu-Ein
- Ausfall-Temp-WWasser
- Ausfall-Zeit
- Betriebs-Mode
- Betriebszustaende
- CPU-Boot-Datum
- CPU-Boot-Zeit
- CRC-Summe
- Datum
- Di-Buffer
- Do-Buffer
- Do-Handkanal
- Do-Handkanal-Ein
- Estrich-Aufhz
- Freigabe-Beckenwasser
- Fremdzugriff
- FuehlRaum-Ausfall
- FuehlRaum-KurzSchl
- FuehlRaum-Zaehler0
- Fuehler-Ausfall
- Fuehler-KurzSchl
- FuehlerZaehler0
- Hz
- Hz-Abschaltung
- Hz-Anhebung-Aus
- Hz-Anhebung-Ein
- Hz-Begrenzung
- Hz-Ext-Anhebung
- Hz-Ext-Freigabe
- Hz-Ext-TempRueckl-Soll
- Hz-ExtSteuerung
- Hz-Hysterese
- Hz-KlSteilheit
- Hz-Messergebnis
- Hz-PumpenNachl
- Hz-Raum-Einfluss
- Hz-SchnellAufhz
- Hz-Stufe2-Begrenzung
- Hz-Temp-BasisSoll
- Hz-Temp-Einsatz
- Hz-Temp-RaumSoll
- Hz-Zeit-Aus
- Hz-Zeit-Ein
- Kennwort
- Kompr-Mess-Reset
- KomprBeginn-Datum
- KomprBeginn-Zeit
- KomprBetrStunden
- Mess-Reset
- Messbegin-Datum
- Messbegin-Zeit
- Mode-Heizung
- Mode-Wasser
- Modem-Klingelzeichen
- Msg-* (Binary values to readable strings)
- Neu-Start
- ResetAnforderung
- Run-Flag
- Schluesselnummer
- St2-Temp-QAus-Min
- St2-Temp-Verdampfer-Min
- St2-bei-EvuAbsch
- Status-Gesamt
- Status-Heizung
- Status-Stufe2
- Status-Verriegel
- Status-WPumpe
- Status-Wasser
- Temp-Aussen
- Temp-Aussen-1h
- Temp-Aussen-24h
- Temp-Kondensator
- Temp-Raum
- Temp-Raum-1h
- Temp-Ruecklauf
- Temp-Ruecklauf-Soll
- Temp-Verdampfer
- Temp-Vorlauf
- Temp-WQuelle-Aus
- Temp-WQuelle-Ein
- Uhrzeit
- Unterbrechungen
- Unterdr-Warnung-Ausgang
- Unterdr-Warnung-Eingang
- Unterdr-Warnung-Sonstige
- Versions-Datum
- Warnung-Ausgang
- Warnung-Eingang
- Warnung-Sonstige
- Werkseinstellung
- Ww
- Ww-Abschaltung
- Ww-Becken-Hysterese
- Ww-Becken-Temp-Soll
- Ww-Hysterese
- Ww-Messergenis
- Ww-Temp
- Ww-Temp-Soll
- Ww-Zeit-Aus
- Ww-Zeit-Ein
- Zeit