ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
kamstrup_kmp.h
Go to the documentation of this file.
1#pragma once
2
3#include <queue>
7
8namespace esphome::kamstrup_kmp {
9
10/*
11 ===========================================================================
12 === KAMSTRUP KMP ===
13 ===========================================================================
14
15 Kamstrup Meter Protocol (KMP) is a protocol used with Kamstrup district
16 heating meters, e.g. Kamstrup MULTICAL 403.
17 These devices register consumed heat from a district heating system.
18 It does this by measuring the incoming and outgoing water temperature
19 and by measuring the water flow. The temperature difference (delta T)
20 together with the water flow results in consumed energy, typically
21 in giga joule (GJ).
22
23 The Kamstrup Multical has an optical interface just above the display.
24 This interface is essentially an RS-232 interface using a proprietary
25 protocol (Kamstrup Meter Protocol [KMP]).
26
27 The integration uses this optical interface to periodically read the
28 configured values (sensors) from the meter. Supported sensors are:
29 - Heat Energy [GJ]
30 - Current Power Consumption [kW]
31 - Temperature 1 [°C]
32 - Temperature 2 [°C]
33 - Temperature Difference [°K]
34 - Water Flow [l/h]
35 - Volume [m3]
36
37 Apart from these supported 'fixed' sensors, the user can configure up to
38 five custom sensors. The KMP command (16 bit unsigned int) has to be
39 provided in that case.
40
41 Note:
42 The optical interface is enabled as soon as a button on the meter is pushed.
43 The interface stays active for a few minutes. To keep the interface 'alive'
44 magnets must be placed around the optical sensor.
45
46 Units:
47 Units are set using the regular Sensor config in the user yaml. However,
48 KMP does also send the correct unit with every value. When DEBUG logging
49 is enabled, the received value with the received unit are logged.
50
51 Acknowledgement:
52 This interface was inspired by:
53 - https://atomstar.tweakblogs.net/blog/19110/reading-out-kamstrup-multical-402-403-with-home-built-optical-head
54 - https://wiki.hal9k.dk/projects/kamstrup
55*/
56
57// KMP Commands
58static const uint16_t CMD_HEAT_ENERGY = 0x003C;
59static const uint16_t CMD_POWER = 0x0050;
60static const uint16_t CMD_TEMP1 = 0x0056;
61static const uint16_t CMD_TEMP2 = 0x0057;
62static const uint16_t CMD_TEMP_DIFF = 0x0059;
63static const uint16_t CMD_FLOW = 0x004A;
64static const uint16_t CMD_VOLUME = 0x0044;
65
67 public:
68 SUB_SENSOR(heat_energy)
69 SUB_SENSOR(power)
70 SUB_SENSOR(temp1)
71 SUB_SENSOR(temp2)
72 SUB_SENSOR(temp_diff)
73 SUB_SENSOR(flow)
74 SUB_SENSOR(volume)
75 void dump_config() override;
76 void update() override;
77 void loop() override;
78 void add_custom_sensor(sensor::Sensor *sensor, uint16_t command) {
79 this->custom_sensors_.push_back(sensor);
80 this->custom_commands_.push_back(command);
81 }
82
83 protected:
84 // Custom sensors and commands
85 std::vector<sensor::Sensor *> custom_sensors_;
86 std::vector<uint16_t> custom_commands_;
87
88 // Command queue
89 std::queue<uint16_t> command_queue_;
90
91 // Methods
92
93 // Sends a command to the meter and receives its response
94 void send_command_(uint16_t command);
95 // Sends a message to the meter. A prefix/suffix and CRC are added
96 void send_message_(const uint8_t *msg, int msg_len);
97 // Clears and data that might be in the UART Rx buffer
98 // Reads and validates the response to a send command
99 void read_command_(uint16_t command);
100 // Parses a received message
101 void parse_command_message_(uint16_t command, const uint8_t *msg, int msg_len);
102 // Sets the received value to the correct sensor
103 void set_sensor_value_(uint16_t command, float value, uint8_t unit_idx);
104};
105
106} // namespace esphome::kamstrup_kmp
virtual void dump_config()
This class simplifies creating components that periodically check a state.
Definition component.h:532
void set_sensor_value_(uint16_t command, float value, uint8_t unit_idx)
void add_custom_sensor(sensor::Sensor *sensor, uint16_t command)
std::vector< sensor::Sensor * > custom_sensors_
SUB_SENSOR(heat_energy) SUB_SENSOR(power) SUB_SENSOR(temp1) SUB_SENSOR(temp2) SUB_SENSOR(temp_diff) SUB_SENSOR(flow) SUB_SENSOR(volume) void dump_config() override
void parse_command_message_(uint16_t command, const uint8_t *msg, int msg_len)
void send_message_(const uint8_t *msg, int msg_len)
Base-class for all sensors.
Definition sensor.h:48
uint32_t value
Definition hal.cpp:41