Documentation for BL0939 (Sonoff Dual R3 v2) (#1970)

components/sensor/bl0939.rst

@@ -0,0 +1,89 @@
+BL0939 Power Sensor
+====================
+
+.. seo::
+    :description: Instructions for setting up BL0939 power sensors for the Sonoff Dual R3 v2
+    :image: bl0939.png
+    :keywords: bl0939, Sonoff Dual R3 v2
+
+The ``bl0939`` sensor platform allows you to use your BL0939 voltage/current/power and energy
+sensors with ESPHome. This sensor is commonly found in Sonoff Dual R3 v2.
+
+.. note::
+
+    SAFETY HAZARD: Some devices such as Sonoff POWs/Shelly/etc, have the digital GND connected directly to mains voltage so **the GPIOs become LIVE during normal operation**. Our advice is to mark these boards to prevent any use of the dangerous digital pins.
+
+As the communication with the BL0939 done using UART, you need
+to have an :ref:`UART bus <uart>` in your configuration with the ``tx_pin`` and ``rx_pin`` connected to the BL0939.
+Additionally, you need to set the baud rate to 4800, parity to ``NONE`` and stop_bits to 2.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    # Disable logging over serial
+    logger:
+      baud_rate: 0
+
+    uart:
+      tx_pin: GPIO25
+      rx_pin: GPIO26
+      baud_rate: 4800
+      parity: NONE
+      stop_bits: 2
+
+    sensor:
+      - platform: bl0939
+        update_interval: 30s
+        voltage:
+          name: 'BL0939 Voltage'
+        current_1:
+          name: 'BL0939 Current 1'
+        current_2:
+          name: 'BL0939 Current 2'
+        active_power_1:
+          name: 'BL0939 Active Power 1'
+        active_power_2:
+          name: 'BL0939 Active Power 2'
+        energy_1:
+          name: 'BL0939 Energy 1'
+        energy_2:
+          name: 'BL0939 Energy 2'
+        energy_total:
+          name: 'BL0939 Energy Total'
+
+.. note::
+
+    The configuration above should work for Sonoff Dual R3 v2.
+
+Configuration variables:
+------------------------
+
+- **voltage** (*Optional*): Use the voltage value of the sensor in V (RMS).
+  All options from :ref:`Sensor <config-sensor>`.
+- **current_1** (*Optional*): Use the current value of the channel 1 in amperes. All options from
+  :ref:`Sensor <config-sensor>`.
+- **current_2** (*Optional*): Use the current value of the channel 2 in amperes. All options from
+  :ref:`Sensor <config-sensor>`.
+- **active_power_1** (*Optional*): Use the (active) power value of the channel 1 in watts. All options from
+  :ref:`Sensor <config-sensor>`.
+- **active_power_2** (*Optional*): Use the (active) power value of the channel 2 in watts. All options from
+  :ref:`Sensor <config-sensor>`.
+- **energy_1** (*Optional*): Use the energy counter value of the channel 1 in kWh. All options from
+  :ref:`Sensor <config-sensor>`.
+- **energy_2** (*Optional*): Use the energy counter value of the channel 2 in kWh. All options from
+  :ref:`Sensor <config-sensor>`.
+- **energy_total** (*Optional*): Use the energy counter value of both channels in kWh. 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.
+
+See Also
+--------
+
+- :ref:`sensor-filters`
+- :doc:`cse7761`
+- :doc:`bl0940`
+- :apiref:`bl0939/bl0939.h`
+- :ghedit:`Edit`

index.rst

@@ -252,6 +252,7 @@ Electricity
 
     ADE7953, components/sensor/ade7953, ade7953.svg, Power
     ATM90E32, components/sensor/atm90e32, atm90e32.jpg, Voltage & Current & Power
+    BL0939, components/sensor/bl0939, bl0939.png, Voltage & Current & Power & Energy
     BL0940, components/sensor/bl0940, bl0940.png, Voltage & Current & Power
     CS5460A, components/sensor/cs5460a, cs5460a.png, Voltage & Current & Power
     CSE7761, components/sensor/cse7761, cse7761.svg, Voltage & Current & Power