ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
usb_cdc_acm.cpp
Go to the documentation of this file.
1#if defined(USE_ESP32_VARIANT_ESP32P4) || defined(USE_ESP32_VARIANT_ESP32S2) || defined(USE_ESP32_VARIANT_ESP32S3) || \
2 defined(USE_ESP32_VARIANT_ESP32S31) || defined(USE_ESP32_VARIANT_ESP32H4) || defined(USE_ZEPHYR)
3#include "usb_cdc_acm.h"
5#include "esphome/core/hal.h"
7#include "esphome/core/log.h"
9
10ESPHOME_LOG_TAG(TAG, "usb_cdc_acm");
11
12// Global component instance for managing USB device
13USBCDCACMComponent *global_usb_cdc_component = nullptr; // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
14
15//==============================================================================
16// USBCDCACMInstance Implementation
17//==============================================================================
18
19// NOLINTBEGIN(clang-analyzer-unix.Malloc)
21 // Allocate event from pool
22 CDCEvent *event = this->event_pool_.allocate();
23 if (event == nullptr) {
24 ESP_LOGW(TAG, "Event pool exhausted, line state event dropped (itf=%d)", this->itf_);
25 return;
26 }
27
29 event->data.line_state.dtr = dtr;
30 event->data.line_state.rts = rts;
31
32 // Push always succeeds: pool is sized to queue capacity (SIZE-1), so if
33 // allocate() returned non-null, the queue cannot be full.
34 this->event_queue_.push(event);
36}
37
38void USBCDCACMInstance::queue_line_coding_event(uint32_t bit_rate, uint8_t stop_bits, uint8_t parity,
39 uint8_t data_bits) {
40 // Allocate event from pool
41 CDCEvent *event = this->event_pool_.allocate();
42 if (event == nullptr) {
43 ESP_LOGW(TAG, "Event pool exhausted, line coding event dropped (itf=%d)", this->itf_);
44 return;
45 }
46
48 event->data.line_coding.bit_rate = bit_rate;
49 event->data.line_coding.stop_bits = stop_bits;
50 event->data.line_coding.parity = parity;
51 event->data.line_coding.data_bits = data_bits;
52
53 // Push always succeeds: pool is sized to queue capacity (SIZE-1), so if
54 // allocate() returned non-null, the queue cannot be full.
55 this->event_queue_.push(event);
57}
58// NOLINTEND(clang-analyzer-unix.Malloc)
59
61 // Process all pending events from the queue
62 CDCEvent *event;
63 while ((event = this->event_queue_.pop()) != nullptr) {
64 switch (event->type) {
66 bool dtr = event->data.line_state.dtr;
67 bool rts = event->data.line_state.rts;
68
69 // Invoke user callback in main loop context
70 if (this->line_state_callback_ != nullptr) {
71 this->line_state_callback_(dtr, rts);
72 }
73 break;
74 }
76 uint32_t bit_rate = event->data.line_coding.bit_rate;
77 uint8_t stop_bits = event->data.line_coding.stop_bits;
78 uint8_t parity = event->data.line_coding.parity;
79 uint8_t data_bits = event->data.line_coding.data_bits;
80
81 // Update UART configuration based on CDC line coding
82 this->baud_rate_ = bit_rate;
83 this->data_bits_ = data_bits;
84
85 // Convert CDC stop bits to UART stop bits format
86 // CDC: 0=1 stop bit, 1=1.5 stop bits, 2=2 stop bits
87 this->stop_bits_ = (stop_bits == 0) ? 1 : (stop_bits == 1) ? 1 : 2;
88
89 // Convert CDC parity to UART parity format
90 // CDC: 0=None, 1=Odd, 2=Even, 3=Mark, 4=Space
91 switch (parity) {
92 case 0:
94 break;
95 case 1:
97 break;
98 case 2:
100 break;
101 default:
102 // Mark and Space parity are not commonly supported, default to None
104 break;
105 }
106
107 // Invoke user callback in main loop context
108 if (this->line_coding_callback_ != nullptr) {
109 this->line_coding_callback_(bit_rate, stop_bits, parity, data_bits);
110 }
111 break;
112 }
113 }
114 // Return event to pool for reuse
115 this->event_pool_.release(event);
116 }
117}
118
119bool USBCDCACMInstance::peek_byte(uint8_t *data) {
120 if (this->has_peek_) {
121 *data = this->peek_buffer_;
122 return true;
123 }
124
125 if (this->read_byte(&this->peek_buffer_)) {
126 *data = this->peek_buffer_;
127 this->has_peek_ = true;
128 return true;
129 }
130
131 return false;
132}
133
134bool USBCDCACMInstance::consume_peek_(uint8_t *&data, size_t &len) {
135 if (!this->has_peek_) {
136 return false;
137 }
138 // No debug callback here: peek_byte() read this byte through read_array(), which already reported it
139 *data++ = this->peek_buffer_;
140 this->has_peek_ = false;
141 return --len == 0;
142}
143
145 // During a sustained host stall the buffer stays full, so this runs for every write; throttle the
146 // warning. The total is never reset, so each line accounts for every byte dropped so far and the
147 // first drop since boot is logged unthrottled.
148 const bool first_drop = this->tx_dropped_bytes_ == 0;
149 this->tx_dropped_bytes_ += dropped;
150 const uint32_t now = millis();
151 if (first_drop || (now - this->tx_dropped_log_ms_) >= LOG_THROTTLE_MS) {
152 this->tx_dropped_log_ms_ = now;
153 ESP_LOGW(TAG, "USB TX itf=%d: buffer full, %zu bytes dropped total", this->itf_, this->tx_dropped_bytes_);
154 }
155}
156
157//==============================================================================
158// USBCDCACMComponent Implementation
159//==============================================================================
160
161USBCDCACMComponent::USBCDCACMComponent() { global_usb_cdc_component = this; }
162
164 // Setup all registered interfaces
165 for (auto *interface : this->interfaces_) {
166 if (interface != nullptr) {
167 interface->setup();
168 }
169 }
170}
171
173 // Call loop() on all registered interfaces to process events
174 for (auto *interface : this->interfaces_) {
175 if (interface != nullptr) {
176 interface->loop();
177 }
178 }
179}
180
182 ESP_LOGCONFIG(TAG,
183 "USB CDC-ACM:\n"
184 " Number of Interfaces: %d",
185 ESPHOME_MAX_USB_CDC_INSTANCES);
186 for (uint8_t i = 0; i < ESPHOME_MAX_USB_CDC_INSTANCES; ++i) {
187 if (this->interfaces_[i] != nullptr) {
188 this->interfaces_[i]->dump_config();
189 } else {
190 ESP_LOGCONFIG(TAG, " Interface %u is disabled", i);
191 }
192 }
193}
194
196 uint8_t itf_num = static_cast<uint8_t>(interface->get_itf());
197 if (itf_num < ESPHOME_MAX_USB_CDC_INSTANCES) {
198 this->interfaces_[itf_num] = interface;
199 } else {
200 ESP_LOGE(TAG, "Interface number must be less than %u", ESPHOME_MAX_USB_CDC_INSTANCES);
201 }
202}
203
205 for (auto *interface : this->interfaces_) {
206 if ((interface != nullptr) && (interface->get_itf() == itf)) {
207 return interface;
208 }
209 }
210 return nullptr;
211}
212
213} // namespace esphome::usb_cdc_acm
214#endif
void wake_loop_threadsafe()
Wake the main event loop from another thread or callback.
bool read_byte(uint8_t *data)
Main USB CDC ACM component that manages the USB device and all CDC interfaces.
void add_interface(USBCDCACMInstance *interface)
std::array< USBCDCACMInstance *, ESPHOME_MAX_USB_CDC_INSTANCES > interfaces_
USBCDCACMInstance * get_interface_by_number(uint8_t itf)
Represents a single CDC ACM interface instance.
Definition usb_cdc_acm.h:96
EventPool< CDCEvent, EVENT_QUEUE_SIZE - 1 > event_pool_
bool peek_byte(uint8_t *data) override
LockFreeQueue< CDCEvent, EVENT_QUEUE_SIZE > event_queue_
void queue_line_coding_event(uint32_t bit_rate, uint8_t stop_bits, uint8_t parity, uint8_t data_bits)
bool consume_peek_(uint8_t *&data, size_t &len)
void queue_line_state_event(bool dtr, bool rts)
ESPHOME_LOG_TAG(TAG, "usb_cdc_acm")
USBCDCACMComponent * global_usb_cdc_component
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.
static void uint32_t