[bl0940] document new configuration options

components/api.rst

@@ -295,6 +295,8 @@ if logs are shown remotely.
         then:
           - logger.log: API is connected!
 
+The lambda equivalent for this is ``id(api_id).is_connected()``.
+
 .. _api-device-actions:
 
 User-defined Actions

components/sensor/bl0940.rst

@@ -14,7 +14,7 @@ Belling BL0940 Energy Monitor
       - 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 +50,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 +70,73 @@ 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 presedence 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
+
 
 See Also
 --------

components/sensor/template.rst

@@ -79,6 +79,37 @@ Configuration options:
 
         id(template_sens).publish_state(42.0);
 
+Useful Template Sensors
+-----------------------
+
+Here are some useful sensors for debugging and tracking Bluetooth proxies.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    sensor:
+      - platform: template
+        name: "Bluetooth Proxy Connections Limit"
+        id: bluetooth_proxy_connections_limit
+        icon: "mdi:bluetooth-settings"
+        update_interval: 30s
+        entity_category: "diagnostic"
+        lambda: |-
+          int limit = bluetooth_proxy::global_bluetooth_proxy->get_bluetooth_connections_limit();
+          ESP_LOGD("bluetooth_proxy_sensor", "Current connections limit => %d", limit);
+          return limit;
+
+      - platform: template
+        name: "Bluetooth Proxy Connections Free"
+        id: bluetooth_proxy_connections_free
+        icon: "mdi:bluetooth-settings"
+        update_interval: 30s
+        entity_category: "diagnostic"
+        lambda: |-
+          int free = bluetooth_proxy::global_bluetooth_proxy->get_bluetooth_connections_free();
+          ESP_LOGD("bluetooth_proxy_sensor", "Current connections free => %d", free);
+          return free;
+
 See Also
 --------
 

components/text_sensor/template.rst

@@ -75,6 +75,42 @@ Configuration options:
 
         id(template_text).publish_state("Hello World");
 
+Useful Template Sensors
+-----------------------
+
+Here are some useful text sensors for debugging and tracking project info.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    text_sensor:
+      - platform: template
+        name: "ESPHome Project Version"
+        id: esphome_project_version_text_short
+        icon: "mdi:information-box"
+        entity_category: "diagnostic"
+        update_interval: 600s
+        lambda: |-
+          return { ESPHOME_PROJECT_VERSION };
+
+      - platform: template
+        name: "ESPHome Project Version Detailed"
+        id: esphome_project_version_text_detailed
+        icon: "mdi:information-box"
+        entity_category: "diagnostic"
+        update_interval: 600s
+        lambda: |-
+          return { ESPHOME_PROJECT_VERSION " " + App.get_compilation_time() };
+
+      - platform: template
+        name: "ESPHome Project Name"
+        id: esphome_project_name
+        icon: "mdi:information-box"
+        entity_category: "diagnostic"
+        update_interval: 600s
+        lambda: |-
+          return { ESPHOME_PROJECT_NAME };
+
 See Also
 --------