Belling BL0940 Energy Monitor

The bl0940 component allows you to use BL0940 energy monitors sensors with 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 UART. You must therefore have a uart: entry in your configuration with both the TX and RX pins set to some pins on your board and the baud rate set to 4800 with 1 stop bit.

Sensor

# Example configuration entry
sensor:
  - platform: bl0940
    voltage:
      name: 'BL0940 Voltage'
    current:
      name: 'BL0940 Current'
    power:
      name: 'BL0940 Power'
    energy:
      name: 'BL0940 Energy'
    internal_temperature:
      name: 'BL0940 Internal temperature'
    external_temperature:
      name: 'BL0940 External temperature'

Configuration Variables

uart_id (Optional): Manually specify the ID of the UART Component if you want to use multiple UART buses.
legacy_mode (Optional, boolean): Whether to use the legacy 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 legacy_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 legacy_mode.
voltage (Optional): The voltage value of the sensor in Volts. All options from Sensor.
current (Optional): The current value of the sensor in Amperes. All options from Sensor.
power (Optional): The (active) power value of the sensor in Watts. All options from Sensor.
energy (Optional): Use the voltage value of the sensor in kWh. All options from Sensor.
internal_temperature (Optional): The internal temperature value of the sensor in °C. All options from Sensor.
external_temperature (Optional): The external value of the sensor in °C. Often not connected and gives garbage data. All options from Sensor.
update_interval (Optional): The interval to check the sensor. Defaults to 60s.

Calibration Parameters

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.

Sensor 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

# 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.

By default all the reference values will be calculated using the above values in the exact order shown below.

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 legacy_mode is enabled the reference values will be set according to initial implementation.

this->voltage_reference_ = 33000;
this->current_reference_ = 275000;
this->power_reference_   = 1430;
this->energy_reference_  = 3.6e6 / 297;

Any of the reference values may be manually configured; user-specified values will take precedence over the calculated/predefined values.

Theoretically, configuring voltage_reference and current_reference should be enough to calibrate the sensors, but, for completeness, power_reference and energy_reference are also configurable.

# custom references
voltage_reference: 17158.9201389365
current_reference: 266013.136288998
power_reference:   713.104696500825
energy_reference:  6120.6267056536

Number

The bl0940 number platform allows for online calibration of the sensor readings.

number:
  - platform: bl0940
    current_calibration:
      name: Current Calibration
    voltage_calibration:
      name: Voltage Calibration
    power_calibration:
      name: Power Calibration
    energy_calibration:
      name: Energy Calibration

Configuration Variables

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. Maximal 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 Number.

Calibration details

Calibration factor is calculated in % based on submitted value from the configured calibration component.

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.

Button

The bl0940 button platform allows to reset all external calibration values to their initial state.

button:
  - platform: bl0940
    name: Reset Calibration

Configuration Variables

All options from Button.