ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
mqtt_backend_esp32.cpp
Go to the documentation of this file.
2
3#ifdef USE_MQTT
4#ifdef USE_ESP32
5
6#include <algorithm>
7#include <string>
9#include "esphome/core/log.h"
11
12#ifdef USE_MQTT_CERT_BUNDLE
13#include "esp_crt_bundle.h"
14#endif
15
16namespace esphome::mqtt {
17
18ESPHOME_LOG_TAG(TAG, "mqtt");
19
21 mqtt_cfg_.broker.address.hostname = this->host_.c_str();
22 mqtt_cfg_.broker.address.port = this->port_;
23 mqtt_cfg_.session.keepalive = this->keep_alive_;
24 mqtt_cfg_.session.disable_clean_session = !this->clean_session_;
25
26 if (!this->username_.empty()) {
27 mqtt_cfg_.credentials.username = this->username_.c_str();
28 if (!this->password_.empty()) {
29 mqtt_cfg_.credentials.authentication.password = this->password_.c_str();
30 }
31 }
32
33 if (!this->lwt_topic_.empty()) {
34 mqtt_cfg_.session.last_will.topic = this->lwt_topic_.c_str();
35 this->mqtt_cfg_.session.last_will.qos = this->lwt_qos_;
36 this->mqtt_cfg_.session.last_will.retain = this->lwt_retain_;
37
38 if (!this->lwt_message_.empty()) {
39 mqtt_cfg_.session.last_will.msg = this->lwt_message_.c_str();
40 mqtt_cfg_.session.last_will.msg_len = this->lwt_message_.size();
41 }
42 }
43
44 if (!this->client_id_.empty()) {
45 mqtt_cfg_.credentials.client_id = this->client_id_.c_str();
46 }
47#ifdef USE_MQTT_TLS
48 mqtt_cfg_.broker.verification.skip_cert_common_name_check = this->skip_cert_cn_check_;
49 mqtt_cfg_.broker.verification.certificate = this->ca_certificate_;
50#ifdef USE_MQTT_CERT_BUNDLE
51 mqtt_cfg_.broker.verification.crt_bundle_attach = esp_crt_bundle_attach;
52#endif
53 // Validation only accepts the client certificate together with its key
54 mqtt_cfg_.credentials.authentication.certificate = this->cl_certificate_;
55 mqtt_cfg_.credentials.authentication.key = this->cl_key_;
56#endif
57 // Validation keeps TLS off plain ws, so only the TCP transport has two forms
58 switch (this->transport_) {
60 mqtt_cfg_.broker.address.transport = MQTT_TRANSPORT_OVER_WS;
61 break;
63 mqtt_cfg_.broker.address.transport = MQTT_TRANSPORT_OVER_WSS;
64 break;
66 default:
67#ifdef USE_MQTT_TLS
68 mqtt_cfg_.broker.address.transport = MQTT_TRANSPORT_OVER_SSL;
69#else
70 mqtt_cfg_.broker.address.transport = MQTT_TRANSPORT_OVER_TCP;
71#endif
72 break;
73 }
74 // Only set for the WebSocket transports
75 mqtt_cfg_.broker.address.path = this->ws_path_;
76
77 auto *mqtt_client = esp_mqtt_client_init(&mqtt_cfg_);
78 if (mqtt_client) {
79 handler_.reset(mqtt_client);
80 is_initalized_ = true;
81 esp_mqtt_client_register_event(mqtt_client, MQTT_EVENT_ANY, mqtt_event_handler, this);
82#if defined(USE_MQTT_IDF_ENQUEUE)
83 // Create the task only after MQTT client is initialized successfully
84 // Use larger stack size when TLS is enabled
85#ifdef USE_MQTT_TLS
86 constexpr size_t stack_size = TASK_STACK_SIZE_TLS;
87#else
88 constexpr size_t stack_size = TASK_STACK_SIZE;
89#endif
90 xTaskCreate(esphome_mqtt_task, "esphome_mqtt", stack_size, (void *) this, TASK_PRIORITY, &this->task_handle_);
91 if (this->task_handle_ == nullptr) {
92 ESP_LOGE(TAG, "Failed to create MQTT task");
93 // Clean up MQTT client since we can't start the async task
94 handler_.reset();
95 is_initalized_ = false;
96 return false;
97 }
98 // Set the task handle so the queue can notify it
99 this->mqtt_queue_.set_task_to_notify(this->task_handle_);
100#endif
101 return true;
102 } else {
103 ESP_LOGE(TAG, "Failed to init client");
104 return false;
105 }
106}
107
109 // Capped by count and time so slow on_message automations cannot hold the loop
111 for (uint8_t i = 0; i < MQTT_EVENT_POOL_SIZE; i++) {
112 Event *event = this->mqtt_event_queue_.pop();
113 if (event == nullptr)
114 break;
115 const auto event_id = event->event_id;
116 {
117 DispatchGuard dispatching(this->dispatching_);
118 this->mqtt_event_handler_(*event);
119 }
120 this->mqtt_event_pool_.release(event);
121 // Let the client handle a connection change first
122 if (event_id == MQTT_EVENT_CONNECTED || event_id == MQTT_EVENT_DISCONNECTED ||
123 millis() - start >= EVENT_DRAIN_BUDGET_MS)
124 break;
125 }
126
127 // Log dropped inbound events (check is cheap - single atomic load in common case)
128 uint16_t inbound_dropped = this->mqtt_event_queue_.get_and_reset_dropped_count();
129 if (inbound_dropped > 0) {
130 ESP_LOGW(TAG, "Dropped %u inbound MQTT events", inbound_dropped);
131 }
132
133#if defined(USE_MQTT_IDF_ENQUEUE)
134 // Periodically log dropped messages to avoid blocking during spikes.
135 // During high load, many messages can be dropped in quick succession.
136 // Logging each drop immediately would flood the logs and potentially
137 // cause more drops if MQTT logging is enabled (cascade effect).
138 // Instead, we accumulate the count and log a summary periodically.
139 // IMPORTANT: Don't move this to the scheduler - if drops are due to memory
140 // pressure, the scheduler's heap allocations would make things worse.
142 // Handle rollover: (now - last_time) works correctly with unsigned arithmetic
143 // even when now < last_time due to rollover
144 if ((now - this->last_dropped_log_time_) >= DROP_LOG_INTERVAL_MS) {
145 uint16_t dropped = this->mqtt_queue_.get_and_reset_dropped_count();
146 if (dropped > 0) {
147 ESP_LOGW(TAG, "Dropped %u messages (%" PRIu32 "s)", dropped, DROP_LOG_INTERVAL_MS / 1000);
148 }
149 this->last_dropped_log_time_ = now;
150 }
151#endif
152}
153
155 ESP_LOGV(TAG, "Event dispatched from event loop event_id=%d", event.event_id);
156 switch (event.event_id) {
157 case MQTT_EVENT_BEFORE_CONNECT:
158 ESP_LOGV(TAG, "MQTT_EVENT_BEFORE_CONNECT");
159 break;
160
161 case MQTT_EVENT_CONNECTED:
162 ESP_LOGV(TAG, "MQTT_EVENT_CONNECTED");
163 this->is_connected_ = true;
164 // The MQTT task already reset subacks_
165 this->subscribes_sent_ = 0;
166#if defined(USE_MQTT_IDF_ENQUEUE)
167 this->subscribes_lost_at_connect_ = this->subscribes_lost_.load(std::memory_order_relaxed);
168 this->last_dropped_log_time_ = 0;
169 xTaskNotifyGive(this->task_handle_);
170#endif
171 this->on_connect_.call(event.session_present);
172 break;
173 case MQTT_EVENT_DISCONNECTED:
174 ESP_LOGV(TAG, "MQTT_EVENT_DISCONNECTED");
175 // TODO is there a way to get the disconnect reason?
176 this->is_connected_ = false;
177#if defined(USE_MQTT_IDF_ENQUEUE)
178 this->last_dropped_log_time_ = 0;
179 xTaskNotifyGive(this->task_handle_);
180#endif
182 break;
183
184 case MQTT_EVENT_SUBSCRIBED:
185 ESP_LOGV(TAG, "MQTT_EVENT_SUBSCRIBED, msg_id=%d", event.msg_id);
186 // One topic per SUBSCRIBE, so data[0] is its return code
187 this->on_subscribe_.call((int) event.msg_id,
188 event.data.empty() ? SUBACK_FAILURE : static_cast<uint8_t>(event.data[0]));
189 break;
190 case MQTT_EVENT_UNSUBSCRIBED:
191 ESP_LOGV(TAG, "MQTT_EVENT_UNSUBSCRIBED, msg_id=%d", event.msg_id);
192 this->on_unsubscribe_.call((int) event.msg_id);
193 break;
194 case MQTT_EVENT_PUBLISHED:
195 ESP_LOGV(TAG, "MQTT_EVENT_PUBLISHED, msg_id=%d", event.msg_id);
196 this->on_publish_.call((int) event.msg_id);
197 break;
198 case MQTT_EVENT_DATA: {
199 if (!event.topic.empty()) {
200 // When a single message arrives as multiple chunks, the topic will be empty
201 // on any but the first message, leading to event.topic being an empty string.
202 // To ensure handlers get the correct topic, cache the last seen topic to
203 // simulate always receiving the topic from underlying library
204 this->cached_topic_ = event.topic;
205 }
206 ESP_LOGV(TAG, "MQTT_EVENT_DATA %s", this->cached_topic_.c_str());
207 this->on_message_.call(this->cached_topic_.c_str(), event.data.data(), event.data.size(),
208 event.current_data_offset, event.total_data_len);
209 } break;
210 case MQTT_EVENT_ERROR:
211 ESP_LOGE(TAG, "MQTT_EVENT_ERROR");
212 if (event.error_handle.error_type == MQTT_ERROR_TYPE_TCP_TRANSPORT) {
213 ESP_LOGE(TAG, "Last esp-tls error: 0x%x, tls stack error: 0x%x, socket errno: %d (%s)",
214 event.error_handle.esp_tls_last_esp_err, event.error_handle.esp_tls_stack_err,
215 event.error_handle.esp_transport_sock_errno, strerror(event.error_handle.esp_transport_sock_errno));
216 } else if (event.error_handle.error_type == MQTT_ERROR_TYPE_CONNECTION_REFUSED) {
217 ESP_LOGE(TAG, "Connection refused error: 0x%x", event.error_handle.connect_return_code);
218 } else {
219 ESP_LOGE(TAG, "Unknown error type: 0x%x", event.error_handle.error_type);
220 }
221 break;
222 default:
223 ESP_LOGV(TAG, "Other event id:%d", event.event_id);
224 break;
225 }
226}
227
229void MQTTBackendESP32::mqtt_event_handler(void *handler_args, esp_event_base_t base, int32_t event_id,
230 void *event_data) {
231 MQTTBackendESP32 *instance = static_cast<MQTTBackendESP32 *>(handler_args);
232 if (instance == nullptr)
233 return;
234 const auto *mqtt_event = static_cast<esp_mqtt_event_t *>(event_data);
235 // Acks are queued only when a callback wants them
236 bool listened = true;
237 switch (event_id) {
238 case MQTT_EVENT_CONNECTED:
239 instance->subacks_.reset();
240 break;
241 case MQTT_EVENT_SUBSCRIBED:
242 listened = instance->on_subscribe_.size() != 0;
243 break;
244 case MQTT_EVENT_UNSUBSCRIBED:
245 listened = instance->on_unsubscribe_.size() != 0;
246 break;
247 case MQTT_EVENT_PUBLISHED: {
248 // Also seen by teardown without dispatching
249 auto msg_id = static_cast<uint16_t>(mqtt_event->msg_id);
250 instance->acked_msg_id_.store(msg_id);
251 if (msg_id == instance->tracked_msg_id_.load())
252 instance->tracked_acked_.store(1);
253 listened = instance->on_publish_.size() != 0;
254 break;
255 }
256 case MQTT_EVENT_DATA:
257 // Queue only the first chunk of an oversized message, so the client logs the drop
258 if (mqtt_event->total_data_len > MQTT_MAX_PAYLOAD_SIZE && mqtt_event->current_data_offset != 0)
259 return;
260 break;
261 default:
262 break;
263 }
264 if (listened) {
265 // queue event to decouple processing from ESP-IDF MQTT task to main loop
266 auto *event = instance->mqtt_event_pool_.allocate();
267 if (event != nullptr) {
268 event->populate(*mqtt_event);
269 // Push always succeeds: pool is sized to queue capacity (SIZE-1), so if
270 // allocate() returned non-null, the queue cannot be full.
271 instance->mqtt_event_queue_.push(event);
272 } else {
273 // Pool exhausted, drop event (counted via queue's dropped counter)
274 instance->mqtt_event_queue_.increment_dropped_count();
275 }
276 } else {
277 ESP_LOGV(TAG, "Ack event_id=%" PRId32 ", msg_id=%d", event_id, mqtt_event->msg_id);
278 }
279 if (event_id == MQTT_EVENT_SUBSCRIBED) {
280 // Counted after queueing so its slot stays reserved
281 // One topic per SUBSCRIBE, so data[0] is its return code
282 instance->subacks_.add(mqtt_event->data_len > 0 ? static_cast<uint8_t>(mqtt_event->data[0]) : SUBACK_FAILURE);
283 } else if (!listened) {
284 return;
285 }
286 // A filtered SUBACK may still let the next SUBSCRIBE go out
288}
289
291 this->tracked_acked_.store(0, std::memory_order_relaxed);
292 // Sent directly even with idf_send_async, so the message id is known here
293 int msg_id = esp_mqtt_client_publish(this->handler_.get(), message.topic.c_str(), message.payload.c_str(),
294 message.payload.length(), std::max<uint8_t>(message.qos, 1), message.retain);
295 if (msg_id <= 0)
296 return false;
297 this->tracked_msg_id_.store(static_cast<uint16_t>(msg_id));
298 // The confirmation may have arrived before the store above
299 if (this->acked_msg_id_.load() == msg_id)
300 this->tracked_acked_.store(1);
301 return true;
302}
303
304#if defined(USE_MQTT_IDF_ENQUEUE)
306 MQTTBackendESP32 *this_mqtt = (MQTTBackendESP32 *) params;
307
308 while (true) {
309 // Wait for notification indefinitely
310 ulTaskNotifyTake(pdTRUE, portMAX_DELAY);
311
312 // Process all queued items
313 struct QueueElement *elem;
314 while ((elem = this_mqtt->mqtt_queue_.pop()) != nullptr) {
315 if (this_mqtt->is_connected_) {
316 switch (elem->type) {
318 if (esp_mqtt_client_subscribe(this_mqtt->handler_.get(), elem->topic, elem->qos) == -1)
319 this_mqtt->count_lost_subscribe_();
320 break;
321
323 esp_mqtt_client_unsubscribe(this_mqtt->handler_.get(), elem->topic);
324 break;
325
327 esp_mqtt_client_publish(this_mqtt->handler_.get(), elem->topic, elem->payload, elem->payload_len, elem->qos,
328 elem->retain);
329 break;
330
331 default:
332 ESP_LOGE(TAG, "Invalid operation type from MQTT queue");
333 break;
334 }
335 } else if (elem->type == MQTT_QUEUE_TYPE_SUBSCRIBE) {
336 this_mqtt->count_lost_subscribe_();
337 }
338 this_mqtt->mqtt_outbound_pool_.release(elem);
339 }
340 }
341}
342
343bool MQTTBackendESP32::enqueue_(MqttQueueTypeT type, const char *topic, int qos, bool retain, const char *payload,
344 size_t len) {
345 auto *elem = this->mqtt_outbound_pool_.allocate();
346
347 if (!elem) {
348 // Queue is full - increment counter but don't log immediately.
349 // Logging here can cause a cascade effect: if MQTT logging is enabled,
350 // each dropped message would generate a log message, which could itself
351 // be sent via MQTT, causing more drops and more logs in a feedback loop
352 // that eventually triggers a watchdog reset. Instead, we log periodically
353 // in loop() to prevent blocking the event loop during spikes.
354 this->mqtt_queue_.increment_dropped_count();
355 return false;
356 }
357
358 elem->type = type;
359 elem->qos = qos;
360 elem->retain = retain;
361
362 // Use the helper to allocate and copy data
363 if (!elem->set_data(topic, payload, len)) {
364 // Allocation failed, return elem to pool
365 this->mqtt_outbound_pool_.release(elem);
366 // Increment counter without logging to avoid cascade effect during memory pressure
367 this->mqtt_queue_.increment_dropped_count();
368 return false;
369 }
370
371 // Push to queue - always succeeds since we allocated from the pool
372 this->mqtt_queue_.push(elem);
373 return true;
374}
375#endif // USE_MQTT_IDF_ENQUEUE
376
377} // namespace esphome::mqtt
378#endif // USE_ESP32
379#endif
void wake_loop_threadsafe()
Wake the main event loop from another thread or callback.
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.
Sets a flag for the guard's scope and restores its previous value on exit.
EventPool< struct QueueElement, MQTT_QUEUE_LENGTH - 1 > mqtt_outbound_pool_
CallbackManager< on_connect_callback_t > on_connect_
CallbackManager< on_disconnect_callback_t > on_disconnect_
uint16_t subscribes_sent_
SUBSCRIBEs sent on this connection.
std::atomic< uint16_t > acked_msg_id_
CallbackManager< on_message_callback_t > on_message_
std::atomic< uint16_t > tracked_msg_id_
static void mqtt_event_handler(void *handler_args, esp_event_base_t base, int32_t event_id, void *event_data)
static - Dispatch event to instance method
static constexpr uint32_t EVENT_DRAIN_BUDGET_MS
CallbackManager< on_subscribe_callback_t > on_subscribe_
static void esphome_mqtt_task(void *params)
EventPool< Event, MQTT_EVENT_POOL_SIZE > mqtt_event_pool_
bool enqueue_(MqttQueueTypeT type, const char *topic, int qos=0, bool retain=false, const char *payload=NULL, size_t len=0)
bool publish_tracked(const MQTTMessage &message) final
static constexpr size_t TASK_STACK_SIZE_TLS
CallbackManager< on_unsubscribe_callback_t > on_unsubscribe_
std::atomic< uint8_t > tracked_acked_
esp_mqtt_client_config_t mqtt_cfg_
static constexpr size_t TASK_STACK_SIZE
CallbackManager< on_publish_user_callback_t > on_publish_
static constexpr uint32_t DROP_LOG_INTERVAL_MS
NotifyingLockFreeQueue< struct QueueElement, MQTT_QUEUE_LENGTH > mqtt_queue_
static constexpr uint8_t MQTT_EVENT_POOL_SIZE
void mqtt_event_handler_(const Event &event)
std::atomic< uint16_t > subscribes_lost_
static constexpr ssize_t TASK_PRIORITY
LockFreeQueue< Event, MQTT_EVENT_QUEUE_LENGTH > mqtt_event_queue_
const LogString * message
Definition component.cpp:35
uint8_t type
ESPHOME_LOG_TAG(TAG, "alarm_control_panel")
const void size_t len
Definition hal.h:68
uint32_t IRAM_ATTR HOT millis()
Definition hal.cpp:25
Application App
Global storage of Application pointer - only one Application can exist.
internal struct for MQTT messages.
uint8_t event_id
Definition tt21100.cpp:3