scratch/esphome
1
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity

[hlw8032] Single-phase metering IC (#7241)

Browse Source 
Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>
Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
Co-authored-by: Jonathan Swoboda <154711427+swoboda1337@users.noreply.github.com>
This commit is contained in:
Richard Kubíček
2025-12-08 15:07:10 +01:00
committed by GitHub
parent 95efb37045
commit c7382fc494
9 changed files with 362 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
CODEOWNERS
View File

@@ -212,6 +212,7 @@ esphome/components/he60r/* @clydebarrow
esphome/components/heatpumpir/* @rob-deutsch
esphome/components/hitachi_ac424/* @sourabhjaiswal
esphome/components/hlk_fm22x/* @OnFreund
esphome/components/hlw8032/* @rici4kubicek
esphome/components/hm3301/* @freekode
esphome/components/hmac_md5/* @dwmw2
esphome/components/homeassistant/* @esphome/core @OttoWinter

1
esphome/components/hlw8032/__init__.py Normal file
View File

@@ -0,0 +1 @@
CODEOWNERS = ["@rici4kubicek"]

194
esphome/components/hlw8032/hlw8032.cpp Normal file
View File

@@ -0,0 +1,194 @@
#include "hlw8032.h"
#include "esphome/core/log.h"
#include <cinttypes>
namespace esphome::hlw8032 {
static const char *const TAG = "hlw8032";
static constexpr uint8_t STATE_REG_OFFSET = 0;
static constexpr uint8_t VOLTAGE_PARAM_OFFSET = 2;
static constexpr uint8_t VOLTAGE_REG_OFFSET = 5;
static constexpr uint8_t CURRENT_PARAM_OFFSET = 8;
static constexpr uint8_t CURRENT_REG_OFFSET = 11;
static constexpr uint8_t POWER_PARAM_OFFSET = 14;
static constexpr uint8_t POWER_REG_OFFSET = 17;
static constexpr uint8_t DATA_UPDATE_REG_OFFSET = 20;
static constexpr uint8_t CHECKSUM_REG_OFFSET = 23;
static constexpr uint8_t PARAM_REG_USABLE_BIT = (1 << 0);
static constexpr uint8_t POWER_OVERFLOW_BIT = (1 << 1);
static constexpr uint8_t CURRENT_OVERFLOW_BIT = (1 << 2);
static constexpr uint8_t VOLTAGE_OVERFLOW_BIT = (1 << 3);
static constexpr uint8_t HAVE_POWER_BIT = (1 << 4);
static constexpr uint8_t HAVE_CURRENT_BIT = (1 << 5);
static constexpr uint8_t HAVE_VOLTAGE_BIT = (1 << 6);
static constexpr uint8_t CHECK_REG = 0x5A;
static constexpr uint8_t STATE_REG_CORRECTION_FUNC_NORMAL = 0x55;
static constexpr uint8_t STATE_REG_CORRECTION_FUNC_FAIL = 0xAA;
static constexpr uint8_t STATE_REG_CORRECTION_MASK = 0xF0;
static constexpr uint8_t STATE_REG_OVERFLOW_MASK = 0xF;
static constexpr uint8_t PACKET_LENGTH = 24;
void HLW8032Component::loop() {
while (this->available()) {
uint8_t data = this->read();
if (!this->header_found_) {
if ((data == STATE_REG_CORRECTION_FUNC_NORMAL) || (data == STATE_REG_CORRECTION_FUNC_FAIL) ||
(data & STATE_REG_CORRECTION_MASK) == STATE_REG_CORRECTION_MASK) {
this->header_found_ = true;
this->raw_data_[0] = data;
}
} else if (data == CHECK_REG) {
this->raw_data_[1] = data;
this->raw_data_index_ = 2;
this->check_ = 0;
} else if (this->raw_data_index_ >= 2 && this->raw_data_index_ < PACKET_LENGTH) {
this->raw_data_[this->raw_data_index_++] = data;
if (this->raw_data_index_ < PACKET_LENGTH) {
this->check_ += data;
} else if (this->raw_data_index_ == PACKET_LENGTH) {
if (this->check_ == this->raw_data_[CHECKSUM_REG_OFFSET]) {
this->parse_data_();
} else {
ESP_LOGW(TAG, "Invalid checksum: 0x%02X != 0x%02X", this->check_, this->raw_data_[CHECKSUM_REG_OFFSET]);
}
this->raw_data_index_ = 0;
this->header_found_ = false;
memset(this->raw_data_, 0, PACKET_LENGTH);
}
}
}
}
uint32_t HLW8032Component::read_uint24_(uint8_t offset) {
return encode_uint24(this->raw_data_[offset], this->raw_data_[offset + 1], this->raw_data_[offset + 2]);
}
void HLW8032Component::parse_data_() {
// Parse header
uint8_t state_reg = this->raw_data_[STATE_REG_OFFSET];
if (state_reg == STATE_REG_CORRECTION_FUNC_FAIL) {
ESP_LOGE(TAG, "The chip's function of error correction fails.");
return;
}
// Parse data frame
uint32_t voltage_parameter = this->read_uint24_(VOLTAGE_PARAM_OFFSET);
uint32_t voltage_reg = this->read_uint24_(VOLTAGE_REG_OFFSET);
uint32_t current_parameter = this->read_uint24_(CURRENT_PARAM_OFFSET);
uint32_t current_reg = this->read_uint24_(CURRENT_REG_OFFSET);
uint32_t power_parameter = this->read_uint24_(POWER_PARAM_OFFSET);
uint32_t power_reg = this->read_uint24_(POWER_REG_OFFSET);
uint8_t data_update_register = this->raw_data_[DATA_UPDATE_REG_OFFSET];
bool have_power = data_update_register & HAVE_POWER_BIT;
bool have_current = data_update_register & HAVE_CURRENT_BIT;
bool have_voltage = data_update_register & HAVE_VOLTAGE_BIT;
bool power_cycle_exceeds_range = false;
bool parameter_regs_usable = true;
if ((state_reg & STATE_REG_CORRECTION_MASK) == STATE_REG_CORRECTION_MASK) {
if (state_reg & STATE_REG_OVERFLOW_MASK) {
if (state_reg & VOLTAGE_OVERFLOW_BIT) {
have_voltage = false;
}
if (state_reg & CURRENT_OVERFLOW_BIT) {
have_current = false;
}
if (state_reg & POWER_OVERFLOW_BIT) {
have_power = false;
}
if (state_reg & PARAM_REG_USABLE_BIT) {
parameter_regs_usable = false;
}
ESP_LOGW(TAG,
"Reports: (0x%02X)\n"
" Voltage REG overflows: %s\n"
" Current REG overflows: %s\n"
" Power REG overflows: %s\n"
" Voltage/Current/Power Parameter REGs not usable: %s\n",
state_reg, YESNO(!have_voltage), YESNO(!have_current), YESNO(!have_power),
YESNO(!parameter_regs_usable));
if (!parameter_regs_usable) {
return;
}
}
power_cycle_exceeds_range = have_power;
}
ESP_LOGVV(TAG,
"Parsed data:\n"
" Voltage: Parameter REG 0x%06" PRIX32 ", REG 0x%06" PRIX32 "\n"
" Current: Parameter REG 0x%06" PRIX32 ", REG 0x%06" PRIX32 "\n"
" Power: Parameter REG 0x%06" PRIX32 ", REG 0x%06" PRIX32 "\n"
" Data Update: REG 0x%02" PRIX8 "\n",
voltage_parameter, voltage_reg, current_parameter, current_reg, power_parameter, power_reg,
data_update_register);
const float current_multiplier = 1 / (this->current_resistor_ * 1000);
float voltage = 0.0f;
if (have_voltage && voltage_reg) {
voltage = float(voltage_parameter) * this->voltage_divider_ / float(voltage_reg);
}
if (this->voltage_sensor_ != nullptr) {
this->voltage_sensor_->publish_state(voltage);
}
float power = 0.0f;
if (have_power && power_reg && !power_cycle_exceeds_range) {
power = (float(power_parameter) / float(power_reg)) * this->voltage_divider_ * current_multiplier;
}
if (this->power_sensor_ != nullptr) {
this->power_sensor_->publish_state(power);
}
float current = 0.0f;
if (have_current && current_reg) {
current = float(current_parameter) * current_multiplier / float(current_reg);
}
if (this->current_sensor_ != nullptr) {
this->current_sensor_->publish_state(current);
}
float pf = NAN;
const float apparent_power = voltage * current;
if (have_voltage && have_current) {
if (have_power || power_cycle_exceeds_range) {
if (apparent_power > 0) {
pf = power / apparent_power;
if (pf < 0 || pf > 1) {
ESP_LOGD(TAG, "Impossible power factor: %.4f not in interval [0, 1]", pf);
pf = NAN;
}
} else if (apparent_power == 0 && power == 0) {
// No load, report ideal power factor
pf = 1.0f;
}
}
}
if (this->apparent_power_sensor_ != nullptr) {
this->apparent_power_sensor_->publish_state(apparent_power);
}
if (this->power_factor_sensor_ != nullptr) {
this->power_factor_sensor_->publish_state(pf);
}
}
void HLW8032Component::dump_config() {
ESP_LOGCONFIG(TAG,
"Configuration:\n"
" Current resistor: %.1f mΩ\n"
" Voltage Divider: %.3f",
this->current_resistor_ * 1000.0f, this->voltage_divider_);
LOG_SENSOR(" ", "Voltage", this->voltage_sensor_);
LOG_SENSOR(" ", "Current", this->current_sensor_);
LOG_SENSOR(" ", "Power", this->power_sensor_);
LOG_SENSOR(" ", "Apparent Power", this->apparent_power_sensor_);
LOG_SENSOR(" ", "Power Factor", this->power_factor_sensor_);
}
} // namespace esphome::hlw8032

44
esphome/components/hlw8032/hlw8032.h Normal file
View File

@@ -0,0 +1,44 @@
#pragma once
#include "esphome/core/component.h"
#include "esphome/components/sensor/sensor.h"
#include "esphome/components/uart/uart.h"
namespace esphome::hlw8032 {
class HLW8032Component : public Component, public uart::UARTDevice {
public:
void loop() override;
void dump_config() override;
void set_current_resistor(float current_resistor) { this->current_resistor_ = current_resistor; }
void set_voltage_divider(float voltage_divider) { this->voltage_divider_ = voltage_divider; }
void set_voltage_sensor(sensor::Sensor *voltage_sensor) { this->voltage_sensor_ = voltage_sensor; }
void set_current_sensor(sensor::Sensor *current_sensor) { this->current_sensor_ = current_sensor; }
void set_power_sensor(sensor::Sensor *power_sensor) { this->power_sensor_ = power_sensor; }
void set_apparent_power_sensor(sensor::Sensor *apparent_power_sensor) {
this->apparent_power_sensor_ = apparent_power_sensor;
}
void set_power_factor_sensor(sensor::Sensor *power_factor_sensor) {
this->power_factor_sensor_ = power_factor_sensor;
}
protected:
void parse_data_();
uint32_t read_uint24_(uint8_t offset);
sensor::Sensor *voltage_sensor_{nullptr};
sensor::Sensor *current_sensor_{nullptr};
sensor::Sensor *power_sensor_{nullptr};
sensor::Sensor *apparent_power_sensor_{nullptr};
sensor::Sensor *power_factor_sensor_{nullptr};
float current_resistor_{0.001f};
float voltage_divider_{1.720f};
uint8_t raw_data_[24]{};
uint8_t check_{0};
uint8_t raw_data_index_{0};
bool header_found_{false};
};
} // namespace esphome::hlw8032

93
esphome/components/hlw8032/sensor.py Normal file
View File

@@ -0,0 +1,93 @@
import esphome.codegen as cg
from esphome.components import sensor, uart
import esphome.config_validation as cv
from esphome.const import (
CONF_APPARENT_POWER,
CONF_CURRENT,
CONF_CURRENT_RESISTOR,
CONF_ID,
CONF_POWER,
CONF_POWER_FACTOR,
CONF_VOLTAGE,
CONF_VOLTAGE_DIVIDER,
DEVICE_CLASS_APPARENT_POWER,
DEVICE_CLASS_CURRENT,
DEVICE_CLASS_POWER,
DEVICE_CLASS_POWER_FACTOR,
DEVICE_CLASS_VOLTAGE,
STATE_CLASS_MEASUREMENT,
UNIT_AMPERE,
UNIT_VOLT,
UNIT_VOLT_AMPS,
UNIT_WATT,
)
DEPENDENCIES = ["uart"]
hlw8032_ns = cg.esphome_ns.namespace("hlw8032")
HLW8032Component = hlw8032_ns.class_("HLW8032Component", cg.Component, uart.UARTDevice)
CONFIG_SCHEMA = cv.Schema(
{
cv.GenerateID(): cv.declare_id(HLW8032Component),
cv.Optional(CONF_VOLTAGE): sensor.sensor_schema(
unit_of_measurement=UNIT_VOLT,
accuracy_decimals=1,
device_class=DEVICE_CLASS_VOLTAGE,
state_class=STATE_CLASS_MEASUREMENT,
),
cv.Optional(CONF_CURRENT): sensor.sensor_schema(
unit_of_measurement=UNIT_AMPERE,
accuracy_decimals=2,
device_class=DEVICE_CLASS_CURRENT,
state_class=STATE_CLASS_MEASUREMENT,
),
cv.Optional(CONF_POWER): sensor.sensor_schema(
unit_of_measurement=UNIT_WATT,
accuracy_decimals=1,
device_class=DEVICE_CLASS_POWER,
state_class=STATE_CLASS_MEASUREMENT,
),
cv.Optional(CONF_APPARENT_POWER): sensor.sensor_schema(
unit_of_measurement=UNIT_VOLT_AMPS,
accuracy_decimals=1,
device_class=DEVICE_CLASS_APPARENT_POWER,
state_class=STATE_CLASS_MEASUREMENT,
),
cv.Optional(CONF_POWER_FACTOR): sensor.sensor_schema(
accuracy_decimals=2,
device_class=DEVICE_CLASS_POWER_FACTOR,
state_class=STATE_CLASS_MEASUREMENT,
),
cv.Optional(CONF_CURRENT_RESISTOR, default=0.001): cv.resistance,
cv.Optional(CONF_VOLTAGE_DIVIDER, default=1.720): cv.positive_float,
}
).extend(uart.UART_DEVICE_SCHEMA)
FINAL_VALIDATE_SCHEMA = uart.final_validate_device_schema(
"hlw8032", baud_rate=4800, require_rx=True, data_bits=8, parity="EVEN"
)
async def to_code(config):
var = cg.new_Pvariable(config[CONF_ID])
await cg.register_component(var, config)
await uart.register_uart_device(var, config)
if voltage_config := config.get(CONF_VOLTAGE):
sens = await sensor.new_sensor(voltage_config)
cg.add(var.set_voltage_sensor(sens))
if current_config := config.get(CONF_CURRENT):
sens = await sensor.new_sensor(current_config)
cg.add(var.set_current_sensor(sens))
if power_config := config.get(CONF_POWER):
sens = await sensor.new_sensor(power_config)
cg.add(var.set_power_sensor(sens))
if apparent_power_config := config.get(CONF_APPARENT_POWER):
sens = await sensor.new_sensor(apparent_power_config)
cg.add(var.set_apparent_power_sensor(sens))
if power_factor_config := config.get(CONF_POWER_FACTOR):
sens = await sensor.new_sensor(power_factor_config)
cg.add(var.set_power_factor_sensor(sens))
cg.add(var.set_current_resistor(config[CONF_CURRENT_RESISTOR]))
cg.add(var.set_voltage_divider(config[CONF_VOLTAGE_DIVIDER]))

17
tests/components/hlw8032/common.yaml Normal file
View File

@@ -0,0 +1,17 @@
sensor:
- platform: hlw8032
voltage:
name: HLW8032 Voltage
id: hlw8032_voltage
current:
name: HLW8032 Current
id: hlw8032_current
power:
name: HLW8032 Power
id: hlw8032_power
apparent_power:
name: HLW8032 Apparent Power
id: hlw8032_apparent_power
power_factor:
name: HLW8032 Power Factor
id: hlw8032_power_factor

4
tests/components/hlw8032/test.esp32-idf.yaml Normal file
View File

@@ -0,0 +1,4 @@
packages:
uart_4800_even: !include ../../test_build_components/common/uart_4800_even/esp32-idf.yaml
<<: !include common.yaml

4
tests/components/hlw8032/test.esp8266-ard.yaml Normal file
View File

@@ -0,0 +1,4 @@
packages:
uart_4800_even: !include ../../test_build_components/common/uart_4800_even/esp8266-ard.yaml
<<: !include common.yaml

4
tests/components/hlw8032/test.rp2040-ard.yaml Normal file
View File

@@ -0,0 +1,4 @@
packages:
uart_4800_even: !include ../../test_build_components/common/uart_4800_even/rp2040-ard.yaml
<<: !include common.yaml