feat(serial): BoardFamily reset_method + dispatch_reset (#687)

[zackees]

Summary

#687 — polymorphic reset dispatch. Until now reset was implicit: deploy paths called esp_hard_reset_blocking directly, LPC callers had to do their own SWD-via-CMSIS-DAP, and Teensy/SAMD/RP2040 had no path at all. This PR builds the dispatch surface.

What this PR ships

boards.rs extensions

• New ResetMethod enum: DtrRtsPulse | DtrPulse | TouchBaud1200 | SwdViaCmsisDap. Only DtrRtsPulse has an in-fbuild-serial implementation today (esp_hard_reset_blocking); the other three delegate to the caller.
• BoardFamily::reset_method() — the family → primitive mapping.
• BoardFamily::reset_is_serial_native() — true iff dispatch_reset can run the reset inline.
• Expanded variants: added Teensy, NativeUsbCdcReset1200Bps, ArduinoAutoReset. Renamed Arduino → ArduinoAutoReset. Existing CdcAcmBridge stays without payload (future enhancement noted in doc-comment).
• family_for_vid_pid updated: RP2040 now classifies as NativeUsbCdcReset1200Bps. Arduino returns ArduinoAutoReset. Teensy shares VID:PID with LPC11U35 — kept as CdcAcmBridge (more common case); Teensy variant must be constructed explicitly.

esp_reset.rs extensions

• ResetDispatchOutcome { Done | DelegateToCaller(ResetMethod) }.
• dispatch_reset(family, port) -> Result<ResetDispatchOutcome> — routes ESP families to esp_hard_reset_blocking, returns DelegateToCaller(other) for the three primitives fbuild-serial doesn't own. The match-on-reset_method() IS the debug-assert fbuild-serial: BoardFamily enum + polymorphic ResetMethod dispatch registry #687 criterion 3 asks for: a non-ESP family ends at DelegateToCaller instead of pulsing DTR=low on an LPC VCOM bridge (the [BLOCKER] LPC845-BRK AutoResearch bring-up echo returns empty RX (suspected HardFault) — blocks #3102 FastLED#3300 trap).

manager::open_port signature change

Added family: Option<BoardFamily> as a 4th positional arg. Consults idle_dtr_rts() for the post-open DTR/RTS state; None defaults to (true, true) (the prior hardcoded behavior). Updated three external callers (websockets, deploy, monitor) and the internal test to pass None.

Tests — 80 passed (was 72)

8 new tests, key one being dispatch_reset_cdc_acm_delegates_without_touching_dtr_rts which pins the FastLED/FastLED#3300 invariant at the dispatcher level — CDC-ACM dispatch MUST NOT pulse DTR/RTS.

test result: ok. 80 passed; 0 failed; 1 ignored; ...

cargo clippy -p fbuild-serial -p fbuild-daemon --all-targets -- -D warnings clean. cargo fmt --all --check clean.

Out of scope (follow-ups)

• BoardFamily plumbing through the daemon's request layer (websockets, deploy, monitor all pass None for now). Needs an HTTP-API contract decision: client-supplied vs server-inferred via family_for_vid_pid.
• Implementations of DtrPulse / TouchBaud1200 — each gets its own follow-up. The dispatcher returns DelegateToCaller so callers can wire them externally without blocking this landing.
• CdcAcmBridge { vid, pid } payload — non-breaking variant evolution later.
• Renaming esp_hard_reset_blocking → esp_dtr_rts_reset_blocking (criterion 3): kept current name (already renamed in fbuild-serial: hard_reset_blocking leaves DTR=low — fatal for CDC-ACM bridges (LPC11U35, FTDI CDC). Mirror the FastLED #3300/#3339 lessons. #684); a second rename burns caller breakage for marginal clarity. The debug-assert intent is satisfied by dispatch_reset's family check.

Test plan

• cargo test -p fbuild-serial --lib (80/80)
• cargo clippy -p fbuild-serial -p fbuild-daemon --all-targets -- -D warnings clean
• cargo fmt --all --check clean
• Workspace CI green

Closes#687.

Summary by CodeRabbit

• Refactor
  • Improved serial port initialization and board type detection for enhanced compatibility with various development boards (Arduino, RP2040, Teensy, ESP32).
  • Enhanced reset handling to provide more reliable device connections across different board types.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

The PR restructures BoardFamily by renaming Arduino to ArduinoAutoReset, splitting out CdcAcmBridge, Teensy, and NativeUsbCdcReset1200Bps variants, and updating idle_dtr_rts, reset_method, and reset_is_serial_native accordingly. open_port gains an Option<BoardFamily> parameter to drive per-family DTR/RTS idle-state selection. A new dispatch_reset function and ResetDispatchOutcome enum route reset handling by family. Daemon call sites pass None to match the new signature.

Changes

BoardFamily enum refactor, reset dispatch, and open_port signature

Layer / File(s)	Summary
BoardFamily variants and methods crates/fbuild-serial/src/boards.rs	BoardFamily enum restructured with CdcAcmBridge, Teensy, NativeUsbCdcReset1200Bps, ArduinoAutoReset variants replacing Arduino; idle_dtr_rts, reset_method, reset_is_serial_native, and family_for_vid_pid updated for the new set; ResetMethod docs updated; existing tests revised and new invariant tests added.
open_port signature extended with Option<BoardFamily> crates/fbuild-serial/src/manager.rs	open_port accepts a new family: Option<BoardFamily> parameter; post-open DTR/RTS values derived from family.idle_dtr_rts() or default (true, true); logging reports chosen idle levels and family; regression test updated to pass None.
dispatch_reset and ResetDispatchOutcome crates/fbuild-serial/src/esp_reset.rs	New ResetDispatchOutcome enum (Done, DelegateToCaller(ResetMethod)) and dispatch_reset function: calls esp_hard_reset_blocking for DtrRtsPulse families and returns DelegateToCaller for all others; dispatcher tests verify ESP families complete and non-ESP families delegate without DTR/RTS events.
Daemon call-site updates crates/fbuild-daemon/src/handlers/operations/deploy.rs, ...monitor.rs, crates/fbuild-daemon/src/handlers/websockets.rs	ctx.serial_manager.open_port calls in the deploy monitor path, /api/monitor handler, and WebSocket attach handshake each pass an additional None argument to match the new signature.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• fbuild-serial: BoardFamily enum + polymorphic ResetMethod dispatch registry #687 — This PR directly implements the acceptance criteria from that issue: BoardFamily with idle_dtr_rts() and reset_method(), open_port accepting Option<BoardFamily> with (true, true) default, and a dispatch_reset helper routing to the correct primitive or delegating SWD/touch-baud resets to callers.
• fbuild-serial: vendor a serial-probe CLI + shared BOARD_FINGERPRINTS table (companion to closed #684, parallel to FastLED #3339) #686 — The open_port signature extension and per-family DTR/RTS idle-state selection are foundational for the serial-probe fingerprint table that #686 describes.
• fbuild: standardize flash→monitor handoff timing as per-family HandoffTiming on BoardFamily #691 — The new BoardFamily variants and idle_dtr_rts method provide the per-family infrastructure that #691's proposed HandoffTiming settings would extend.

Possibly related PRs

• FastLED/fbuild#577: Introduced hard_reset_blocking in esp_reset.rs; this PR builds on that by adding dispatch_reset and ResetDispatchOutcome on top of esp_hard_reset_blocking.
• FastLED/fbuild#685: Renamed/introduced ESP reset primitives including esp_hard_reset_blocking, which dispatch_reset in this PR directly calls for DTR/RTS-pulse families.
• FastLED/fbuild#700: Adds the boards/BoardFamily infrastructure that drives the per-family DTR/RTS idle-state decisions consumed by the open_port changes here.

Poem

🐇 Hoppity-hop, the board variants grow,
ArduinoAutoReset now steals the show!
dispatch_reset routes each family's call —
ESP gets a pulse, the bridge gets SWD hall.
open_port takes None with a knowing wink,
All the daemon sites updated in a blink! 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately describes the main change: introducing BoardFamily enum with reset_method dispatch and the accompanying infrastructure for polymorphic reset handling.
Linked Issues check	✅ Passed	All core acceptance criteria from #687 are met: BoardFamily enum created with idle_dtr_rts() and reset_method(), manager::open_port updated to accept optional BoardFamily, dispatch_reset() implemented with family routing, and documentation linking FastLED#3300 incident provided.
Out of Scope Changes check	✅ Passed	All changes align with the PR scope; unimplemented TouchBaud1200 and DtrPulse primitives are intentionally deferred per the linked issue, and no extraneous modifications beyond the required structural additions are present.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/687-board-family-reset-method

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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