ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
mqtt_backend_esp32.h
Go to the documentation of this file.
1#pragma once
2
3#include "mqtt_backend.h"
4#ifdef USE_MQTT
5#ifdef USE_ESP32
6
7#include <atomic>
8#include <string>
9#include <cstring>
10#include <mqtt_client.h>
11#include <freertos/FreeRTOS.h>
12#include <freertos/task.h>
18
19namespace esphome::mqtt {
20
21struct Event {
22 esp_mqtt_event_id_t event_id{};
23 std::vector<char> data;
26 std::string topic;
27 int msg_id{0};
28 bool retain{false};
29 int qos{0};
30 bool dup{false};
31 bool session_present{false};
32 esp_mqtt_error_codes_t error_handle{};
33
34 // Populate from esp_mqtt_event_t
35 // Copies pointer-based data to owned storage for safe cross-thread transfer
36 void populate(const esp_mqtt_event_t &event) {
37 this->event_id = event.event_id;
38 this->data.assign(event.data, event.data + event.data_len);
39 this->total_data_len = event.total_data_len;
40 this->current_data_offset = event.current_data_offset;
41 this->topic.assign(event.topic, event.topic_len);
42 this->msg_id = event.msg_id;
43 this->retain = event.retain;
44 this->qos = event.qos;
45 this->dup = event.dup;
46 this->session_present = event.session_present;
47 this->error_handle = *event.error_handle;
48 }
49
50 // Release owned resources for pool reuse (keeps allocated capacity for efficiency)
51 void release() {
52 this->data.clear();
53 this->topic.clear();
54 }
55};
56
63
65 char *topic;
66 char *payload;
67 uint16_t payload_len; // MQTT max payload is 64KiB
68 uint8_t type : 2;
69 uint8_t qos : 2; // QoS only needs values 0-2
70 uint8_t retain : 1;
71 uint8_t reserved : 3; // Reserved for future use
72
73 QueueElement() : topic(nullptr), payload(nullptr), payload_len(0), qos(0), retain(0), reserved(0) {}
74
75 // Helper to set topic/payload (uses RAMAllocator)
76 bool set_data(const char *topic_str, const char *payload_data, size_t len) {
77 // Check payload size limit (MQTT max is 64KiB)
78 if (len > std::numeric_limits<uint16_t>::max()) {
79 return false;
80 }
81
82 // Use RAMAllocator with default flags (tries external RAM first, falls back to internal)
83 RAMAllocator<char> allocator;
84
85 // Allocate and copy topic
86 size_t topic_len = strlen(topic_str) + 1;
87 topic = allocator.allocate(topic_len);
88 if (!topic)
89 return false;
90 memcpy(topic, topic_str, topic_len);
91
92 if (payload_data && len) {
93 payload = allocator.allocate(len);
94 if (!payload) {
95 allocator.deallocate(topic, topic_len);
96 topic = nullptr;
97 return false;
98 }
99 memcpy(payload, payload_data, len);
100 payload_len = static_cast<uint16_t>(len);
101 } else {
102 payload = nullptr;
103 payload_len = 0;
104 }
105 return true;
106 }
107
108 // Helper to release (uses RAMAllocator)
109 void release() {
110 RAMAllocator<char> allocator;
111 if (topic) {
112 allocator.deallocate(topic, strlen(topic) + 1);
113 topic = nullptr;
114 }
115 if (payload) {
116 allocator.deallocate(payload, payload_len);
117 payload = nullptr;
118 }
119 payload_len = 0;
120 }
121};
122
123class MQTTBackendESP32 final : public MQTTBackend {
124 public:
125 static constexpr size_t MQTT_BUFFER_SIZE = 4096;
126 static constexpr size_t TASK_STACK_SIZE = 3072;
127 static constexpr size_t TASK_STACK_SIZE_TLS = 4096; // Larger stack for TLS operations
128 static constexpr ssize_t TASK_PRIORITY = 5;
129 static constexpr uint8_t MQTT_QUEUE_LENGTH = 30; // 30*12 bytes = 360
130 static constexpr uint8_t MQTT_EVENT_QUEUE_LENGTH = 32; // Inbound events from broker
131 static constexpr uint32_t EVENT_DRAIN_BUDGET_MS = 10;
132 static constexpr uint8_t MQTT_EVENT_POOL_SIZE = MQTT_EVENT_QUEUE_LENGTH - 1;
133
134 void set_keep_alive(uint16_t keep_alive) final { this->keep_alive_ = keep_alive; }
135 void set_client_id(const char *client_id) final { this->client_id_ = client_id; }
136 void set_clean_session(bool clean_session) final { this->clean_session_ = clean_session; }
137
138 void set_credentials(const char *username, const char *password) final {
139 if (username)
140 this->username_ = username;
141 if (password)
142 this->password_ = password;
143 }
144 void set_will(const char *topic, uint8_t qos, bool retain, const char *payload) final {
145 if (topic)
146 this->lwt_topic_ = topic;
147 this->lwt_qos_ = qos;
148 if (payload)
149 this->lwt_message_ = payload;
150 this->lwt_retain_ = retain;
151 }
152 void set_server(network::IPAddress ip, uint16_t port) final {
153 char ip_buf[network::IP_ADDRESS_BUFFER_SIZE];
154 this->host_ = ip.str_to(ip_buf);
155 this->port_ = port;
156 }
157 void set_server(const char *host, uint16_t port) final {
158 this->host_ = host;
159 this->port_ = port;
160 }
161 void set_on_connect(std::function<on_connect_callback_t> &&callback) final {
162 this->on_connect_.add(std::move(callback));
163 }
164 void set_on_disconnect(std::function<on_disconnect_callback_t> &&callback) final {
165 this->on_disconnect_.add(std::move(callback));
166 }
167 void set_on_subscribe(std::function<on_subscribe_callback_t> &&callback) final {
168 this->on_subscribe_.add(std::move(callback));
169 }
170 void set_on_unsubscribe(std::function<on_unsubscribe_callback_t> &&callback) final {
171 this->on_unsubscribe_.add(std::move(callback));
172 }
173 void set_on_message(std::function<on_message_callback_t> &&callback) final {
174 this->on_message_.add(std::move(callback));
175 }
176 void set_on_publish(std::function<on_publish_user_callback_t> &&callback) final {
177 this->on_publish_.add(std::move(callback));
178 }
179 bool connected() const final { return this->is_connected_; }
180
181 void connect() final {
182 if (!is_initalized_) {
183 if (initialize_()) {
184 esp_mqtt_client_start(handler_.get());
185 }
186 }
187 }
188 void disconnect() final {
189 if (is_initalized_)
190 esp_mqtt_client_disconnect(handler_.get());
191 }
192
193 bool subscribe(const char *topic, uint8_t qos) final {
194 // Stray SUBACKs for resent SUBSCRIBEs of an earlier connection give no credit once they outnumber
195 // ours; one counted mid-burst still frees a slot until the burst ends
196 const uint16_t counted = this->sent_on_connection_();
197 this->subscribes_sent_ += static_cast<uint16_t>(rebase_sent(counted, this->subacks_.received()) - counted);
198#if defined(USE_MQTT_IDF_ENQUEUE)
199 const bool sent = this->enqueue_(MQTT_QUEUE_TYPE_SUBSCRIBE, topic, qos);
200#else
201 const bool sent = esp_mqtt_client_subscribe(this->handler_.get(), topic, qos) != -1;
202#endif
203 if (sent)
204 this->subscribes_sent_++;
205 return sent;
206 }
207 bool can_subscribe() const final {
208 const uint16_t sent = this->sent_on_connection_();
209 // Loaded before the queue size, so retained data queued after a counted SUBACK is seen
210 const uint16_t answered = this->subacks_.received();
211 // The event being dispatched still holds its pool slot
212 const size_t free_slots = MQTT_EVENT_POOL_SIZE - this->mqtt_event_queue_.size() - this->dispatching_;
213 return subscribe_fits(
214 sent, answered, free_slots,
215 this->on_subscribe_.size() != 0 ? INBOUND_SLOTS_PER_SUBSCRIBE_WITH_ACK : INBOUND_SLOTS_PER_SUBSCRIBE);
216 }
217 bool unsubscribe(const char *topic) final {
218#if defined(USE_MQTT_IDF_ENQUEUE)
220#else
221 return esp_mqtt_client_unsubscribe(handler_.get(), topic) != -1;
222#endif
223 }
224
225 bool publish(const char *topic, const char *payload, size_t length, uint8_t qos, bool retain) final {
226#if defined(USE_MQTT_IDF_ENQUEUE)
227 return enqueue_(MQTT_QUEUE_TYPE_PUBLISH, topic, qos, retain, payload, length);
228#else
229 // might block for several seconds, either due to network timeout (10s)
230 // or if publishing payloads longer than internal buffer (due to message fragmentation)
231 return esp_mqtt_client_publish(handler_.get(), topic, payload, length, qos, retain) != -1;
232#endif
233 }
235 bool publish_tracked(const MQTTMessage &message) final;
236 bool publish_acknowledged() const final { return this->tracked_acked_.load(std::memory_order_acquire) != 0; }
237 const SubackCounter &get_subacks() const { return this->subacks_; }
238
239 void loop() final;
240
241#ifdef USE_MQTT_TLS
242 // The certificates are string literals from code generation, so only the pointers are kept
243 void set_ca_certificate(const char *cert) { this->ca_certificate_ = cert; }
244 void set_cl_certificate(const char *cert) { this->cl_certificate_ = cert; }
245 void set_cl_key(const char *key) { this->cl_key_ = key; }
246 void set_skip_cert_cn_check(bool skip_check) { this->skip_cert_cn_check_ = skip_check; }
247#endif
248 void set_transport(MQTTTransport transport) { this->transport_ = transport; }
249 void set_ws_path(const char *path) { this->ws_path_ = path; }
250 MQTTTransport get_transport() const { return this->transport_; }
251 const char *get_ws_path() const { return this->ws_path_; }
252
253 // No destructor needed: ESPHome components live for the entire device runtime.
254 // The MQTT task and queue will run until the device reboots or loses power,
255 // at which point the entire process terminates and FreeRTOS cleans up all tasks.
256 // Implementing a destructor would add complexity and potential race conditions
257 // for a scenario that never occurs in practice.
258
259 protected:
260 bool initialize_();
261 void mqtt_event_handler_(const Event &event);
262 static void mqtt_event_handler(void *handler_args, esp_event_base_t base, int32_t event_id, void *event_data);
263
265 void operator()(esp_mqtt_client *client_handler) { esp_mqtt_client_destroy(client_handler); }
266 };
268 uint16_t sent_on_connection_() const {
269#if defined(USE_MQTT_IDF_ENQUEUE)
270 return static_cast<uint16_t>(this->subscribes_sent_ - (this->subscribes_lost_.load(std::memory_order_relaxed) -
272#else
273 return this->subscribes_sent_;
274#endif
275 }
276 using ClientHandler_ = std::unique_ptr<esp_mqtt_client, MqttClientDeleter>;
278
279 bool is_connected_{false};
280 bool is_initalized_{false};
281#if defined(USE_MQTT_IDF_ENQUEUE)
282 // Queued SUBSCRIBEs the task could not send
283 std::atomic<uint16_t> subscribes_lost_{0};
284#endif
285
286 esp_mqtt_client_config_t mqtt_cfg_{};
287
288 std::string host_;
289 uint16_t port_;
291 uint16_t subscribes_sent_{0};
292 std::string username_;
293 std::string password_;
294 std::string lwt_topic_;
295 std::string lwt_message_;
296 uint8_t lwt_qos_;
298#if defined(USE_MQTT_IDF_ENQUEUE)
299 // subscribes_lost_ when this connection started
301#endif
302 std::string client_id_;
303 uint16_t keep_alive_;
305 bool dispatching_{false};
306 // uint8_t because atomic<bool> is out of line on Xtensa
307 std::atomic<uint8_t> tracked_acked_{0};
308#ifdef USE_MQTT_TLS
309 const char *ca_certificate_{nullptr};
310 const char *cl_certificate_{nullptr};
311 const char *cl_key_{nullptr};
313#endif
315 const char *ws_path_{nullptr};
316#if defined(USE_MQTT_IDF_ENQUEUE)
317 static void esphome_mqtt_task(void *params);
318 // Pool sized to queue capacity (SIZE-1) — see mqtt_event_pool_ comment.
321 TaskHandle_t task_handle_{nullptr};
322 // Only the task writes, so no atomic read-modify-write is needed
324 this->subscribes_lost_.store(this->subscribes_lost_.load(std::memory_order_relaxed) + 1, std::memory_order_relaxed);
325 }
326 bool enqueue_(MqttQueueTypeT type, const char *topic, int qos = 0, bool retain = false, const char *payload = NULL,
327 size_t len = 0);
328#endif
329
330 // callbacks
337 std::string cached_topic_;
338 // Set by the ESP-IDF MQTT task, which runs at a higher priority; publish_tracked() checks the last
339 // confirmed id in case the confirmation beat its store. Packet ids are never 0.
340 std::atomic<uint16_t> tracked_msg_id_{0};
341 std::atomic<uint16_t> acked_msg_id_{0};
342 // Counted in the ESP-IDF MQTT task, see mqtt_event_handler()
344 // Pool sized to queue capacity (SIZE-1) because LockFreeQueue<T,N> is a ring
345 // buffer that holds N-1 elements (one slot distinguishes full from empty).
346 // This guarantees allocate() returns nullptr before push() can fail, which:
347 // 1. Prevents leaking a pool slot (the Nth allocate succeeds but push fails)
348 // 2. Avoids needing release() on the producer path after a failed push(),
349 // preserving the SPSC contract on the pool's internal free list
352
353#if defined(USE_MQTT_IDF_ENQUEUE)
355 static constexpr uint32_t DROP_LOG_INTERVAL_MS = 10000; // Log every 10 seconds
356#endif
357};
358
359} // namespace esphome::mqtt
360
361#endif
362#endif
An STL allocator that uses SPI or internal RAM.
Definition helpers.h:2396
void deallocate(T *p, size_t n)
Definition helpers.h:2453
T * allocate(size_t n)
Definition helpers.h:2423
void set_keep_alive(uint16_t keep_alive) final
EventPool< struct QueueElement, MQTT_QUEUE_LENGTH - 1 > mqtt_outbound_pool_
void set_on_message(std::function< on_message_callback_t > &&callback) final
CallbackManager< on_connect_callback_t > on_connect_
const SubackCounter & get_subacks() const
CallbackManager< on_disconnect_callback_t > on_disconnect_
uint16_t subscribes_sent_
SUBSCRIBEs sent on this connection.
static constexpr size_t MQTT_BUFFER_SIZE
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
void set_client_id(const char *client_id) final
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_
void set_on_publish(std::function< on_publish_user_callback_t > &&callback) final
bool enqueue_(MqttQueueTypeT type, const char *topic, int qos=0, bool retain=false, const char *payload=NULL, size_t len=0)
void set_server(const char *host, uint16_t port) final
static constexpr uint8_t MQTT_EVENT_QUEUE_LENGTH
bool publish_tracked(const MQTTMessage &message) final
void set_on_connect(std::function< on_connect_callback_t > &&callback) final
void set_ca_certificate(const char *cert)
void set_will(const char *topic, uint8_t qos, bool retain, const char *payload) final
bool subscribe(const char *topic, uint8_t qos) final
void set_server(network::IPAddress ip, uint16_t port) final
void set_transport(MQTTTransport transport)
uint16_t sent_on_connection_() const
SUBSCRIBEs sent on this connection, less those the task could not send.
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_
void set_skip_cert_cn_check(bool skip_check)
void set_on_unsubscribe(std::function< on_unsubscribe_callback_t > &&callback) final
bool publish(const char *topic, const char *payload, size_t length, uint8_t qos, bool retain) final
static constexpr size_t TASK_STACK_SIZE
CallbackManager< on_publish_user_callback_t > on_publish_
void set_clean_session(bool clean_session) final
bool unsubscribe(const char *topic) final
static constexpr uint32_t DROP_LOG_INTERVAL_MS
NotifyingLockFreeQueue< struct QueueElement, MQTT_QUEUE_LENGTH > mqtt_queue_
static constexpr uint8_t MQTT_QUEUE_LENGTH
static constexpr uint8_t MQTT_EVENT_POOL_SIZE
void set_on_subscribe(std::function< on_subscribe_callback_t > &&callback) final
void mqtt_event_handler_(const Event &event)
void set_on_disconnect(std::function< on_disconnect_callback_t > &&callback) final
void set_cl_certificate(const char *cert)
void set_credentials(const char *username, const char *password) final
std::atomic< uint16_t > subscribes_lost_
static constexpr ssize_t TASK_PRIORITY
std::unique_ptr< esp_mqtt_client, MqttClientDeleter > ClientHandler_
LockFreeQueue< Event, MQTT_EVENT_QUEUE_LENGTH > mqtt_event_queue_
virtual bool publish(const char *topic, const char *payload, size_t length, uint8_t qos, bool retain)=0
SUBACKs received on the current connection.
const LogString * message
Definition component.cpp:35
uint8_t type
const char * key
__int64 ssize_t
Definition httplib.h:178
MQTTTransport
Transport for the broker connection; only the ESP-IDF backend supports WebSocket.
constexpr uint16_t rebase_sent(uint16_t sent, uint16_t answered)
The sent count raised to the SUBACKs counted, so stray SUBACKs give no credit; wrap safe.
constexpr bool subscribe_fits(uint16_t sent, uint16_t answered, size_t free_slots, size_t slots_per_subscribe=INBOUND_SLOTS_PER_SUBSCRIBE)
Whether one more SUBSCRIBE fits; wrap safe.
const void size_t len
Definition hal.h:68
std::vector< char > data
esp_mqtt_error_codes_t error_handle
void populate(const esp_mqtt_event_t &event)
void operator()(esp_mqtt_client *client_handler)
internal struct for MQTT messages.
bool set_data(const char *topic_str, const char *payload_data, size_t len)
uint16_t length
Definition tt21100.cpp:0
uint8_t event_id
Definition tt21100.cpp:3