ESPHome 2025.8.0-dev
Loading...
Searching...
No Matches
api_connection.h
Go to the documentation of this file.
1#pragma once
2
4#ifdef USE_API
5#include "api_frame_helper.h"
6#include "api_pb2.h"
7#include "api_pb2_service.h"
8#include "api_server.h"
12
13#include <vector>
14#include <functional>
15
16namespace esphome::api {
17
18// Client information structure
19struct ClientInfo {
20 std::string name; // Client name from Hello message
21 std::string peername; // IP:port from socket
22
23 std::string get_combined_info() const {
24 if (name == peername) {
25 // Before Hello message, both are the same
26 return name;
27 }
28 return name + " (" + peername + ")";
29 }
30};
31
32// Keepalive timeout in milliseconds
33static constexpr uint32_t KEEPALIVE_TIMEOUT_MS = 60000;
34// Maximum number of entities to process in a single batch during initial state/info sending
35// This was increased from 20 to 24 after removing the unique_id field from entity info messages,
36// which reduced message sizes allowing more entities per batch without exceeding packet limits
37static constexpr size_t MAX_INITIAL_PER_BATCH = 24;
38// Maximum number of packets to process in a single batch (platform-dependent)
39// This limit exists to prevent stack overflow from the PacketInfo array in process_batch_
40// Each PacketInfo is 8 bytes, so 64 * 8 = 512 bytes, 32 * 8 = 256 bytes
41#if defined(USE_ESP32) || defined(USE_HOST)
42static constexpr size_t MAX_PACKETS_PER_BATCH = 64; // ESP32 has 8KB+ stack, HOST has plenty
43#else
44static constexpr size_t MAX_PACKETS_PER_BATCH = 32; // ESP8266/RP2040/etc have smaller stacks
45#endif
46
48 public:
49 friend class APIServer;
51 APIConnection(std::unique_ptr<socket::Socket> socket, APIServer *parent);
52 virtual ~APIConnection();
53
54 void start();
55 void loop();
56
61#ifdef USE_BINARY_SENSOR
63#endif
64#ifdef USE_COVER
65 bool send_cover_state(cover::Cover *cover);
66 void cover_command(const CoverCommandRequest &msg) override;
67#endif
68#ifdef USE_FAN
69 bool send_fan_state(fan::Fan *fan);
70 void fan_command(const FanCommandRequest &msg) override;
71#endif
72#ifdef USE_LIGHT
74 void light_command(const LightCommandRequest &msg) override;
75#endif
76#ifdef USE_SENSOR
78#endif
79#ifdef USE_SWITCH
80 bool send_switch_state(switch_::Switch *a_switch);
81 void switch_command(const SwitchCommandRequest &msg) override;
82#endif
83#ifdef USE_TEXT_SENSOR
85#endif
86#ifdef USE_CAMERA
87 void set_camera_state(std::shared_ptr<camera::CameraImage> image);
88 void camera_image(const CameraImageRequest &msg) override;
89#endif
90#ifdef USE_CLIMATE
92 void climate_command(const ClimateCommandRequest &msg) override;
93#endif
94#ifdef USE_NUMBER
96 void number_command(const NumberCommandRequest &msg) override;
97#endif
98#ifdef USE_DATETIME_DATE
100 void date_command(const DateCommandRequest &msg) override;
101#endif
102#ifdef USE_DATETIME_TIME
104 void time_command(const TimeCommandRequest &msg) override;
105#endif
106#ifdef USE_DATETIME_DATETIME
108 void datetime_command(const DateTimeCommandRequest &msg) override;
109#endif
110#ifdef USE_TEXT
111 bool send_text_state(text::Text *text);
112 void text_command(const TextCommandRequest &msg) override;
113#endif
114#ifdef USE_SELECT
115 bool send_select_state(select::Select *select);
116 void select_command(const SelectCommandRequest &msg) override;
117#endif
118#ifdef USE_BUTTON
119 void button_command(const ButtonCommandRequest &msg) override;
120#endif
121#ifdef USE_LOCK
122 bool send_lock_state(lock::Lock *a_lock);
123 void lock_command(const LockCommandRequest &msg) override;
124#endif
125#ifdef USE_VALVE
126 bool send_valve_state(valve::Valve *valve);
127 void valve_command(const ValveCommandRequest &msg) override;
128#endif
129#ifdef USE_MEDIA_PLAYER
131 void media_player_command(const MediaPlayerCommandRequest &msg) override;
132#endif
133 bool try_send_log_message(int level, const char *tag, const char *line, size_t message_len);
134#ifdef USE_API_HOMEASSISTANT_SERVICES
140#endif
141#ifdef USE_BLUETOOTH_PROXY
144
145 void bluetooth_device_request(const BluetoothDeviceRequest &msg) override;
146 void bluetooth_gatt_read(const BluetoothGATTReadRequest &msg) override;
147 void bluetooth_gatt_write(const BluetoothGATTWriteRequest &msg) override;
151 void bluetooth_gatt_notify(const BluetoothGATTNotifyRequest &msg) override;
154
155#endif
156#ifdef USE_HOMEASSISTANT_TIME
161#endif
162
163#ifdef USE_VOICE_ASSISTANT
165 void on_voice_assistant_response(const VoiceAssistantResponse &msg) override;
167 void on_voice_assistant_audio(const VoiceAssistantAudio &msg) override;
172#endif
173
174#ifdef USE_ALARM_CONTROL_PANEL
177#endif
178
179#ifdef USE_EVENT
180 void send_event(event::Event *event, const std::string &event_type);
181#endif
182
183#ifdef USE_UPDATE
185 void update_command(const UpdateCommandRequest &msg) override;
186#endif
187
188 void on_disconnect_response(const DisconnectResponse &value) override;
189 void on_ping_response(const PingResponse &value) override {
190 // we initiated ping
191 this->flags_.sent_ping = false;
192 }
193#ifdef USE_API_HOMEASSISTANT_STATES
195#endif
196#ifdef USE_HOMEASSISTANT_TIME
197 void on_get_time_response(const GetTimeResponse &value) override;
198#endif
199 bool send_hello_response(const HelloRequest &msg) override;
200 bool send_connect_response(const ConnectRequest &msg) override;
201 bool send_disconnect_response(const DisconnectRequest &msg) override;
202 bool send_ping_response(const PingRequest &msg) override;
203 bool send_device_info_response(const DeviceInfoRequest &msg) override;
204 void list_entities(const ListEntitiesRequest &msg) override { this->list_entities_iterator_.begin(); }
205 void subscribe_states(const SubscribeStatesRequest &msg) override {
206 this->flags_.state_subscription = true;
208 }
209 void subscribe_logs(const SubscribeLogsRequest &msg) override {
210 this->flags_.log_subscription = msg.level;
211 if (msg.dump_config)
213 }
214#ifdef USE_API_HOMEASSISTANT_SERVICES
218#endif
219#ifdef USE_API_HOMEASSISTANT_STATES
221#endif
222 bool send_get_time_response(const GetTimeRequest &msg) override;
223#ifdef USE_API_SERVICES
224 void execute_service(const ExecuteServiceRequest &msg) override;
225#endif
226#ifdef USE_API_NOISE
228#endif
229
230 bool is_authenticated() override {
232 }
233 bool is_connection_setup() override {
235 this->is_authenticated();
236 }
237 uint8_t get_log_subscription_level() const { return this->flags_.log_subscription; }
238
239 // Get client API version for feature detection
240 bool client_supports_api_version(uint16_t major, uint16_t minor) const {
241 return this->client_api_version_major_ > major ||
242 (this->client_api_version_major_ == major && this->client_api_version_minor_ >= minor);
243 }
244
245 void on_fatal_error() override;
246#ifdef USE_API_PASSWORD
247 void on_unauthenticated_access() override;
248#endif
249 void on_no_setup_connection() override;
250 ProtoWriteBuffer create_buffer(uint32_t reserve_size) override {
251 // FIXME: ensure no recursive writes can happen
252
253 // Get header padding size - used for both reserve and insert
254 uint8_t header_padding = this->helper_->frame_header_padding();
255
256 // Get shared buffer from parent server
257 std::vector<uint8_t> &shared_buf = this->parent_->get_shared_buffer_ref();
258 shared_buf.clear();
259 // Reserve space for header padding + message + footer
260 // - Header padding: space for protocol headers (7 bytes for Noise, 6 for Plaintext)
261 // - Footer: space for MAC (16 bytes for Noise, 0 for Plaintext)
262 shared_buf.reserve(reserve_size + header_padding + this->helper_->frame_footer_size());
263 // Resize to add header padding so message encoding starts at the correct position
264 shared_buf.resize(header_padding);
265 return {&shared_buf};
266 }
267
268 // Prepare buffer for next message in batch
269 ProtoWriteBuffer prepare_message_buffer(uint16_t message_size, bool is_first_message) {
270 // Get reference to shared buffer (it maintains state between batch messages)
271 std::vector<uint8_t> &shared_buf = this->parent_->get_shared_buffer_ref();
272
273 if (is_first_message) {
274 shared_buf.clear();
275 }
276
277 size_t current_size = shared_buf.size();
278
279 // Calculate padding to add:
280 // - First message: just header padding
281 // - Subsequent messages: footer for previous message + header padding for this message
282 size_t padding_to_add = is_first_message
283 ? this->helper_->frame_header_padding()
284 : this->helper_->frame_header_padding() + this->helper_->frame_footer_size();
285
286 // Reserve space for padding + message
287 shared_buf.reserve(current_size + padding_to_add + message_size);
288
289 // Resize to add the padding bytes
290 shared_buf.resize(current_size + padding_to_add);
291
292 return {&shared_buf};
293 }
294
295 bool try_to_clear_buffer(bool log_out_of_space);
296 bool send_buffer(ProtoWriteBuffer buffer, uint8_t message_type) override;
297
298 std::string get_client_combined_info() const { return this->client_info_.get_combined_info(); }
299
300 // Buffer allocator methods for batch processing
303
304 protected:
305 // Helper function to handle authentication completion
307
308#ifdef USE_API_HOMEASSISTANT_STATES
310#endif
311
312 // Non-template helper to encode any ProtoMessage
313 static uint16_t encode_message_to_buffer(ProtoMessage &msg, uint8_t message_type, APIConnection *conn,
314 uint32_t remaining_size, bool is_single);
315
316 // Helper to fill entity state base and encode message
317 static uint16_t fill_and_encode_entity_state(EntityBase *entity, StateResponseProtoMessage &msg, uint8_t message_type,
318 APIConnection *conn, uint32_t remaining_size, bool is_single) {
319 msg.key = entity->get_object_id_hash();
320#ifdef USE_DEVICES
321 msg.device_id = entity->get_device_id();
322#endif
323 return encode_message_to_buffer(msg, message_type, conn, remaining_size, is_single);
324 }
325
326 // Helper to fill entity info base and encode message
327 static uint16_t fill_and_encode_entity_info(EntityBase *entity, InfoResponseProtoMessage &msg, uint8_t message_type,
328 APIConnection *conn, uint32_t remaining_size, bool is_single) {
329 // Set common fields that are shared by all entity types
330 msg.key = entity->get_object_id_hash();
331 // IMPORTANT: get_object_id() may return a temporary std::string
332 std::string object_id = entity->get_object_id();
333 msg.set_object_id(StringRef(object_id));
334
335 if (entity->has_own_name()) {
336 msg.set_name(entity->get_name());
337 }
338
339 // Set common EntityBase properties
340#ifdef USE_ENTITY_ICON
341 msg.set_icon(entity->get_icon_ref());
342#endif
344 msg.entity_category = static_cast<enums::EntityCategory>(entity->get_entity_category());
345#ifdef USE_DEVICES
346 msg.device_id = entity->get_device_id();
347#endif
348 return encode_message_to_buffer(msg, message_type, conn, remaining_size, is_single);
349 }
350
351#ifdef USE_VOICE_ASSISTANT
352 // Helper to check voice assistant validity and connection ownership
353 inline bool check_voice_assistant_api_connection_() const;
354#endif
355
356 // Helper method to process multiple entities from an iterator in a batch
357 template<typename Iterator> void process_iterator_batch_(Iterator &iterator) {
358 size_t initial_size = this->deferred_batch_.size();
359 while (!iterator.completed() && (this->deferred_batch_.size() - initial_size) < MAX_INITIAL_PER_BATCH) {
360 iterator.advance();
361 }
362
363 // If the batch is full, process it immediately
364 // Note: iterator.advance() already calls schedule_batch_() via schedule_message_()
365 if (this->deferred_batch_.size() >= MAX_INITIAL_PER_BATCH) {
366 this->process_batch_();
367 }
368 }
369
370#ifdef USE_BINARY_SENSOR
371 static uint16_t try_send_binary_sensor_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
372 bool is_single);
373 static uint16_t try_send_binary_sensor_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
374 bool is_single);
375#endif
376#ifdef USE_COVER
377 static uint16_t try_send_cover_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
378 bool is_single);
379 static uint16_t try_send_cover_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single);
380#endif
381#ifdef USE_FAN
382 static uint16_t try_send_fan_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single);
383 static uint16_t try_send_fan_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single);
384#endif
385#ifdef USE_LIGHT
386 static uint16_t try_send_light_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
387 bool is_single);
388 static uint16_t try_send_light_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single);
389#endif
390#ifdef USE_SENSOR
391 static uint16_t try_send_sensor_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
392 bool is_single);
393 static uint16_t try_send_sensor_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
394 bool is_single);
395#endif
396#ifdef USE_SWITCH
397 static uint16_t try_send_switch_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
398 bool is_single);
399 static uint16_t try_send_switch_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
400 bool is_single);
401#endif
402#ifdef USE_TEXT_SENSOR
403 static uint16_t try_send_text_sensor_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
404 bool is_single);
405 static uint16_t try_send_text_sensor_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
406 bool is_single);
407#endif
408#ifdef USE_CLIMATE
409 static uint16_t try_send_climate_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
410 bool is_single);
411 static uint16_t try_send_climate_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
412 bool is_single);
413#endif
414#ifdef USE_NUMBER
415 static uint16_t try_send_number_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
416 bool is_single);
417 static uint16_t try_send_number_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
418 bool is_single);
419#endif
420#ifdef USE_DATETIME_DATE
421 static uint16_t try_send_date_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single);
422 static uint16_t try_send_date_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single);
423#endif
424#ifdef USE_DATETIME_TIME
425 static uint16_t try_send_time_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single);
426 static uint16_t try_send_time_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single);
427#endif
428#ifdef USE_DATETIME_DATETIME
429 static uint16_t try_send_datetime_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
430 bool is_single);
431 static uint16_t try_send_datetime_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
432 bool is_single);
433#endif
434#ifdef USE_TEXT
435 static uint16_t try_send_text_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single);
436 static uint16_t try_send_text_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single);
437#endif
438#ifdef USE_SELECT
439 static uint16_t try_send_select_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
440 bool is_single);
441 static uint16_t try_send_select_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
442 bool is_single);
443#endif
444#ifdef USE_BUTTON
445 static uint16_t try_send_button_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
446 bool is_single);
447#endif
448#ifdef USE_LOCK
449 static uint16_t try_send_lock_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single);
450 static uint16_t try_send_lock_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single);
451#endif
452#ifdef USE_VALVE
453 static uint16_t try_send_valve_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
454 bool is_single);
455 static uint16_t try_send_valve_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single);
456#endif
457#ifdef USE_MEDIA_PLAYER
458 static uint16_t try_send_media_player_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
459 bool is_single);
460 static uint16_t try_send_media_player_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
461 bool is_single);
462#endif
463#ifdef USE_ALARM_CONTROL_PANEL
464 static uint16_t try_send_alarm_control_panel_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
465 bool is_single);
466 static uint16_t try_send_alarm_control_panel_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
467 bool is_single);
468#endif
469#ifdef USE_EVENT
470 static uint16_t try_send_event_response(event::Event *event, const std::string &event_type, APIConnection *conn,
471 uint32_t remaining_size, bool is_single);
472 static uint16_t try_send_event_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single);
473#endif
474#ifdef USE_UPDATE
475 static uint16_t try_send_update_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
476 bool is_single);
477 static uint16_t try_send_update_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
478 bool is_single);
479#endif
480#ifdef USE_CAMERA
481 static uint16_t try_send_camera_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
482 bool is_single);
483#endif
484
485 // Method for ListEntitiesDone batching
486 static uint16_t try_send_list_info_done(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
487 bool is_single);
488
489 // Method for DisconnectRequest batching
490 static uint16_t try_send_disconnect_request(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
491 bool is_single);
492
493 // Batch message method for ping requests
494 static uint16_t try_send_ping_request(EntityBase *entity, APIConnection *conn, uint32_t remaining_size,
495 bool is_single);
496
497 // === Optimal member ordering for 32-bit systems ===
498
499 // Group 1: Pointers (4 bytes each on 32-bit)
500 std::unique_ptr<APIFrameHelper> helper_;
502
503 // Group 2: Larger objects (must be 4-byte aligned)
504 // These contain vectors/pointers internally, so putting them early ensures good alignment
507#ifdef USE_CAMERA
508 std::unique_ptr<camera::CameraImageReader> image_reader_;
509#endif
510
511 // Group 3: Client info struct (24 bytes on 32-bit: 2 strings × 12 bytes each)
513
514 // Group 4: 4-byte types
516#ifdef USE_API_HOMEASSISTANT_STATES
518#endif
519
520 // Function pointer type for message encoding
521 using MessageCreatorPtr = uint16_t (*)(EntityBase *, APIConnection *, uint32_t remaining_size, bool is_single);
522
524 public:
525 // Constructor for function pointer
526 MessageCreator(MessageCreatorPtr ptr) { data_.function_ptr = ptr; }
527
528 // Constructor for string state capture
529 explicit MessageCreator(const std::string &str_value) { data_.string_ptr = new std::string(str_value); }
530
531 // No destructor - cleanup must be called explicitly with message_type
532
533 // Delete copy operations - MessageCreator should only be moved
534 MessageCreator(const MessageCreator &other) = delete;
535 MessageCreator &operator=(const MessageCreator &other) = delete;
536
537 // Move constructor
538 MessageCreator(MessageCreator &&other) noexcept : data_(other.data_) { other.data_.function_ptr = nullptr; }
539
540 // Move assignment
542 if (this != &other) {
543 // IMPORTANT: Caller must ensure cleanup() was called if this contains a string!
544 // In our usage, this happens in add_item() deduplication and vector::erase()
545 data_ = other.data_;
546 other.data_.function_ptr = nullptr;
547 }
548 return *this;
549 }
550
551 // Call operator - uses message_type to determine union type
552 uint16_t operator()(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single,
553 uint8_t message_type) const;
554
555 // Manual cleanup method - must be called before destruction for string types
556 void cleanup(uint8_t message_type) {
557#ifdef USE_EVENT
558 if (message_type == EventResponse::MESSAGE_TYPE && data_.string_ptr != nullptr) {
559 delete data_.string_ptr;
560 data_.string_ptr = nullptr;
561 }
562#endif
563 }
564
565 private:
566 union Data {
567 MessageCreatorPtr function_ptr;
568 std::string *string_ptr;
569 } data_; // 4 bytes on 32-bit, 8 bytes on 64-bit - same as before
570 };
571
572 // Generic batching mechanism for both state updates and entity info
574 struct BatchItem {
575 EntityBase *entity; // Entity pointer
576 MessageCreator creator; // Function that creates the message when needed
577 uint8_t message_type; // Message type for overhead calculation (max 255)
578 uint8_t estimated_size; // Estimated message size (max 255 bytes)
579
580 // Constructor for creating BatchItem
583 };
584
585 std::vector<BatchItem> items;
586 uint32_t batch_start_time{0};
587
588 private:
589 // Helper to cleanup items from the beginning
590 void cleanup_items_(size_t count) {
591 for (size_t i = 0; i < count; i++) {
592 items[i].creator.cleanup(items[i].message_type);
593 }
594 }
595
596 public:
598 // Pre-allocate capacity for typical batch sizes to avoid reallocation
599 items.reserve(8);
600 }
601
603 // Ensure cleanup of any remaining items
604 clear();
605 }
606
607 // Add item to the batch
608 void add_item(EntityBase *entity, MessageCreator creator, uint8_t message_type, uint8_t estimated_size);
609 // Add item to the front of the batch (for high priority messages like ping)
610 void add_item_front(EntityBase *entity, MessageCreator creator, uint8_t message_type, uint8_t estimated_size);
611
612 // Clear all items with proper cleanup
613 void clear() {
614 cleanup_items_(items.size());
615 items.clear();
617 }
618
619 // Remove processed items from the front with proper cleanup
620 void remove_front(size_t count) {
621 cleanup_items_(count);
622 items.erase(items.begin(), items.begin() + count);
623 }
624
625 bool empty() const { return items.empty(); }
626 size_t size() const { return items.size(); }
627 const BatchItem &operator[](size_t index) const { return items[index]; }
628 };
629
630 // DeferredBatch here (16 bytes, 4-byte aligned)
632
633 // ConnectionState enum for type safety
634 enum class ConnectionState : uint8_t {
636 CONNECTED = 1,
637 AUTHENTICATED = 2,
638 };
639
640 // Group 5: Pack all small members together to minimize padding
641 // This group starts at a 4-byte boundary after DeferredBatch
642 struct APIFlags {
643 // Connection state only needs 2 bits (3 states)
644 uint8_t connection_state : 2;
645 // Log subscription needs 3 bits (log levels 0-7)
646 uint8_t log_subscription : 3;
647 // Boolean flags (1 bit each)
648 uint8_t remove : 1;
650 uint8_t sent_ping : 1;
651
653 uint8_t next_close : 1;
654 uint8_t batch_scheduled : 1;
655 uint8_t batch_first_message : 1; // For batch buffer allocation
656 uint8_t should_try_send_immediately : 1; // True after initial states are sent
657#ifdef HAS_PROTO_MESSAGE_DUMP
658 uint8_t log_only_mode : 1;
659#endif
660 } flags_{}; // 2 bytes total
661
662 // 2-byte types immediately after flags_ (no padding between them)
665 // Total: 2 (flags) + 2 + 2 = 6 bytes, then 2 bytes padding to next 4-byte boundary
666
667 uint32_t get_batch_delay_ms_() const;
668 // Message will use 8 more bytes than the minimum size, and typical
669 // MTU is 1500. Sometimes users will see as low as 1460 MTU.
670 // If its IPv6 the header is 40 bytes, and if its IPv4
671 // the header is 20 bytes. So we have 1460 - 40 = 1420 bytes
672 // available for the payload. But we also need to add the size of
673 // the protobuf overhead, which is 8 bytes.
674 //
675 // To be safe we pick 1390 bytes as the maximum size
676 // to send in one go. This is the maximum size of a single packet
677 // that can be sent over the network.
678 // This is to avoid fragmentation of the packet.
679 static constexpr size_t MAX_BATCH_PACKET_SIZE = 1390; // MTU
680
681 bool schedule_batch_();
682 void process_batch_();
684 this->deferred_batch_.clear();
685 this->flags_.batch_scheduled = false;
686 }
687
688#ifdef HAS_PROTO_MESSAGE_DUMP
689 // Helper to log a proto message from a MessageCreator object
690 void log_proto_message_(EntityBase *entity, const MessageCreator &creator, uint8_t message_type) {
691 this->flags_.log_only_mode = true;
692 creator(entity, this, MAX_BATCH_PACKET_SIZE, true, message_type);
693 this->flags_.log_only_mode = false;
694 }
695
697 // Use the helper to log the message
698 this->log_proto_message_(item.entity, item.creator, item.message_type);
699 }
700#endif
701
702 // Helper method to send a message either immediately or via batching
703 bool send_message_smart_(EntityBase *entity, MessageCreatorPtr creator, uint8_t message_type,
704 uint8_t estimated_size) {
705 // Try to send immediately if:
706 // 1. It's an UpdateStateResponse (always send immediately to handle cases where
707 // the main loop is blocked, e.g., during OTA updates)
708 // 2. OR: We should try to send immediately (should_try_send_immediately = true)
709 // AND Batch delay is 0 (user has opted in to immediate sending)
710 // 3. AND: Buffer has space available
711 if ((
712#ifdef USE_UPDATE
713 message_type == UpdateStateResponse::MESSAGE_TYPE ||
714#endif
715 (this->flags_.should_try_send_immediately && this->get_batch_delay_ms_() == 0)) &&
716 this->helper_->can_write_without_blocking()) {
717 // Now actually encode and send
718 if (creator(entity, this, MAX_BATCH_PACKET_SIZE, true) &&
719 this->send_buffer(ProtoWriteBuffer{&this->parent_->get_shared_buffer_ref()}, message_type)) {
720#ifdef HAS_PROTO_MESSAGE_DUMP
721 // Log the message in verbose mode
722 this->log_proto_message_(entity, MessageCreator(creator), message_type);
723#endif
724 return true;
725 }
726
727 // If immediate send failed, fall through to batching
728 }
729
730 // Fall back to scheduled batching
731 return this->schedule_message_(entity, creator, message_type, estimated_size);
732 }
733
734 // Helper function to schedule a deferred message with known message type
735 bool schedule_message_(EntityBase *entity, MessageCreator creator, uint8_t message_type, uint8_t estimated_size) {
736 this->deferred_batch_.add_item(entity, std::move(creator), message_type, estimated_size);
737 return this->schedule_batch_();
738 }
739
740 // Overload for function pointers (for info messages and current state reads)
741 bool schedule_message_(EntityBase *entity, MessageCreatorPtr function_ptr, uint8_t message_type,
742 uint8_t estimated_size) {
743 return schedule_message_(entity, MessageCreator(function_ptr), message_type, estimated_size);
744 }
745
746 // Helper function to schedule a high priority message at the front of the batch
747 bool schedule_message_front_(EntityBase *entity, MessageCreatorPtr function_ptr, uint8_t message_type,
748 uint8_t estimated_size) {
749 this->deferred_batch_.add_item_front(entity, MessageCreator(function_ptr), message_type, estimated_size);
750 return this->schedule_batch_();
751 }
752
753 // Helper function to log API errors with errno
754 void log_warning_(const char *message, APIError err);
755 // Specific helper for duplicated error message
757};
758
759} // namespace esphome::api
760#endif
void begin(bool include_internal=false)
bool has_own_name() const
Definition entity_base.h:29
uint32_t get_object_id_hash()
const StringRef & get_name() const
StringRef get_icon_ref() const
Definition entity_base.h:57
uint32_t get_device_id() const
Definition entity_base.h:68
bool is_disabled_by_default() const
Definition entity_base.h:45
std::string get_object_id() const
EntityCategory get_entity_category() const
Definition entity_base.h:49
StringRef is a reference to a string owned by something else.
Definition string_ref.h:22
MessageCreator(MessageCreator &&other) noexcept
uint16_t operator()(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single, uint8_t message_type) const
MessageCreator(const MessageCreator &other)=delete
MessageCreator(const std::string &str_value)
MessageCreator & operator=(const MessageCreator &other)=delete
MessageCreator & operator=(MessageCreator &&other) noexcept
static uint16_t try_send_binary_sensor_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
static uint16_t try_send_climate_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
struct esphome::api::APIConnection::APIFlags flags_
bool send_ping_response(const PingRequest &msg) override
bool send_message_smart_(EntityBase *entity, MessageCreatorPtr creator, uint8_t message_type, uint8_t estimated_size)
void subscribe_voice_assistant(const SubscribeVoiceAssistantRequest &msg) override
static uint16_t try_send_switch_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
void select_command(const SelectCommandRequest &msg) override
static uint16_t encode_message_to_buffer(ProtoMessage &msg, uint8_t message_type, APIConnection *conn, uint32_t remaining_size, bool is_single)
void bluetooth_gatt_write(const BluetoothGATTWriteRequest &msg) override
bool send_get_time_response(const GetTimeRequest &msg) override
static uint16_t try_send_text_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
static uint16_t try_send_fan_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
bool send_media_player_state(media_player::MediaPlayer *media_player)
static uint16_t try_send_datetime_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
bool send_time_state(datetime::TimeEntity *time)
static uint16_t try_send_date_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
void time_command(const TimeCommandRequest &msg) override
static uint16_t try_send_sensor_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
void update_command(const UpdateCommandRequest &msg) override
void on_ping_response(const PingResponse &value) override
static uint16_t try_send_lock_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
bool send_connect_response(const ConnectRequest &msg) override
void on_voice_assistant_announce_request(const VoiceAssistantAnnounceRequest &msg) override
bool send_subscribe_bluetooth_connections_free_response(const SubscribeBluetoothConnectionsFreeRequest &msg) override
ProtoWriteBuffer create_buffer(uint32_t reserve_size) override
static uint16_t try_send_lock_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
static uint16_t try_send_time_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
bool send_text_sensor_state(text_sensor::TextSensor *text_sensor)
bool send_fan_state(fan::Fan *fan)
static uint16_t try_send_switch_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
void bluetooth_scanner_set_mode(const BluetoothScannerSetModeRequest &msg) override
static uint16_t try_send_media_player_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
void on_voice_assistant_response(const VoiceAssistantResponse &msg) override
bool check_voice_assistant_api_connection_() const
void log_proto_message_(EntityBase *entity, const MessageCreator &creator, uint8_t message_type)
static uint16_t try_send_number_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
void log_socket_operation_failed_(APIError err)
InitialStateIterator initial_state_iterator_
void subscribe_logs(const SubscribeLogsRequest &msg) override
std::unique_ptr< APIFrameHelper > helper_
void date_command(const DateCommandRequest &msg) override
bool schedule_message_(EntityBase *entity, MessageCreatorPtr function_ptr, uint8_t message_type, uint8_t estimated_size)
void set_camera_state(std::shared_ptr< camera::CameraImage > image)
static uint16_t try_send_binary_sensor_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
uint32_t get_batch_delay_ms_() const
void send_event(event::Event *event, const std::string &event_type)
bool send_sensor_state(sensor::Sensor *sensor)
std::string get_client_combined_info() const
static constexpr size_t MAX_BATCH_PACKET_SIZE
void log_batch_item_(const DeferredBatch::BatchItem &item)
void datetime_command(const DateTimeCommandRequest &msg) override
uint16_t(*)(EntityBase *, APIConnection *, uint32_t remaining_size, bool is_single) MessageCreatorPtr
void voice_assistant_set_configuration(const VoiceAssistantSetConfiguration &msg) override
bool send_binary_sensor_state(binary_sensor::BinarySensor *binary_sensor)
void process_iterator_batch_(Iterator &iterator)
static uint16_t try_send_climate_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
bool send_valve_state(valve::Valve *valve)
static uint16_t try_send_light_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
bool send_select_state(select::Select *select)
bool send_switch_state(switch_::Switch *a_switch)
void bluetooth_gatt_write_descriptor(const BluetoothGATTWriteDescriptorRequest &msg) override
void bluetooth_gatt_read(const BluetoothGATTReadRequest &msg) override
static uint16_t try_send_ping_request(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
void text_command(const TextCommandRequest &msg) override
bool send_lock_state(lock::Lock *a_lock)
bool send_hello_response(const HelloRequest &msg) override
static uint16_t try_send_button_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
static uint16_t try_send_time_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
static uint16_t try_send_text_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
static uint16_t try_send_datetime_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
static uint16_t try_send_list_info_done(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
ProtoWriteBuffer allocate_batch_message_buffer(uint16_t size)
static uint16_t try_send_camera_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
static uint16_t try_send_valve_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
static uint16_t try_send_media_player_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
static uint16_t try_send_update_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
void log_warning_(const char *message, APIError err)
bool send_update_state(update::UpdateEntity *update)
void on_voice_assistant_audio(const VoiceAssistantAudio &msg) override
static uint16_t fill_and_encode_entity_state(EntityBase *entity, StateResponseProtoMessage &msg, uint8_t message_type, APIConnection *conn, uint32_t remaining_size, bool is_single)
bool schedule_message_(EntityBase *entity, MessageCreator creator, uint8_t message_type, uint8_t estimated_size)
static uint16_t try_send_light_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
static uint16_t try_send_event_response(event::Event *event, const std::string &event_type, APIConnection *conn, uint32_t remaining_size, bool is_single)
void alarm_control_panel_command(const AlarmControlPanelCommandRequest &msg) override
static uint16_t fill_and_encode_entity_info(EntityBase *entity, InfoResponseProtoMessage &msg, uint8_t message_type, APIConnection *conn, uint32_t remaining_size, bool is_single)
static uint16_t try_send_fan_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
bool send_device_info_response(const DeviceInfoRequest &msg) override
bool schedule_message_front_(EntityBase *entity, MessageCreatorPtr function_ptr, uint8_t message_type, uint8_t estimated_size)
void unsubscribe_bluetooth_le_advertisements(const UnsubscribeBluetoothLEAdvertisementsRequest &msg) override
void number_command(const NumberCommandRequest &msg) override
void list_entities(const ListEntitiesRequest &msg) override
std::unique_ptr< camera::CameraImageReader > image_reader_
void media_player_command(const MediaPlayerCommandRequest &msg) override
void bluetooth_gatt_notify(const BluetoothGATTNotifyRequest &msg) override
void subscribe_homeassistant_services(const SubscribeHomeassistantServicesRequest &msg) override
APIConnection(std::unique_ptr< socket::Socket > socket, APIServer *parent)
void subscribe_states(const SubscribeStatesRequest &msg) override
ProtoWriteBuffer allocate_single_message_buffer(uint16_t size)
void subscribe_bluetooth_le_advertisements(const SubscribeBluetoothLEAdvertisementsRequest &msg) override
bool send_date_state(datetime::DateEntity *date)
static uint16_t try_send_sensor_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
static uint16_t try_send_update_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
void bluetooth_gatt_read_descriptor(const BluetoothGATTReadDescriptorRequest &msg) override
void climate_command(const ClimateCommandRequest &msg) override
static uint16_t try_send_valve_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
void bluetooth_gatt_get_services(const BluetoothGATTGetServicesRequest &msg) override
bool is_connection_setup() override
bool send_number_state(number::Number *number)
void on_voice_assistant_timer_event_response(const VoiceAssistantTimerEventResponse &msg) override
void fan_command(const FanCommandRequest &msg) override
void on_voice_assistant_event_response(const VoiceAssistantEventResponse &msg) override
static uint16_t try_send_select_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
bool send_noise_encryption_set_key_response(const NoiseEncryptionSetKeyRequest &msg) override
bool send_light_state(light::LightState *light)
bool send_voice_assistant_get_configuration_response(const VoiceAssistantConfigurationRequest &msg) override
void valve_command(const ValveCommandRequest &msg) override
void on_home_assistant_state_response(const HomeAssistantStateResponse &msg) override
void cover_command(const CoverCommandRequest &msg) override
uint8_t get_log_subscription_level() const
void on_get_time_response(const GetTimeResponse &value) override
static uint16_t try_send_select_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
void subscribe_home_assistant_states(const SubscribeHomeAssistantStatesRequest &msg) override
void send_homeassistant_service_call(const HomeassistantServiceResponse &call)
void on_disconnect_response(const DisconnectResponse &value) override
bool send_datetime_state(datetime::DateTimeEntity *datetime)
ListEntitiesIterator list_entities_iterator_
static uint16_t try_send_alarm_control_panel_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
static uint16_t try_send_text_sensor_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
bool send_disconnect_response(const DisconnectRequest &msg) override
bool send_alarm_control_panel_state(alarm_control_panel::AlarmControlPanel *a_alarm_control_panel)
static uint16_t try_send_text_sensor_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
void camera_image(const CameraImageRequest &msg) override
void light_command(const LightCommandRequest &msg) override
bool send_text_state(text::Text *text)
void switch_command(const SwitchCommandRequest &msg) override
static uint16_t try_send_cover_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
static uint16_t try_send_date_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
bool try_send_log_message(int level, const char *tag, const char *line, size_t message_len)
static uint16_t try_send_disconnect_request(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
static uint16_t try_send_number_state(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
bool client_supports_api_version(uint16_t major, uint16_t minor) const
void lock_command(const LockCommandRequest &msg) override
void bluetooth_device_request(const BluetoothDeviceRequest &msg) override
bool send_buffer(ProtoWriteBuffer buffer, uint8_t message_type) override
void execute_service(const ExecuteServiceRequest &msg) override
bool send_climate_state(climate::Climate *climate)
bool try_to_clear_buffer(bool log_out_of_space)
bool send_cover_state(cover::Cover *cover)
void button_command(const ButtonCommandRequest &msg) override
static uint16_t try_send_alarm_control_panel_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
static uint16_t try_send_cover_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
static uint16_t try_send_event_info(EntityBase *entity, APIConnection *conn, uint32_t remaining_size, bool is_single)
ProtoWriteBuffer prepare_message_buffer(uint16_t message_size, bool is_first_message)
void on_unauthenticated_access() override
bool send_message(const ProtoMessage &msg, uint8_t message_type)
std::vector< uint8_t > & get_shared_buffer_ref()
Definition api_server.h:49
static constexpr uint8_t MESSAGE_TYPE
Definition api_pb2.h:2726
static constexpr uint8_t MESSAGE_TYPE
Definition api_pb2.h:1163
static constexpr uint8_t MESSAGE_TYPE
Definition api_pb2.h:1089
void set_object_id(const StringRef &ref)
Definition api_pb2.h:286
enums::EntityCategory entity_category
Definition api_pb2.h:295
void set_icon(const StringRef &ref)
Definition api_pb2.h:293
void set_name(const StringRef &ref)
Definition api_pb2.h:289
static constexpr uint8_t MESSAGE_TYPE
Definition api_pb2.h:577
static constexpr uint8_t ESTIMATED_SIZE
Definition api_pb2.h:578
static constexpr uint8_t MESSAGE_TYPE
Definition api_pb2.h:2869
Base class for all binary_sensor-type classes.
ClimateDevice - This is the base class for all climate integrations.
Definition climate.h:168
Base class for all cover devices.
Definition cover.h:111
This class represents the communication layer between the front-end MQTT layer and the hardware outpu...
Definition light_state.h:66
Base class for all locks.
Definition lock.h:103
Base-class for all numbers.
Definition number.h:39
Base-class for all selects.
Definition select.h:31
Base-class for all sensors.
Definition sensor.h:59
Base class for all switches.
Definition switch.h:39
Base-class for all text inputs.
Definition text.h:24
Base class for all valve devices.
Definition valve.h:105
Application App
Global storage of Application pointer - only one Application can exist.
BatchItem(EntityBase *entity, MessageCreator creator, uint8_t message_type, uint8_t estimated_size)
const BatchItem & operator[](size_t index) const
void add_item(EntityBase *entity, MessageCreator creator, uint8_t message_type, uint8_t estimated_size)
void add_item_front(EntityBase *entity, MessageCreator creator, uint8_t message_type, uint8_t estimated_size)
std::string get_combined_info() const