The present article describes how I integrated a Buderus heat pump into a KNX smart home using the Buderus KM200 module. The primary goal was to read out the states of the device in order to understand when device is doing what and why. The secondary goal was to be able to switch between heating/cooling mode in order to switch the season (winter/summer) of the heating system globally.
The KM 200
The KM200 is a sort of cloud gateway for Buderus heating systems. With it you can get access to your heat pump through the Buderus mobile App MyDevice. The App can access the KM200 either throught the Buderus cloud or through the local network using an HTTP API. However, the local HTTP API is encrypted.
Decrypting the API
Searching through the Internet, fortunately many others already found out the detail about the used encryption. A good description can be found at web-km200. The steps described there need to be followed in order to deduce the encryption key.
The HTTP API exposes various paths that depend on the attached heating system, i.e. the heat pump model and its characteristics.
Here are the ones I found on mine:
{Id:/dhwCircuits/dhw1/charge Value:stop Writeable:true}
{Id:/dhwCircuits/dhw1/chargeDuration Value:60 Writeable:true}
{Id:/dhwCircuits/dhw1/currentSetpoint Value:50 Writeable:false}
{Id:/dhwCircuits/dhw1/holidayMode/activated Value: Writeable:false}
{Id:/dhwCircuits/dhw1/operationMode Value:high Writeable:true}
{Id:/dhwCircuits/dhw1/singleChargeSetpoint Value:60 Writeable:true}
{Id:/dhwCircuits/dhw1/status Value:ACTIVE Writeable:false}
{Id:/dhwCircuits/dhw1/temperatureLevels/high Value:50 Writeable:true}
{Id:/dhwCircuits/dhw1/temperatureLevels/low Value:45 Writeable:true}
{Id:/dhwCircuits/dhw1/temperatureLevels/off Value:0 Writeable:false}
{Id:/dhwCircuits/dhw1/waterFlow Value:0 Writeable:false}
{Id:/dhwCircuits/dhw1/workingTime Value:0 Writeable:false}
{Id:/gateway/DateTime Value:2024-01-20T20:26:02 Writeable:true}
{Id:/gateway/instAccess Value:off Writeable:true}
{Id:/gateway/instWriteAccess Value:off Writeable:true}
{Id:/gateway/logging/userAcceptance Value:false Writeable:true}
{Id:/gateway/update/status Value:completed Writeable:false}
{Id:/gateway/uuid Value:340100668 Writeable:false}
{Id:/gateway/versionFirmware Value:04.08.02 Writeable:false}
{Id:/gateway/versionHardware Value:iCom_Low_NSC_v1 Writeable:false}
{Id:/heatSources/CHpumpModulation Value:0 Writeable:false}
{Id:/heatSources/ChimneySweeper Value:off Writeable:false}
{Id:/heatSources/actualModulation Value:0 Writeable:false}
{Id:/heatSources/actualSupplyTemperature Value:42.1 Writeable:false}
{Id:/heatSources/applianceSupplyTemperature Value:44 Writeable:false}
{Id:/heatSources/burnerModulationSetpoint Value:0 Writeable:false}
{Id:/heatSources/delayTimer Value:<nil> Writeable:false}
{Id:/heatSources/emStatus Value:notConnected Writeable:false}
{Id:/heatSources/energyMonitoring/consumption Value:938361.9 Writeable:true}
{Id:/heatSources/energyMonitoring/correctionFactor Value:1 Writeable:true}
{Id:/heatSources/energyMonitoring/maxTankLevel Value:0 Writeable:true}
{Id:/heatSources/energyMonitoring/minTankLevel Value:0 Writeable:true}
{Id:/heatSources/energyMonitoring/startDateTime Value:2024-01-03T14:04:01 Writeable:false}
{Id:/heatSources/energyMonitoring/tankLevel Value:0 Writeable:true}
{Id:/heatSources/fanSpeed_setpoint Value:0 Writeable:false}
{Id:/heatSources/flameStatus Value:off Writeable:false}
{Id:/heatSources/hs1/actualModulation Value:0 Writeable:false}
{Id:/heatSources/hs1/flameStatus Value:off Writeable:false}
{Id:/heatSources/hs1/info Value:<nil> Writeable:false}
{Id:/heatSources/hs1/type Value:Heatpump Writeable:false}
{Id:/heatSources/info Value:<nil> Writeable:false}
{Id:/heatSources/nominalCHPower Value:24 Writeable:false}
{Id:/heatSources/nominalDHWPower Value:24 Writeable:false}
{Id:/heatSources/numberOfStarts Value:1396 Writeable:false}
{Id:/heatSources/poolTemperature Value:0 Writeable:false}
{Id:/heatSources/powerSetpoint Value:0 Writeable:false}
{Id:/heatSources/returnTemperature Value:37.5 Writeable:false}
{Id:/heatSources/supplyTemperatureSetpoint Value:45 Writeable:false}
{Id:/heatSources/workingTime/centralHeating Value:0 Writeable:false}
{Id:/heatSources/workingTime/secondBurner Value:0 Writeable:false}
{Id:/heatSources/workingTime/totalSystem Value:8.19162e+06 Writeable:false}
{Id:/heatingCircuits/hc1/actualSupplyTemperature Value:42.2 Writeable:false}
{Id:/heatingCircuits/hc1/currentRoomSetpoint Value:21 Writeable:false}
{Id:/heatingCircuits/hc1/currentSuWiMode Value:forced Writeable:false}
{Id:/heatingCircuits/hc1/holidayMode/activated Value: Writeable:false}
{Id:/heatingCircuits/hc1/manualRoomSetpoint Value:21 Writeable:true}
{Id:/heatingCircuits/hc1/operationMode Value:manual Writeable:true}
{Id:/heatingCircuits/hc1/pumpModulation Value:0 Writeable:false}
{Id:/heatingCircuits/hc1/roomtemperature Value:22.7 Writeable:false}
{Id:/heatingCircuits/hc1/status Value:ACTIVE Writeable:false}
{Id:/heatingCircuits/hc1/suWiSwitchMode Value:forced Writeable:true}
{Id:/heatingCircuits/hc1/supplyTemperatureSetpoint Value:45 Writeable:false}
{Id:/heatingCircuits/hc1/switchPrograms/A Value:<nil> Writeable:true}
{Id:/heatingCircuits/hc1/switchPrograms/B Value:<nil> Writeable:true}
{Id:/heatingCircuits/hc1/temperatureRoomSetpoint Value:21 Writeable:true}
{Id:/heatingCircuits/hc2/actualSupplyTemperature Value:31.6 Writeable:false}
{Id:/heatingCircuits/hc2/currentRoomSetpoint Value:21 Writeable:false}
{Id:/heatingCircuits/hc2/currentSuWiMode Value:forced Writeable:false}
{Id:/heatingCircuits/hc2/holidayMode/activated Value: Writeable:false}
{Id:/heatingCircuits/hc2/manualRoomSetpoint Value:21 Writeable:true}
{Id:/heatingCircuits/hc2/operationMode Value:manual Writeable:true}
{Id:/heatingCircuits/hc2/pumpModulation Value:100 Writeable:false}
{Id:/heatingCircuits/hc2/roomtemperature Value:22.7 Writeable:false}
{Id:/heatingCircuits/hc2/status Value:ACTIVE Writeable:false}
{Id:/heatingCircuits/hc2/suWiSwitchMode Value:forced Writeable:true}
{Id:/heatingCircuits/hc2/supplyTemperatureSetpoint Value:30 Writeable:false}
{Id:/heatingCircuits/hc2/switchPrograms/A Value:<nil> Writeable:true}
{Id:/heatingCircuits/hc2/switchPrograms/B Value:<nil> Writeable:true}
{Id:/heatingCircuits/hc2/temperatureRoomSetpoint Value:21 Writeable:true}
{Id:/notifications Value:<nil> Writeable:false}
{Id:/recordings/dhwCircuits/dhw1/actualTemp Value:<nil> Writeable:false}
{Id:/recordings/heatSources/total/energyMonitoring/compressor Value:<nil> Writeable:false}
{Id:/recordings/heatSources/total/energyMonitoring/consumedEnergy Value:<nil> Writeable:false}
{Id:/recordings/heatSources/total/energyMonitoring/eheater Value:<nil> Writeable:false}
{Id:/recordings/heatSources/total/energyMonitoring/outputProduced Value:<nil> Writeable:false}
{Id:/recordings/heatingCircuits/hc1/roomtemperature Value:<nil> Writeable:false}
{Id:/recordings/heatingCircuits/hc2/roomtemperature Value:<nil> Writeable:false}
{Id:/recordings/system/sensors/temperatures/outdoor_t1 Value:<nil> Writeable:false}
{Id:/system/appliance/actualSupplyTemperature Value:42.2 Writeable:false}
{Id:/system/brand Value:Buderus Writeable:false}
{Id:/system/bus Value:EMS2_0 Writeable:false}
{Id:/system/healthStatus Value:ok Writeable:false}
{Id:/system/holidayModes/hm1/assignedTo Value:<nil> Writeable:true}
{Id:/system/holidayModes/hm1/dhwMode Value:OFF Writeable:true}
{Id:/system/holidayModes/hm1/fixTemperature Value:17 Writeable:true}
{Id:/system/holidayModes/hm1/hcMode Value:FIX_TEMP Writeable:true}
{Id:/system/holidayModes/hm1/startStop Value:2017-01-01/2017-01-01 Writeable:true}
{Id:/system/holidayModes/hm2/assignedTo Value:<nil> Writeable:true}
{Id:/system/holidayModes/hm2/dhwMode Value:OFF Writeable:true}
{Id:/system/holidayModes/hm2/fixTemperature Value:17 Writeable:true}
{Id:/system/holidayModes/hm2/hcMode Value:FIX_TEMP Writeable:true}
{Id:/system/holidayModes/hm2/startStop Value:2017-01-01/2017-01-01 Writeable:true}
{Id:/system/holidayModes/hm3/assignedTo Value:<nil> Writeable:true}
{Id:/system/holidayModes/hm3/dhwMode Value:OFF Writeable:true}
{Id:/system/holidayModes/hm3/fixTemperature Value:17 Writeable:true}
{Id:/system/holidayModes/hm3/hcMode Value:FIX_TEMP Writeable:true}
{Id:/system/holidayModes/hm3/startStop Value:2017-01-01/2017-01-01 Writeable:true}
{Id:/system/holidayModes/hm4/assignedTo Value:<nil> Writeable:true}
{Id:/system/holidayModes/hm4/dhwMode Value:OFF Writeable:true}
{Id:/system/holidayModes/hm4/fixTemperature Value:17 Writeable:true}
{Id:/system/holidayModes/hm4/hcMode Value:FIX_TEMP Writeable:true}
{Id:/system/holidayModes/hm4/startStop Value:2017-01-01/2017-01-01 Writeable:true}
{Id:/system/holidayModes/hm5/assignedTo Value:<nil> Writeable:true}
{Id:/system/holidayModes/hm5/dhwMode Value:OFF Writeable:true}
{Id:/system/holidayModes/hm5/fixTemperature Value:17 Writeable:true}
{Id:/system/holidayModes/hm5/hcMode Value:FIX_TEMP Writeable:true}
{Id:/system/holidayModes/hm5/startStop Value:2017-01-01/2017-01-01 Writeable:true}
{Id:/system/info Value:<nil> Writeable:false}
{Id:/system/minOutdoorTemp Value:-10 Writeable:true}
{Id:/system/sensors/temperatures/outdoor_t1 Value:-1.5 Writeable:false}
{Id:/system/sensors/temperatures/return Value:37.6 Writeable:false}
{Id:/system/sensors/temperatures/supply_t1 Value:42.2 Writeable:false}
{Id:/system/sensors/temperatures/supply_t1_setpoint Value:45 Writeable:false}
{Id:/system/sensors/temperatures/switch Value:42.2 Writeable:false}
{Id:/system/systemType Value:NSC_ICOM_GATEWAY Writeable:false}
Accessing the API with Node-RED
Once the encryption key has been deduced it is easy to create a flow in Node-RED to access the API.
timestamp issues a timestamp every 20s to trigger the API read at a certain interval.
setup Request defines the combinations of the API paths, the KNX group address and the KNX datapoint type (DTP). This generates one request for every path.
limit 5 msg/s slows the request chain down so that at max 5 requests/s go towards the KM200.
Request KM200 issues an HTTP request towards the API
statusCode2XX checks that the returned HTTP status code is 2XX
decode payload decodes the payload in order to get the real value
KNX Device sends the value to the specified KNX group address through a connected KNX IP interface
The complete flow can be downloaded here: node-red-flow.json.
In order for the flow to work search for <KM200-IP-ADDRESS> and <ENCRYPTION-KEY> and replace them accordingly.
The flow has the following javascript dependencies:
- mcrypt
- buffertrim
and the following node-red module dependencies:
- node-red-contrib-knx
- node-red-contrib-knx-ultimate
