[bl0940] document new configuration options

components/index.rst

@@ -320,7 +320,7 @@ Electricity
     ATM90E32, components/sensor/atm90e32, atm90e32.jpg, Voltage & Current & Power
     BL0906, components/sensor/bl0906, bl0906.png, Voltage & Current & Power & Energy
     BL0939, components/sensor/bl0939, bl0939.png, Voltage & Current & Power & Energy
-    BL0940, components/sensor/bl0940, bl0940.png, Voltage & Current & Power
+    BL0940, components/sensor/bl0940, bl0940.png, Voltage & Current & Power & Energy
     BL0942, components/sensor/bl0942, bl0942.png, Voltage & Current & Power
     CS5460A, components/sensor/cs5460a, cs5460a.png, Voltage & Current & Power
     CSE7761, components/sensor/cse7761, cse7761.svg, Voltage & Current & Power

components/sensor/bl0940.rst

@@ -6,15 +6,8 @@ Belling BL0940 Energy Monitor
     :image: bl0940.png
     :keywords: BL0940
 
-.. note::
-
-    This page is incomplete and could some work. If you want to contribute, please see our
-    `developer site <https://developers.esphome.io>`__. This page is missing:
-
-      - Images/screenshots/example configs of this device being used in action.
-
 The ``bl0940`` sensor platform allows you to use BL0940 energy monitors sensors with
-ESPHome. These are used in some Tuya-devices (e.g. the power metering BW-SHP10)
+ESPHome. These are used in some Tuya-devices (e.g. the power metering BW-SHP10) and the Vaiotech Rowi2 Smart Plug
 
 The communication with this component is done via a :ref:`UART <uart>`.
 You must therefore have a ``uart:`` entry in your configuration with both the TX and RX pins set
@@ -50,6 +43,12 @@ to some pins on your board and the baud rate set to 4800 with 1 stop bit.
 Configuration variables:
 ------------------------
 
+- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`UART Component <uart>` if you want
+  to use multiple UART buses.
+- **tuya_mode** (*Optional*, boolean): Whether to use the tuya configuration from initial implementation.
+  Defaults to ``true`` to prevent breaking change.
+- **read_command** (*Optional*): The byte used for the read commands when communicating with the BL0940. By default, it is set to ``0x58`` or ``0x50`` in ``tuya_mode``.
+- **write_command** (*Optional*): byte used for the write commands when communicating with the BL0940. By default, it is set to ``0xA8`` or ``0xA0`` in ``tuya_mode``.
 - **voltage** (*Optional*): The voltage value of the sensor in Volts.
   All options from :ref:`Sensor <config-sensor>`.
 - **current** (*Optional*): The current value of the sensor in Amperes. All options from
@@ -64,8 +63,208 @@ Configuration variables:
   All options from :ref:`Sensor <config-sensor>`.
 - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
   sensor. Defaults to ``60s``.
-- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`UART Component <uart>` if you want
-  to use multiple UART buses.
+
+- **reference_voltage** (*Optional*, float): The calibration parameter for Vref. Defaults to ``1.218``.
+- **resistor_shunt** (*Optional*, float): The calibration parameter for RL. Defaults to ``1``.
+- **resistor_one** (*Optional*, float): The calibration parameter for R1. Defaults to ``0.51``.
+- **resistor_two** (*Optional*, float): The calibration parameter for R2. Defaults to ``1950``.
+
+- **voltage_reference** (*Optional*, float): The calibration parameter for voltage readings. Defaults to ``266013.136288998`` as calculated using schema defaults.
+- **current_reference** (*Optional*, float): The calibration parameter for current readings. Defaults to ``17158.9201389365`` as calculated using schema defaults.
+- **power_reference** (*Optional*, float): The calibration parameter for power readings. Defaults to ``713.104696500825`` as calculated using schema defaults.
+- **energy_reference** (*Optional*, float): The calibration parameter for cumulative energy readings. Defaults to ``6120.6267056536`` as calculated using schema defaults.
+
+.. _bl0940-calibration:
+
+Calibration
+-----------
+
+There are two fundamental calibration parameters which are dependent on the hardware design: ``voltage_reference`` and ``current_reference``.
+
+These can be determined by inspecting the actual hardware design or by using an accurate voltage and current meter with a simple resistive load
+
+Available calibration options:
+
+.. code-block:: yaml
+
+    # schematic option defaults
+    reference_voltage: 1.218  # Vref = 1.218
+    resistor_shunt: 1         # RL = 1 mΩ
+    resistor_one: 0.51        # R1 = 0.51 kΩ
+    resistor_two: 1950        # R2 = 5 x 390 kΩ -> 1950 kΩ
+
+Default values are based on `BL0940_APPNote_TSSOP14_V1.04_EN.pdf <https://www.belling.com.cn/media/file_object/bel_product/BL0940/guide/BL0940_APPNote_TSSOP14_V1.04_EN.pdf>`__.
+
+By default all the reference values will be calculated using the above values in the exact order shown below.
+
+.. code-block:: cpp
+
+    this->voltage_reference_ = 79931 / this->vref_ * (this->r_one_ * 1000) / (this->r_one_ + this->r_two_);
+    this->current_reference_ = 324004 * this->r_shunt_ / this->vref_;
+
+    // if voltage reference and current_reference have been configured
+    this->power_reference_ = this->voltage_reference_ * this->current_reference_ * 4046 / 324004 / 79931;
+    // if not, we use this formula based on provided formula in the specification
+    this->power_reference_ = 4046 * this->r_shunt_ * this->r_one_ * 1000 / this->vref_ / this->vref_ / (this->r_one_ + this->r_two_);
+
+    this->energy_reference_ = this->power_reference_ * 3600000 / (1638.4 * 256);
+
+If ``tuya_mode`` is enabled the reference values will be set according to initial implementation.
+
+.. code-block:: cpp
+
+    this->voltage_reference_ = 33000;
+    this->current_reference_ = 275000;
+    this->power_reference_   = 1430;
+    this->energy_reference_  = 3.6e6 / 297;
+
+Any of the reference values is configurable and will take precedence over the calculated or predefined values.
+
+Theoreticaly configuring ``voltage_reference`` and ``current_reference`` should be enough to calibrate the sensors but for completeness ``power_reference`` and ``energy_reference`` are also configurable.
+
+.. code-block:: yaml
+
+    # custom references
+    voltage_reference: 17158.9201389365
+    current_reference: 266013.136288998
+    power_reference:   713.104696500825
+    energy_reference:  6120.6267056536
+
+Online Calibration
+------------------
+
+It is possible to adjust the sensor readings without need to update sensor configuration using the provided number platform.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    sensor:
+      - platform: bl0940
+        id: bl0940_id
+        uart_id: uart_bus
+        ...
+
+    number:
+      - platform: bl0940
+        bl0940_id: bl0940_id
+        current_calibration:
+          name: Current Calibration
+        voltage_calibration:
+          name: Voltage Calibration
+        power_calibration:
+          name: Power Calibration
+        energy_calibration:
+          name: Energy Calibration
+
+Configuration variables:
+************************
+- **bl0940_id** (*Required*, :ref:`config-id`): Manually specify the ID of the `BL0940 Sensor Component`
+- **current_calibration** (*Optional*): Enables current calibration configuration.
+- **voltage_calibration** (*Optional*): Enables voltage calibration configuration.
+- **power_calibration** (*Optional*): Enables power calibration configuration.
+- **energy_calibration** (*Optional*): Enables energy calibration configuration.
+
+Calibration variables:
+**********************
+- **min_value** (*Optional*, float): The minimum value this number can be. Minimal allowed value is ``-50`` defaults to ``-10``.
+- **max_value** (*Optional*, float): The maximum value this number can be. Maiximal allowed value is ``50`` defaults to ``10``.
+- **step** (*Optional*, float): The granularity with which the number can be set. Defaults to ``0.1``.
+- **restore_value** (*Optional*, boolean): Saves and loads the state to RTC/Flash. Defaults to ``True``
+- All other options from :ref:`Number <config-number>`.
+
+.. note::
+
+    There are some fixed values defined:
+
+    - **unit_of_measurement**: `UNIT_PERCENT`
+    - **mode**: `BOX`
+    - **initial_value**: ``0``
+
+Calibration details:
+********************
+Calibration factor is calculated in ``%`` based on submitted value from the configured ``calibration`` component.
+
+.. code-block:: cpp
+
+    float BL0940::calculate_calibration_value_(float state) { return (100 + state) / 100; }
+
+When changing calibration values on the UI all calibrated reference values will be recalculated.
+
+``voltage_calibration`` and ``current_calibration`` will affect ``power_reference`` and ``energy_reference`` if they have not been specified manually.
+
+Reset Calibration:
+******************
+To reset all external calibration values to their initial state you can use the provided calibration reset button
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    sensor:
+      - platform: bl0940
+        id: bl0940_id
+        uart_id: uart_bus
+        ...
+
+    button:
+      - platform: bl0940
+        bl0940_id: bl0940_id
+        name: Reset Calibration
+
+Configuration variables:
+************************
+- **bl0940_id** (*Required*, :ref:`config-id`): Manually specify the ID of the `BL0940 Sensor Component`
+- All other options from :ref:`Button <config-button>`.
+
+.. figure:: images/bl0940-cal.png
+    :align: center
+    :width: 80.0%
+
+
+Sample full configuration:
+--------------------------
+
+.. code-block:: yaml
+
+    uart:
+      id: uart_bus
+      tx_pin: TX
+      rx_pin: RX
+      baud_rate: 4800
+      stop_bits: 1
+
+    button:
+      - platform: bl0940
+        bl0940_id: bl0940_id
+        name: "Cal  Reset"
+
+    sensor:
+      - platform: bl0940
+        id: bl0940_id
+        uart_id: uart_bus
+        tuya_mode: false
+        resistor_one: 0.5113 # base voltage calibration
+        resistor_shunt: 1.035 # base current calibration
+        voltage:
+          ...
+
+    number:
+      - platform: bl0940
+        bl0940_id: bl0940_id # reference to sensor component
+        current_calibration:
+          id: current_calibration_ui
+          name: "Cal Current"
+        voltage_calibration:
+          id: voltage_calibration_ui
+          name: "Cal Voltage"
+        power_calibration:
+          id: power_calibration_ui
+          name: "Cal Power"
+          disabled_by_default: true
+        energy_calibration:
+          id: energy_calibration_ui
+          name: "Cal Energy"
+          disabled_by_default: true
+
 
 See Also
 --------