tools: Add automatic PTY device detection for QEMU

Summary

Bothmpremote andpyboard.py can hang when connecting to PTY devices (QEMU serial output) due to PTYinWaiting() timing behavior. While the official test suite usually passes (short tests + timing workarounds mask the issue), long-running operations and heavy serial traffic expose intermittent hangs. This adds automatic PTY detection to both tools and uses blocking reads for PTY devices while maintaining non-blocking behavior for real serial devices.

Impact:

• Eliminates intermittent hangs in QEMU-based testing workflows
• Improves official test suite reliability (removes timing-dependent failures)
• Enables long-running QEMU tests without manual patches
• Consistent behavior across both serial communication tools

Problem

PTY (pseudo-terminal) devices used by QEMU don't reliably reportinWaiting() status. Since commit0d46e45a1 switched to non-blocking reads, mpremote can fail on PTY devices:

serial.serialutil.SerialException: device reports readiness to read but returned no data

Why it fails (when it does):

1. PTYinWaiting() behavior depends on timing - when it's called relative to when data arrives
2. mpremote waits forinWaiting() > 0 before reading
3. If the timing is unfavorable, the connection times out spinning in the polling loop

The timing-dependent nature:

• PTYinWaiting() behavior depends on OS scheduling and data arrival timing
• Sometimes data arrives fast enough that the polling loop catches it (tests pass)
• Sometimes the process scheduler is favorable (tests pass)
• Long-running operations increase probability of hitting the timing window whereinWaiting() returns 0 while data is actually buffered (tests fail)

Current workarounds:

• Users must manually patch mpremote/pyboard.py for reliable QEMU testing
• Timing delays (0.1s sleep, commit0950f65) reduce but don't eliminate failures

Why Official Tests Usually Pass

The official MicroPython test suite runs against QEMU (usingpyboard.py from line 369 oftests/run-tests.py) and generally passes in CI, despite this underlying PTY issue. Several factors mask the problem:

1. Short test duration: Most tests run <1s, limiting exposure to the timing window
2. Timing workaround: Commit0950f65 added a 0.1s sleep after PTY detection, reducing (but not eliminating) race conditions
3. Favorable conditions: Quick tests with minimal serial traffic often complete before hitting the timing issue
4. Dismissed failures: Occasional CI failures likely attributed to "QEMU flaky" rather than investigated

What exposes the bug reliably:

• Long-running operations: OpenMV's 180s test suite (81 sequential tests with image processing)
• Heavy serial traffic: Image data transfer, continuous operations
• Production workloads: Real-world usage patterns vs. minimal test cases

The fix eliminates the timing dependency entirely by using blocking reads (which pyserial handles correctly for PTYs) instead of pollinginWaiting().

Root Cause Technical Details

PTY devices (Unix98 pseudo-terminals at/dev/pts/N) have timing-dependent I/O behavior:

The race condition:

Time  | QEMU/Target        | mpremote (stock)------|-------------------|------------------T0    | Sends data        |T1    |                   | Calls inWaiting()T2    | Data buffered     | Returns 0 (race!)T3    |                   | sleep(0.01)T4    |                   | Calls inWaiting() again...   | (repeat)          | (spinning)

Stock mpremote code path:

whileTrue:ifdata.endswith(ending):breakelifself.serial.inWaiting()>0:# PTY: Timing-dependent!new_data=self.serial.read(1)# Process dataelse:time.sleep(0.01)# Can spin here if race condition hits

The code checksinWaiting() before reading, which is unreliable for PTY devices due to timing.

Solution

Auto-detect PTY devices and use appropriate read strategy:

• PTY devices: Blocking reads (timeout handled by pyserial)
• Serial devices: Non-blocking withinWaiting() check (unchanged)

Detection method:

1. Check device path:/dev/pts/[0-9]+ (Linux Unix98 PTY)
2. Verify character device with major number 136
3. Fall back to serial behavior if detection fails or errors

Addressing the Original Concern

The original commit0d46e45a1 introduced theinWaiting() check to solve a legitimate problem:

"If the target does not return any data thenread_until() will block indefinitely."

Our fix respects this concern by relying on pyserial's timeout mechanism:

1. interCharTimeout: 1 - Blocking reads return empty after 1 second if no data arrives
2. read_until() timeout checks - Function returns on timeout (default 10s)
3. No indefinite blocking - Even if target sends no data, reads will timeout

The difference is:

• Serial devices: Still use non-blocking reads withinWaiting() check (commit0d46e45 behavior preserved)
• PTY devices: Use blocking reads with pyserial timeout (avoidsinWaiting() timing issues)

Both approaches prevent indefinite blocking - the PTY path just uses the timeout mechanism that was already present in the code.

Patch benefits:

• ✅ Zero configuration required
• ✅ No breaking changes
• ✅ Graceful fallback on errors
• ✅ No performance impact on serial devices
• ✅ Preserves original fix for non-responsive targets

OpenMV Testing

The primary validation comes from OpenMV's production use case, which consistently exposed the issue:

Test environment:

• Firmware: OpenMV vision processing firmware on QEMU MPS2-AN500
• Test suite: 81 image processing tests
• Duration: ~180 seconds continuous operation
• Workload: Filesystem I/O, raw REPL, large data transfers, ML inference
• Serial traffic: Heavy (image data transfer)

Results:

• Without fix: Intermittent hangs requiring manual patch
• With fix: 81/81 tests passed (100%)

OpenMV has been maintaining a manual patch for this issue:tools/mpremote-qemu-serial.patch

This PR upstreams their fix with automatic detection, allowing them to remove the downstream patch.

Why Long-Running Tests Matter

The timing-dependent nature of this issue means:

• Short tests (<1s): Often pass due to favorable timing
• Long tests (>60s): Expose the race condition reliably

OpenMV's 180-second continuous workload provided the consistent reproduction needed to identify and fix the issue.

Compatibility

Safety guarantees:

• Detection failure → Falls back to current serial behavior
• os.major() missing → Falls back (Python 3.3+ has it)
• stat() errors → Falls back
• No code paths removed → Zero breaking changes

Performance

Serial devices: Zero performance impact - code path unchanged, still uses efficient non-blocking reads withinWaiting() checks.

PTY devices: Improved performance by eliminating 10ms sleep polling.

Platform Notes

Linux-specific: Current implementation detects Linux Unix98 PTY (major 136). Other platforms fall back to serial behavior.

Background

OpenMV (https://github.com/openmv/openmv) uses QEMU for CI/CD testing of their MicroPython-based vision firmware. They've maintained a manual patch to work around this issue. This PR upstreams their fix with automatic detection.

References

• MicroPython commit that triggered issue:0d46e45a1 (non-blocking read change)
• OpenMV manual patch:https://github.com/openmv/openmv/blob/master/tools/mpremote-qemu-serial.patch
• Unix98 PTY specification: POSIX pseudo-terminal interfaces
• pyserial inWaiting():https://pyserial.readthedocs.io/en/latest/pyserial_api.html#serial.Serial.inWaiting

Checklist

• Code follows MicroPython style guidelines
• Tested with OpenMV QEMU (real-world validation)
• No breaking changes
• Backward compatible (graceful fallback)
• Performance impact analyzed (zero for serial)
• Pre-commit hooks passed

TL;DR: mpremote and pyboard.py can hang intermittently on QEMU PTY devices due to timing-dependentinWaiting() behavior. While official tests usually pass (short duration + timing workarounds mask it), long-running operations expose the issue reliably. This adds automatic PTY detection (path + device major number) and uses blocking reads for PTY while keeping non-blocking behavior for real serial. Eliminates timing dependency. Fully backward compatible with graceful fallback. Validated with OpenMV's 180s continuous workload (81/81 tests passed).