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.
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:
uv pip show fbuild)COM22.build/pio/esp32s3A 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:
Observed output:
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 explicitfbuild daemon stopis run.This is also likely to affect
esptooland any other non-fbuild tool that opens the same COM port after an fbuild monitor session.Expected Behavior
After
fbuild monitorexits, including timeout exits, fbuild should close/release the serial handle for the monitored port. A subsequent pyserial or esptool open should succeed without requiringfbuild daemon stop.Acceptance Criteria
fbuild monitor ... --timeout Nreleases the COM port before returning on Windows.fbuild resetplusfbuild monitordoes not leave the daemon holding the serial port.fbuild daemon stopshould 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.