ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
airton_serial_climate.cpp
Go to the documentation of this file.
2
3#include <algorithm>
4#include <cmath>
5#include <cstring>
6#include <iterator>
7
9#include "esphome/core/hal.h"
11#include "esphome/core/log.h"
12
14
15ESPHOME_LOG_TAG(TAG, "airton_serial.climate");
16
17static constexpr uint8_t SYNC_BYTE = 0x7A;
18static constexpr uint8_t LENGTH_POS = 4;
19static constexpr uint8_t OPCODE_POS = 7;
20static constexpr uint8_t MIN_FRAME_LEN = OPCODE_POS + 1 + 2; // Up to the opcode, then the CRC
21// A partial frame left this long without a new byte is not a frame start.
22static constexpr uint32_t FRAME_GAP_MS = 50;
23
24static constexpr uint8_t ADDR_MODULE = 0x21;
25static constexpr uint8_t ADDR_DISPLAY = 0xD1;
26static constexpr uint8_t ADDR_BOARD = 0xD5;
27
28static constexpr uint8_t OP_A3_STATE = 0xA3;
29static constexpr uint8_t OP_A4_ACK = 0xA4;
30static constexpr uint8_t OP_AC_POLL = 0xAC;
31
32// Announcement sent to the display every 10 s, followed by the ESP's MAC address and the CRC.
33static constexpr uint8_t A5_HEADER[] PROGMEM = {
34 0x7A, 0x7A, 0x21, 0xD1, 0x1B, 0x00, 0x00, 0xA5, 0x0A, 0x0A, 0x01, 0x03, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02,
35};
36
37// Poll sent to the climate board every 60 s.
38static constexpr uint8_t AB_FRAME[] PROGMEM = {
39 0x7A, 0x7A, 0x21, 0xD5, 0x0C, 0x00, 0x00, 0xAB, 0x0A, 0x0A, 0xFC, 0xF9,
40};
41
42static constexpr uint8_t TEMP_MIN = 16;
43static constexpr uint8_t TEMP_MAX = 31;
44
45// State byte: bit 7 super, bits 4-6 fan speed, bit 3 power, bits 0-2 mode.
46static constexpr uint8_t POWER_BIT = 0x08;
47static constexpr uint8_t MODE_MASK = 0x07;
48static constexpr uint8_t FAN_AUTO = 0x0;
49static constexpr uint8_t FAN_SUPER = 0x8; // Bit 7 of the state byte, the top bit of the fan nibble
50static constexpr uint8_t FAN_STRONG = FAN_SUPER | 0x5;
51// Setpoint byte: bit 6 mute, bit 5 Fahrenheit display, bits 0-4 setpoint above TEMP_MIN.
52static constexpr uint8_t FLAG_QUIET = 0x40;
53static constexpr uint8_t FLAG_FAHRENHEIT = 0x20;
54static constexpr uint8_t SETPOINT_MASK = 0x1F;
55// Swing byte: bit 0 vertical, bit 4 horizontal.
56static constexpr uint8_t SWING_VERTICAL = 0x01;
57static constexpr uint8_t SWING_HORIZONTAL = 0x10;
58static constexpr uint8_t SWING_MASK = SWING_VERTICAL | SWING_HORIZONTAL;
59
60struct CodeMap {
61 uint8_t value; // ESPHome enum value
62 uint8_t code; // Protocol nibble
63};
64
65// Mode bits; off is the power bit, which keeps the mode bits.
66static constexpr CodeMap MODE_CODES[] PROGMEM = {
69};
70
71static constexpr CodeMap SWING_CODES[] PROGMEM = {
73 {climate::CLIMATE_SWING_VERTICAL, SWING_VERTICAL},
74 {climate::CLIMATE_SWING_HORIZONTAL, SWING_HORIZONTAL},
75 {climate::CLIMATE_SWING_BOTH, SWING_MASK},
76};
77
78static constexpr CodeMap FAN_CODES[] PROGMEM = {
79 {climate::CLIMATE_FAN_AUTO, FAN_AUTO},
83};
84
85// Speeds with no standard ESPHome fan mode, and their codes at the same index.
86static constexpr const char *const CUSTOM_FAN_MODES[] = {"medlow", "medhigh", "strong"};
87static constexpr uint8_t CUSTOM_FAN_CODES[] PROGMEM = {0x2, 0x4, FAN_STRONG};
88
89template<size_t N> static bool code_of(const CodeMap (&table)[N], uint8_t value, uint8_t &code) {
90 for (const CodeMap &entry : table) {
91 if (progmem_read_byte(&entry.value) == value) {
92 code = progmem_read_byte(&entry.code);
93 return true;
94 }
95 }
96 return false;
97}
98
99template<size_t N> static bool value_of(const CodeMap (&table)[N], uint8_t code, uint8_t &value) {
100 for (const CodeMap &entry : table) {
101 if (progmem_read_byte(&entry.code) == code) {
102 value = progmem_read_byte(&entry.value);
103 return true;
104 }
105 }
106 return false;
107}
108
110 this->set_supported_custom_fan_modes_static(CUSTOM_FAN_MODES, std::size(CUSTOM_FAN_MODES));
111 this->target_temperature = 21.0f;
112}
113
115 // Announce and poll immediately, then keep the module's cadence.
116 this->send_a5_();
117 this->send_ab_();
118 this->set_interval(10000, [this]() { this->send_a5_(); });
119 this->set_interval(60000, [this]() { this->send_ab_(); });
120}
121
124 bool received = false;
125 this->read_available([this, &received](uint8_t byte) {
126 received = true;
127 this->handle_byte_(byte);
128 });
129 if (received) {
130 this->last_rx_ms_ = now;
131 } else if (this->rx_pos_ > 0 && now - this->last_rx_ms_ >= FRAME_GAP_MS) {
132 // A corrupt length can hold back complete frames behind it; look for them in what is buffered.
133 while (this->rx_pos_ > 0)
134 this->drop_first_byte_();
135 }
136}
137
139 // Bytes are checked as they arrive, so rx_pos_ stays below the longest frame length.
140 this->rx_buffer_[this->rx_pos_++] = byte;
141 this->scan_buffer_();
142}
143
145 this->rx_pos_--;
146 std::memmove(this->rx_buffer_.data(), this->rx_buffer_.data() + 1, this->rx_pos_);
147 this->scan_buffer_();
148}
149
151 const uint8_t *buf = this->rx_buffer_.data();
152 while (this->rx_pos_ > 0) {
153 uint8_t drop = 1;
154 if (buf[0] == SYNC_BYTE && (this->rx_pos_ < 2 || buf[1] == SYNC_BYTE)) {
155 if (this->rx_pos_ <= LENGTH_POS)
156 return;
157 const uint8_t len = buf[LENGTH_POS];
158 if (len >= MIN_FRAME_LEN && len <= MAX_FRAME_LEN) {
159 if (this->rx_pos_ < len)
160 return;
161 if (crc16(buf, len - 2) == encode_uint16(buf[len - 2], buf[len - 1])) {
162 this->handle_frame_(buf, len);
163 drop = len;
164 } else {
165 ESP_LOGW(TAG, "Bad CRC on %u-byte frame", len);
166 }
167 }
168 }
169 // Not a frame start, or a bad frame: look for the next start after its first byte.
170 this->rx_pos_ -= drop;
171 std::memmove(this->rx_buffer_.data(), buf + drop, this->rx_pos_);
172 }
173}
174
175void AirtonSerialClimate::handle_frame_(const uint8_t *data, size_t len) {
176 const uint8_t opcode = data[OPCODE_POS];
177#if ESPHOME_LOG_LEVEL >= ESPHOME_LOG_LEVEL_VERBOSE
178 if (opcode == OP_A3_STATE || opcode == OP_AC_POLL) {
179 char hex[format_hex_pretty_size(MAX_FRAME_LEN)];
180 ESP_LOGV(TAG, "%02X raw: %s", opcode, format_hex_pretty_to(hex, data, len));
181 }
182#endif
183 if (data[3] != ADDR_MODULE)
184 return;
185 if (data[2] == ADDR_BOARD) {
186 if (len == 34 && opcode == OP_A3_STATE) {
187 this->handle_a3_(data);
188 } else if (len == 18 && opcode == OP_AC_POLL) {
189 this->handle_ac_(data);
190 }
191 } else if (data[2] == ADDR_DISPLAY && len == 13 && opcode == OP_A4_ACK) {
192 ESP_LOGD(TAG, "A4 acknowledgement from display");
193 }
194}
195
196void AirtonSerialClimate::handle_a3_(const uint8_t *data) {
197 const uint8_t mode_fan = data[13];
198 const uint8_t setpoint_raw = data[14];
199 // Kept so that quiet, which mutes whatever speed is set, and speeds with no fan mode are sent back unchanged.
200 this->fan_raw_ = mode_fan >> 4;
201 this->fahrenheit_ = (setpoint_raw & FLAG_FAHRENHEIT) != 0;
202 // Super is reported with the speed it runs at; it is the "strong" custom mode.
203 const uint8_t fan = (this->fan_raw_ & FAN_SUPER) != 0 ? FAN_STRONG : this->fan_raw_;
204 const uint8_t mode = mode_fan & (POWER_BIT | MODE_MASK);
205 const uint8_t setpoint = (setpoint_raw & SETPOINT_MASK) + TEMP_MIN;
206
207 this->current_temperature = static_cast<float>(data[10]) + static_cast<float>(data[11]) / 10.0f;
208 this->target_temperature = static_cast<float>(setpoint);
209
210 uint8_t value;
211 this->mode_bits_ = mode & MODE_MASK;
212 if ((mode & POWER_BIT) == 0) {
213 this->mode = climate::CLIMATE_MODE_OFF;
214 } else if (value_of(MODE_CODES, this->mode_bits_, value)) {
215 this->mode = static_cast<climate::ClimateMode>(value);
216 }
217
218 if ((setpoint_raw & FLAG_QUIET) != 0) {
220 } else if (value_of(FAN_CODES, fan, value)) {
221 this->set_fan_mode_(static_cast<climate::ClimateFanMode>(value));
222 } else {
223 bool found = false;
224 for (size_t i = 0; i < std::size(CUSTOM_FAN_MODES) && !found; i++) {
225 found = progmem_read_byte(&CUSTOM_FAN_CODES[i]) == fan;
226 if (found)
227 this->set_custom_fan_mode_(CUSTOM_FAN_MODES[i]);
228 }
229 if (!found) {
230 // Speed 6 has no fan mode; with none set, commands send fan_raw_ back.
231 this->fan_mode.reset();
233 }
234 }
235
236 this->swing_ = data[15];
237 if (value_of(SWING_CODES, this->swing_ & SWING_MASK, value))
238 this->swing_mode = static_cast<climate::ClimateSwingMode>(value);
239 this->flags_ = data[16];
240 this->state_received_ = true;
241 ESP_LOGD(TAG, "A3: mode=0x%02X fan=0x%02X setpoint=%u ambient=%.1f swing=%u flags=0x%02X", mode, fan, setpoint,
242 this->current_temperature, data[15], data[16]);
243 this->publish_settings_();
244 this->publish_state();
245}
246
247void AirtonSerialClimate::handle_ac_(const uint8_t *data) {
248 const uint16_t total_usage_time = encode_uint16(data[10], data[11]);
249 const uint16_t revision = encode_uint16(data[13], data[14]);
250#ifdef USE_SENSOR
251 this->total_usage_time_sensor_.publish_state_if_not_dup(total_usage_time);
252 this->revision_sensor_.publish_state_if_not_dup(revision);
253#endif
254 ESP_LOGD(TAG, "AC: total_usage_time=%u h revision=%u", total_usage_time, revision);
255}
256
258#ifdef USE_SWITCH
259 PUBLISH_STATE(this->display_switch_, (this->flags_ & FLAG_DISPLAY) != 0);
260 PUBLISH_STATE(this->ionizer_switch_, (this->flags_ & FLAG_IONIZER) != 0);
261 PUBLISH_STATE(this->sleep_switch_, (this->flags_ & FLAG_SLEEP) != 0);
262 PUBLISH_STATE(this->eco_switch_, (this->flags_ & FLAG_ECO) != 0);
263 PUBLISH_STATE(this->health_switch_, (this->flags_ & FLAG_HEALTH) != 0);
264#endif
265}
266
268 if (!this->state_received_) {
269 ESP_LOGW(TAG, "No state from the unit yet, change ignored");
270 }
271 return this->state_received_;
272}
273
274bool AirtonSerialClimate::set_flag(uint8_t flag, bool state) {
275 if (!this->can_send_command_())
276 return false;
277 assign_bits(this->flags_, flag, state);
278 this->send_command_();
279 return true;
280}
281
283 // A1 carries the whole state, so sending it before the unit reported its own would apply the defaults.
284 if (!this->can_send_command_())
285 return;
286 if (call.get_mode().has_value())
287 this->mode = *call.get_mode();
288 if (call.get_target_temperature().has_value()) {
289 // The unit takes whole degrees.
290 this->target_temperature = static_cast<float>(
291 std::clamp<int32_t>(static_cast<int32_t>(std::lround(*call.get_target_temperature())), TEMP_MIN, TEMP_MAX));
292 }
293 if (call.has_custom_fan_mode()) {
295 } else if (call.get_fan_mode().has_value()) {
296 this->set_fan_mode_(*call.get_fan_mode());
297 }
298 if (call.get_swing_mode().has_value()) {
299 this->swing_mode = *call.get_swing_mode();
300 uint8_t code = 0;
301 code_of(SWING_CODES, this->swing_mode, code);
302 // Other bits of the swing byte are kept as the unit reported them.
303 this->swing_ = static_cast<uint8_t>((this->swing_ & ~SWING_MASK) | code);
304 }
305
306 this->send_command_();
307 this->publish_state();
308}
309
311 // Off clears the power bit and leaves the last mode bits, as the unit reports them.
312 uint8_t mode_nibble = this->mode_bits_;
313 if (code_of(MODE_CODES, this->mode, this->mode_bits_))
314 mode_nibble = this->mode_bits_ | POWER_BIT;
315
316 uint8_t fan_nibble = this->fan_raw_;
317 bool quiet = false;
318 if (this->has_custom_fan_mode()) {
319 const StringRef custom = this->get_custom_fan_mode();
320 for (size_t i = 0; i < std::size(CUSTOM_FAN_MODES); i++) {
321 if (custom == CUSTOM_FAN_MODES[i]) {
322 fan_nibble = progmem_read_byte(&CUSTOM_FAN_CODES[i]);
323 break;
324 }
325 }
326 // Super runs on top of a speed; keep the one the unit reported instead of forcing speed 5
327 if (fan_nibble == FAN_STRONG && (this->fan_raw_ & FAN_SUPER) != 0)
328 fan_nibble = this->fan_raw_;
329 } else if (this->fan_mode.has_value()) {
330 quiet = *this->fan_mode == climate::CLIMATE_FAN_QUIET;
331 if (!quiet)
332 code_of(FAN_CODES, *this->fan_mode, fan_nibble);
333 }
334 this->fan_raw_ = fan_nibble;
335
336 const int32_t rounded =
337 std::clamp<int32_t>(static_cast<int32_t>(std::lround(this->target_temperature)), TEMP_MIN, TEMP_MAX);
338 uint8_t setpoint = static_cast<uint8_t>(rounded - TEMP_MIN);
339 if (quiet)
340 setpoint |= FLAG_QUIET;
341 if (this->fahrenheit_)
342 setpoint |= FLAG_FAHRENHEIT;
343
344 const uint8_t state = static_cast<uint8_t>((fan_nibble << 4) | mode_nibble);
345
346 uint8_t frame[24]{};
347 frame[0] = SYNC_BYTE;
348 frame[1] = SYNC_BYTE;
349 frame[2] = ADDR_MODULE;
350 frame[3] = ADDR_BOARD;
351 frame[LENGTH_POS] = sizeof(frame);
352 frame[OPCODE_POS] = 0xA1;
353 frame[12] = state;
354 frame[13] = setpoint;
355 frame[14] = this->swing_;
356 frame[15] = this->flags_;
357 this->write_frame_(frame, sizeof(frame));
358 ESP_LOGD(TAG, "A1: state=0x%02X setpoint=0x%02X swing=0x%02X flags=0x%02X", state, setpoint, this->swing_,
359 this->flags_);
360}
361
362void AirtonSerialClimate::send_a5_() {
363 uint8_t frame[sizeof(A5_HEADER) + MAC_ADDRESS_SIZE + 2]{}; // MAC stays zero without networking
364 progmem_memcpy(frame, A5_HEADER, sizeof(A5_HEADER));
365 get_mac_address_raw(frame + sizeof(A5_HEADER));
366 this->write_frame_(frame, sizeof(frame));
367}
368
370 uint8_t frame[sizeof(AB_FRAME)];
371 progmem_memcpy(frame, AB_FRAME, sizeof(AB_FRAME));
372 this->write_array(frame, sizeof(frame));
373}
374
375void AirtonSerialClimate::write_frame_(uint8_t *frame, size_t len) {
376 const uint16_t crc = crc16(frame, len - 2);
377 frame[len - 2] = static_cast<uint8_t>(crc >> 8);
378 frame[len - 1] = static_cast<uint8_t>(crc);
379 this->write_array(frame, len);
380}
381
397
399 LOG_CLIMATE("", "Airton Serial Climate", this);
400#ifdef USE_SWITCH
401 LOG_SWITCH(" ", "Display", this->display_switch_);
402 LOG_SWITCH(" ", "Ionizer", this->ionizer_switch_);
403 LOG_SWITCH(" ", "Sleep", this->sleep_switch_);
404 LOG_SWITCH(" ", "Eco", this->eco_switch_);
405 LOG_SWITCH(" ", "Health", this->health_switch_);
406#endif
407#ifdef USE_SENSOR
408 LOG_SENSOR_WITH_DEDUP(" ", "Total Usage Time", this->total_usage_time_sensor_);
409 LOG_SENSOR_WITH_DEDUP(" ", "Revision", this->revision_sensor_);
410#endif
411}
412
413} // namespace esphome::airton_serial
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
StringRef is a reference to a string owned by something else.
Definition string_ref.h:31
void control(const climate::ClimateCall &call) override
uint16_t SUB_SENSOR_WITH_DEDUP(revision, uint16_t) protected void send_ab_()
std::array< uint8_t, MAX_FRAME_LEN > rx_buffer_
bool set_flag(uint8_t flag, bool state)
Set or clear one FLAG_* bit and send it to the unit; false until the unit has reported its state.
void handle_frame_(const uint8_t *data, size_t len)
This class is used to encode all control actions on a climate device.
Definition climate.h:31
const optional< ClimateSwingMode > & get_swing_mode() const
Definition climate.cpp:317
const optional< ClimateFanMode > & get_fan_mode() const
Definition climate.cpp:316
StringRef get_custom_fan_mode() const
Definition climate.h:124
const optional< ClimateMode > & get_mode() const
Definition climate.cpp:315
ClimateMode mode
The active mode of the climate device.
Definition climate.h:317
optional< ClimateFanMode > fan_mode
The active fan mode of the climate device.
Definition climate.h:311
float target_temperature
The target temperature of the climate device.
Definition climate.h:298
ClimateSwingMode swing_mode
The active swing mode of the climate device.
Definition climate.h:323
bool set_fan_mode_(ClimateFanMode mode)
Set fan mode. Reset custom fan mode. Return true if fan mode has been changed.
Definition climate.cpp:663
void clear_custom_fan_mode_()
Clear custom fan mode.
Definition climate.cpp:672
float current_temperature
The current temperature of the climate device, as reported from the integration.
Definition climate.h:291
void set_supported_custom_fan_modes_static(const char *const *modes, size_t count)
Points at a static table that outlives the climate (codegen); call before any runtime copy.
Definition climate.h:265
void publish_state()
Publish the state of the climate device, to be called from integrations.
Definition climate.cpp:432
bool has_custom_fan_mode() const
Check if a custom fan mode is currently active.
Definition climate.h:285
bool set_custom_fan_mode_(const char *mode)
Set custom fan mode. Reset primary fan mode. Return true if fan mode has been changed.
Definition climate.h:339
StringRef get_custom_fan_mode() const
Get the active custom fan mode (read-only access). Returns StringRef.
Definition climate.h:326
void set_visual_max_temperature(float visual_max_temperature)
void add_feature_flags(uint32_t feature_flags)
void set_visual_target_temperature_step(float temperature_step)
void set_supported_swing_modes(ClimateSwingModeMask modes)
void set_visual_min_temperature(float visual_min_temperature)
void set_visual_current_temperature_step(float temperature_step)
void set_supported_modes(ClimateModeMask modes)
void set_supported_fan_modes(ClimateFanModeMask modes)
bool read_available(F &&on_byte)
Same as read_available_chunks(), calling on_byte(uint8_t) once per byte.
Definition uart.h:77
void write_array(const uint8_t *data, size_t len)
Definition uart.h:30
bool state
Definition fan.h:2
ESPHOME_LOG_TAG(TAG, "airton_serial.climate")
@ CLIMATE_SUPPORTS_CURRENT_TEMPERATURE
ClimateSwingMode
Enum for all modes a climate swing can be in NOTE: If adding values, update ClimateSwingModeMask in c...
@ CLIMATE_SWING_OFF
The swing mode is set to Off.
@ CLIMATE_SWING_HORIZONTAL
The fan mode is set to Horizontal.
@ CLIMATE_SWING_VERTICAL
The fan mode is set to Vertical.
@ CLIMATE_SWING_BOTH
The fan mode is set to Both.
ClimateMode
Enum for all modes a climate device can be in.
@ CLIMATE_MODE_DRY
The climate device is set to dry/humidity mode.
@ CLIMATE_MODE_FAN_ONLY
The climate device only has the fan enabled, no heating or cooling is taking place.
@ CLIMATE_MODE_HEAT
The climate device is set to heat to reach the target temperature.
@ CLIMATE_MODE_COOL
The climate device is set to cool to reach the target temperature.
@ CLIMATE_MODE_HEAT_COOL
The climate device is set to heat/cool to reach the target temperature.
@ CLIMATE_MODE_OFF
The climate device is off.
ClimateFanMode
NOTE: If adding values, update ClimateFanModeMask in climate_traits.h to use the new last value.
@ CLIMATE_FAN_MEDIUM
The fan mode is set to Medium.
@ CLIMATE_FAN_AUTO
The fan mode is set to Auto.
@ CLIMATE_FAN_LOW
The fan mode is set to Low.
@ CLIMATE_FAN_QUIET
The fan mode is set to Quiet.
@ CLIMATE_FAN_HIGH
The fan mode is set to High.
uint16_t crc16(const uint8_t *data, uint16_t len, uint16_t crc, uint16_t reverse_poly, bool refin, bool refout)
Calculate a CRC-16 checksum of data with size len.
Definition helpers.cpp:95
void progmem_memcpy(void *dst, const void *src, size_t len)
Definition hal.h:56
uint32_t value
Definition hal.cpp:41
ESPHOME_ALWAYS_INLINE constexpr void assign_bits(T &value, std::type_identity_t< T > mask, bool on)
Set the bits of mask in value when on is true, clear them otherwise.
Definition helpers.h:1150
const void size_t len
Definition hal.h:68
char * format_hex_pretty_to(char *buffer, size_t buffer_size, const uint8_t *data, size_t length, char separator)
Format byte array as uppercase hex to buffer (base implementation).
Definition helpers.cpp:498
constexpr size_t format_hex_pretty_size(size_t byte_count)
Calculate buffer size needed for format_hex_pretty_to with separator: "XX:XX:...:XX\0".
Definition helpers.h:1687
constexpr uint16_t encode_uint16(uint8_t msb, uint8_t lsb)
Encode a 16-bit value given the most and least significant byte.
Definition helpers.h:1043
void get_mac_address_raw(uint8_t *mac)
Get the device MAC address as raw bytes, written into the provided byte array (6 bytes).
Definition helpers.cpp:71
Application App
Global storage of Application pointer - only one Application can exist.
uint8_t progmem_read_byte(const uint8_t *addr)
Definition hal.h:51
static void uint32_t