Skip to content
Get started

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 entry
sensor:
- 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.

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 Meter
sensor:
- 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.

  • 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_CREEP register units, from 0 to 255. Defaults to the chip’s reset value 11 (0x0B). Set to 0 to 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, set anti_creep_threshold: 0 so the chip does not force current readings to zero.