HLW8012 功率传感器

hlw8012 传感器平台允许您在 ESPHome 中使用 HLW8012 电压/电流和功率传感器（数据手册）。此传感器常见于 Sonoff POW 产品中。CSE7759 和 BL0937 与 HLW8012 类似，也可使用此组件。请注意 CSE7759B 不同，应与 CSE7766 组件配合使用。

NOTE

安全隐患：某些设备（如 Sonoff POW、Shelly 等）的数字 GND 直接连接到市电电压，因此GPIO 在正常运行期间会带电。我们的建议是标记这些电路板，以阻止使用危险数字引脚。

此传感器有两个数据输出，均使用调制信号的频率来编码值：CF 和 CF1。 CF 的频率与测得的（有功）功率成正比，CF1 与电流/电压成正比。通过 SEL 引脚，可以选择使用哪种模式。

ESPHome 会持续循环切换 SEL 引脚状态以测量电流和电压，但两者无法在同一精确时刻测量。

# Example configuration entry
sensor:
  - platform: hlw8012
    sel_pin: GPIOXX
    cf_pin: GPIOXX
    cf1_pin: GPIOXX
    current:
      name: "HLW8012 Current"
    voltage:
      name: "HLW8012 Voltage"
    power:
      name: "HLW8012 Power"
    energy:
      name: "HLW8012 Energy"
    update_interval: 60s

NOTE

上述配置应适用于 Sonoff POW（R1）。

配置变量

sel_pin（必选，Pin Schema）: SEL 连接的引脚。
cf_pin（必选，Pin）: CF 连接的引脚。
cf1_pin（必选，Pin）: CF1 连接的引脚。
current (可选): 以安培为单位使用传感器的电流值。来自 Sensor 的所有选项。
power (可选): 以瓦特为单位使用传感器的（有功）功率值。来自 Sensor 的所有选项。
voltage (可选): 以 V（RMS）为单位使用传感器的电压值。来自 Sensor 的所有选项。
energy (可选): 以 Wh 为单位使用传感器的总能量值。来自 Sensor 的所有选项。
update_interval (可选，Time): 检查传感器的间隔。默认为 60s。

高级选项：

current_resistor (可选，float): 电流测量分流电阻的值。默认为 Sonoff POW 的值 0.001 ohm。
voltage_divider (可选，float): 板上分压器的值，格式为 (R_upstream + R_downstream) / R_downstream。默认为 Sonoff POW 的值 2351。
model (可选，string): 板上的传感器型号，用于设置将脉冲转换为测量值的内部常数因子。可能的值为 HLW8012、CSE7759、BL0937。默认为 HLW8012。 CSE7759 使用相同的常数，默认设置也能工作。BL0937 必须设置才能同时校准所有三项测量。
change_mode_every (可选，int): 经过多少次更新后在电流/电压测量模式之间循环切换。注意，切换后的第一个值会被丢弃，因为它通常不准确。设置为 "never" 时测量模式将保持设定的 initial_mode。默认为 8。
initial_mode (可选，string): 初始测量模式。默认为 VOLTAGE。可能的初始测量模式为 VOLTAGE 或 CURRENT。

固定 SEL 引脚

某些设备的 SEL 引脚被永久拉高或拉低。如果是这种情况，您可以配置初始测量模式以匹配设备使用的模式，并禁用模式切换。

# Example configuration entry for device with fixed measurement mode
sensor:
  - platform: hlw8012
    sel_pin: GPIOXX
    cf_pin: GPIOXX
    cf1_pin: GPIOXX
    current:
      name: "HLW8012 Current"
    voltage:
      name: "HLW8012 Voltage"
    power:
      name: "HLW8012 Power"
    update_interval: 60s
    initial_mode: CURRENT
    change_mode_every: "never"

SEL 引脚反转

如果使用型号 BL0937，SEL 引脚的功能与默认相反。SEL=0 时测量电流， SEL=1 时测量电压。要适配此更改，请使用以下配置：

# Example configuration entry for device BL0937 using inverted SEL pin functionality
sensor:
  - platform: hlw8012
    model: BL0937
    sel_pin:
      number: GPIOXX
      inverted: true
    cf_pin: GPIOXX
    cf1_pin: GPIOXX
    current:
      name: "BL0937 Current"
    voltage:
      name: "BL0937 Voltage"
    power:
      name: "BL0937 Power"
    update_interval: 60s

校准

您需要：

您的 ESPHome 功率测量插座
一个可测量电压、电流、功率和功率因数的校准功率计
一个大电阻负载，如电加热器或水壶，理想情况在 1000W 以上

步骤：

在设备的 YAML 配置中找到当前使用的 current_resistor 和 voltage_divider 校准值，或上传一个带有已知校准值的新固件到 ESP。
将 ESP 功率测量插座插入校准功率计。
将负载插入 ESP 插座。
打开负载，确保功率计上显示的功率因数（PF）为 1.0。如果不是，您需要选择另一个负载。
等待功率计和 ESP 上的读数稳定。
同时记下功率计和 ESP 的电压读数。
同时记下功率计和 ESP 的功率读数。
同时记下功率计和 ESP 的电流读数。
使用下方计算器计算 ESP 的新校准值。这些值将帮助 ESP 在未来准确测量功率、电压和电流。
将新值上传到 ESP。

ESP 上的校准值
voltage_divider
current_resistor
current_multiply

ESP 测量值
电压	V
功率	W
电流	A

功率计测量值
电压	V
功率	W
电流	A

新的校准值
voltage_divider
current_resistor
current_multiply

新的 ESP 测量值
电压	V
功率	W
电流	A

示例配置：

substitutions:
  voltage_divider: "2351"
  current_resistor: "0.001"
  current_multiply: "1.0"

sensor:
  - platform: hlw8012
    current_resistor: ${current_resistor}
    voltage_divider: ${voltage_divider}
    current:
      name: "HLW8012 Current"
      filters:
        - multiply: ${current_multiply}
    voltage:
      name: "HLW8012 Voltage"
    power:
      name: "HLW8012 Power"
    energy:
      name: "HLW8012 Energy"
    update_interval: 60s

HLW8012 功率传感器

配置变量

固定 SEL 引脚

SEL 引脚反转

校准

参见