ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
pl2303.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)
3#include "usb_uart.h"
4#include "usb/usb_host.h"
6#include "esphome/core/log.h"
7#include <cinttypes>
8
9namespace esphome::usb_uart {
10
11// Control request types
12static constexpr uint8_t SET_LINE_REQUEST_TYPE = 0x21;
13static constexpr uint8_t SET_LINE_REQUEST = 0x20;
14
15static constexpr uint8_t SET_CONTROL_REQUEST_TYPE = 0x21;
16static constexpr uint8_t SET_CONTROL_REQUEST = 0x22;
17static constexpr uint8_t CONTROL_DTR = 0x01;
18static constexpr uint8_t CONTROL_RTS = 0x02;
19
20static constexpr uint8_t VENDOR_WRITE_REQUEST_TYPE = 0x40;
21static constexpr uint8_t VENDOR_WRITE_REQUEST = 0x01;
22
23static constexpr uint8_t VENDOR_READ_REQUEST_TYPE = 0xc0;
24static constexpr uint8_t VENDOR_READ_REQUEST = 0x01;
25
26// HXN takes its own vendor requests and reads a register at its plain address. The other
27// chips read it at the address with bit 7 set.
28static constexpr uint8_t VENDOR_WRITE_NREQUEST = 0x80;
29static constexpr uint8_t VENDOR_READ_NREQUEST = 0x81;
30static constexpr uint16_t VENDOR_READ_REG_FLAG = 0x80;
31
32static constexpr uint8_t FLOWCTRL_REG = 0x00;
33static constexpr uint8_t FLOWCTRL_MASK = 0xf0;
34static constexpr uint8_t FLOWCTRL_NONE = 0x00;
35static constexpr uint8_t FLOWCTRL_RTS_CTS_LEGACY = 0x40;
36static constexpr uint8_t FLOWCTRL_RTS_CTS = 0x60;
37static constexpr uint8_t FLOWCTRL_XON_XOFF = 0xc0;
38
39static constexpr uint8_t HXN_FLOWCTRL_REG = 0x0a;
40static constexpr uint8_t HXN_FLOWCTRL_MASK = 0x1c;
41static constexpr uint8_t HXN_FLOWCTRL_NONE = 0x1c;
42static constexpr uint8_t HXN_FLOWCTRL_RTS_CTS = 0x18;
43static constexpr uint8_t HXN_FLOWCTRL_XON_XOFF = 0x0c;
44
45// Supported standard baud rates for direct encoding (TYPE_H, TYPE_HX, TYPE_HXD, TYPE_HXN)
46static const uint32_t SUPPORTED_BAUD_RATES[] = {
47 75, 150, 300, 600, 1200, 1800, 2400, 3600, 4800, 7200, 9600, 14400, 19200,
48 28800, 38400, 57600, 115200, 230400, 460800, 614400, 921600, 1228800, 2457600, 3000000, 6000000,
49};
50
51static const char *pl2303_type_name(Pl2303ChipType type) {
52 switch (type) {
53 case PL2303_TYPE_H:
54 return "H (legacy)";
55 case PL2303_TYPE_HX:
56 return "HX";
57 case PL2303_TYPE_TA:
58 return "TA";
59 case PL2303_TYPE_TB:
60 return "TB";
61 case PL2303_TYPE_HXD:
62 return "HXD";
63 case PL2303_TYPE_HXN:
64 return "G/HXN (newer)";
65 default:
66 return "unknown";
67 }
68}
69
70// The flow control register bits for the mode on each chip type
71static uint8_t pl2303_flow_control_bits(Pl2303ChipType type, uart::UARTFlowControl flow_control) {
72 if (type == PL2303_TYPE_HXN) {
73 switch (flow_control) {
75 return HXN_FLOWCTRL_RTS_CTS;
77 return HXN_FLOWCTRL_XON_XOFF;
78 default:
79 return HXN_FLOWCTRL_NONE;
80 }
81 }
82 switch (flow_control) {
84 return type == PL2303_TYPE_H ? FLOWCTRL_RTS_CTS_LEGACY : FLOWCTRL_RTS_CTS;
86 // The legacy chip has no automatic XON/XOFF
87 return type == PL2303_TYPE_H ? FLOWCTRL_NONE : FLOWCTRL_XON_XOFF;
88 default:
89 return FLOWCTRL_NONE;
90 }
91}
92
93// Find nearest supported baud rate for direct encoding
94static uint32_t nearest_supported_baud(uint32_t baud) {
95 size_t n = sizeof(SUPPORTED_BAUD_RATES) / sizeof(SUPPORTED_BAUD_RATES[0]);
96 for (size_t i = 0; i < n; i++) {
97 if (SUPPORTED_BAUD_RATES[i] > baud) {
98 if (i == 0)
99 return SUPPORTED_BAUD_RATES[0];
100 uint32_t lower = SUPPORTED_BAUD_RATES[i - 1];
101 uint32_t upper = SUPPORTED_BAUD_RATES[i];
102 return (upper - baud) > (baud - lower) ? lower : upper;
103 }
104 }
105 return SUPPORTED_BAUD_RATES[n - 1];
106}
107
108// Divisor encoding for TYPE_HX, TYPE_HXD: baudrate = 12M*32 / (mantissa * 4^exponent)
109static void encode_baud_divisor(uint8_t buf[4], uint32_t baud) {
110 static constexpr uint32_t BASELINE = 12000000 * 32;
111 uint32_t mantissa = BASELINE / baud;
112 if (mantissa == 0)
113 mantissa = 1;
114 uint8_t exponent = 0;
115 while (mantissa >= 512) {
116 if (exponent < 7) {
117 mantissa >>= 2;
118 exponent++;
119 } else {
120 mantissa = 511;
121 break;
122 }
123 }
124 buf[3] = 0x80;
125 buf[2] = 0;
126 buf[1] = (exponent << 1) | (mantissa >> 8);
127 buf[0] = mantissa & 0xFF;
128}
129
130// Alt divisor encoding for TYPE_TA, TYPE_TB: baudrate = 12M*32 / (mantissa * 2^exponent)
131static void encode_baud_divisor_alt(uint8_t buf[4], uint32_t baud) {
132 static constexpr uint32_t BASELINE = 12000000 * 32;
133 uint32_t mantissa = BASELINE / baud;
134 if (mantissa == 0)
135 mantissa = 1;
136 uint8_t exponent = 0;
137 while (mantissa >= 2048) {
138 if (exponent < 15) {
139 mantissa >>= 1;
140 exponent++;
141 } else {
142 mantissa = 2047;
143 break;
144 }
145 }
146 buf[3] = 0x80;
147 buf[2] = exponent & 0x01;
148 buf[1] = ((exponent & ~0x01) << 4) | (mantissa >> 8);
149 buf[0] = mantissa & 0xFF;
150}
151
152std::vector<CdcEps> USBUartTypePL2303::parse_descriptors(usb_device_handle_t dev_hdl) {
153 const usb_config_desc_t *config_desc;
154 const usb_device_desc_t *device_desc;
155 std::vector<CdcEps> cdc_devs{};
156
157 if (usb_host_get_device_descriptor(dev_hdl, &device_desc) != ESP_OK) {
158 ESP_LOGE(TAG, "PL2303: get_device_descriptor failed");
159 return {};
160 }
161 if (usb_host_get_active_config_descriptor(dev_hdl, &config_desc) != ESP_OK) {
162 ESP_LOGE(TAG, "PL2303: get_active_config_descriptor failed");
163 return {};
164 }
165
166 // Detect chip type from USB descriptor fields (mirrors pl2303_detect_type in Linux driver)
167 uint16_t bcd_device = device_desc->bcdDevice;
168 uint16_t bcd_usb = device_desc->bcdUSB;
169 uint8_t bmax_packet = device_desc->bMaxPacketSize0;
170 uint8_t bdev_class = device_desc->bDeviceClass;
171
172 if (bdev_class == 0x02 || bmax_packet != 0x40) {
174 } else {
175 switch (bcd_usb) {
176 case 0x0101:
177 case 0x0110:
178 this->chip_type_ = (bcd_device == 0x0400) ? PL2303_TYPE_HXD : PL2303_TYPE_HX;
179 break;
180 default:
181 // TA and TB are distinguishable by bcdDevice without any USB probe.
182 if (bcd_device == 0x0300) {
184 } else if (bcd_device == 0x0500) {
186 } else {
188 }
189 break;
190 }
191 }
192
193 ESP_LOGI(TAG, "PL2303 chip type: %s (bcdUSB=0x%04X bcdDevice=0x%04X bMaxPkt=%u)", pl2303_type_name(this->chip_type_),
194 bcd_usb, bcd_device, bmax_packet);
195
196 // PL2303 is single-port: find first interface with 2 bulk endpoints
197 int conf_offset = 0;
198 for (uint8_t i = 0; i < config_desc->bNumInterfaces; i++) {
199 int ep_offset = conf_offset;
200 const auto *intf = usb_parse_interface_descriptor(config_desc, i, 0, &conf_offset);
201 if (!intf)
202 break;
203 if (intf->bNumEndpoints < 2)
204 continue;
205
206 const usb_ep_desc_t *in_ep = nullptr;
207 const usb_ep_desc_t *out_ep = nullptr;
208 const usb_ep_desc_t *notify_ep = nullptr;
209
210 for (uint8_t e = 0; e < intf->bNumEndpoints; e++) {
211 ep_offset = conf_offset;
212 const auto *ep = usb_parse_endpoint_descriptor_by_index(intf, e, config_desc->wTotalLength, &ep_offset);
213 if (!ep)
214 break;
215 if (ep->bmAttributes == USB_BM_ATTRIBUTES_XFER_BULK) {
216 if (ep->bEndpointAddress & usb_host::USB_DIR_IN) {
217 in_ep = ep;
218 } else {
219 out_ep = ep;
220 }
221 } else if (ep->bmAttributes == USB_BM_ATTRIBUTES_XFER_INT) {
222 notify_ep = ep;
223 }
224 }
225
226 if (in_ep && out_ep) {
227 CdcEps eps{notify_ep, in_ep, out_ep, intf->bInterfaceNumber, intf->bInterfaceNumber};
228 eps.bulk_interface_class = intf->bInterfaceClass;
229 eps.interrupt_interface_class = intf->bInterfaceClass;
230 cdc_devs.push_back(eps);
231 break; // PL2303 is single-port
232 }
233 }
234
235 if (cdc_devs.empty()) {
236 ESP_LOGE(TAG, "PL2303: failed to find bulk IN+OUT endpoints");
237 }
238
239 return cdc_devs;
240}
241
242// Vendor init sequence for non-HXN chips (mirrors pl2303_startup in the Linux driver):
243// read 0x8484, write 0x0404=0, read 0x8484, read 0x8383, read 0x8484, write 0x0404=1,
244// read 0x8484, read 0x8383, write 0=1, write 1=0, write 2=0x24 (legacy) or 0x44 (HX+).
245// The final entry's wIndex is patched at runtime depending on the chip type.
246struct Pl2303InitStep {
247 uint8_t type;
248 uint8_t request;
249 uint16_t value;
250 uint16_t index;
251 bool read; // reads need a 1-byte buffer to set wLength=1 so the IN data stage runs
252};
253static const Pl2303InitStep PL2303_INIT[] = {
254 {VENDOR_READ_REQUEST_TYPE, VENDOR_READ_REQUEST, 0x8484, 0, true},
255 {VENDOR_WRITE_REQUEST_TYPE, VENDOR_WRITE_REQUEST, 0x0404, 0, false},
256 {VENDOR_READ_REQUEST_TYPE, VENDOR_READ_REQUEST, 0x8484, 0, true},
257 {VENDOR_READ_REQUEST_TYPE, VENDOR_READ_REQUEST, 0x8383, 0, true},
258 {VENDOR_READ_REQUEST_TYPE, VENDOR_READ_REQUEST, 0x8484, 0, true},
259 {VENDOR_WRITE_REQUEST_TYPE, VENDOR_WRITE_REQUEST, 0x0404, 1, false},
260 {VENDOR_READ_REQUEST_TYPE, VENDOR_READ_REQUEST, 0x8484, 0, true},
261 {VENDOR_READ_REQUEST_TYPE, VENDOR_READ_REQUEST, 0x8383, 0, true},
262 {VENDOR_WRITE_REQUEST_TYPE, VENDOR_WRITE_REQUEST, 0, 1, false},
263 {VENDOR_WRITE_REQUEST_TYPE, VENDOR_WRITE_REQUEST, 1, 0, false},
264 {VENDOR_WRITE_REQUEST_TYPE, VENDOR_WRITE_REQUEST, 2, 0, false},
265};
266static constexpr uint8_t PL2303_INIT_COUNT = sizeof(PL2303_INIT) / sizeof(PL2303_INIT[0]);
267
268bool USBUartTypePL2303::config_step(USBUartChannelBase *channel, uint8_t step, bool reload, bool ok,
269 const uint8_t *response) {
270 bool is_legacy = (this->chip_type_ == PL2303_TYPE_H);
271 bool is_hxn = (this->chip_type_ == PL2303_TYPE_HXN);
272
273 // Vendor init burst runs only on full init for non-HXN chips.
274 uint8_t init_count = (!reload && !is_hxn) ? PL2303_INIT_COUNT : 0;
275 if (step < init_count) {
276 const auto &e = PL2303_INIT[step];
277 uint16_t index = (step == PL2303_INIT_COUNT - 1) ? (is_legacy ? 0x24 : 0x44) : e.index;
278 this->config_transfer_(e.type, e.request, e.value, index,
279 e.read ? std::vector<uint8_t>{0} : std::vector<uint8_t>{});
280 return true;
281 }
282 step -= init_count;
283
284 uint16_t iface = channel->cdc_dev_.bulk_interface_number;
285 switch (step) {
286 case 0: {
287 // Build 7-byte line coding structure:
288 // [0-3] baud rate (LE32), [4] stop bits, [5] parity, [6] data bits
289 uint8_t line_coding[7] = {};
290 uint32_t baud = channel->get_baud_rate();
291
292 // Choose baud encoding based on chip type
293 uint32_t nearest = nearest_supported_baud(baud);
294 if (baud == nearest || this->chip_type_ == PL2303_TYPE_HXN) {
295 put_le32(line_coding, baud);
296 } else if (this->chip_type_ == PL2303_TYPE_TA || this->chip_type_ == PL2303_TYPE_TB) {
297 encode_baud_divisor_alt(line_coding, baud);
298 } else {
299 encode_baud_divisor(line_coding, baud);
300 }
301
302 line_coding[4] = static_cast<uint8_t>(channel->line_stop_bits_());
303
304 line_coding[5] = static_cast<uint8_t>(channel->line_parity_());
305
306 // Data bits
307 line_coding[6] = channel->get_data_bits();
308
309 ESP_LOGD(TAG, "PL2303: SET_LINE_REQUEST baud=%" PRIu32 " stop=%u parity=%u data=%u", baud, line_coding[4],
310 line_coding[5], line_coding[6]);
311
312 std::vector<uint8_t> lc_vec(line_coding, line_coding + 7);
313 this->config_transfer_(SET_LINE_REQUEST_TYPE, SET_LINE_REQUEST, 0, iface, lc_vec);
314 return true;
315 }
316 case 1:
317 // Read the flow control register, re-applied on every settings change. A short reply fails
318 // the step, so no write follows.
319 this->config_transfer_(VENDOR_READ_REQUEST_TYPE, is_hxn ? VENDOR_READ_NREQUEST : VENDOR_READ_REQUEST,
320 is_hxn ? HXN_FLOWCTRL_REG : (FLOWCTRL_REG | VENDOR_READ_REG_FLAG), 0,
321 std::vector<uint8_t>(1), this->cfg_response_);
322 return true;
323 case 2: {
324 // Write it back with only the flow control bits changed
325 const uint8_t reg = is_hxn ? HXN_FLOWCTRL_REG : FLOWCTRL_REG;
326 const uint8_t mask = is_hxn ? HXN_FLOWCTRL_MASK : FLOWCTRL_MASK;
327 const uint8_t new_byte =
328 (response[0] & ~mask) | pl2303_flow_control_bits(this->chip_type_, channel->flow_control_);
329 ESP_LOGD(TAG, "PL2303: flow control register 0x%02X: 0x%02X -> 0x%02X", reg, response[0], new_byte);
330 this->config_transfer_(VENDOR_WRITE_REQUEST_TYPE, is_hxn ? VENDOR_WRITE_NREQUEST : VENDOR_WRITE_REQUEST, reg,
331 new_byte);
332 return true;
333 }
334 case 3:
335 // Assert DTR + RTS (init only)
336 if (reload)
337 return false;
338 this->modem_control_transfer(channel);
339 return true;
340 default:
341 return false;
342 }
343}
344
346 const uint16_t value = (channel->dtr_ ? CONTROL_DTR : 0) | (channel->rts_ ? CONTROL_RTS : 0);
347 ESP_LOGD(TAG, "PL2303: SET_CONTROL_REQUEST DTR=%s RTS=%s", ONOFF(channel->dtr_), ONOFF(channel->rts_));
348 this->config_transfer_(SET_CONTROL_REQUEST_TYPE, SET_CONTROL_REQUEST, value, channel->cdc_dev_.bulk_interface_number);
349}
350
351} // namespace esphome::usb_uart
352#endif // USE_ESP32_VARIANT_ESP32P4 || USE_ESP32_VARIANT_ESP32S2 || USE_ESP32_VARIANT_ESP32S3 ||
353 // USE_ESP32_VARIANT_ESP32S31 || USE_ESP32_VARIANT_ESP32H4
LineStopBits line_stop_bits_() const
Definition usb_uart.cpp:709
void config_transfer_(uint8_t type, uint8_t request, uint16_t value, uint16_t index, const std::vector< uint8_t > &data={}, uint8_t *dest=nullptr)
Definition usb_uart.cpp:569
std::vector< CdcEps > parse_descriptors(usb_device_handle_t dev_hdl) override
Definition pl2303.cpp:152
bool config_step(USBUartChannelBase *channel, uint8_t step, bool reload, bool ok, const uint8_t *response) override
Definition pl2303.cpp:268
void modem_control_transfer(USBUartChannelBase *channel) override
Definition pl2303.cpp:345
uint8_t type
uint32_t value
Definition hal.cpp:41
constexpr uint8_t * put_le32(uint8_t *dst, uint32_t value)
Definition helpers.h:1135
static void uint32_t