ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
ota_esphome_udp.cpp
Go to the documentation of this file.
1#include "ota_esphome.h"
2#if defined(USE_OTA) && defined(ESPHOME_OTA_UDP)
3
5#include "esphome/core/hal.h"
7#include "esphome/core/log.h"
8
9#ifdef ESPHOME_OTA_UDP_LWIP
10#include "lwip/inet.h"
11#ifdef USE_LIBRETINY
12#include "lwip/tcpip.h"
13#endif
14#endif
15
16#include <algorithm>
17#include <cstring>
18#include <memory>
19
20/*
21 * UDP data phase: the same byte stream as TCP, cut into numbered datagrams.
22 * client -> device [type | COMMITTED][token u32][seq u16][device bytes received u16][payload]
23 * device -> client [ACK][token u32][received u16][seq that prompted it u16][stream offset u16][window u8][our bytes]
24 * The lwIP callback acks each datagram on arrival, so flash writes never look like loss, and keeps messages in its
25 * UDP_WINDOW slots until the OTA loop reads them. "window": free slots in the high nibble, and in the low nibble bit k
26 * set when received + k is already here (like TCP SACK).
27 */
28
29namespace esphome {
30
31ESPHOME_LOG_TAG(TAG, "esphome.ota");
32
33// PING (0x02) and PROBE (0x03) only prompt an ACK
34static constexpr uint8_t UDP_MSG_DATA = 0x01;
35static constexpr uint8_t UDP_FLAG_COMMITTED = 0x80;
36static constexpr uint8_t UDP_MSG_ACK = 0x40;
37static constexpr size_t UDP_HEADER_SIZE = 9;
38static constexpr size_t UDP_ACK_HEADER_SIZE = 12;
39// The client's 60 s wait for the token over a lossy TCP link, plus its 15 s probe
40static constexpr uint32_t UDP_COMMIT_TIMEOUT = 80000;
41// Like the TCP socket's SO_RCVTIMEO in handle_data_, so readall_ treats both alike
42static constexpr uint32_t UDP_READ_WAIT_MS = 2000;
43// How often the commit wait looks at the UDP link between reads of the TCP fallback byte
44static constexpr uint32_t UDP_COMMIT_POLL_MS = 100;
45static constexpr uint32_t UDP_LINGER_MS = 3000;
46
47#ifdef ESPHOME_OTA_UDP_LWIP
48#ifdef USE_LIBRETINY
49// LibreTiny's LwIPLock is a no-op; take the core lock directly (the header drops UDP without one)
50struct UdpLock {
51 UdpLock() { LOCK_TCPIP_CORE(); }
52 ~UdpLock() { UNLOCK_TCPIP_CORE(); }
53};
54#else
55using UdpLock = LwIPLock;
56#endif
57static uint16_t slot_len(struct pbuf *p) { return p->tot_len; }
58static uint16_t slot_copy(struct pbuf *p, void *dst, uint16_t len, uint16_t offset) {
59 return pbuf_copy_partial(p, dst, len, offset);
60}
61static void slot_free(struct pbuf *p) { pbuf_free(p); }
62#else
63// The host has no lwIP thread: the OTA loop drains the socket itself. Empty bodies, not = default, so clang-tidy
64// does not flag the guards as unused
65struct UdpLock {
66 UdpLock() {}
67 ~UdpLock() {}
68};
69struct OtaUdpDatagram {
70 uint16_t len;
71 uint8_t data[1500];
72};
73static uint16_t slot_len(OtaUdpDatagram *p) { return p->len; }
74static uint16_t slot_copy(OtaUdpDatagram *p, void *dst, uint16_t len, uint16_t offset) {
75 const uint16_t n = std::min<uint16_t>(len, p->len - offset);
76 memcpy(dst, p->data + offset, n);
77 return n;
78}
79static void slot_free(OtaUdpDatagram *p) { delete p; }
80#endif
81
83
85 UdpLock lock;
86#ifdef ESPHOME_OTA_UDP_LWIP
87 if (this->pcb != nullptr)
88 udp_remove(this->pcb);
89 this->pcb = nullptr;
90#else
91 this->sock = nullptr;
92#endif
93 for (auto &p : this->queue) {
94 if (p != nullptr)
95 slot_free(p);
96 p = nullptr;
97 }
98}
99
100void ESPHomeOTAComponent::udp_send_ack(UdpLink &link, uint16_t prompted_by) {
101 const uint16_t len = UDP_ACK_HEADER_SIZE + link.out_len;
102#ifdef ESPHOME_OTA_UDP_LWIP
103 struct pbuf *p = pbuf_alloc(PBUF_TRANSPORT, len, PBUF_RAM);
104 if (p == nullptr)
105 return; // Like a lost ACK: the client asks again
106 auto *ack = static_cast<uint8_t *>(p->payload);
107#else
108 uint8_t ack[UDP_ACK_HEADER_SIZE + UDP_OUT_SIZE];
109#endif
110 ack[0] = UDP_MSG_ACK;
111 memcpy(ack + 1, link.reply, 4);
112 put_be16(ack + 5, link.received);
113 put_be16(ack + 7, prompted_by);
114 put_be16(ack + 9, link.out_base);
115 uint8_t window = (UDP_WINDOW - static_cast<uint16_t>(link.received - link.consumed)) << 4;
116 for (uint8_t k = 1; k < UDP_WINDOW; k++) {
117 if (link.queue[(link.received + k) % UDP_WINDOW] != nullptr)
118 window |= 1 << k;
119 }
120 ack[11] = window;
121 memcpy(ack + UDP_ACK_HEADER_SIZE, link.out, link.out_len);
122 // Best effort: a lost ACK is repeated for the client's next datagram
123#ifdef ESPHOME_OTA_UDP_LWIP
124 udp_sendto(link.pcb, p, &link.peer_ip, link.peer_port);
125 pbuf_free(p);
126#else
127 struct sockaddr_storage to = link.peer;
128 if (to.ss_family == AF_INET6) {
129 reinterpret_cast<sockaddr_in6 *>(&to)->sin6_port = htons(link.peer_port);
130 } else {
131 reinterpret_cast<sockaddr_in *>(&to)->sin_port = htons(link.peer_port);
132 }
133 link.sock->sendto(ack, len, 0, reinterpret_cast<const struct sockaddr *>(&to), link.peer_len);
134#endif
135}
136
138 uint8_t hdr[UDP_HEADER_SIZE];
139 if (slot_copy(p, hdr, UDP_HEADER_SIZE, 0) != UDP_HEADER_SIZE || memcmp(hdr + 1, link.reply, 4) != 0) {
140 slot_free(p);
141 return;
142 }
143 // The token proves the sender; answer the port it arrived from, which NAT may have rewritten
144 link.peer_port = port;
145 link.committed |= (hdr[0] & UDP_FLAG_COMMITTED) != 0;
146 // Drop the responses the client already has
147 const uint16_t acked = encode_uint16(hdr[7], hdr[8]) - link.out_base;
148 if (acked != 0 && acked <= link.out_len) {
149 link.out_len -= acked;
150 memmove(link.out, link.out + acked, link.out_len);
151 link.out_base += acked;
152 }
153 const uint16_t seq = encode_uint16(hdr[5], hdr[6]);
154 UdpSlot &slot = link.queue[seq % UDP_WINDOW];
155 if ((hdr[0] & ~UDP_FLAG_COMMITTED) == UDP_MSG_DATA && slot_len(p) > UDP_HEADER_SIZE &&
156 static_cast<uint16_t>(seq - link.consumed) < UDP_WINDOW && slot == nullptr) {
157 slot = p;
158 while (static_cast<uint16_t>(link.received - link.consumed) < UDP_WINDOW &&
159 link.queue[link.received % UDP_WINDOW] != nullptr)
160 link.received++;
161 } else {
162 slot_free(p);
163 }
164 udp_send_ack(link, seq);
165}
166
167#ifdef ESPHOME_OTA_UDP_LWIP
168// lwIP context: the tcpip thread (ESP32, LibreTiny), SYS (ESP8266) or an IRQ (RP2040)
169void ESPHomeOTAComponent::udp_recv_cb(void *arg, struct udp_pcb * /*pcb*/, struct pbuf *p, const ip_addr_t *addr,
170 uint16_t port) {
171 auto &link = *static_cast<UdpLink *>(arg);
172 if (!ip_addr_cmp(addr, &link.peer_ip)) {
173 pbuf_free(p);
174 return;
175 }
176 udp_on_datagram(link, p, port);
177}
178#else
179static bool same_ip(const struct sockaddr_storage &a, const struct sockaddr_storage &b) {
180 uint32_t ipv4_a, ipv4_b;
181 const bool v4_a = socket::sockaddr_to_ipv4(reinterpret_cast<const struct sockaddr *>(&a), &ipv4_a);
182 const bool v4_b = socket::sockaddr_to_ipv4(reinterpret_cast<const struct sockaddr *>(&b), &ipv4_b);
183 if (v4_a || v4_b)
184 return v4_a && v4_b && ipv4_a == ipv4_b;
185 return a.ss_family == AF_INET6 && b.ss_family == AF_INET6 &&
186 memcmp(&reinterpret_cast<const sockaddr_in6 *>(&a)->sin6_addr,
187 &reinterpret_cast<const sockaddr_in6 *>(&b)->sin6_addr, sizeof(in6_addr)) == 0;
188}
189
191 UdpLink &link = *this->udp_;
192 for (;;) {
193 uint8_t buf[sizeof(OtaUdpDatagram::data)];
194 struct sockaddr_storage from;
195 socklen_t from_len = sizeof(from);
196 const ssize_t len = link.sock->recvfrom(buf, sizeof(buf), reinterpret_cast<struct sockaddr *>(&from), &from_len);
197 if (len < 0)
198 return;
199 if (!same_ip(from, link.peer))
200 continue;
201 auto *datagram = new OtaUdpDatagram; // NOLINT(cppcoreguidelines-owning-memory)
202 datagram->len = len;
203 memcpy(datagram->data, buf, len);
204 const uint16_t port = from.ss_family == AF_INET6 ? ntohs(reinterpret_cast<sockaddr_in6 *>(&from)->sin6_port)
205 : ntohs(reinterpret_cast<sockaddr_in *>(&from)->sin_port);
206 udp_on_datagram(link, datagram, port);
207 }
208}
209#endif
210
212 struct sockaddr_storage peer;
213 socklen_t peer_len = sizeof(peer);
214 if (this->client_->getpeername(reinterpret_cast<struct sockaddr *>(&peer), &peer_len) != 0)
215 return;
216 uint8_t token[4];
217 if (!random_bytes(token, sizeof(token)))
218 return;
219#ifdef ESPHOME_OTA_UDP_LWIP
220#if USE_NETWORK_IPV4
221 uint32_t ipv4;
222 if (socket::sockaddr_to_ipv4(reinterpret_cast<const struct sockaddr *>(&peer), &ipv4)) {
223 ip_addr_set_ip4_u32(&link.peer_ip, ipv4);
224 } else
225#endif
226 {
227#if USE_NETWORK_IPV6 && LWIP_IPV6
228 inet6_addr_to_ip6addr(ip_2_ip6(&link.peer_ip), &reinterpret_cast<const sockaddr_in6 *>(&peer)->sin6_addr);
229 IP_SET_TYPE_VAL(link.peer_ip, IPADDR_TYPE_V6);
230#else
231 return;
232#endif
233 }
234 UdpLock lock;
235#if LWIP_IPV6
236 link.pcb = udp_new_ip_type(IPADDR_TYPE_ANY);
237#else
238 link.pcb = udp_new();
239#endif
240 // On failure the reply stays all zero and ~UdpLink removes the pcb
241 if (link.pcb == nullptr || udp_bind(link.pcb, IP_ANY_TYPE, this->port_) != ERR_OK)
242 return;
243 udp_recv(link.pcb, udp_recv_cb, &link);
244#else
245 link.peer = peer;
246 link.peer_len = peer_len;
247 // Same domain as the listener, so the peer address from getpeername fits
248 link.sock = socket::socket_ip(SOCK_DGRAM, IPPROTO_UDP);
249 struct sockaddr_storage local;
250 const socklen_t local_len =
251 socket::set_sockaddr_any(reinterpret_cast<struct sockaddr *>(&local), sizeof(local), this->port_);
252 if (link.sock == nullptr || local_len == 0 ||
253 link.sock->bind(reinterpret_cast<struct sockaddr *>(&local), local_len) != 0 ||
254 link.sock->setblocking(false) != 0)
255 return;
256#endif
257 // Below the error codes (0x80 and up) the client checks the first byte against, and never all zero
258 token[0] = (token[0] & 0x7F) | 0x01;
259 memcpy(link.reply, token, sizeof(token));
260}
261
263 // TCP now only carries a fallback byte; short read timeouts let the UDP link be checked in between
264 struct timeval tv{0, UDP_COMMIT_POLL_MS * 1000};
265 this->client_->setsockopt(SOL_SOCKET, SO_RCVTIMEO, &tv, sizeof(tv));
266 const uint32_t start = millis();
267 while (millis() - start < UDP_COMMIT_TIMEOUT) {
268 this->udp_poll_();
269 bool committed;
270 {
271 UdpLock lock;
272 committed = this->udp_->committed;
273 }
274 if (committed) {
275 // The client heard us over UDP, so TCP is done. Outside the lock: closing a socket waits on the tcpip thread
276 this->client_ = nullptr;
277 return true;
278 }
279 // A raw byte outside any Noise frame: the client heard nothing over UDP. Forging it only forces the ordinary
280 // TCP path, which dropping our datagrams forces anyway
281 uint8_t fallback;
282 const ssize_t read = this->client_->read(&fallback, 1);
283 if (read == 1) {
284 this->udp_->release();
285 this->udp_ = nullptr;
286 tv = {UDP_READ_WAIT_MS / 1000, 0};
287 this->client_->setsockopt(SOL_SOCKET, SO_RCVTIMEO, &tv, sizeof(tv));
288 return true;
289 }
290 if (read == 0) {
291 this->remote_closed_ = true;
292 return false;
293 }
294 if (!this->would_block_(errno))
295 return false;
296 App.feed_wdt();
297 }
298 return false;
299}
300
302 UdpLink &link = *this->udp_;
303 const uint32_t start = millis();
304 size_t got = 0;
305 for (;;) {
306 this->udp_poll_();
307 UdpSlot p;
308 {
309 UdpLock lock;
310 p = link.consumed != link.received ? link.queue[link.consumed % UDP_WINDOW] : nullptr;
311 }
312 if (p == nullptr) {
313 if (got != 0)
314 return got;
315 if (millis() - start >= UDP_READ_WAIT_MS)
316 break;
318 continue;
319 }
320 // The callback never touches the slot being read, so the copy runs without the lock
321 const uint16_t offset = UDP_HEADER_SIZE + link.read_offset;
322 const uint16_t n = slot_copy(p, buf + got, std::min<size_t>(len - got, slot_len(p) - offset), offset);
323 got += n;
324 link.read_offset += n;
325 if (UDP_HEADER_SIZE + link.read_offset >= slot_len(p)) {
326 UdpLock lock;
327 slot_free(p);
328 link.queue[link.consumed % UDP_WINDOW] = nullptr;
329 // A full window just opened: tell the client, which is holding back
330 const bool was_full = static_cast<uint16_t>(link.received - link.consumed) == UDP_WINDOW;
331 link.consumed++;
332 link.read_offset = 0;
333 if (was_full)
334 udp_send_ack(link, link.received - 1);
335 }
336 if (got == len)
337 return got;
338 }
339 errno = EWOULDBLOCK;
340 return -1;
341}
342
343bool ESPHomeOTAComponent::udp_send_(const uint8_t *data, size_t len) {
344 UdpLink &link = *this->udp_;
345 UdpLock lock;
346 if (link.out_len + len > UDP_OUT_SIZE)
347 return false;
348 memcpy(link.out + link.out_len, data, len);
349 link.out_len += len;
350 // Prompted by nothing new, so the client takes no round trip sample from it
351 udp_send_ack(link, link.received - 1);
352 return true;
353}
354
356 if (this->udp_ == nullptr)
357 return;
358 const uint32_t start = millis();
359 while (millis() - start < UDP_LINGER_MS) {
360 this->udp_poll_();
361 {
362 UdpLock lock;
363 if (this->udp_->out_len == 0)
364 return;
365 }
367 }
368}
369
370} // namespace esphome
371#endif // USE_OTA && ESPHOME_OTA_UDP
void feed_wdt()
Feed the task watchdog.
bool would_block_(int error_code) const
bool udp_send_(const uint8_t *data, size_t len)
static void udp_recv_cb(void *arg, struct udp_pcb *pcb, struct pbuf *p, const ip_addr_t *addr, uint16_t port)
ssize_t udp_read_(uint8_t *buf, size_t len)
static constexpr uint8_t UDP_WINDOW
Definition ota_esphome.h:92
static void udp_on_datagram(UdpLink &link, UdpSlot p, uint16_t port)
static constexpr size_t UDP_OUT_SIZE
Definition ota_esphome.h:90
std::unique_ptr< socket::Socket > client_
static void udp_send_ack(UdpLink &link, uint16_t prompted_by)
Helper class to lock the lwIP TCPIP core when making lwIP API calls from non-TCPIP threads.
Definition helpers.h:2276
uint32_t socklen_t
Definition headers.h:109
__int64 ssize_t
Definition httplib.h:178
@ IPADDR_TYPE_V6
Definition ip_address.h:32
ESPHOME_LOG_TAG(TAG, CRASH_LOG_TAG)
std::unique_ptr< Socket > socket_ip(int type, int protocol)
Create a socket in the newest available IP domain (IPv6 or IPv4) of the given type and protocol.
bool sockaddr_to_ipv4(const struct sockaddr *addr, uint32_t *out)
Network order IPv4 of an AF_INET or v4 mapped AF_INET6 peer; false for anything else.
socklen_t set_sockaddr_any(struct sockaddr *addr, socklen_t addrlen, uint16_t port)
Set a sockaddr to the any address and specified port for the IP version used by socket_ip().
bool random_bytes(uint8_t *data, size_t len)
Generate len random bytes using the platform's secure RNG (hardware RNG or OS CSPRNG).
Definition helpers.cpp:20
const void size_t len
Definition hal.h:68
LwIPLock UdpLock
constexpr uint8_t * put_be16(uint8_t *dst, uint16_t value)
Write the low 16, 24 or 32 bits of value to dst, most significant byte first (be) or least significan...
Definition helpers.h:1112
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
uint32_t IRAM_ATTR HOT millis()
Definition hal.cpp:25
Application App
Global storage of Application pointer - only one Application can exist.
static void uint32_t
struct in6_addr sin6_addr
Definition headers.h:89
sa_family_t ss_family
Definition headers.h:104
uint16_t seq
uint8_t ack
SemaphoreHandle_t lock