make half-duplex safe on a shared wire: hdsel before te, open-drain park with per-write push-pull

Author: aq1018

CHANGELOG.md

@@ -4,6 +4,10 @@ Releases up through `v0.4.0` were workspace-wide and tagged `vX.Y.Z`. From `0.4.
 
 ## [Unreleased]
 
+### Fixed
+
+- `tinyboot-ch32`: half-duplex is now safe on a shared (multi-drop) wire. `usart::init` sets HDSEL before TE — the reverse order latched the half-duplex TX output LOW until the first own transmission, clamping the bus from init (measured on CH32V006). The single-wire pin now parks AF open-drain (the bus pull-up owns idle) and flips to push-pull only around writes, so an idle node never drives against other talkers.
+
 ## [tinyboot-ch32-rt 0.4.1] - 2026-05-08
 
 ### Fixed

ch32/src/hal/usart/usart_common.rs

@@ -2,16 +2,21 @@ pub use ch32_metapac::usart::Usart as Regs;
 
 #[inline(always)]
 pub fn init(r: Regs, pclk: u32, baud: u32, half_duplex: bool) {
+    // HDSEL strictly before TE: enabling the transmitter first latches the
+    // half-duplex TX output LOW until the first own transmission, which
+    // clamps a shared wire even through an open-drain pin (measured on
+    // CH32V006: the line sat low from init and rose the moment the pin
+    // left AF mode).
+    if half_duplex {
+        r.ctlr3().write(|w| w.set_hdsel(true));
+    }
+
     // CTLR1 default (M=0, PCE=0, STOP=00) gives 8N1; just set TE+RE.
     r.ctlr1().write(|w| {
         w.set_te(true);
         w.set_re(true);
     });
 
-    if half_duplex {
-        r.ctlr3().write(|w| w.set_hdsel(true));
-    }
-
     let brr = (pclk + baud / 2) / baud;
     r.brr().write_value(ch32_metapac::usart::regs::Brr(brr));
 

ch32/src/platform/transport/usart/mod.rs

@@ -59,6 +59,10 @@ pub struct UsartConfig {
 pub struct Usart {
     regs: crate::hal::usart::Regs,
     tx_en: Option<TxEnConfig>,
+    /// Half-duplex: the single-wire pin, CNF-flipped per write — push-pull
+    /// while driving, open-drain parked so an idle node never fights the
+    /// wire's other talkers (the bus pull-up owns the idle level).
+    drive_pin: Option<Pin>,
 }
 
 impl tinyboot_core::traits::Transport for Usart {}
@@ -89,8 +93,12 @@ impl Usart {
 
         afio::set_usart_remap(usart_n, config.mapping.remap_value());
 
-        gpio::configure(tx_pin, PinMode::AF_PUSH_PULL);
-        if !half_duplex {
+        if half_duplex {
+            // Park the single wire open-drain: TX idles mark (released) and
+            // RX keeps hearing through the pin; writes flip to push-pull.
+            gpio::configure(tx_pin, PinMode::AF_OPEN_DRAIN);
+        } else {
+            gpio::configure(tx_pin, PinMode::AF_PUSH_PULL);
             gpio::configure(rx_pin, PinMode::input_pull(config.rx_pull));
         }
 
@@ -106,18 +114,25 @@ impl Usart {
         Usart {
             regs,
             tx_en: config.tx_en,
+            drive_pin: half_duplex.then_some(tx_pin),
         }
     }
 
     #[inline(always)]
     fn set_tx_mode(&self) {
+        if let Some(pin) = self.drive_pin {
+            gpio::configure(pin, PinMode::AF_PUSH_PULL);
+        }
         if let Some(ref tx_en) = self.tx_en {
             gpio::set_level(tx_en.pin, tx_en.tx_level);
         }
     }
 
     #[inline(always)]
     fn set_rx_mode(&self) {
+        if let Some(pin) = self.drive_pin {
+            gpio::configure(pin, PinMode::AF_OPEN_DRAIN);
+        }
         if let Some(ref tx_en) = self.tx_en {
             gpio::set_level(tx_en.pin, invert(tx_en.tx_level));
         }

docs/transports.md

@@ -25,7 +25,7 @@ Usart::new(&UsartConfig {
 
 ## Setup 2: single-wire UART (MCU-level half duplex)
 
-The MCU muxes RX onto the TX pin — one wire to the host, no external buffer. Useful when both ends speak half duplex directly (some probes, some DXL servo chains where the MCU is the sole driver on its segment).
+The MCU muxes RX onto the TX pin — one wire to the host, no external buffer. Useful when both ends speak half duplex directly: probes, DXL-style servo chains, any shared single-wire bus.
 
 ```rust
 Usart::new(&UsartConfig {
@@ -35,6 +35,10 @@ Usart::new(&UsartConfig {
 });
 ```
 
+**Hardware requirement: the wire needs an external pull-up.** In `Duplex::Half` the driver parks the pin **open-drain** while idle or listening and flips it to push-pull only around its own writes, so between frames nothing holds the line at mark except the pull-up. Without one the wire floats and the receiver sees noise and framing errors — garbage bytes the protocol has to sync past. 4.7–10 kΩ to the bus voltage is typical; go stiffer for high baud rates or long, capacitive buses.
+
+This discipline is what makes the single wire **shareable**: an idle node never drives the line, so several half-duplex devices (and the host) can sit on one bus without contention. The driver also raises HDSEL before enabling the transmitter — the reverse order latches the TX output low until the first own transmission, which would clamp the whole bus from init to the first reply.
+
 ## Setup 3: full-duplex UART + external half-duplex buffer (RS-485 / DXL TTL)
 
 This is the OpenServoCore hardware style: the MCU runs regular full-duplex UART to a hardware transceiver (MAX485, 74LVC2G241, etc.), and `tx_en` drives the transceiver's direction pin so its output stage only drives the bus while the MCU is transmitting.
@@ -67,6 +71,8 @@ Usart::new(&UsartConfig {
 });
 ```
 
+The open-drain idle park applies in this setup too — it's the `Duplex::Half` discipline, independent of `tx_en` — so the stub between the pin and the buffer input needs a pull-up (or a transceiver with internal biasing) to keep the buffer's input at mark while the MCU listens.
+
 ## What `tx_en` actually does
 
 When configured, the driver toggles the direction pin around every frame:

docs/troubleshooting.md

@@ -28,6 +28,7 @@ Something in the UART chain isn't right. Work through these in order:
 - **`rx_pull`** — floating RX lines need `Pull::Up`; externally pulled-up lines should use `Pull::None`.
 - **RS-485 / DXL TTL** — a DE/RE pin must be configured via `TxEnConfig`, with `tx_level` matching the transceiver's DE polarity.
 - **Half-duplex contention** — on some boards the programmer's TX driver and the MCU's TX driver both reach MCU_RX. Flipping `tx_level` (so the MCU's side is tri-stated while idle) often resolves it. See the [transports guide](transports.md).
+- **Half-duplex missing pull-up** — `Duplex::Half` parks the pin open-drain while idle, so the wire needs an external pull-up to hold mark between frames. A floating wire reads as noise and framing errors. See the [transports guide](transports.md).
 
 ---