Add docs for SML (#1493)

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>

components/sml.rst

@@ -0,0 +1,179 @@
+SML (Smart Message Language)
+============================
+
+.. seo::
+    :description: Instructions for setting up SML sensors
+    :image: sml.svg
+    :keywords: sml
+
+The ``SML`` component connects to smart meters which use the *Smart Message Language* (SML) protocol.
+
+Although the SML protocol is well defined, it gives a lot of freedom to the manufacturers how to store
+and identify the transmitted data. Within a telegram the physical values are identified by *OBIS* codes
+(Object Identification System). If it is known which code the manufacturer assigns to the physical value,
+the corresponding value can be extracted.
+
+Hardware
+--------
+
+This component is passive, it does not transmit any data to your equipment. Usually a smart meter transmit
+a telegram at regular intervals (2-4 seconds) on its own.
+This component decodes and updates the configured sensors at the pace the data is received.
+
+Most smart meters transmit the telegrams using an infrared optical interface. As a sensor a  suitable photo
+transistor (e.g. BPW40) can be attached to the ESP's UART (emitter to `GND` and collector to `RX` pin). A more
+mature solution can be found `here
+<https://wiki.volkszaehler.org/hardware/controllers/ir-schreib-lesekopf-ttl-ausgang>`_ (in German).
+There are plenty of other examples and ready to buy solutions on the web.
+
+Configuration
+-------------
+
+As the communciation with the sensor is done using UART, you need to have the :ref:`UART bus <uart>`
+in your configuration. The interface parameters should be set to 9600/8N1 or 9600/7E1 depending on your
+smart meter. If you see checksum errors in the log try changing the interface parameter.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    uart:
+      id: uart_bus
+      rx_pin: GPIO3
+      baud_rate: 9600
+      data_bits: 8
+      parity: NONE
+      stop_bits: 1
+
+    sml:
+      id: mysml
+      uart_id: uart_bus
+
+    sensor:
+      - platform: sml
+        name: "Total energy"
+        sml_id: mysml
+        server_id: "0123456789abcdef"
+        obis_code: "1-0:1.8.0"
+        unit_of_measurement: kWh
+        accuracy_decimals: 1
+        device_class: energy
+        state_class: total_increasing
+        filters:
+          - multiply: 0.0001
+
+    text_sensor:
+      - platform: sml
+        name: "Manufacturer"
+        sml_id: mysml
+        server_id: "0123456789abcdef"
+        obis_code: "129-129:199.130.3"
+        format: text
+
+
+Configuration variables:
+------------------------
+
+.. _sml-platform:
+
+SML platform
+************
+
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
+- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`UART Component <uart>` if you want
+  to use multiple UART buses.
+
+Sensor
+******
+
+- **obis_code** (*Required*, string): Specify the OBIS code you want to retrieve data for from the device.
+  The format must be (A-B:C.D.E, e.g. 1-0:1.8.0)
+- **server_id** (*Optional*, string): Specify the device's server_id to retrieve the OBIS code from. Should be specified if more then one device is connected to the same hardware sensor component.
+- **sml_id** (*Optional*, :ref:`config-id`): The ID of the :ref:`SML platform <sml-platform>`
+- All other options from :ref:`Sensor <config-sensor>`.
+
+Text Sensor
+***********
+
+- **obis_code** (*Required*, string): Specify the OBIS code you want to retrieve data for from the device.
+  The format must be (A-B:C.D.E, e.g. 1-0:1.8.0)
+- **server_id** (*Optional*, string): Specify the device's server_id to retrieve the OBIS code from. Should be specified if more then one device is connected to the same hardware sensor component.
+- **sml_id** (*Optional*, :ref:`config-id`): The ID of the :ref:`SML platform <sml-platform>`
+- **format** (*Optional*, string): Override the automatic interpretation of the transmitted binary data value. Possible values (`int`, `uint`, `bool`, `hex`, `text`).
+- All other options from :ref:`Text Sensor <config-text_sensor>`.
+
+
+Getting OBIS codes and sensor ids
+---------------------------------
+
+The physical values in the transmitted SML telegram are identified by a *server id* and *OBIS codes*. The *server id*
+identifies your smart meter. If you have only one hardware component attached to your optical sensor you usually
+don't have to care about the server id and you may ommit it in your configuration.
+
+In order to get the server id and the available OBIS codes provided by your smart meter, simply set up the
+:ref:`SML platform <sml-platform>` and observe the log output (the :ref:`log level <logger-log_levels>`
+must be set to at least ``debug``!).
+
+Your log output will show something like this:
+
+.. figure:: images/sml-log.png
+    :align: center
+    :width: 100.0%
+
+    OBIS information in the log of the `SML` component
+
+Each line represents a combination of the server id (in brackets), the OBIS code and the transmitted hex value
+(in square brackets).
+
+
+Precision errors
+----------------
+Many smart meters emit very huge numbers for certain OBIS codes (like the accumulated total active energy).
+This may lead to precision errors for the values reported by the sensor component to ESPHome. This shows in
+the fact that slightly wrong numbers may be reported to HomeAssistant. This is a result from internal limitations
+in ESPHome and has nothing to do with the SML component.
+
+If you cannot live with this, you can use the `TextSensor` with an appropriate format to transmit the value as
+a string to HomeAssistant. On the HomeAssistant side you can define a `Template Sensor <https://www.home-assistant.io/integrations/template/>`_
+to cast the value into the appropriate format and do some scaling.
+
+For ESPHome we have:
+
+.. code-block:: yaml
+
+    # ESPHome configuration file
+    text_sensor:
+      - platform: sml
+        name: "Total energy text"
+        obis_code: "1-0:1.8.0"
+        format: uint
+
+The `format` parameter is optional. If ommited, the SML component will try to guess the correct datatype
+from the received SML message.
+
+And in HomeAssistant:
+
+.. code-block:: yaml
+
+    # Home Assistant configuration.yaml
+    template:
+      - sensor:
+          - name: "Total Energy Consumption"
+            unit_of_measurement: "kWh"
+            state: >
+              {% if states('sensor.total_energy_text') == 'unavailable' %}
+                {{ states('sensor.total_energy_consumption') }}
+              {% else %}
+                {{ ((states('sensor.total_energy_text') | float) * 0.0001) | round(2) }}
+              {% endif %}
+
+Usually the template sensor's value would turn to 0 if the ESP device is unavailable.
+This results in problems when using the sensor in combination with the `Utility Meter <https://www.home-assistant.io/integrations/utility_meter/>`_ integration.
+The state template provided above checks for the sensor's availability and keeps the
+current state in case of unavailability.
+
+
+See Also
+--------
+
+- :apiref:`sml/sml.h`
+- :ghedit:`Edit`

images/sml.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="124" height="60" version="1.1"><path d="M20.49 1.333H104c10.31 0 18.667 8.358 18.667 18.667v20.667c0 10.309-8.358 18.666-18.667 18.666H20.49c-10.31 0-18.668-8.357-18.668-18.666V20c0-10.31 8.358-18.667 18.667-18.667z"/><path d="M20.49 1.333H104c10.31 0 18.667 8.358 18.667 18.667v20.667c0 10.309-8.358 18.666-18.667 18.666H20.49c-10.31 0-18.668-8.357-18.668-18.666V20c0-10.31 8.358-18.667 18.667-18.667z" fill="none" stroke="#000" stroke-linecap="round" stroke-linejoin="round" stroke-miterlimit="10" stroke-width="1.333"/><g transform="translate(1.0749 2.0002)" fill="#fff"><path d="m24.374 45.413c-2.7067 0-5.351-0.29567-7.933-0.887-2.5513-0.622-4.6513-1.4463-6.3-2.473l3.547-8.027c1.5553 0.902 3.2973 1.633 5.226 2.193 1.9293 0.52933 3.7807 0.794 5.554 0.794 1.524 0 2.6127-0.14 3.266-0.42 0.65333-0.31133 0.98-0.76267 0.98-1.354 0-0.684-0.43533-1.1973-1.306-1.54-0.84-0.342-2.24-0.71533-4.2-1.12-2.52-0.52867-4.62-1.0887-6.3-1.68-1.68-0.622-3.1423-1.6173-4.387-2.986-1.2447-1.4-1.867-3.2823-1.867-5.647 0-2.0533 0.57567-3.92 1.727-5.6s2.8623-3.0023 5.133-3.967c2.3027-0.964 5.0873-1.446 8.354-1.446 2.24 0 4.4333 0.24867 6.58 0.746 2.1773 0.46667 4.0907 1.1667 5.74 2.1l-3.314 7.98c-3.204-1.6173-6.2373-2.426-9.1-2.426-2.8307 0-4.246 0.68433-4.246 2.053 0 0.65333 0.42 1.151 1.26 1.493 0.84 0.31133 2.2243 0.65367 4.153 1.027 2.4887 0.46667 4.5887 1.011 6.3 1.633 1.7113 0.59133 3.189 1.5713 4.433 2.94 1.276 1.3693 1.914 3.236 1.914 5.6 0 2.0533-0.57567 3.92-1.727 5.6-1.1513 1.6493-2.878 2.9717-5.18 3.967-2.2713 0.96467-5.0403 1.447-8.307 1.447z" aria-label="SPL"/><path d="m73.238 45.37-0.093-15.528-7.093 12.462h-4.854l-7.093-11.927v14.993h-10.033v-34.075h9.053l10.64 18.157 10.36-18.157h9.053l0.094 34.075z" stroke-width="1.0213"/><path d="m87.756 11.295h10.45v25.168h13.992v8.9085h-24.442z" stroke-width=".99488"/></g></svg>

index.rst

@@ -679,6 +679,7 @@ Misc Components
     Prometheus, components/prometheus, prometheus.svg
     PipSolar - compatible PV Inverter, components/pipsolar, pipsolar.jpg
     Grow Fingerprint Reader, components/fingerprint_grow, fingerprint.svg
+    SML, components/sml, sml.svg
     Demo, components/demo, description.svg
     Copy, components/copy, content-copy.svg