Skip to content

Opt-in --remote-usb profile for ESP32-C6 native USB over USB-over-IP passthrough (ESPTOOL-1403) #1196

Closed as not planned

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 SYNC reply (direction, opcode, length, value 0x20120707 and 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 changing port.timeout per 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_INFO reply.

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:

  1. Is an opt-in flag the right shape, or would you prefer the tolerance as default behavior for 303a:1001 devices? It costs about 0.1 s per connect on a directly attached board, so removing the option is easy.
  2. 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-usb full write-flash of a 1,657,424-byte image passes (40.7 s, hash verified); verify-flash passes; 30/30 consecutive chip-id runs.
  • SEH UTN: --remote-usb full write-flash passes (14.0 s, hash verified), and the board boots.
  • Local USB: default path and --remote-usb both pass chip-id 5/5 on two boards.
  • Full test_esptool.py hardware suite in USB-Serial/JTAG mode: 99 passed with no flag on local USB, 98 passed with --remote-usb locally. The failures over passthrough are test_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

  1. github-actions commented on Oct 7, 2026

    @github-actions

    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:

    1. Remote serial ports are already supported via RFC2217 and raw sockets, but with an explicit limitation: [Remote Serial Ports]

      USB-OTG and USB-Serial-JTAG are not supported when the esptool client uses a remote port (rfc2217://… or socket://…). Esptool distinguishes these native USB interfaces from UART bridges using the USB vendor and product ID of the local serial device. Remote URLs do not expose those IDs to the client, so esptool cannot apply behavior specific to USB-OTG or USB-Serial-JTAG.

    2. 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-usb flag 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]

  2. changed the title [-]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)[/+] on Oct 7, 2026
  3. Dzarda7 commented on Oct 7, 2026

    @Dzarda7
    Collaborator

    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 means read_reg might 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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions