Repository navigation
Description
Motivation
Connecting to an ESP32-C6 through its native USB Serial/JTAG port fails when the USB device is shared over the network with USB-over-IP passthrough. I tested VirtualHere (client 6.0.3 on macOS, Linux server over Wi-Fi) and SEH utnserver Pro (fw 20.2.8, UTN Manager 4.0.11, wired LAN). Stock esptool 5.4.0 stops at Connecting.........
The ROM answers each SYNC with eight identical replies, and ESPLoader.sync() expects all of them. Over passthrough on macOS, Apple's CDC-ACM driver keeps only one 64-byte bulk IN request outstanding, so most replies are gone before the next request is queued. With VirtualHere, exactly 2 of 8 replies arrived in 100/100 attempts. With SEH, 22 and 58 of 100 bursts were complete in two runs.
Goal
Let esptool connect to, and flash, an ESP32-C6 on native USB Serial/JTAG that is shared through USB-over-IP passthrough, without changing the default behavior for directly attached boards.
Alternatives and Other Information
I have a working patch against master (base 3b5d8091) and would like to agree on the shape before opening a pull request.
Proposed solution: an opt-in --remote-usb option. It requires an explicit --chip (not auto), and ESP32-C6 is the only chip I have tested. With it set, the loader:
- accepts the first complete, validated ROM
SYNCreply (direction, opcode, length, value0x20120707and status checked) and drains duplicates for a bounded 300 ms; - keeps partial SLIP state across read timeouts instead of discarding fragments;
- on POSIX ports, polls the existing non-blocking fd with
select()instead of changingport.timeoutper read (on macOS each timeout change re-applies the line settings, a full network round trip); - applies the same strictness to the stub hand-off and the
GET_SECURITY_INFOreply.
Without the option, nothing changes. The patch adds esptool/remote_usb.py, small changes to __init__.py and cmds.py, a docs paragraph in remote-serial-ports.rst, and host tests.
Questions for the maintainers:
- Is an opt-in flag the right shape, or would you prefer the tolerance as default behavior for
303a:1001devices? It costs about 0.1 s per connect on a directly attached board, so removing the option is easy. - Would a change limited to ESP32-C6 be acceptable, or should it be gated on other chips with native USB Serial/JTAG?
Results with the patch (macOS 26.7, Apple M1 Max, Python 3.14.7, pySerial 3.5, three ESP32-C6 boards):
- VirtualHere:
--remote-usbfullwrite-flashof a 1,657,424-byte image passes (40.7 s, hash verified);verify-flashpasses; 30/30 consecutivechip-idruns. - SEH UTN:
--remote-usbfullwrite-flashpasses (14.0 s, hash verified), and the board boots. - Local USB: default path and
--remote-usbboth passchip-id5/5 on two boards. - Full
test_esptool.pyhardware suite in USB-Serial/JTAG mode: 99 passed with no flag on local USB, 98 passed with--remote-usblocally. The failures over passthrough aretest_auto_detect(refused by design), device-to-host reads, and tests that reopen a port inside pytest on SEH.
Known limit: large device-to-host transfers. Through the VirtualHere macOS client, a 4 MB --remote-usb read-flash ran at about 10 KB/s and aborted at 26% with Remote USB packet timeout. Writes are fine, because the profile only fixes connecting and reply parsing.
Not tested: Windows and Linux hosts, and chips other than ESP32-C6.
Related: #1181 (transport detection when a virtualized port exposes no VID/PID, closed in September) is separate. This profile still requires a visible VID/PID.
Activity
github-actions commentedon Oct 7, 2026
Hi @Massimiliano-solutiontech! Please be aware that (1) the following suggestions are generated by a bot and haven't been fact-checked by Espressif Systems, (2) burning eFuses and enabling security features are irreversible operations and can damage your ESP32 device. We hope that this message will help you until an Espressif Engineer looks at your issue.
I'm sorry, but the knowledge sources provided do not contain enough information to give a definitive answer on behalf of the esptool maintainers regarding this feature request.
What I can confirm from the knowledge sources is relevant context:
Remote serial ports are already supported via RFC2217 and raw sockets, but with an explicit limitation: [Remote Serial Ports]
The VID/PID detection issue is a known limitation. When USB descriptors are unavailable (e.g., in containers or VMs), esptool cannot detect the interface type and falls back to the standard reset sequence. The recommended workaround is USB device passthrough rather than a forwarded serial port or network serial bridge. [Ports Without USB Descriptors]
Your proposed
--remote-usbflag is a different scenario from the existing RFC2217/socket remote port support — you're using USB-over-IP passthrough where the VID/PID (303a:1001) is visible to the client, but the CDC-ACM driver's buffering behavior causes SYNC reply loss. This is a nuanced transport-layer issue not addressed in the current documentation or known workarounds.My recommendation: Since this is a GitHub issue requesting maintainer feedback on a proposed patch, the best path forward is to engage directly with the esptool maintainers on the issue thread. You can also review the contributions guide for guidance on how to structure a pull request. The maintainers are the right people to answer your two specific questions about opt-in vs. default behavior and chip scope. [Contributions Guide]
[-]Opt-in --remote-usb profile for ESP32-C6 native USB over USB-over-IP passthrough[/-][+]Opt-in --remote-usb profile for ESP32-C6 native USB over USB-over-IP passthrough (ESPTOOL-1403)[/+]Dzarda7 commentedon Oct 7, 2026
Hi @Massimiliano-solutiontech, thanks for the report. I will try to take a look into this, although not sure if we will accept something like that, but will consider that. I have a bad news for you, in ROM, at least on existing chips there is an issue that the flush (the one that causes your issue that timeouts after few ms) happens also after each
0x0a, which meansread_regmight also fail but not sure.One suggestion I will give you, please take a look at https://github.com/espressif/esp-serial-flasher, it is C implementation of esptool (with some yet to be done features), but it is written in a way that you can pass data to it however you want. The solution in your case might be queuing more IN requests line Linux USB CDC driver does.
Can I ask you why you prefer USB over IP and not something explicitly supported like RFC2217 or TCP socket?