Skip to content
ESPHome - Smart Home Made Simple

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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “Button”

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

button:
  - platform: bl0940
    name: Reset Calibration

Configuration Variables

Section titled “Configuration Variables”

See Also

Section titled “See Also”