Skip to content

ESP32-S2 USB-OTG read-flash: 4096-byte read stalls, 4095-byte read succeeds (esptool 5.3.1) (ESPTOOL-1424) #1205

Open

Description

@NGL3324

Problem Description

On an Adafruit ESP32-S2 Reverse TFT Feather using native USB-OTG, read-flash repeatedly stalls for a particular 4096-byte sector. Reading 4095 bytes from exactly the same address, using the same running helper, succeeds in 0.1 s. Full-flash backups therefore fail. The affected sectors can be read through the slower --no-stub command path. Expected: both read lengths should return their original flash bytes successfully.

Cause

Unconfirmed hypothesis: a USB-OTG transfer-completion problem at exact 64-byte packet multiples. At 0x7b000, the 4096-byte data has 58 bytes 0xC0 and 4 bytes 0xDB, so its SLIP frame length is 4096+58+4+2=4160=65*64. Removing one byte avoids the stall. The legacy helper also fails at a sector giving 4160 bytes after its separately flushed opening delimiter.

Operating System

Microsoft Windows; Command Prompt reports version 10.0.26300.9974.

Esptool Version

5.3.1, bundled Windows executable from Arduino-ESP32 3.3.12. Latest master branch: NOT YET TESTED on this hardware.

Chip Description

ESP32-S2FNR2 revision v0.0; embedded flash 4 MB, embedded PSRAM 2 MB; 40 MHz crystal; native USB-OTG.

Hardware Description

Adafruit ESP32-S2 Reverse TFT Feather with an external power-measurement module connected over I²C. TinyUF2 4 MB No OTA partition scheme. Known-good USB data cable connected directly to the computer. Board manually entered ROM download mode using BOOT/D0+Reset; other serial monitors closed. The esptool reproduction occurs with the application not running.

How is Esptool Run

Windows Command Prompt, invoking Arduino-ESP32 package esptool.exe directly; not an IDE flash operation. Bundled Python runtime version unknown.

Command and Output

Start from manual ROM download mode. esptool.exe below is the bundled 5.3.1 executable. Use uppercase COM7 on this machine (USB-OTG is correctly identified).

esptool.exe --chip esp32s2 --port COM7 --baud 115200 --before no-reset --after no-reset --stub-version 2 read-flash 0x7b000 0x1000 helper2_4096.bin

esptool v5.3.1
Serial port COM7:
Connected to ESP32-S2 on COM7:
Chip type: ESP32-S2FNR2 (revision v0.0)
USB mode: USB-OTG
Uploading stub flasher...
Running stub flasher...
Stub flasher running.
Configuring flash size...
Staying in bootloader.
A fatal error occurred: No more data to read from the serial port.

Next, same address and same running helper, one byte less:

esptool.exe --chip esp32s2 --port COM7 --baud 115200 --before no-reset --after no-reset --stub-version 2 read-flash 0x7b000 0xfff helper2_4095.bin

esptool v5.3.1
Serial port COM7:
Connected to ESP32-S2 on COM7:
Stub flasher is already running. No upload is necessary.
Configuring flash size...
Reading from 0x0007bfff [...] 100.0% 4095/4095 bytes...
Read 4095 bytes from 0x0007b000 in 0.1 seconds (424.2 kbit/s).
Staying in bootloader.

Observed_output_sanitized (for MAC etc) attached below.

More Information

Possibly related: #823. Its closing comment could not reproduce the helper-enabled stalls and invited an updated issue. Both current failure addresses here are below 512 KiB, unlike the separate >2MB ROM-read error discussed there.

Possibly related: espressif/esp-flasher-stub#90, see comment below.

ESP32_S2_diagnostic_evidence.zip

check_samples.py
observed_output_sanitized.txt
sample_analysis.json
SHA256SUMS.txt
verified_transfer_sanitized.txt

Additional observations:

  • Helper2 full read from 0 stops before sector 0x7b000 (503808 bytes received).
  • Helper2 read 64 KiB from 0x78000 stops at the same sector, after 12288 bytes.
  • Slow read of that 64 KiB succeeds in 46.0 s; helper1 reads it in 0.4 s. Those two complete files match byte-for-byte (SHA256 d2812c57487d60247ec4d1cf416308396b60d118c91aec5b3ad45956ade7fc64).
  • Helper1 full reads stop before 0x39000, after 233472 bytes, at both 460800 and 115200.
  • A slow 4096-byte read at 0x39000 succeeds in 3.2 s. That sector has 42 bytes 0xC0 and 21 bytes 0xDB. Its encoded data plus closing delimiter is 4096+42+21+1=4160 bytes after the legacy helper separately flushes its opening delimiter.
  • A later --no-stub attempt while helper2 was still running failed with SPI configuration/bad data length. It is NOT counted as a successful flash read; the attached slow-reference sector came from an earlier successful run.

Attachment: two actual 4 KiB flash-sector samples, hashes/counts, an offline checker and sanitized observed output. No full-flash image or NVS storage is included. The successful 4095-byte output has not yet been independently compared against the slow-reference prefix. The exact original flash data matters for this reproduction; uploading new firmware changes it.

On the same board, a custom running-firmware USB protocol successfully retrieved the entire 983,040-byte logging partition in separately requested ranges of at most 4 KiB. Each range was checked for offsets, length and CRC. The completed area's CRC was checked, the computer file was synced/read back, and a second independent full-area download matched the saved archive byte-for-byte. No retry messages appeared during either pass in the supplied console output.

This was the logging partition at 0x310000..0x3fffff, not the application sectors at 0x39000 and 0x7b000 used in the failing esptool reproduction. It used the running firmware's flash-read API and USB application stack, rather than the esptool helper read path. It is therefore a successful workaround for this device's data-backup task, not proof that esptool can now read the failing addresses or that a specific USB termination defect has been fixed.

Potentially related: espressif/esp-flasher-stub#90 and its fix espressif/esp-stub-lib#121. Our failing sector produces a SLIP frame of exactly 4160 bytes (65 × 64); requesting 4095 rather than 4096 raw bytes succeeds. This appears consistent with the full-packet USB termination problem addressed by #121. We have not yet verified whether the helper bundled with our esptool 5.3.1 contains that fix or tested a current build containing it. Issue #1202 references the same earlier fix, but concerns different hardware (ESP32-S31).

observed_output_sanitized.txt

I Have Read the Troubleshooting Guide

  • I confirm I have read the troubleshooting guide.

Activity

  1. changed the title [-]ESP32-S2 USB-OTG read-flash: 4096-byte read stalls, 4095-byte read succeeds (esptool 5.3.1)[/-] [+]ESP32-S2 USB-OTG read-flash: 4096-byte read stalls, 4095-byte read succeeds (esptool 5.3.1) (ESPTOOL-1424)[/+] on Nov 18, 2026
  2. github-actions commented on Nov 18, 2026

    @github-actions

    Hi @NGL3324! 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 do not contain enough information to confirm the root cause or say whether a fix is present in your esptool build. They don't mention esp-flasher-stub#90 or esp-stub-lib#121, so I can't verify that they apply here.

    What the sources do support

    • USB-OTG packet size: On the ESP32-S2, USB-OTG Full Speed bulk transfers have a maximum packet size of 64 bytes. [USB-OTG Peripheral] This is consistent with your observation that a 4160-byte frame is exactly 65 × 64 bytes. The sources don't say how the stub handles a frame that ends on a packet boundary, so the zero-length-packet hypothesis is unconfirmed.
    • How the stub reads flash: The stub's READ_FLASH sends raw SLIP packets and expects a 4-byte acknowledgement after each one. After the last packet it sends a 16-byte MD5 digest. [Reading Flash] The host side in loader.py follows this flow, using a 3 s timeout per read. A stalled packet would therefore surface as a read error such as "No more data to read from the serial port". [loader.py]
    • Workaround: --no-stub makes the ROM loader handle the operation. It is slower, but you report that it works. [Flasher Stub] The docs also say the read-flash command with --no-stub may need --flash-size set. [read-flash]

    Suggested next steps

    1. Run --no-stub from a fresh ROM download mode, without the helper already running. Your later attempt failed because the stub was still active. Add --flash-size if needed.
    2. Test the latest esptool master or release, which would bundle a newer stub.
    3. Report stub-side behavior in the esp-flasher-stub issue tracker. The docs direct stub problems there, and esptool integration problems to the esptool tracker. [Flasher Stub]

    The maintainers will need to confirm whether the stub bundled with 5.3.1 includes the fix you mention.

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

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions