ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
atm90e32.h
Go to the documentation of this file.
1#pragma once
2
3#include "atm90e32_reg.h"
6#include <cmath>
7#include <span>
8#include <unordered_map>
9#ifdef USE_TEXT_SENSOR
11#endif
14#include "esphome/core/gpio.h"
17
18namespace esphome::atm90e32 {
19
20inline bool offset_register_value_matches(uint16_t actual, int16_t expected) {
21 return actual == static_cast<uint16_t>(expected);
22}
23
25 int16_t first_offset{0};
26 int16_t second_offset{0};
27};
28
30 uint16_t voltage_gain{1};
31 uint16_t current_gain{1};
32};
33
34// Stored size of each calibration table; an all-zero payload marks a table as cleared.
35static constexpr size_t CALIBRATION_PAYLOAD_SIZE = 12;
36
37static_assert(sizeof(OffsetCalibration[3]) == CALIBRATION_PAYLOAD_SIZE,
38 "Offset calibration preference layout must remain compatible");
39static_assert(sizeof(GainCalibration[3]) == CALIBRATION_PAYLOAD_SIZE,
40 "Gain calibration preference layout must remain compatible");
41
46
48 public spi::SPIDevice<spi::BIT_ORDER_MSB_FIRST, spi::CLOCK_POLARITY_HIGH,
49 spi::CLOCK_PHASE_TRAILING, spi::DATA_RATE_1MHZ> {
50 public:
51 static const uint8_t PHASEA = 0;
52 static const uint8_t PHASEB = 1;
53 static const uint8_t PHASEC = 2;
54 const char *phase_labels[3] = {"A", "B", "C"};
55 // these registers are not sucessive, so we can't just do 'base + phase'
56 const uint16_t voltage_gain_registers[3] = {ATM90E32_REGISTER_UGAINA, ATM90E32_REGISTER_UGAINB,
57 ATM90E32_REGISTER_UGAINC};
58 const uint16_t current_gain_registers[3] = {ATM90E32_REGISTER_IGAINA, ATM90E32_REGISTER_IGAINB,
59 ATM90E32_REGISTER_IGAINC};
60 const uint16_t voltage_offset_registers[3] = {ATM90E32_REGISTER_UOFFSETA, ATM90E32_REGISTER_UOFFSETB,
61 ATM90E32_REGISTER_UOFFSETC};
62 const uint16_t current_offset_registers[3] = {ATM90E32_REGISTER_IOFFSETA, ATM90E32_REGISTER_IOFFSETB,
63 ATM90E32_REGISTER_IOFFSETC};
64 const uint16_t power_offset_registers[3] = {ATM90E32_REGISTER_POFFSETA, ATM90E32_REGISTER_POFFSETB,
65 ATM90E32_REGISTER_POFFSETC};
66 const uint16_t reactive_power_offset_registers[3] = {ATM90E32_REGISTER_QOFFSETA, ATM90E32_REGISTER_QOFFSETB,
67 ATM90E32_REGISTER_QOFFSETC};
68 const uint16_t over_voltage_flags[3] = {ATM90E32_STATUS_S0_OVPHASEAST, ATM90E32_STATUS_S0_OVPHASEBST,
69 ATM90E32_STATUS_S0_OVPHASECST};
70 const uint16_t voltage_sag_flags[3] = {ATM90E32_STATUS_S1_SAGPHASEAST, ATM90E32_STATUS_S1_SAGPHASEBST,
71 ATM90E32_STATUS_S1_SAGPHASECST};
72 const uint16_t phase_loss_flags[3] = {ATM90E32_STATUS_S1_PHASELOSSAST, ATM90E32_STATUS_S1_PHASELOSSBST,
73 ATM90E32_STATUS_S1_PHASELOSSCST};
74 void loop() override;
75 void setup() override;
76 void dump_config() override;
77 float get_setup_priority() const override;
78 void update() override;
79 void set_voltage_sensor(int phase, sensor::Sensor *obj) { this->phase_[phase].voltage_sensor_ = obj; }
80 void set_current_sensor(int phase, sensor::Sensor *obj) { this->phase_[phase].current_sensor_ = obj; }
81 void set_power_sensor(int phase, sensor::Sensor *obj) { this->phase_[phase].power_sensor_ = obj; }
82 void set_reactive_power_sensor(int phase, sensor::Sensor *obj) { this->phase_[phase].reactive_power_sensor_ = obj; }
83 void set_apparent_power_sensor(int phase, sensor::Sensor *obj) { this->phase_[phase].apparent_power_sensor_ = obj; }
85 this->phase_[phase].forward_active_energy_sensor_ = obj;
86 }
88 this->phase_[phase].reverse_active_energy_sensor_ = obj;
89 }
90 void set_power_factor_sensor(int phase, sensor::Sensor *obj) { this->phase_[phase].power_factor_sensor_ = obj; }
91 void set_phase_angle_sensor(int phase, sensor::Sensor *obj) { this->phase_[phase].phase_angle_sensor_ = obj; }
93 this->phase_[phase].harmonic_active_power_sensor_ = obj;
94 }
95 void set_peak_current_sensor(int phase, sensor::Sensor *obj) { this->phase_[phase].peak_current_sensor_ = obj; }
96 void set_volt_gain(int phase, uint16_t gain) {
97 this->phase_[phase].voltage_gain_ = gain;
98 this->has_config_voltage_gain_[phase] = true;
99 }
100 void set_ct_gain(int phase, uint16_t gain) {
101 this->phase_[phase].ct_gain_ = gain;
102 this->has_config_current_gain_[phase] = true;
103 }
104 void set_voltage_offset(uint8_t phase, int16_t offset) {
105 this->offset_phase_[phase].first_offset = offset;
106 this->has_config_voltage_offset_[phase] = true;
107 }
108 void set_current_offset(uint8_t phase, int16_t offset) {
109 this->offset_phase_[phase].second_offset = offset;
110 this->has_config_current_offset_[phase] = true;
111 }
112 void set_active_power_offset(uint8_t phase, int16_t offset) {
113 this->power_offset_phase_[phase].first_offset = offset;
114 this->has_config_active_power_offset_[phase] = true;
115 }
116 void set_reactive_power_offset(uint8_t phase, int16_t offset) {
117 this->power_offset_phase_[phase].second_offset = offset;
118 this->has_config_reactive_power_offset_[phase] = true;
119 }
121 void set_threshold_voltage_sag_v(float voltage) { this->threshold_voltage_sag_v_ = voltage; }
122 void set_threshold_voltage_peak_v(float voltage) { this->threshold_voltage_peak_v_ = voltage; }
123 void set_threshold_current_peak_a(float current) { this->threshold_current_peak_a_ = current; }
124 void set_frequency_thresholds(uint16_t low, uint16_t high) {
125 this->frequency_low_threshold_ = low;
126 this->frequency_high_threshold_ = high;
127 }
128 void set_line_freq(int freq) { line_freq_ = freq; }
129 void set_current_phases(int phases) { current_phases_ = phases; }
130 void set_pga_gain(uint16_t gain) { pga_gain_ = gain; }
138 void set_instance_id(const char *id) { instance_id_ = id; }
139 int16_t calibrate_offset(uint8_t phase, bool voltage);
140 int16_t calibrate_power_offset(uint8_t phase, bool reactive);
142 // Body of the calibration buttons: logs the button name and the hint lines, then runs action.
143 void press_calibration_button(EntityBase *entity, void (ATM90E32Component::*action)(),
144 const LogString *hint = nullptr, const LogString *hint2 = nullptr);
145#ifdef USE_NUMBER
146 void set_reference_voltage(uint8_t phase, number::Number *ref_voltage) { ref_voltages_[phase] = ref_voltage; }
147 void set_reference_current(uint8_t phase, number::Number *ref_current) { ref_currents_[phase] = ref_current; }
148#endif
149 float get_reference_voltage(uint8_t phase) {
150#ifdef USE_NUMBER
151 return (phase < 3 && ref_voltages_[phase]) ? ref_voltages_[phase]->state : 120.0; // Default voltage
152#else
153 return 120.0; // Default voltage
154#endif
155 }
156 float get_reference_current(uint8_t phase) {
157#ifdef USE_NUMBER
158 return (phase < 3 && ref_currents_[phase]) ? ref_currents_[phase]->state : 5.0f; // Default current
159#else
160 return 5.0f; // Default current
161#endif
162 }
163#ifdef USE_TEXT_SENSOR
164 void check_phase_status();
165 void check_freq_status();
167 this->phase_status_text_sensor_[phase] = sensor;
168 }
169#endif
170 static uint16_t calculate_voltage_threshold_from_volts(float voltage_rms, uint16_t ugain);
171 static uint16_t calculate_current_threshold_from_amps(float current_rms, uint16_t igain);
172
173 protected:
175#ifdef USE_NUMBER
176 number::Number *ref_voltages_[3]{nullptr, nullptr, nullptr};
177 number::Number *ref_currents_[3]{nullptr, nullptr, nullptr};
178#endif
179 uint16_t read16_(uint16_t a_register);
180 int read32_(uint16_t addr_h, uint16_t addr_l);
181 void write16_(uint16_t a_register, uint16_t val, bool validate = true);
182 float get_local_phase_voltage_(uint8_t phase);
183 float get_local_phase_current_(uint8_t phase);
184 float get_local_phase_active_power_(uint8_t phase);
185 float get_local_phase_reactive_power_(uint8_t phase);
186 float get_local_phase_apparent_power_(uint8_t phase);
187 float get_local_phase_power_factor_(uint8_t phase);
188 float get_local_phase_forward_active_energy_(uint8_t phase);
189 float get_local_phase_reverse_active_energy_(uint8_t phase);
190 float get_local_phase_angle_(uint8_t phase);
191 float get_local_phase_harmonic_active_power_(uint8_t phase);
192 float get_local_phase_peak_current_(uint8_t phase);
193 float get_phase_voltage_(uint8_t phase);
194 float get_phase_voltage_avg_(uint8_t phase);
195 float get_phase_current_(uint8_t phase);
196 float get_phase_current_avg_(uint8_t phase);
197 float get_phase_active_power_(uint8_t phase);
198 float get_phase_reactive_power_(uint8_t phase);
199 float get_phase_apparent_power_(uint8_t phase);
200 float get_phase_power_factor_(uint8_t phase);
201 float get_phase_forward_active_energy_(uint8_t phase);
202 float get_phase_reverse_active_energy_(uint8_t phase);
203 float get_phase_angle_(uint8_t phase);
204 float get_phase_harmonic_active_power_(uint8_t phase);
205 float get_phase_peak_current_(uint8_t phase);
206 float get_frequency_();
207 float get_chip_temperature_();
212 void finish_gain_calibration_(const GainCalibration (&previous)[3]);
214 // Persists verified register values; otherwise rollback() rewrites the previous values and returns their readback.
215 // name starts a sentence; noun is used mid-sentence, keeping the log text the calibration helper matches.
216 template<typename T, typename F>
217 void finish_calibration_(const LogString *name, const LogString *noun, ESPPreferenceObject &preference,
218 const T (&values)[3], bool writes_verified, bool &has_stored, bool &restored,
219 bool (&mismatches)[3], F &&rollback);
220 bool clear_calibration_pref_(ESPPreferenceObject &preference, bool &has_stored, bool &restored,
221 bool (&mismatches)[3]);
222 void configure_chip_();
223 void write_offsets_to_registers_(uint8_t phase, int16_t first_offset, int16_t second_offset,
226 void write_thresholds_();
227 bool verify_gain_writes_();
229 bool validate_spi_read_(uint16_t expected, const char *context = nullptr);
231 const char *get_calibration_id_();
232 void get_cs_summary_(std::span<char, GPIO_SUMMARY_MAX_LEN> buffer);
233
266
271
274
275 bool has_config_voltage_offset_[3]{false, false, false};
276 bool has_config_current_offset_[3]{false, false, false};
277 bool has_config_active_power_offset_[3]{false, false, false};
278 bool has_config_reactive_power_offset_[3]{false, false, false};
279 bool has_config_voltage_gain_[3]{false, false, false};
280 bool has_config_current_gain_[3]{false, false, false};
281
285
287
288#ifdef USE_TEXT_SENSOR
290#endif
291 uint16_t pga_gain_{0x15};
292 int line_freq_{60};
300 float threshold_current_peak_a_{NAN}; // NAN keeps the legacy OITH register and 65.53 A software limit
303 const char *instance_id_{nullptr};
311#ifdef USE_TEXT_SENSOR
314#endif
315 bool offset_calibration_mismatch_[3]{false, false, false};
316 bool power_offset_calibration_mismatch_[3]{false, false, false};
317 bool gain_calibration_mismatch_[3]{false, false, false};
318
319 // Last, so no member below them becomes public
320 SUB_SENSOR(freq)
321 SUB_SENSOR(chip_temperature)
322#ifdef USE_TEXT_SENSOR
323 SUB_TEXT_SENSOR(freq_status)
324#endif
325};
326
327} // namespace esphome::atm90e32
This class simplifies creating components that periodically check a state.
Definition component.h:532
float get_local_phase_reactive_power_(uint8_t phase)
Definition atm90e32.cpp:475
float get_phase_forward_active_energy_(uint8_t phase)
Definition atm90e32.cpp:558
OffsetCalibration config_power_offset_phase_[3]
Definition atm90e32.h:270
float get_phase_current_avg_(uint8_t phase)
Definition atm90e32.cpp:517
float get_local_phase_apparent_power_(uint8_t phase)
Definition atm90e32.cpp:477
void set_frequency_thresholds(uint16_t low, uint16_t high)
Definition atm90e32.h:124
void write16_(uint16_t a_register, uint16_t val, bool validate=true)
Definition atm90e32.cpp:454
void finish_gain_calibration_(const GainCalibration(&previous)[3])
Definition atm90e32.cpp:784
void set_apparent_power_sensor(int phase, sensor::Sensor *obj)
Definition atm90e32.h:83
ESPPreferenceObject power_offset_pref_
Definition atm90e32.h:283
const uint16_t voltage_gain_registers[3]
Definition atm90e32.h:56
void restore_offset_calibrations_(OffsetCalibrationType type)
float get_phase_voltage_avg_(uint8_t phase)
Definition atm90e32.cpp:503
const uint16_t current_gain_registers[3]
Definition atm90e32.h:58
float get_reference_voltage(uint8_t phase)
Definition atm90e32.h:149
number::Number * ref_voltages_[3]
Definition atm90e32.h:176
void set_power_sensor(int phase, sensor::Sensor *obj)
Definition atm90e32.h:81
void set_current_offset(uint8_t phase, int16_t offset)
Definition atm90e32.h:108
void press_calibration_button(EntityBase *entity, void(ATM90E32Component::*action)(), const LogString *hint=nullptr, const LogString *hint2=nullptr)
Definition atm90e32.cpp:608
const uint16_t current_offset_registers[3]
Definition atm90e32.h:62
static const uint8_t PHASEB
Definition atm90e32.h:52
float get_phase_reverse_active_energy_(uint8_t phase)
Definition atm90e32.cpp:569
void set_reactive_power_offset(uint8_t phase, int16_t offset)
Definition atm90e32.h:116
float get_local_phase_harmonic_active_power_(uint8_t phase)
Definition atm90e32.cpp:491
float get_phase_angle_(uint8_t phase)
Definition atm90e32.cpp:585
float get_local_phase_current_(uint8_t phase)
Definition atm90e32.cpp:471
bool validate_spi_read_(uint16_t expected, const char *context=nullptr)
void set_peak_current_sensor(int phase, sensor::Sensor *obj)
Definition atm90e32.h:95
const uint16_t reactive_power_offset_registers[3]
Definition atm90e32.h:66
const uint16_t over_voltage_flags[3]
Definition atm90e32.h:68
void set_reverse_active_energy_sensor(int phase, sensor::Sensor *obj)
Definition atm90e32.h:87
float get_phase_voltage_(uint8_t phase)
Definition atm90e32.cpp:497
void set_current_sensor(int phase, sensor::Sensor *obj)
Definition atm90e32.h:80
GainCalibration config_gain_phase_[3]
Definition atm90e32.h:273
int16_t calibrate_offset(uint8_t phase, bool voltage)
float get_local_phase_reverse_active_energy_(uint8_t phase)
Definition atm90e32.cpp:485
void set_harmonic_active_power_sensor(int phase, sensor::Sensor *obj)
Definition atm90e32.h:92
float get_local_phase_forward_active_energy_(uint8_t phase)
Definition atm90e32.cpp:481
OffsetCalibration config_offset_phase_[3]
Definition atm90e32.h:268
void set_active_power_offset(uint8_t phase, int16_t offset)
Definition atm90e32.h:112
static uint16_t calculate_voltage_threshold_from_volts(float voltage_rms, uint16_t ugain)
float get_local_phase_power_factor_(uint8_t phase)
Definition atm90e32.cpp:479
float get_phase_reactive_power_(uint8_t phase)
Definition atm90e32.cpp:542
void set_enable_gain_calibration(bool flag)
Definition atm90e32.h:137
const uint16_t phase_loss_flags[3]
Definition atm90e32.h:72
float get_phase_apparent_power_(uint8_t phase)
Definition atm90e32.cpp:547
void set_threshold_current_peak_a(float current)
Definition atm90e32.h:123
float get_local_phase_voltage_(uint8_t phase)
Definition atm90e32.cpp:469
void set_phase_status_text_sensor(uint8_t phase, text_sensor::TextSensor *sensor)
Definition atm90e32.h:166
void set_pga_gain(uint16_t gain)
Definition atm90e32.h:130
void set_reference_current(uint8_t phase, number::Number *ref_current)
Definition atm90e32.h:147
ESPPreferenceObject gain_calibration_pref_
Definition atm90e32.h:284
void set_instance_id(const char *id)
Definition atm90e32.h:138
void set_threshold_voltage_peak_v(float voltage)
Definition atm90e32.h:122
static const uint8_t PHASEA
Definition atm90e32.h:51
float get_reference_current(uint8_t phase)
Definition atm90e32.h:156
number::Number * ref_currents_[3]
Definition atm90e32.h:177
float get_phase_peak_current_(uint8_t phase)
Definition atm90e32.cpp:590
void set_voltage_offset(uint8_t phase, int16_t offset)
Definition atm90e32.h:104
void finish_offset_calibration_(const OffsetCalibration(&previous)[3], OffsetCalibrationType type)
Definition atm90e32.cpp:795
float get_phase_harmonic_active_power_(uint8_t phase)
Definition atm90e32.cpp:580
const uint16_t voltage_sag_flags[3]
Definition atm90e32.h:70
float get_phase_active_power_(uint8_t phase)
Definition atm90e32.cpp:537
void get_cs_summary_(std::span< char, GPIO_SUMMARY_MAX_LEN > buffer)
Definition atm90e32.cpp:116
static const uint8_t PHASEC
Definition atm90e32.h:53
const uint16_t power_offset_registers[3]
Definition atm90e32.h:64
float get_setup_priority() const override
Definition atm90e32.cpp:421
uint16_t read16_(uint16_t a_register)
Definition atm90e32.cpp:426
int read32_(uint16_t addr_h, uint16_t addr_l)
Definition atm90e32.cpp:441
void write_offsets_to_registers_(uint8_t phase, int16_t first_offset, int16_t second_offset, OffsetCalibrationType type)
Definition atm90e32.cpp:936
void set_threshold_voltage_sag_v(float voltage)
Definition atm90e32.h:121
float get_phase_power_factor_(uint8_t phase)
Definition atm90e32.cpp:552
void set_voltage_sensor(int phase, sensor::Sensor *obj)
Definition atm90e32.h:79
OffsetCalibration power_offset_phase_[3]
Definition atm90e32.h:269
float get_local_phase_angle_(uint8_t phase)
Definition atm90e32.cpp:489
const uint16_t voltage_offset_registers[3]
Definition atm90e32.h:60
void set_ct_gain(int phase, uint16_t gain)
Definition atm90e32.h:100
void set_phase_angle_sensor(int phase, sensor::Sensor *obj)
Definition atm90e32.h:91
OffsetCalibration offset_phase_[3]
Definition atm90e32.h:267
void set_reference_voltage(uint8_t phase, number::Number *ref_voltage)
Definition atm90e32.h:146
bool clear_calibration_pref_(ESPPreferenceObject &preference, bool &has_stored, bool &restored, bool(&mismatches)[3])
void set_power_factor_sensor(int phase, sensor::Sensor *obj)
Definition atm90e32.h:90
void set_forward_active_energy_sensor(int phase, sensor::Sensor *obj)
Definition atm90e32.h:84
void set_volt_gain(int phase, uint16_t gain)
Definition atm90e32.h:96
static uint16_t calculate_current_threshold_from_amps(float current_rms, uint16_t igain)
text_sensor::TextSensor * phase_status_text_sensor_[3]
Definition atm90e32.h:289
float get_phase_current_(uint8_t phase)
Definition atm90e32.cpp:531
void set_peak_current_signed(bool flag)
Definition atm90e32.h:120
float get_local_phase_peak_current_(uint8_t phase)
Definition atm90e32.cpp:495
void set_publish_interval_flag_(bool flag)
Definition atm90e32.h:209
int16_t calibrate_power_offset(uint8_t phase, bool reactive)
struct esphome::atm90e32::ATM90E32Component::ATM90E32Phase phase_[3]
bool verify_offset_writes_(OffsetCalibrationType type)
void set_enable_offset_calibration(bool flag)
Definition atm90e32.h:136
ESPPreferenceObject offset_pref_
Definition atm90e32.h:282
void set_reactive_power_sensor(int phase, sensor::Sensor *obj)
Definition atm90e32.h:82
void finish_calibration_(const LogString *name, const LogString *noun, ESPPreferenceObject &preference, const T(&values)[3], bool writes_verified, bool &has_stored, bool &restored, bool(&mismatches)[3], F &&rollback)
Definition atm90e32.cpp:722
float get_local_phase_active_power_(uint8_t phase)
Definition atm90e32.cpp:473
Base-class for all numbers.
Definition number.h:29
Base-class for all sensors.
Definition sensor.h:48
The SPIDevice is what components using the SPI will create.
Definition spi.h:456
uint16_t id
uint8_t type
uint32_t buffer
Definition gif.cpp:50
AlsGain501 gain
mopeka_std_values val[3]
bool offset_register_value_matches(uint16_t actual, int16_t expected)
Definition atm90e32.h:20
static void uint32_t