ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
bl0940.h
Go to the documentation of this file.
1#pragma once
6#ifdef USE_BUTTON
8#endif
9#ifdef USE_NUMBER
11#endif
15namespace esphome::bl0940 {
16
17// Caveat: All these values are big endian (low - middle - high)
18struct DataPacket {
19 uint8_t frame_header; // Packet header (0x58 in EN docs, 0x55 in CN docs and Tasmota tests)
20 uint24_le_t i_fast_rms; // Fast RMS current
21 uint24_le_t i_rms; // RMS current
22 uint24_t RESERVED0; // Reserved
23 uint24_le_t v_rms; // RMS voltage
24 uint24_t RESERVED1; // Reserved
25 int24_le_t watt; // Active power (can be negative for bidirectional measurement)
26 uint24_t RESERVED2; // Reserved
27 uint24_le_t cf_cnt; // Energy pulse count
28 uint24_t RESERVED3; // Reserved
29 uint16_le_t tps1; // Internal temperature sensor 1
30 uint8_t RESERVED4; // Reserved (should be 0x00)
31 uint16_le_t tps2; // Internal temperature sensor 2
32 uint8_t RESERVED5; // Reserved (should be 0x00)
33 uint8_t checksum; // Packet checksum
34} __attribute__((packed));
35
36class BL0940 final : public PollingComponent, public uart::UARTDevice {
37 public:
38 // Sensor setters
39 SUB_SENSOR(voltage)
40 SUB_SENSOR(current)
41 SUB_SENSOR(power) // Power sensor (can be negative for bidirectional)
42 SUB_SENSOR(energy)
43
44 // Temperature sensor setters
45 SUB_SENSOR(internal_temperature)
46 SUB_SENSOR(external_temperature)
47
48 // Configuration setters
49 void set_legacy_mode(bool enable) { this->legacy_mode_enabled_ = enable; }
50 void set_read_command(uint8_t read_command) { this->read_command_ = read_command; }
51 void set_write_command(uint8_t write_command) { this->write_command_ = write_command; }
52
53 // Reference value setters (used for calibration and conversion)
54 void set_current_reference(float current_ref) { this->current_reference_ = current_ref; }
55 void set_energy_reference(float energy_ref) { this->energy_reference_ = energy_ref; }
56 void set_power_reference(float power_ref) { this->power_reference_ = power_ref; }
57 void set_voltage_reference(float voltage_ref) { this->voltage_reference_ = voltage_ref; }
58
59#ifdef USE_NUMBER
60 // Calibration number setters (for Home Assistant number entities)
61 SUB_NUMBER(current_calibration)
62 SUB_NUMBER(voltage_calibration)
63 SUB_NUMBER(power_calibration)
64 SUB_NUMBER(energy_calibration)
65#endif
66
67 // Resets all calibration values to defaults
68 void reset_calibration();
69
70 // Core component methods
71 void loop() override;
72 void update() override;
73 void setup() override;
74 void dump_config() override;
75
76 protected:
77 // --- Internal state ---
78 uint32_t prev_cf_cnt_ = 0; // Previous energy pulse count (for energy calculation)
79 float max_temperature_diff_{0}; // Max allowed temperature difference between two measurements (noise filter)
80
81 // --- Reference values for conversion ---
82 float power_reference_; // Divider for raw power to get Watts
83 float power_reference_cal_; // Calibrated power reference
84 float voltage_reference_; // Divider for raw voltage to get Volts
85 float voltage_reference_cal_; // Calibrated voltage reference
86 float current_reference_; // Divider for raw current to get Amperes
87 float current_reference_cal_; // Calibrated current reference
88 float energy_reference_; // Divider for raw energy to get kWh
89 float energy_reference_cal_; // Calibrated energy reference
90
91 // --- Home Assistant calibration values (multipliers, default 1) ---
92 float current_cal_{1};
93 float voltage_cal_{1};
94 float power_cal_{1};
95 float energy_cal_{1};
96
97 // --- Protocol commands ---
100
101 // --- Mode flags ---
103
104 // --- Methods ---
105 // Converts packed temperature value to float and updates the sensor
106 float update_temp_(sensor::Sensor *sensor, uint16_le_t packed_temperature) const;
107
108 // Validates the checksum of a received data packet
109 bool validate_checksum_(DataPacket *data);
110
111 // Handles a received data packet
112 void received_package_(DataPacket *data);
113
114 // Calculates reference values for calibration and conversion
118
119 // Calibration update callbacks (used with number entities)
125
126 // Recalculates all reference values after calibration changes
127 void recalibrate_();
129
130} // namespace esphome::bl0940
This class simplifies creating components that periodically check a state.
Definition component.h:532
SUB_NUMBER(current_calibration) SUB_NUMBER(voltage_calibration) SUB_NUMBER(power_calibration) SUB_NUMBER(energy_calibration) void reset_calibration()
float calculate_calibration_value_(float state)
Definition bl0940.cpp:122
float update_temp_(sensor::Sensor *sensor, uint16_le_t packed_temperature) const
Definition bl0940.cpp:189
void set_read_command(uint8_t read_command)
Definition bl0940.h:50
float max_temperature_diff_
Definition bl0940.h:79
float current_reference_cal_
Definition bl0940.h:87
void set_voltage_reference(float voltage_ref)
Definition bl0940.h:57
void current_calibration_callback_(float state)
Definition bl0940.cpp:143
void dump_config() override
Definition bl0940.cpp:235
void set_energy_reference(float energy_ref)
Definition bl0940.h:55
void voltage_calibration_callback_(float state)
Definition bl0940.cpp:148
void update() override
Definition bl0940.cpp:56
void setup() override
Definition bl0940.cpp:62
float calculate_energy_reference_()
Definition bl0940.cpp:116
void energy_calibration_callback_(float state)
Definition bl0940.cpp:158
float calculate_power_reference_()
Definition bl0940.cpp:111
void set_power_reference(float power_ref)
Definition bl0940.h:56
bool validate_checksum_(DataPacket *data)
Definition bl0940.cpp:46
uint32_t prev_cf_cnt_
Definition bl0940.h:78
void received_package_(DataPacket *data)
Definition bl0940.cpp:203
void set_current_reference(float current_ref)
Definition bl0940.h:54
float energy_reference_cal_
Definition bl0940.h:89
float voltage_reference_cal_
Definition bl0940.h:85
void set_write_command(uint8_t write_command)
Definition bl0940.h:51
SUB_SENSOR(voltage) SUB_SENSOR(current) SUB_SENSOR(power) SUB_SENSOR(energy) SUB_SENSOR(internal_temperature) SUB_SENSOR(external_temperature) void set_legacy_mode(bool enable)
Definition bl0940.h:39
void loop() override
Definition bl0940.cpp:30
void power_calibration_callback_(float state)
Definition bl0940.cpp:153
Base-class for all sensors.
Definition sensor.h:48
bool state
Definition fan.h:2
esphome::bl0940::BL0940 __attribute__
static void uint32_t
24-bit unsigned integer type, transparently converting to 32-bit.
Definition datatypes.h:32