Skip to content

fix(esp32): surface ESP ROM download-mode lockup instead of silent timeout - #557

Merged
zackees merged 1 commit into
mainfrom
fix/esp32s3-download-mode-detect
Jun 13, 2026
Merged

zackees merged 1 commit into
mainfrom
fix/esp32s3-download-mode-detect

Conversation

@zackees

@zackees zackees commented Jun 13, 2026

Copy link
Copy Markdown
Member

Summary

Part of #532. When an ESP board is strapped into the serial ROM bootloader, it emits waiting for download / boot:0x.. DOWNLOAD(USB/UART) and never produces application output. The monitor loop already detected these strings (fbuild_serial::boot_mode) but only logged a warn! and kept waiting for the full timeout, then returned a bland monitor completed (timeout) success — so a board effectively bricked in ROM looked like a clean exit, and the host looked deadlocked (exactly the confusing failure mode #532 describes).

This halts the monitor on the first download-mode signal and returns a targeted MonitorOutcome::Error carrying the diagnostic. Both the standalone monitor and the post-deploy monitor now fail fast with an actionable message instead of silently timing out.

  • The waiting for download / DOWNLOAD(...) strap strings only appear when the chip is actually strapped into ROM download mode (they are absent from a normal app boot), so halting on them is safe — there is no application output to wait for.
  • The fix(monitor): release Windows COM port after monitor exits #531 port-release path runs on this exit (it executes before the outcome match), so no fbuild daemon stop is needed before a pyserial/esptool recovery client opens the port.

Acceptance criteria addressed (#532)

  • "If the board emits waiting for download, fbuild reports that exact boot-mode problem" — now returned as an Error outcome with the diagnostic.
  • "A failed or timed-out monitor/RPC operation does not require fbuild daemon stop" — port release already runs on the error exit.
  • Covered by regression tests for the monitor state machine.
  • DTR/RTS auto-recovery sequence — remains hardware-gated follow-up (needs an attached S3).

Test plan

  • soldr cargo test -p fbuild-daemon --lib monitor — 4 new tests + existing monitor tests green (13 passed)
  • soldr cargo clippy -p fbuild-daemon --all-targets -- -D warnings — clean (only the pre-existing repo-wide clippy.toml MSRV notice)
  • soldr rustfmt --check clean

New tests:

  • download_mode_line_halts_with_diagnostic
  • waiting_for_download_halts
  • normal_app_output_does_not_halt
  • halt_on_success_and_expect_still_work (guards no behavior regression for expect/halt patterns)

🤖 Generated with Claude Code

…meout

When an ESP board is strapped into the serial ROM bootloader, it emits
`waiting for download` / `boot:0x.. DOWNLOAD(USB/UART)` and never produces
application output. The monitor loop already detected these strings but
only logged a warning and kept waiting for the full timeout, then returned
a bland "monitor completed (timeout)" success — so a board effectively
stuck in ROM looked like a clean exit and the host looked deadlocked.

Halt the monitor immediately on the first download-mode signal and return
a targeted `MonitorOutcome::Error` carrying the diagnostic, so both the
standalone monitor and the post-deploy monitor fail fast with an
actionable message. The #531 port-release path still runs on this exit, so
no `fbuild daemon stop` is needed before a recovery client opens the port.

Addresses part of #532 (boot-mode reporting); the DTR/RTS
auto-recovery sequence remains hardware-gated follow-up.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Jun 13, 2026

Copy link
Copy Markdown

Warning

Review limit reached

@zackees, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 3 minutes and 49 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 5b3bed55-ab46-4014-9595-32929b731e17

📥 Commits

Reviewing files that changed from the base of the PR and between 659c763 and fad2672.

📒 Files selected for processing (1)
  • crates/fbuild-daemon/src/handlers/operations/monitor.rs
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch fix/esp32s3-download-mode-detect

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@zackees
zackees merged commit 696b620 into main Jun 13, 2026
90 checks passed
@fastled-project-sync fastled-project-sync Bot moved this to Triage in FastLED Tracker Jun 14, 2026
@zackees
zackees deleted the fix/esp32s3-download-mode-detect branch October 16, 2026 11:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Triage

Development

Successfully merging this pull request may close these issues.

1 participant