docs(serial): USB CDC DTR/RTS control-line semantics matrix (#689)#701
Conversation
#689 — pin the per-chip `(DTR, RTS) → effect` rules in one place so the next board port doesn't rediscover the FastLED/FastLED#3300 silent-byte-drop trap from first principles. New `docs/usb-cdc-control-line-matrix.md` covers: * TL;DR cheat sheet — the one rule you can't go wrong with (`DTR=True, RTS=True` after open unless you specifically need an ESP reset). * Per-chip matrix with 8 entries, each with a datasheet citation captured at 2026-06: ESP32 native USB CDC, LPC11U35 USB-VCOM bridge, FTDI FT232R/FT231X/FT232H, Silicon Labs CP2102/CP2104/CP2105, WCH CH340/CH341/CH343/CH9102, PJRC Teensy USB-Serial, Raspberry Pi RP2040 native USB CDC, Atmel/Microchip SAMD21/SAMD51 native USB CDC. Satisfies #689 acceptance ≥5 chips + 2 native CDC + Teensy entry. * Worked example: the LPC845-BRK incident with-vs-without this doc — "two debugging sessions" vs "15-minute investigation." * Empirical-probe pointer (future work, mentioned in #686 discussion). * "When to update this doc" trigger list. Cross-links added to the three sites #689 names: * `crates/fbuild-serial/src/esp_reset.rs` — module-level warning block now points at the matrix for the full per-chip table behind the "Do NOT call esp_hard_reset_blocking for CDC bridge boards" rule. * `crates/fbuild-serial/src/manager.rs::open_port` — the DTR/RTS-assert block (already referencing #532) now also points at the matrix. * `crates/fbuild-serial/src/boards.rs` — module header. The matrix is the *why* behind every BoardFamily's `idle_dtr_rts()` answer. Closes #689.
|
Warning Review limit reached
More reviews will be available in 44 minutes and 9 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 To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits. 🚦 How do rate limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (4)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
Summary
#689 — pin the per-chip
(DTR, RTS) → effectrules in one place so the next board port doesn't rediscover the FastLED/FastLED#3300 silent-byte-drop trap from first principles.What this PR ships
docs/usb-cdc-control-line-matrix.mdTL;DR cheat sheet — the one rule you can't go wrong with:
DTR=True, RTS=Trueafter open unless you specifically need an ESP reset.Per-chip matrix with 8 entries, each with a datasheet citation captured at 2026-06:
Satisfies docs: USB CDC DTR/RTS control-line semantics matrix per board family #689 acceptance: ≥5 chips (have 8) + ≥2 native CDC (have ESP32, RP2040, SAMD) + PJRC Teensy entry.
Worked example: the LPC845-BRK incident with-vs-without this doc — "two debugging sessions chasing a fictional Arduino-core regression" vs "15-minute investigation."
Empirical-probe pointer (future work mentioned in fbuild-serial: vendor a serial-probe CLI + shared BOARD_FINGERPRINTS table (companion to closed #684, parallel to FastLED #3339) #686 discussion).
"When to update this doc" trigger list — covers the new-board-family, new-VID-PID, bring-up-incident, and stale-URL cases.
Cross-links from the three sites #689 names
crates/fbuild-serial/src/esp_reset.rs— module-level warning block now points at the matrix for the full per-chip table behind the "Do NOT callesp_hard_reset_blockingfor CDC bridge boards" rule.crates/fbuild-serial/src/manager.rs::open_port— the DTR/RTS-assert block (already referencing fix(esp32): prevent ESP32-S3 serial reset deadlock and boot-mode lockup #532) now also points at the matrix.crates/fbuild-serial/src/boards.rs— module header. The matrix is the why behind everyBoardFamily'sidle_dtr_rts()answer.Test plan
Pure docs change.
cargo check -p fbuild-serial).grep -l usb-cdc-control-line-matrix crates/ -rreturns the three expected files).Closes #689.