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>

components/sensor/images/kamstrup_kmp_holder.svg

@@ -0,0 +1,88 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   viewBox="0 0 125.72441 125.72436"
+   width="125.72441"
+   height="125.72436"
+   version="1.1"
+   id="svg7268"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg">
+  <desc
+     id="desc7230">plate.dxf - scale = 1.0, origin = (0.0, 0.0), method = manual</desc>
+  <defs
+     id="defs7244">
+    <marker
+       id="DistanceX"
+       orient="auto"
+       refX="0"
+       refY="0"
+       style="overflow:visible">
+      <path
+         d="M 3,-3 -3,3 M 0,-5 V 5"
+         style="stroke:#000000;stroke-width:0.5"
+         id="path7232" />
+    </marker>
+    <pattern
+       id="Hatch"
+       patternUnits="userSpaceOnUse"
+       width="8"
+       height="8"
+       x="0"
+       y="0">
+      <path
+         d="M8 4 l-4,4"
+         stroke="#000000"
+         stroke-width="0.25"
+         linecap="square"
+         id="path7235" />
+      <path
+         d="M6 2 l-4,4"
+         stroke="#000000"
+         stroke-width="0.25"
+         linecap="square"
+         id="path7237" />
+      <path
+         d="M4 0 l-4,4"
+         stroke="#000000"
+         stroke-width="0.25"
+         linecap="square"
+         id="path7239" />
+    </pattern>
+    <symbol
+       id="*MODEL_SPACE" />
+    <symbol
+       id="*PAPER_SPACE" />
+  </defs>
+  <g
+     id="g7266"
+     transform="translate(62.862205,-1059.6575)">
+    <path
+       d="m 62.362205,1122.5197 a 62.362205,62.362205 0 1 0 -124.72441,0 62.362205,62.362205 0 1 0 124.72441,0 z"
+       style="fill:none;stroke:#000000"
+       id="path7246" />
+    <path
+       d="m -18.059243,1151.9175 a 11.338583,11.338583 0 1 0 -22.677165,0 11.338583,11.338583 0 1 0 22.677165,0 z"
+       style="fill:#800000;stroke:#000000"
+       id="path7250" />
+    <path
+       d="m 40.736408,1151.9175 a 11.338583,11.338583 0 1 0 -22.677165,0 11.338583,11.338583 0 1 0 22.677165,0 z"
+       style="fill:#800000;stroke:#000000"
+       id="path7252" />
+    <path
+       d="m 40.736408,1093.1219 a 11.338583,11.338583 0 1 0 -22.677165,0 11.338583,11.338583 0 1 0 22.677165,0 z"
+       style="fill:#800000;stroke:#000000"
+       id="path7254" />
+    <path
+       d="m -18.059243,1093.1219 a 11.338583,11.338583 0 1 0 -22.677165,0 11.338583,11.338583 0 1 0 22.677165,0 z"
+       style="fill:#800000;stroke:#000000"
+       id="path7256" />
+    <path
+       d="m -3.779528,1122.5197 a 9.448819,9.448819 0 1 0 -18.897637,0 9.448819,9.448819 0 1 0 18.897637,0 z"
+       style="fill:#008000;stroke:#000000"
+       id="path7262" />
+    <path
+       d="m 22.677165,1122.5197 a 9.448819,9.448819 0 1 0 -18.897637,0 9.448819,9.448819 0 1 0 18.897637,0 z"
+       style="fill:#008000;stroke:#000000"
+       id="path7264" />
+  </g>
+</svg>

components/sensor/kamstrup_kmp.rst

@@ -0,0 +1,120 @@
+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`

index.rst

@@ -282,6 +282,7 @@ Electricity
     INA226, components/sensor/ina226, ina226.jpg, DC Current & Power
     INA260, components/sensor/ina260, ina260.jpg, DC Current & Power
     INA3221, components/sensor/ina3221, ina3221.jpg, 3-Ch DC current
+    Kamstrup KMP, components/sensor/kamstrup_kmp, kamstrup_kmp.jpg, District Heating Meter
     MAX9611, components/sensor/max9611, max9611.jpg, +60VDC Voltage & Current & Power & Temperature
     PZEM AC, components/sensor/pzemac, pzem-ac.jpg, Voltage & Current & Power
     PZEM DC, components/sensor/pzemdc, pzem-dc.jpg, Voltage & Current & Power