BL0939 Power Sensor
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 and in the Seeed Studio XIAO
2-Channel Wi-Fi AC Energy Meter.
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 UART bus 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.
# Example configuration entrysensor: - platform: bl0939 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' internal_temperature: name: 'BL0939 Internal Temperature'NOTE
The configuration above should work for Sonoff Dual R3 v2.
Measurement Modes
Section titled “Measurement Modes”The BL0939 datasheet describes two front end circuits, and each one needs its own scaling to turn the raw
readings into volts, amperes, watts and kWh. Set mode to the circuit your board uses:
direct(default): current shunts and a resistor voltage divider, as in the Sonoff Dual R3 v2. The scaling assumes 1 mΩ shunts and a 0.51 kΩ / 5 × 390 kΩ voltage divider.current_transformer: current transformer (CT) clamps and a voltage transformer, as in the Seeed Studio XIAO 2-Channel Wi-Fi AC Energy Meter. The scaling assumes 100 A:50 mA CT clamps with a 0.6 Ω burden resistor, and a ZMPT107-1 voltage transformer with 5 × 22 kΩ on the primary side and 24.9 Ω on the secondary side.
# Example configuration entry for the Seeed Studio XIAO 2-Channel Wi-Fi AC Energy Metersensor: - platform: bl0939 mode: current_transformer 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_total: name: 'BL0939 Energy Total'NOTE
If your board uses different shunt, CT, burden or divider values than the ones above, the voltage and current
readings are each off by their own fixed factor, and power and energy by the product of the two. Pick the mode
that matches your circuit, then correct each reading with a multiply
sensor filter.
Configuration variables
Section titled “Configuration variables”-
mode (Optional, string): The front end circuit of the board, which sets how raw readings are scaled. See Measurement Modes. One of:
direct(default): Current shunts and a resistor voltage divider (Sonoff Dual R3 v2).current_transformer: CT clamps and a voltage transformer (Seeed Studio XIAO 2-Channel Wi-Fi AC Energy Meter).
-
voltage (Optional): Use the voltage value of the sensor in V (RMS). All options from Sensor.
-
current_1 (Optional): Use the current value of the channel 1 in amperes. All options from Sensor.
-
current_2 (Optional): Use the current value of the channel 2 in amperes. All options from Sensor.
-
active_power_1 (Optional): Use the (active) power value of the channel 1 in watts. All options from Sensor.
-
active_power_2 (Optional): Use the (active) power value of the channel 2 in watts. All options from Sensor.
-
energy_1 (Optional): Use the energy counter value of the channel 1 in kWh. All options from Sensor.
-
energy_2 (Optional): Use the energy counter value of the channel 2 in kWh. All options from Sensor.
-
energy_total (Optional): Use the energy counter value of both channels in kWh. All options from Sensor.
-
internal_temperature (Optional): The internal temperature of the BL0939 chip in °C. This measures chip temperature, not ambient temperature. All options from Sensor.
-
update_interval (Optional, Time): The interval to check the sensor. Defaults to
60s. -
uart_id (Optional, ID): Manually specify the ID of the UART Component if you want to use multiple UART buses.
-
anti_creep_threshold (Optional, int): The active-power threshold in raw
WA_CREEPregister units, from0to255. Defaults to the chip’s reset value11(0x0B). Set to0to disable anti-creep. Both channels share the same threshold, but each channel is checked separately. When a channel’s absolute active power is below the threshold, the chip reports zero for that channel’s active power and RMS current. Lower values let you measure smaller signals, but readings may include more noise. For current-only measurement without a physical voltage input, setanti_creep_threshold: 0so the chip does not force current readings to zero.