Skip to content

fix(monitor): release Windows COM port after monitor exits #531

Description

@zackees

Context

While validating FastLED issue FastLED/FastLED#2991 on Windows, the fbuild serial monitor path left the device COM port locked after the monitor command exited. This blocked follow-up tools that need to reopen the same port, such as pyserial-based JSON-RPC and esptool.

Environment observed:

  • OS: Windows
  • fbuild: 2.2.22 (uv pip show fbuild)
  • Device: ESP32-S3 on COM22
  • Project: staged FastLED AutoResearch project under .build/pio/esp32s3

A skip-build deploy by itself did not reproduce the problem; the monitor/reset path did.

Reproduction

From the FastLED worktree, with an already-built staged ESP32-S3 AutoResearch project:

.venv\Scripts\fbuild.exe .build\pio\esp32s3 reset -e esp32s3 -p COM22
.venv\Scripts\fbuild.exe .build\pio\esp32s3 monitor -e esp32s3 -p COM22 --timeout 5 --no-timestamp
uv run python -c "import serial; p='COM22';\ntry:\n    serial.Serial(p,115200,timeout=0.1,write_timeout=1).close(); print('after_monitor_before_stop open ok')\nexcept Exception as e:\n    print('after_monitor_before_stop', type(e).__name__, e)"
.venv\Scripts\fbuild.exe daemon stop
uv run python -c "import serial; p='COM22';\ntry:\n    serial.Serial(p,115200,timeout=0.1,write_timeout=1).close(); print('after_daemon_stop open ok')\nexcept Exception as e:\n    print('after_daemon_stop', type(e).__name__, e)"

Observed output:

resetting esp32 device on COM22...
device reset successful
monitor completed (timeout)
after_monitor_before_stop SerialException could not open port 'COM22': PermissionError(13, 'Access is denied.', None, 5)
daemon stopped
after_daemon_stop open ok

Impact

FastLED AutoResearch often needs to hand the port from fbuild upload/monitoring to pyserial JSON-RPC immediately. If the daemon retains the serial handle after monitor timeout/exit, the next step fails with PermissionError(13, Access is denied) until an explicit fbuild daemon stop is run.

This is also likely to affect esptool and any other non-fbuild tool that opens the same COM port after an fbuild monitor session.

Expected Behavior

After fbuild monitor exits, including timeout exits, fbuild should close/release the serial handle for the monitored port. A subsequent pyserial or esptool open should succeed without requiring fbuild daemon stop.

Acceptance Criteria

  • fbuild monitor ... --timeout N releases the COM port before returning on Windows.
  • fbuild reset plus fbuild monitor does not leave the daemon holding the serial port.
  • A regression test or integration check covers monitor timeout/normal-exit cleanup if the test harness can mock or exercise serial handles.
  • fbuild daemon stop should not be required as a workaround between monitor and a pyserial/esptool client.

Related Issues

No strong duplicate found. The closest keyword match was #433, but that is Teensy deployer/monitor design work rather than this ESP32/Windows COM handle leak.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    Status
    Triage

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions