esphome-docs/components/sensor/kamstrup_kmp.rst
Chris Feenstra c02f4106d8
Kamstrup KMP (#3513)
Co-authored-by: Chris Feenstra <chris@cfeenstra.nl>
Co-authored-by: H. Árkosi Róbert <robreg@zsurob.hu>
Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
2024-03-13 16:01:26 +13:00

121 lines
4.6 KiB
ReStructuredText

Kamstrup Meter Protocol [KMP]
=============================
.. figure:: images/kamstrup_kmp.jpg
:scale: 75%
Kamstrup MULTICAL 403
The Kamstrup Meter Protocol (KMP) is used by certain Kamstrup utility
meters and can be used to read measurements from the meter.
For example, the Kamstrup MULTICAL 403 is a meter used by some energy
companies in The Netherlands to measure delivered heat by a district heating
network (in Dutch: stadsverwarming).
Heat is transported using warm water to the consumer. The meter measures
the temperature of the water delivered and returned as well as the water
flow. This is used to calculate the consumed energy, typically in giga
joule (GJ).
The Kamstrup Multical has an optical interface just above the display
that uses the Kamstrup Meter Protocol for communication.
This component can be used to request measurements from the meter using
the optical interface.
A :ref:`UART bus <uart>` is required to communicate with the meter. The baudrate
Configuration
-------------
.. code-block:: yaml
# Example configuration entry
sensor:
- platform: kamstrup_kmp
heat_energy:
name: Heat Energy
power:
name: Heat Power
temp_diff:
name: Heat Temperature Difference
flow:
name: Heat Flow
custom:
- name: Custom Heat Energy
command: 0x003C
- name: Custom Heat Power
command: 0x0050
Configuration variables:
- **heat_energy** (*Optional*): Heat energy delivered.
All options from :ref:`Sensor <config-sensor>`.
- **power** (*Optional*): Current power delivered.
All options from :ref:`Sensor <config-sensor>`.
- **temp1** (*Optional*): Temperatue of sensor 1.
All options from :ref:`Sensor <config-sensor>`.
- **temp2** (*Optional*): Temperatue of sensor 2.
All options from :ref:`Sensor <config-sensor>`.
- **temp_diff** (*Optional*): Temperature difference between the 2 sensors.
All options from :ref:`Sensor <config-sensor>`.
- **flow** (*Optional*): Water flow.
All options from :ref:`Sensor <config-sensor>`.
- **volume** (*Optional*): Volume.
All options from :ref:`Sensor <config-sensor>`.
- **custom** (*Optional*): List of custom sensors.
- **command** (**Required**, 2-byte hex): The KMP command code (e.g. 0x003C).
- All other options from :ref:`Sensor <config-sensor>`.
- **update_interval** (*Optional*): The polling interval. Defaults to ``60s``.
.. note::
- The uart baudrate has to be set to 1200 baud and the stop bits to 2.
It is recommended to use pins associated with a hardware UART.
For more information regarding uart configuration, refer to :ref:`UART <uart>`.
- Only the provided sensors will appear as sensor, and only those are read from
the meter.
- Custom sensors can be used to receive measurements from the Kampstrup meter,
other than the ones provided natively with this component. To request extra
measurements, add one or multiple sensors to the ``custom`` setting and provide the
KMP command. This command is a 2 byte integer value. For example ``0x003C`` is
the command code for heat energy. In the example above, two custom sensors were
added. These request the Heat Energy and Heat Power respectively. This will be the
same as the native ``heat_energy`` and ``power`` sensors.
- Keep in mind that the meter is battery operated. The more sensors read and the
lower the update interval, the faster the battery will drain.
Hardware
--------
The Kamstrup meter uses an optical interface, just above the display. The required
optical transceiver can be made using the schematic below. Connect the RX and TX
lines to the pins configured under the uart section in the config file. In the
configuration example above, this would be GPIO pin 13 and 15 respectively.
.. figure:: images/kamstrup_kmp_sch.svg
:scale: 200%
Optical reader schematic
To safe energy, the optical interface of the Kamstrup meter is not active by default.
To activate the interface, press a button on the device. The interface will now be
available for a few minutes. To keep the interface alive, magnets must be placed
around the LED / photo diode. The image below shows the arrangement. The green
circles are the LED and photo diode, which must be placed exactly on top of the
optical interface window of the meter. The red circles indicate 6mm neodymium
magnets.
.. figure:: images/kamstrup_kmp_holder.svg
Magnet arrangement
See Also
--------
- :ref:`config-sensor`
- `DIY hardware with housing <https://github.com/cfeenstra1024/kamstrup-multical-hardware#readme>`__ by `Chris Feenstra <https://github.com/cfeenstra1024>`__
- :ghedit:`Edit`