ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
hon_water_heater.cpp
Go to the documentation of this file.
1#include "hon_water_heater.h"
2
3#include <cmath>
4
6#ifdef USE_NETWORK
8#endif
9#include "esphome/core/log.h"
11
13
14ESPHOME_LOG_TAG(TAG, "haier_water_heater");
15using namespace water_heater_protocol;
16
17#ifdef USE_TEXT_SENSOR
18// Indexed by HonMode, with Unknown as the fallback for out-of-range values.
19PROGMEM_STRING_TABLE(HonModeLabels, "Unknown", "Normal", "ECO", "BPS");
20#endif
21
23 this->status_set_warning(LOG_STR("Waiting for a valid appliance status frame"));
24 this->publish_communication_(false);
26 this->set_interval(NETWORK_STATUS_INTERVAL_ID, NETWORK_STATUS_INTERVAL_MS,
27 [this]() { this->update_network_status_(); });
29}
30
32#ifdef USE_BINARY_SENSOR
33 PUBLISH_STATE(this->communication_binary_sensor_, connected);
34#endif
35}
36
38#ifdef USE_NETWORK
39 const bool ready = network::is_connected();
40#else
41 const bool ready = false;
42#endif
43 const uint8_t status = ready ? NETWORK_READY : NETWORK_NOT_READY;
44 if (status != this->network_status_) {
45 this->network_status_ = status;
46 this->network_pending_ = true;
47 ESP_LOGI(TAG, "Local network status changed: %02X", status);
48 }
49}
50
51void HonWaterHeater::send_frame_(FrameType type, const uint8_t *payload, size_t size) {
52 uint8_t wire[MAX_WIRE_FRAME];
53 const size_t length = encode_frame(type, payload, size, wire);
54 if (length == 0)
55 return;
56 ESP_LOGV_HEX(TAG, wire, length, sizeof(wire), "TX type=%02X: %s", static_cast<uint8_t>(type));
57 this->write_array(wire, length);
58}
59
60void HonWaterHeater::send_request_(uint32_t now, Awaiting kind, FrameType type, const uint8_t *payload, size_t size,
61 FrameType expected) {
62 this->send_frame_(type, payload, size);
63 this->awaiting_ = kind;
64 this->expected_type_ = expected;
65 this->request_sent_ = now;
66}
67
70 this->check_timeouts_(now);
71 if (this->awaiting_ != Awaiting::AWAITING_NONE || this->command_count_ != 0 || this->pending_off_)
72 return;
73 if (this->network_pending_ || now - this->network_sent_ >= NETWORK_REFRESH_MS)
74 return; // the network status goes out first, from loop()
75 // The version and device id are read once per cycle, the status on every other pass.
76 static constexpr uint8_t VERSION_REQUEST[] = {0x00, 0x07};
77 static constexpr uint8_t STATUS_REQUEST[] = {0x4D, 0x01};
78 if (this->poll_stage_ == 0) {
79 this->send_request_(now, Awaiting::AWAITING_POLL, FrameType::FRAME_TYPE_GET_VERSION, VERSION_REQUEST,
80 sizeof(VERSION_REQUEST), FrameType::FRAME_TYPE_VERSION);
81 } else if (this->poll_stage_ == 1) {
82 this->send_request_(now, Awaiting::AWAITING_POLL, FrameType::FRAME_TYPE_GET_DEVICE_ID, nullptr, 0,
83 FrameType::FRAME_TYPE_DEVICE_ID);
84 } else {
85 this->send_request_(now, Awaiting::AWAITING_POLL, FrameType::FRAME_TYPE_CONTROL, STATUS_REQUEST,
86 sizeof(STATUS_REQUEST), FrameType::FRAME_TYPE_STATUS);
87 }
88 this->poll_stage_ = (this->poll_stage_ + 1) % POLL_CYCLE;
89}
90
92 if (this->have_status_ && now - this->last_status_ >= this->communication_timeout_) {
93 this->have_status_ = false;
94 this->status_set_warning(LOG_STR("Heater communication timed out"));
95 ESP_LOGW(TAG, "Heater communication lost: no valid status for %u ms",
96 static_cast<unsigned>(this->communication_timeout_));
97 this->publish_communication_(false);
98 }
99 const uint32_t waited = now - this->request_sent_;
100 switch (this->awaiting_) {
102 break;
104 if (waited >= RESPONSE_TIMEOUT_MS) {
105 ESP_LOGW(TAG, "No matching response type=%02X in %u ms", static_cast<uint8_t>(this->expected_type_),
106 static_cast<unsigned>(RESPONSE_TIMEOUT_MS));
108 }
109 break;
111 if (waited >= RESPONSE_TIMEOUT_MS) {
112 ESP_LOGW(TAG, "Control response timed out; discarding remaining commands");
114 this->command_count_ = 0;
115 }
116 break;
118 if (waited >= NETWORK_ACK_TIMEOUT_MS) {
119 ESP_LOGW(TAG, "Network status: no CONFIRM within %u ms", static_cast<unsigned>(NETWORK_ACK_TIMEOUT_MS));
121 }
122 break;
123 }
124}
125
128 return;
129 if (this->pending_off_) {
130 this->commands_[0] = {Parameter::PARAMETER_POWER, 0};
131 this->command_index_ = 0;
132 this->command_count_ = 1;
133 this->pending_off_ = false;
134 }
135 if (this->command_count_ == 0 && (this->network_pending_ || now - this->network_sent_ >= NETWORK_REFRESH_MS)) {
136 // Signal remains a placeholder; status represents local IP readiness, not cloud access.
137 const uint8_t payload[] = {0x00, this->network_status_, 0x00, 100};
138 this->send_request_(now, Awaiting::AWAITING_NETWORK, FrameType::FRAME_TYPE_NETWORK_STATUS, payload, sizeof(payload),
139 FrameType::FRAME_TYPE_CONFIRM);
140 this->network_sent_ = now;
141 this->network_pending_ = false;
142 return;
143 }
144 if (this->command_count_ != 0)
145 this->send_next_control_(now);
146}
147
149 uint8_t payload[4];
150 encode_control(this->commands_[this->command_index_], payload);
151 this->send_request_(now, Awaiting::AWAITING_CONTROL, FrameType::FRAME_TYPE_CONTROL, payload, sizeof(payload),
152 FrameType::FRAME_TYPE_STATUS);
153}
154
156 if (now - this->last_byte_ > FRAME_GAP_MS)
157 this->parser_.reset();
158 uint8_t budget = MAX_BYTES_PER_LOOP;
159 while (budget-- > 0 && this->available() > 0) {
160 uint8_t value;
161 if (!this->read_byte(&value))
162 break;
163 this->last_byte_ = now;
164 if (this->parser_.feed(value)) {
165 this->process_frame_();
166 } else if (this->parser_.complete()) {
167 if ((this->parser_.data()[FRAME_FLAGS_OFFSET] & FRAME_FLAG_ENCRYPTED) != 0) {
168 ESP_LOGW(TAG, "RX: XOR-encrypted frames are not supported and will be dropped");
169 } else {
170 ESP_LOGW(TAG, "RX: unsupported flags or invalid checksum/CRC");
171 }
172 }
173 }
174}
175
178 this->check_timeouts_(now);
179 this->send_pending_(now);
180 this->read_frames_(now);
181}
182
184 if (this->awaiting_ == Awaiting::AWAITING_POLL && type == this->expected_type_) {
185 ESP_LOGV(TAG, "Response matched type=%02X", static_cast<uint8_t>(type));
187 }
188 switch (type) {
189 case FrameType::FRAME_TYPE_GET_NETWORK_STATUS:
190 this->network_pending_ = true;
191 break;
192 case FrameType::FRAME_TYPE_CONFIRM:
194 ESP_LOGD(TAG, "Network status acknowledged");
196 }
197 break;
198 case FrameType::FRAME_TYPE_INVALID:
199 ESP_LOGW(TAG, "Appliance rejected request");
200 // Controls queued behind a rejected poll were never sent and keep their turn.
202 this->command_count_ = 0;
205 break;
206 case FrameType::FRAME_TYPE_REPORT:
207 this->send_frame_(FrameType::FRAME_TYPE_CONFIRM);
208 break;
209 default:
210 break;
211 }
212}
213
215 const Command &command = this->commands_[this->command_index_];
216 if (!command_confirmed(command, status))
217 return;
218 ESP_LOGD(TAG, "Control confirmed: parameter=%02X value=%02X", static_cast<uint8_t>(command.parameter), command.value);
220 if (++this->command_index_ == this->command_count_)
221 this->command_count_ = 0;
222}
223
225 const uint8_t *frame = this->parser_.data();
226 const auto type = static_cast<FrameType>(frame[FRAME_TYPE_OFFSET]);
227 ESP_LOGV_HEX(TAG, frame, this->parser_.stored_size(), MAX_STORED_FRAME, "RX decoded type=%02X flags=%02X: %s",
228 static_cast<uint8_t>(type), frame[FRAME_FLAGS_OFFSET]);
230
231 Status status{};
232 if (!decode_status(frame, this->parser_.size(), status))
233 return;
234 const bool recovered = !this->have_status_;
235 if (status.mode == HonMode::HON_MODE_UNKNOWN && (recovered || this->reported_mode_ != HonMode::HON_MODE_UNKNOWN)) {
236 const uint8_t *payload = frame + FRAME_PAYLOAD_OFFSET;
237 ESP_LOGW(TAG,
238 "Unknown heater mode: payload[38..41]=%02X %02X %02X %02X; using last recognized active mode, or Electric "
239 "if none is known",
240 payload[38], payload[39], payload[40], payload[41]);
241 }
242 this->have_status_ = true;
244 this->reported_mode_ = status.mode;
245 if (this->awaiting_ == Awaiting::AWAITING_CONTROL && type == FrameType::FRAME_TYPE_STATUS)
247 this->status_clear_warning();
248 this->publish_status_(status);
249 // Published last so an automation on the sensor sees fresh heater state and can send a control.
250 if (recovered) {
251 ESP_LOGI(TAG, "Heater communication established");
252 this->publish_communication_(true);
253 }
254}
255
260 switch (status.mode) {
261 case HonMode::HON_MODE_NORMAL:
263 break;
264 case HonMode::HON_MODE_ECO:
266 break;
267 case HonMode::HON_MODE_BPS:
269 break;
270 case HonMode::HON_MODE_UNKNOWN:
271 break;
272 }
273 // The base entity has no Unknown mode; the text sensor preserves the decoded result.
275#ifdef USE_SENSOR
276 PUBLISH_STATE(this->primary_temperature_sensor_, status.current_temperature);
277 PUBLISH_STATE(this->secondary_temperature_sensor_,
278 status.secondary_temperature <= MAX_REPORTED_TEMPERATURE ? status.secondary_temperature : NAN);
279 PUBLISH_STATE(this->target_temperature_sensor_, status.target_temperature);
280 PUBLISH_STATE(this->estimated_heating_time_sensor_, status.estimated_heating_time);
281 // Three segments of available hot water, published as 0, 33, 66 or 100 percent.
282 PUBLISH_STATE(this->available_water_sensor_,
283 status.available_water <= 3 ? static_cast<uint8_t>(status.available_water * 100 / 3) : NAN);
284#endif
285#ifdef USE_BINARY_SENSOR
286 PUBLISH_STATE(this->power_binary_sensor_, status.powered);
287 PUBLISH_STATE(this->heating_binary_sensor_, status.heating);
288#endif
289#ifdef USE_TEXT_SENSOR
290 PUBLISH_STATE(this->mode_text_sensor_,
291 HonModeLabels::get_progmem_str(static_cast<uint8_t>(status.mode),
292 static_cast<uint8_t>(HonMode::HON_MODE_UNKNOWN)));
293#endif
294 this->publish_state();
295}
296
298 LOG_WATER_HEATER("", "Haier hOn", this);
299 ESP_LOGCONFIG(TAG,
300 " Polling interval: %u ms\n"
301 " Communication timeout: %u ms",
302 static_cast<unsigned>(POLL_INTERVAL_MS), static_cast<unsigned>(this->communication_timeout_));
303#ifdef USE_SENSOR
304 LOG_SENSOR(" ", "Primary temperature", this->primary_temperature_sensor_);
305 LOG_SENSOR(" ", "Secondary temperature", this->secondary_temperature_sensor_);
306 LOG_SENSOR(" ", "Target temperature", this->target_temperature_sensor_);
307 LOG_SENSOR(" ", "Estimated heating time", this->estimated_heating_time_sensor_);
308 LOG_SENSOR(" ", "Available water", this->available_water_sensor_);
309#endif
310#ifdef USE_BINARY_SENSOR
311 LOG_BINARY_SENSOR(" ", "Communication", this->communication_binary_sensor_);
312 LOG_BINARY_SENSOR(" ", "Power", this->power_binary_sensor_);
313 LOG_BINARY_SENSOR(" ", "Heating", this->heating_binary_sensor_);
314#endif
315#ifdef USE_TEXT_SENSOR
316 LOG_TEXT_SENSOR(" ", "Mode", this->mode_text_sensor_);
317#endif
318}
319
323
324// The appliance mode a water heater mode maps to; Unknown for modes the appliance does not have.
326 switch (mode) {
328 return HonMode::HON_MODE_NORMAL;
330 return HonMode::HON_MODE_ECO;
332 return HonMode::HON_MODE_BPS;
333 default:
334 return HonMode::HON_MODE_UNKNOWN;
335 }
336}
337
339 using namespace water_heater;
340 const auto mode = call.get_mode();
341 const auto on = call.get_on();
342 const bool off = (on.has_value() && !*on) || (mode.has_value() && *mode == WATER_HEATER_MODE_OFF);
343 if (off) {
344 // Keep only the command in flight until its reply or timeout; unsent writes are dropped.
346 this->commands_[0] = this->commands_[this->command_index_];
347 this->command_index_ = 0;
348 this->command_count_ = 1;
349 } else {
350 this->command_count_ = 0;
351 }
352 this->pending_off_ = true;
353 return;
354 }
355 if (!this->have_status_ || App.get_loop_component_start_time() - this->last_status_ > CONTROL_STATUS_MAX_AGE_MS) {
356 ESP_LOGW(TAG, "Control rejected: no recent appliance status");
357 return;
358 }
359 if (this->command_count_ != 0 || this->pending_off_) {
360 ESP_LOGW(TAG, "Control busy; wait for the previous request to finish");
361 return;
362 }
363 const float temperature = call.get_target_temperature();
364 if (!std::isnan(temperature)) {
366 std::round(temperature) != temperature) {
367 ESP_LOGW(TAG, "Target must be a whole temperature from %u to %u C", MIN_TARGET_TEMPERATURE,
369 return;
370 }
371 const bool normal =
372 mode.has_value() ? *mode == WATER_HEATER_MODE_ELECTRIC : this->reported_mode_ == HonMode::HON_MODE_NORMAL;
373 if (!normal) {
374 ESP_LOGW(TAG, "Target can only be set in Normal mode");
375 return;
376 }
377 }
378 this->command_index_ = 0;
379 auto append = [this](Parameter parameter, uint8_t value) {
380 this->commands_[this->command_count_++] = {parameter, value};
381 };
382 // A write is only queued when it changes something, so a repeated state costs no round trip.
383 if (!this->is_on() && ((on.has_value() && *on) || mode.has_value()))
384 append(Parameter::PARAMETER_POWER, 1);
385 if (mode.has_value() && hon_mode(*mode) != this->reported_mode_) {
386 // Captures show the appliance moves between ECO and BPS through Normal, never directly.
387 if (*mode != WATER_HEATER_MODE_ELECTRIC && this->reported_mode_ != HonMode::HON_MODE_NORMAL)
388 append(Parameter::PARAMETER_ECO, 0);
389 switch (*mode) {
390 case WATER_HEATER_MODE_ELECTRIC:
391 append(Parameter::PARAMETER_ECO, 0);
392 break;
393 case WATER_HEATER_MODE_ECO:
394 append(Parameter::PARAMETER_ECO, 1);
395 break;
396 case WATER_HEATER_MODE_PERFORMANCE:
397 append(Parameter::PARAMETER_BPS, 1);
398 break;
399 default:
400 break;
401 }
402 }
403 if (!std::isnan(temperature))
404 append(Parameter::PARAMETER_TARGET_TEMPERATURE, static_cast<uint8_t>(temperature - TARGET_TEMPERATURE_OFFSET));
405}
406
408 using namespace water_heater;
409 WaterHeaterTraits traits;
411 traits.add_feature_flags(WATER_HEATER_SUPPORTS_TARGET_TEMPERATURE | WATER_HEATER_SUPPORTS_OPERATION_MODE |
412 WATER_HEATER_SUPPORTS_ON_OFF);
414 {WATER_HEATER_MODE_OFF, WATER_HEATER_MODE_ELECTRIC, WATER_HEATER_MODE_ECO, WATER_HEATER_MODE_PERFORMANCE});
418 return traits;
419}
420
421} // namespace esphome::haier_water_heater
BedjetMode mode
BedJet operating mode.
uint8_t status
Definition bl0942.h:8
uint32_t IRAM_ATTR HOT get_loop_component_start_time() const
Get the cached time in milliseconds from when the current component started its loop execution.
void set_interval(const char *name, uint32_t interval, std::function< void()> &&f)
Set an interval function with a const char* name.
Definition component.cpp:88
void status_clear_warning()
Definition component.h:309
water_heater::WaterHeaterCallInternal make_call() override
void handle_frame_type_(water_heater_protocol::FrameType type)
static SUB_SENSOR(primary_temperature) SUB_SENSOR(secondary_temperature) SUB_SENSOR(target_temperature) SUB_SENSOR(estimated_heating_time) SUB_SENSOR(available_water) SUB_BINARY_SENSOR(communication) SUB_BINARY_SENSOR(power) SUB_BINARY_SENSOR(heating) SUB_TEXT_SENSOR(mode) protected constexpr uint32_t STATUS_POLL_INTERVAL_ID
void send_request_(uint32_t now, Awaiting kind, water_heater_protocol::FrameType type, const uint8_t *payload, size_t size, water_heater_protocol::FrameType expected)
water_heater_protocol::FrameType expected_type_
void publish_status_(const water_heater_protocol::Status &status)
void send_frame_(water_heater_protocol::FrameType type, const uint8_t *payload=nullptr, size_t size=0)
water_heater_protocol::HonMode reported_mode_
static constexpr uint32_t NETWORK_ACK_TIMEOUT_MS
water_heater::WaterHeaterMode last_active_mode_
void control(const water_heater::WaterHeaterCall &call) override
void confirm_control_(const water_heater_protocol::Status &status)
static constexpr uint32_t NETWORK_STATUS_INTERVAL_MS
static constexpr uint32_t CONTROL_STATUS_MAX_AGE_MS
water_heater::WaterHeaterTraits traits() override
water_heater_protocol::FrameParser parser_
std::array< water_heater_protocol::Command, 4 > commands_
bool feed(uint8_t value)
Returns true once a valid frame is complete. A complete but invalid frame leaves complete() set.
Definition hon_parser.h:61
size_t size() const
Logical bytes received, including the checksum and CRC; may exceed MAX_STORED_FRAME.
Definition hon_parser.h:57
const uint8_t * data() const
The stored head of the frame, at most MAX_STORED_FRAME bytes; valid until the next feed or reset.
Definition hon_parser.h:55
bool read_byte(uint8_t *data)
Definition uart.h:39
void write_array(const uint8_t *data, size_t len)
Definition uart.h:30
void set_state_flag_(uint32_t flag, bool value)
Set or clear a state flag. Should only be called from control().
bool is_on() const
Check if the water heater is on.
void set_supported_modes(WaterHeaterModeMask modes)
void add_feature_flags(uint32_t flags)
Get/set feature flags (see WaterHeaterFeature enum)
void set_supports_current_temperature(bool supports)
void set_min_temperature(float min_temperature)
void set_target_temperature_step(float target_temperature_step)
void set_max_temperature(float max_temperature)
uint8_t type
bool decode_status(const uint8_t *frame, size_t size, Status &status)
Decodes a status report or a polled status; false for any other frame or an implausible one.
Definition hon_parser.h:202
bool command_confirmed(const Command &command, const Status &status)
True when a status shows that the command took effect.
Definition hon_parser.h:248
size_t encode_frame(FrameType type, const uint8_t *payload, size_t size, uint8_t *wire)
Writes a clear-text frame with up to MAX_PAYLOAD bytes of payload into wire, which must hold MAX_WIRE...
Definition hon_parser.h:137
void encode_control(const Command &command, uint8_t *payload)
Fills the four-byte control payload for a command.
Definition hon_parser.h:240
PROGMEM_STRING_TABLE(HonModeLabels, "Unknown", "Normal", "ECO", "BPS")
ESPHOME_LOG_TAG(TAG, "haier_water_heater")
ESPHOME_ALWAYS_INLINE bool is_connected()
Return whether the node is connected to the network (through wifi, eth, ...)
Definition util.h:36
@ WATER_HEATER_STATE_ON
Water heater is on (not in standby)
uint32_t value
Definition hal.cpp:41
uint16_t size
Definition helpers.cpp:34
Application App
Global storage of Application pointer - only one Application can exist.
static void uint32_t
uint16_t temperature
Definition sun_gtil2.cpp:12