tools/mpremote: Poll for friendly REPL prompt before raw mode entry.

[andrewleech]

Summary

Issue micropython#13504 has been open since 2023 and affects users primarily on macOS: mpremote fails with TransportError: could not enter raw repl on the first invocation after plugging in a device. The thread has accumulated a workaround (a 2-second sleep inside enter_raw_repl), confirmations across boards and Python versions, and a comment from @pavelrevak noting his mpytool does not hit it because of a different polling strategy.

The root cause is that opening the serial port toggles DTR/RTS on common USB-serial converters, which resets ESP32-class boards. enter_raw_repl then sends a single Ctrl-C, flushes input, sends Ctrl-A, and blocks waiting for the raw banner. If the device is still booting, the banner never arrives and the call times out. The time.sleep(2) workaround works only because the device finishes booting in that window.

This change replaces the single Ctrl-C + flush with _wait_for_friendly_prompt, which polls for \r\n>>> with a 0.2s interval, alternating Ctrl-C (interrupt program) and Ctrl-B (exit raw REPL, every third attempt). After four unsuccessful attempts it also sends the VFS-hook ACK byte (0x18) to unblock a fs_hook agent stuck on a host read. Once the friendly prompt is confirmed, Ctrl-A is sent and the existing banner-read logic runs unchanged. The prompt-confirmation phase is capped at min(3, timeout_overall), so existing callers see at most a small additional delay before the original failure mode is reported, and successful connections on already-responsive devices are not slowed.

Approach is modelled on the polling pattern in mpytool that @pavelrevak described in micropython#13504, adapted to mpremote's existing read_until and serial abstractions.

Testing

Not yet tested on hardware. The change needs to be validated against the macOS + ESP32 + CP2102/CP210x configuration that reproduces micropython#13504, and against a representative set of other ports (STM32, RP2, nRF) to confirm no regression in the fast path where devices respond to the first Ctrl-C. I'm planning to do this before this PR is ready for merge; flagging it now so the approach can be reviewed in parallel.

Trade-offs and Alternatives

The friendly-prompt phase adds up to 3 seconds of wall time on a device that never responds, before the same TransportError is raised. In practice this replaces the 10s banner-read timeout that previously fired in the same scenario, so the failure path is faster, not slower.

An alternative would be to keep the current code path and add time.sleep(2) as the issue thread suggests. That works around the macOS case but does not address devices stuck in raw REPL or with a stalled fs_hook agent, and it penalises every invocation rather than only the ones that need it.

Generative AI

I used generative AI tools when creating this PR, but a human has checked the code and is responsible for the description above.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.47%. Comparing base (1c63211) to head (74fa650).
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@           Coverage Diff           @@
##           master      #48   +/-   ##
=======================================
  Coverage   98.47%   98.47%           
=======================================
  Files         176      176           
  Lines       22845    22845           
=======================================
  Hits        22497    22497           
  Misses        348      348           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.