Skip to content

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

@zackees

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
    No fields configured for issues without a type.

    Projects

    Status
    Triage

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions