refactor: 重构架构并整理仓库

crates/esc-bus/Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+name = "esc-bus"
+description = "Asynchronous ESC frame pump, state, leases, and safety"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+
+[lints]
+workspace = true
+
+[dependencies]
+can = { workspace = true }
+motor = { workspace = true }
+motor-protocol = { workspace = true }
+tokio = { workspace = true }
+thiserror = { workspace = true }
+tracing = { workspace = true }
+
+[dev-dependencies]
+sim-harness = { workspace = true }
+motor-control = { workspace = true }
+motor-model = { workspace = true }
+experiment = { workspace = true }
+tokio = { workspace = true, features = ["test-util"] }
+approx = { workspace = true }

crates/esc-bus/src/lib.rs

@@ -0,0 +1,540 @@
+#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
+
+//! `EscBus` 异步驱动：协议状态机与 1kHz 控制节拍。
+//!
+//! [`EscBus::spawn`] 消费一个 [`CanLink`]，启动收发两个任务：
+//!
+//! - 接收：解码反馈帧，更新各电机共享状态（含多圈累计与方向修正）；
+//! - 发送：按 `period` 节拍为每台电机求值当前命令（速度/位置环 PID / 直发
+//!   effort），按 `0x200`/`0x1FF` 分组组帧发送。
+//!
+//! 电机离线（从未收到反馈或反馈超时）时强制 0 输出并复位控制器。
+//! 命令模式切换时同样复位控制器，避免积分冲击。
+
+use std::sync::{Arc, Mutex, MutexGuard};
+use std::time::Duration;
+
+use can::{CanFrame, CanLink};
+use motor_protocol::common::{
+    EscFeedback, EscModel, clamp_current, command_frame_id, decode_feedback, encode_current_frame,
+};
+use motor_protocol::{COMMAND_FRAME_ID_PRIMARY, COMMAND_FRAME_ID_SECONDARY, TurnTracker};
+use thiserror::Error;
+use tokio::sync::{mpsc, watch};
+use tokio::task::JoinHandle;
+use tokio::time::{Instant, Interval, MissedTickBehavior};
+use tracing::{debug, info, warn};
+
+use motor::{
+    Command, Disable, EffortDrive, EffortPolicy, MotorFeedback, MotorState, PolicyInput,
+    PolicySample, PositionDrive, VelocityDrive,
+};
+
+/// 锁辅助：中毒锁直接恢复内部数据（锁中毒只意味着持锁线程恐慌，
+/// 状态本身仍一致，驱动机不应因此停摆）。
+fn lock<T>(mutex: &Mutex<T>) -> MutexGuard<'_, T> {
+    mutex.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
+}
+
+/// 单台电机的配置。
+#[derive(Debug, Clone)]
+pub struct EscConfig {
+    /// 便于日志辨认的名字（如 `front_left`）。
+    pub name: String,
+    /// 电调 ID（1–8，即 CAN 拨码）。
+    pub esc_id: u8,
+    /// 电调型号。
+    pub model: EscModel,
+    /// 减速比（电机转子 : 输出轴）。
+    ///
+    /// 驱动层**不使用**此字段；由上层 `crate::OutputShaft` 应用。
+    /// 保留于此作为配置元数据，`chassisd` 包装轮子时必须读取本字段（单一来源）。
+    pub gear_ratio: f32,
+    /// 安装方向：`+1.0` 或 `-1.0`。反装电机的读写符号在此统一翻转，
+    /// 上层永远以"输出轴正转 = 前进方向"工作。
+    pub direction: f32,
+    /// effort 限幅（raw，`1..=型号满量程`）。
+    pub current_limit: i16,
+}
+
+impl EscConfig {
+    /// GM3508 + C620 的常用配置。`kp/ki/ff` 为起步值，需按整车整定。
+    #[must_use]
+    pub fn gm3508(name: impl Into<String>, esc_id: u8, direction: f32) -> Self {
+        Self {
+            name: name.into(),
+            esc_id,
+            model: EscModel::C620,
+            // 3591 / 187 ≈ 19.203
+            gear_ratio: 3591.0 / 187.0,
+            direction,
+            current_limit: 12_000,
+        }
+    }
+
+    /// M2006 + C610（拨弹轮）的常用配置。
+    ///
+    /// 减速比按 P36 起步（36.0），接硬件前需核对；电流标度见 [`EscModel::C610`]。
+    #[must_use]
+    pub fn m2006(name: impl Into<String>, esc_id: u8, direction: f32) -> Self {
+        Self {
+            name: name.into(),
+            esc_id,
+            model: EscModel::C610,
+            // M2006 P36 减速比（接入前核对）
+            gear_ratio: 36.0,
+            direction,
+            current_limit: 8_000,
+        }
+    }
+
+    fn validate(&self) -> Result<(), String> {
+        if command_frame_id(self.esc_id).is_none() {
+            return Err(format!("esc_id {} out of range 1..=8", self.esc_id));
+        }
+        if !(self.gear_ratio.is_finite() && self.gear_ratio > 0.0) {
+            return Err(format!("gear_ratio must be > 0, got {}", self.gear_ratio));
+        }
+        // 逐位比较：direction 只允许精确的 ±1.0。
+        let dir_bits = self.direction.to_bits();
+        if dir_bits != 1.0f32.to_bits() && dir_bits != (-1.0f32).to_bits() {
+            return Err(format!("direction must be +1.0 or -1.0, got {}", self.direction));
+        }
+        if !(1..=self.model.max_current_raw()).contains(&self.current_limit) {
+            return Err(format!(
+                "current_limit {} out of range 1..={} for {:?}",
+                self.current_limit,
+                self.model.max_current_raw(),
+                self.model
+            ));
+        }
+        Ok(())
+    }
+}
+
+/// 总线运行参数。
+#[derive(Debug, Clone)]
+pub struct BusOptions {
+    /// 控制节拍（C620 期望 1kHz 命令）。
+    pub period: Duration,
+    /// 反馈离线阈值：超过该时长未收到某电机反馈 → 强制 0 输出。
+    pub feedback_timeout: Duration,
+    /// **命令租约**：上层超过该时长未重新下发命令 → 视为 `Disabled`（0 输出）。
+    ///
+    /// 命令是**租约**而非一次性设定值：`set_velocity` / `set_effort_raw` /
+    /// `set_position` 每次调用都会续租。上层必须按自己的控制节拍周期性下发
+    /// （`chassisd` 的 1kHz 循环天然满足；台架脚本每拍重发即可），
+    /// 否则驱动会判定"上层任务已死"并强制零输出——这是防失控的安全设计。
+    ///
+    /// 设置为 `Duration::MAX` 可退化为纯设定值语义（仅建议在无失控风险的台架场景）。
+    pub command_timeout: Duration,
+}
+
+impl Default for BusOptions {
+    fn default() -> Self {
+        Self {
+            period: Duration::from_millis(1),
+            feedback_timeout: Duration::from_millis(100),
+            // 1kHz 下约 50 拍未刷新即失效。
+            command_timeout: Duration::from_millis(50),
+        }
+    }
+}
+
+/// 启动错误。
+#[derive(Debug, Clone, PartialEq, Eq, Error)]
+pub enum EscBusError {
+    /// 两台电机配置了同一电调 ID。
+    #[error("duplicate ESC id {0}")]
+    DuplicateEscId(u8),
+    /// 电机配置非法（原因见 `reason`）。
+    #[error("invalid config for motor {name}: {reason}")]
+    InvalidConfig {
+        /// 电机名。
+        name: String,
+        /// 非法原因。
+        reason: String,
+    },
+    /// 一台电机都没有配置。
+    #[error("no motors configured")]
+    NoMotors,
+}
+
+/// 单电机共享状态（驱动任务与 [`EscMotor`] 句柄之间）。
+struct MotorShared {
+    cfg: EscConfig,
+    state: Mutex<MotorState>,
+    cmd: Mutex<Command>,
+    /// 命令写入时刻（看门狗用）。
+    cmd_at: Mutex<Option<Instant>>,
+    turn: Mutex<TurnTracker>,
+    last_feedback: Mutex<Option<Instant>>,
+    offline_warned: std::sync::atomic::AtomicBool,
+}
+
+impl MotorShared {
+    fn new(cfg: EscConfig) -> Self {
+        Self {
+            cfg,
+            state: Mutex::new(MotorState::default()),
+            cmd: Mutex::new(Command::Disabled),
+            cmd_at: Mutex::new(None),
+            turn: Mutex::new(TurnTracker::new()),
+            last_feedback: Mutex::new(None),
+            offline_warned: std::sync::atomic::AtomicBool::new(false),
+        }
+    }
+
+    fn store_command(&self, cmd: Command) {
+        *lock(&self.cmd) = cmd;
+        *lock(&self.cmd_at) = Some(Instant::now());
+    }
+
+    /// 应用一帧反馈（原始电调侧值 → 方向修正后的物理量）。
+    fn apply_feedback(&self, fb: EscFeedback, now: Instant) {
+        let esc_rev = lock(&self.turn).update(fb.angle_raw);
+        let dir = self.cfg.direction;
+        {
+            let mut st = lock(&self.state);
+            st.rotor_angle_raw = fb.angle_raw;
+            st.rotor_revolutions = dir * esc_rev;
+            st.rotor_speed_rpm = dir * f32::from(fb.speed_rpm);
+            st.effort_raw = (dir * f32::from(fb.current_raw)) as i16;
+            st.temperature_c = fb.temperature_c;
+            st.feedback_count = st.feedback_count.saturating_add(1);
+        }
+        *lock(&self.last_feedback) = Some(now);
+        self.offline_warned.store(false, std::sync::atomic::Ordering::Relaxed);
+    }
+
+    /// Produce one policy sample while enforcing feedback and command leases.
+    fn sample(
+        &self,
+        feedback_timeout: Duration,
+        command_timeout: Duration,
+        now: Instant,
+    ) -> PolicySample {
+        let online = matches!(
+            *lock(&self.last_feedback),
+            Some(t) if now.saturating_duration_since(t) <= feedback_timeout
+        );
+        if !online && !self.offline_warned.swap(true, std::sync::atomic::Ordering::Relaxed) {
+            warn!(motor = %self.cfg.name, esc_id = self.cfg.esc_id, "feedback offline, forcing zero current");
+        }
+        let fresh = matches!(
+            *lock(&self.cmd_at),
+            Some(t) if now.saturating_duration_since(t) <= command_timeout
+        );
+        let command = if online && fresh { *lock(&self.cmd) } else { Command::Disabled };
+        PolicySample { id: self.cfg.esc_id, state: *lock(&self.state), command, online }
+    }
+}
+
+/// 电机的公共句柄：可克隆，跨任务共享。
+///
+/// # 命令租约
+///
+/// 下发命令（[`VelocityDrive::set_velocity`] / [`EffortDrive::set_effort_raw`] /
+/// [`PositionDrive::set_position`]）即续租，租期见 [`BusOptions::command_timeout`]。
+/// 只在启动时下发一次、之后不再刷新的脚本会在租约到期后自动失电（0 输出），
+/// 因此台架工具必须在控制循环里逐拍重发同一个设定值。
+#[derive(Clone)]
+pub struct EscMotor {
+    shared: Arc<MotorShared>,
+}
+
+impl EscMotor {
+    /// 电机名。
+    #[must_use]
+    pub fn name(&self) -> &str {
+        &self.shared.cfg.name
+    }
+
+    /// 电机配置。
+    #[must_use]
+    pub fn config(&self) -> &EscConfig {
+        &self.shared.cfg
+    }
+
+    /// 当前命令。
+    #[must_use]
+    pub fn command(&self) -> Command {
+        *lock(&self.shared.cmd)
+    }
+
+    /// 最近一帧反馈的时刻（诊断用）。
+    #[must_use]
+    pub fn last_feedback(&self) -> Option<Instant> {
+        *lock(&self.shared.last_feedback)
+    }
+}
+
+impl MotorFeedback for EscMotor {
+    fn id(&self) -> u8 {
+        self.shared.cfg.esc_id
+    }
+
+    fn state(&self) -> MotorState {
+        *lock(&self.shared.state)
+    }
+
+    fn feedback_age(&self) -> Option<std::time::Duration> {
+        let t = *lock(&self.shared.last_feedback);
+        Some(Instant::now().saturating_duration_since(t?))
+    }
+}
+
+impl VelocityDrive for EscMotor {
+    /// 设定目标转子转速（**租约**，见 [`EscMotor`] 的命令租约说明）。
+    fn set_velocity(&self, rotor_rpm: f32) {
+        self.shared.store_command(Command::Velocity(rotor_rpm));
+    }
+}
+
+impl EffortDrive for EscMotor {
+    /// 直发开环 raw（**租约**，见 [`EscMotor`] 的命令租约说明）。
+    fn set_effort_raw(&self, raw: i16) {
+        self.shared.store_command(Command::EffortRaw(raw));
+    }
+}
+
+impl PositionDrive for EscMotor {
+    /// 设定目标转子多圈位置（**租约**，见 [`EscMotor`] 的命令租约说明）。
+    fn set_position(&self, rotor_rev: f32) {
+        self.shared.store_command(Command::Position(rotor_rev));
+    }
+}
+
+impl Disable for EscMotor {
+    /// 停用（0 输出）；同样受租约保护——上层若已死，租约到期后依旧归零。
+    fn disable(&self) {
+        self.shared.store_command(Command::Disabled);
+    }
+}
+
+/// 运行中的电调总线。
+pub struct EscBus;
+
+impl EscBus {
+    /// 启动收发任务，返回句柄。
+    ///
+    /// # Errors
+    ///
+    /// 配置为空、电调 ID 重复或单台配置非法时返回 [`EscBusError`]。
+    pub fn spawn<P: EffortPolicy>(
+        link: CanLink,
+        configs: Vec<EscConfig>,
+        options: BusOptions,
+        policy: P,
+    ) -> Result<EscBusHandle<P>, EscBusError> {
+        if configs.is_empty() {
+            return Err(EscBusError::NoMotors);
+        }
+        let mut motors = Vec::with_capacity(configs.len());
+        let mut seen = std::collections::HashSet::new();
+        for cfg in configs {
+            cfg.validate()
+                .map_err(|reason| EscBusError::InvalidConfig { name: cfg.name.clone(), reason })?;
+            if !seen.insert(cfg.esc_id) {
+                return Err(EscBusError::DuplicateEscId(cfg.esc_id));
+            }
+            motors.push(EscMotor { shared: Arc::new(MotorShared::new(cfg)) });
+        }
+
+        let (shutdown_tx, shutdown_rx) = watch::channel(false);
+        let CanLink { outgoing_tx, incoming_rx } = link;
+        let motors = Arc::new(motors);
+        let policy = Arc::new(Mutex::new(policy));
+        let rx_handle =
+            tokio::spawn(rx_loop(incoming_rx, Arc::clone(&motors), shutdown_rx.clone()));
+        let tx_handle = tokio::spawn(tx_loop(
+            outgoing_tx,
+            Arc::clone(&motors),
+            Arc::clone(&policy),
+            options,
+            shutdown_rx,
+        ));
+
+        Ok(EscBusHandle { motors, policy, shutdown_tx, tasks: vec![rx_handle, tx_handle] })
+    }
+}
+
+/// `EscBus` 的控制句柄。
+pub struct EscBusHandle<P> {
+    motors: Arc<Vec<EscMotor>>,
+    policy: Arc<Mutex<P>>,
+    shutdown_tx: watch::Sender<bool>,
+    tasks: Vec<JoinHandle<()>>,
+}
+
+impl<P: EffortPolicy> EscBusHandle<P> {
+    /// 按电调 ID 取电机句柄。
+    #[must_use]
+    pub fn motor(&self, esc_id: u8) -> Option<&EscMotor> {
+        self.motors.iter().find(|m| m.id() == esc_id)
+    }
+
+    /// 全部电机（按配置顺序）。
+    #[must_use]
+    pub fn motors(&self) -> &[EscMotor] {
+        &self.motors
+    }
+
+    /// Mutate the composed control policy between bus ticks.
+    pub fn with_policy<R>(&self, update: impl FnOnce(&mut P) -> R) -> R {
+        update(&mut lock(&self.policy))
+    }
+
+    /// 停止收发任务并等待退出。
+    pub async fn shutdown(self) {
+        let _ = self.shutdown_tx.send(true);
+        for task in self.tasks {
+            let _ = task.await;
+        }
+    }
+}
+
+async fn rx_loop(
+    mut incoming: mpsc::Receiver<CanFrame>,
+    motors: Arc<Vec<EscMotor>>,
+    mut shutdown: watch::Receiver<bool>,
+) {
+    loop {
+        let frame = tokio::select! {
+            _ = shutdown.changed() => break,
+            frame = incoming.recv() => match frame {
+                Some(frame) => frame,
+                None => break,
+            },
+        };
+        match decode_feedback(&frame) {
+            Ok((esc_id, fb)) => {
+                if let Some(motor) = motors.iter().find(|m| m.id() == esc_id) {
+                    motor.shared.apply_feedback(fb, Instant::now());
+                }
+            }
+            Err(e) => {
+                debug!(error = %e, id = frame.id, "ignore non-feedback frame");
+            }
+        }
+    }
+}
+
+async fn tx_loop<P: EffortPolicy>(
+    outgoing: mpsc::Sender<CanFrame>,
+    motors: Arc<Vec<EscMotor>>,
+    policy: Arc<Mutex<P>>,
+    options: BusOptions,
+    mut shutdown: watch::Receiver<bool>,
+) {
+    let nominal_dt = options.period.as_secs_f32();
+    let mut ticker = tick_every(options.period);
+    let mut last_tick = Instant::now();
+    loop {
+        tokio::select! {
+            _ = shutdown.changed() => break,
+            _ = ticker.tick() => {}
+        }
+        let now = Instant::now();
+        let raw_dt = now.saturating_duration_since(last_tick).as_secs_f32();
+        last_tick = now;
+        let dt = raw_dt.clamp(nominal_dt * 0.5, nominal_dt * 4.0);
+        let mut samples: [PolicySample; 8] = std::array::from_fn(|index| PolicySample {
+            id: u8::try_from(index + 1).unwrap_or(0),
+            state: MotorState::default(),
+            command: Command::Disabled,
+            online: false,
+        });
+        for motor in motors.iter() {
+            let sample =
+                motor.shared.sample(options.feedback_timeout, options.command_timeout, now);
+            if let Some(slot) = samples.get_mut(usize::from(sample.id.saturating_sub(1))) {
+                *slot = sample;
+            }
+        }
+        let efforts = lock(&policy).step(&PolicyInput { samples, dt });
+        for (frame_id, group_start) in
+            [(COMMAND_FRAME_ID_PRIMARY, 1u8), (COMMAND_FRAME_ID_SECONDARY, 5u8)]
+        {
+            let group: Vec<&EscMotor> = motors
+                .iter()
+                .filter(|m| (group_start..group_start + 4).contains(&m.id()))
+                .collect();
+            if group.is_empty() {
+                continue;
+            }
+            let mut currents = [0i16; 4];
+            for motor in &group {
+                let slot = usize::from(motor.id() - group_start);
+                let policy_index = usize::from(motor.id().saturating_sub(1));
+                let physical = efforts.get(policy_index).copied().unwrap_or(0);
+                let directed = (f32::from(physical) * motor.shared.cfg.direction) as i16;
+                currents[slot] = clamp_current(
+                    motor.shared.cfg.model,
+                    directed.clamp(-motor.shared.cfg.current_limit, motor.shared.cfg.current_limit),
+                );
+            }
+            if outgoing.send(encode_current_frame(frame_id, currents)).await.is_err() {
+                info!("can link closed, tx loop exiting");
+                return;
+            }
+        }
+    }
+}
+
+fn tick_every(period: Duration) -> Interval {
+    let mut ticker = tokio::time::interval(period);
+    // 错过节拍后直接跳到当前节拍，避免补发帧风暴。
+    ticker.set_missed_tick_behavior(MissedTickBehavior::Skip);
+    ticker
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn config_validate_rejects_bad_values() {
+        let mut cfg = EscConfig::gm3508("m", 1, 1.0);
+
+        cfg.esc_id = 0;
+        assert!(cfg.validate().is_err());
+        cfg.esc_id = 9;
+        assert!(cfg.validate().is_err());
+        cfg.esc_id = 5;
+
+        cfg.gear_ratio = 0.0;
+        assert!(cfg.validate().is_err());
+        cfg.gear_ratio = 19.2;
+
+        cfg.direction = 0.5;
+        assert!(cfg.validate().is_err());
+        cfg.direction = -1.0;
+
+        cfg.current_limit = 0;
+        assert!(cfg.validate().is_err());
+        cfg.current_limit = 16385;
+        assert!(cfg.validate().is_err());
+        cfg.current_limit = 12_000;
+
+        assert!(cfg.validate().is_ok());
+    }
+
+    #[test]
+    fn gm3508_defaults_are_sane() {
+        let cfg = EscConfig::gm3508("front_left", 1, -1.0);
+        assert_eq!(cfg.model, EscModel::C620);
+        assert!((cfg.gear_ratio - 19.2).abs() < 0.01);
+        assert_eq!(cfg.current_limit, 12_000);
+        assert_eq!(cfg.direction.to_bits(), (-1.0f32).to_bits());
+        assert!(cfg.validate().is_ok());
+    }
+
+    #[test]
+    fn m2006_defaults_are_sane() {
+        let cfg = EscConfig::m2006("feeder", 5, 1.0);
+        assert_eq!(cfg.model, EscModel::C610);
+        assert!((cfg.gear_ratio - 36.0).abs() < 0.01);
+        assert!(cfg.validate().is_ok());
+    }
+}

crates/esc-bus/tests/closed_loop.rs

@@ -0,0 +1,431 @@
+//! 闭环集成测试：`EscBus` + 内存通道 + 一阶电机仿真。
+//!
+//! 全部可在任意平台（macOS / Linux / CI）运行，无需硬件。
+
+#![allow(clippy::unwrap_used, clippy::expect_used)]
+
+use std::time::Duration;
+
+use can::{CanFrame, CanLink};
+use esc_bus::{BusOptions, EscBus, EscBusError, EscConfig};
+use motor::{Disable, EffortDrive, MotorFeedback, VelocityDrive};
+use motor_control::{MotorPolicy, VelocityGains};
+use motor_protocol::{EscFeedback, encode_feedback_frame};
+use sim_harness::spawn_plant;
+use tokio::sync::mpsc;
+use tokio::task::JoinHandle;
+use tokio::time::{MissedTickBehavior, interval, sleep, timeout};
+
+/// 与 `PlantParams::gm3508` 增益精确匹配的速度环参数（ff = 16384 / 9254）。
+fn tuned(esc_id: u8, direction: f32) -> EscConfig {
+    EscConfig::gm3508(format!("m{esc_id}"), esc_id, direction)
+}
+
+fn tuned_gains() -> VelocityGains {
+    VelocityGains::new(8.0, 2.0, 0.0, 16384.0 / 9254.0)
+}
+
+fn spawn_bus(
+    link: CanLink,
+    configs: Vec<EscConfig>,
+    options: BusOptions,
+) -> Result<esc_bus::EscBusHandle<MotorPolicy>, EscBusError> {
+    let mut policy = MotorPolicy::new();
+    for config in &configs {
+        policy.configure(config.esc_id, config.current_limit, tuned_gains());
+    }
+    EscBus::spawn(link, configs, options, policy)
+}
+
+/// 轮询直到条件满足或超时（毫秒，仿真时间）。
+async fn wait_until(total_ms: u64, mut cond: impl FnMut() -> bool) -> bool {
+    let mut waited = 0u64;
+    while waited < total_ms {
+        if cond() {
+            return true;
+        }
+        sleep(Duration::from_millis(5)).await;
+        waited += 5;
+    }
+    cond()
+}
+
+/// 与 [`wait_until`] 相同，但每次轮询都重新下发 `target_rpm`。
+///
+/// **命令是租约**：驱动在 [`BusOptions::command_timeout`]（默认 50ms）内未收到
+/// 新命令就强制 0 输出。真实底盘循环每 1ms 重发一次，这里以 5ms 节拍模拟。
+async fn hold_until<M: VelocityDrive>(
+    total_ms: u64,
+    motor: &M,
+    target_rpm: f32,
+    mut cond: impl FnMut() -> bool,
+) -> bool {
+    let mut waited = 0u64;
+    loop {
+        motor.set_velocity(target_rpm); // 续租
+        if cond() {
+            return true;
+        }
+        if waited >= total_ms {
+            return false;
+        }
+        sleep(Duration::from_millis(5)).await;
+        waited += 5;
+    }
+}
+
+/// 保持 `target_rpm` 共 `ms` 毫秒（期间持续续租），仅推进仿真时间。
+async fn hold<M: VelocityDrive>(motor: &M, target_rpm: f32, ms: u64) {
+    let _ = hold_until(ms, motor, target_rpm, || false).await;
+}
+
+/// 手动向总线注入一帧所有电机的反馈（新鲜度 100ms 内有效）。
+async fn send_feedback(peer: &CanLink, esc_ids: &[u8]) {
+    for &id in esc_ids {
+        let fb = EscFeedback { angle_raw: 0, speed_rpm: 0, current_raw: 0, temperature_c: 30 };
+        peer.outgoing_tx.send(encode_feedback_frame(id, &fb)).await.unwrap();
+    }
+}
+
+async fn recv_command(peer: &mut CanLink) -> CanFrame {
+    timeout(Duration::from_millis(100), peer.incoming_rx.recv())
+        .await
+        .expect("timed out waiting for command frame")
+        .expect("link closed")
+}
+
+fn slot_current(frame: &CanFrame, slot: usize) -> i16 {
+    i16::from_be_bytes([frame.data[slot * 2], frame.data[slot * 2 + 1]])
+}
+
+// ---------------------------------------------------------------- 收敛性
+
+#[tokio::test(start_paused = true)]
+async fn velocity_loop_converges() {
+    let (bus_link, plant_link) = CanLink::pair(512);
+    let plant = spawn_plant(plant_link, &[1], Duration::from_millis(1));
+    let bus = spawn_bus(bus_link, vec![tuned(1, 1.0)], BusOptions::default()).unwrap();
+    let motor = bus.motor(1).unwrap().clone();
+
+    motor.set_velocity(3000.0);
+    let ok = hold_until(2000, &motor, 3000.0, || motor.state().rotor_speed_rpm >= 2950.0).await;
+    assert!(ok, "not converged, rpm = {}", motor.state().rotor_speed_rpm);
+
+    // 稳态保持（速度无漂移、反馈持续流入）；期间必须继续续租命令。
+    let count_before = motor.state().feedback_count;
+    hold(&motor, 3000.0, 300).await;
+    let st = motor.state();
+    assert!((2950.0..=3050.0).contains(&st.rotor_speed_rpm), "steady state drifted: {st:?}");
+    assert!(
+        st.feedback_count >= count_before + 280,
+        "feedback should keep flowing: {} → {}",
+        count_before,
+        st.feedback_count
+    );
+
+    plant.abort();
+    bus.shutdown().await;
+}
+
+#[tokio::test(start_paused = true)]
+async fn reversed_motor_converges_in_physical_frame() {
+    // direction = -1：物理 +2000 rpm ⇔ 电调侧 -2000 rpm。
+    let (bus_link, plant_link) = CanLink::pair(512);
+    let plant = spawn_plant(plant_link, &[2], Duration::from_millis(1));
+    let bus = spawn_bus(bus_link, vec![tuned(2, -1.0)], BusOptions::default()).unwrap();
+    let motor = bus.motor(2).unwrap().clone();
+
+    motor.set_velocity(2000.0);
+    let ok = hold_until(2000, &motor, 2000.0, || motor.state().rotor_speed_rpm >= 1950.0).await;
+    assert!(ok, "not converged, rpm = {}", motor.state().rotor_speed_rpm);
+
+    let st = motor.state();
+    assert!((1950.0..=2050.0).contains(&st.rotor_speed_rpm), "{st:?}");
+    // 物理转速为正 ⇒ 电调电流为负 ⇒ 物理电流 = dir × esc > 0。
+    assert!(st.effort_raw > 0, "{st:?}");
+
+    plant.abort();
+    bus.shutdown().await;
+}
+
+// ---------------------------------------------------------------- 安全
+
+#[tokio::test(start_paused = true)]
+async fn motor_without_feedback_commands_zero_current() {
+    let (bus_link, mut peer) = CanLink::pair(64);
+    // 不接 plant → 永远没有反馈。
+    let bus = spawn_bus(bus_link, vec![tuned(1, 1.0)], BusOptions::default()).unwrap();
+
+    bus.motor(1).unwrap().set_velocity(5000.0);
+    for _ in 0..5 {
+        let frame = recv_command(&mut peer).await;
+        assert_eq!(frame.id, 0x200);
+        assert_eq!(frame.data, [0; 8], "must send zero current while offline");
+    }
+    bus.shutdown().await;
+}
+
+#[tokio::test(start_paused = true)]
+async fn current_limit_clamps_saturation() {
+    let (bus_link, mut peer) = CanLink::pair(64);
+    let mut cfg = tuned(1, 1.0);
+    cfg.current_limit = 5000;
+    let bus = spawn_bus(bus_link, vec![cfg], BusOptions::default()).unwrap();
+
+    send_feedback(&peer, &[1]).await;
+    bus.motor(1).unwrap().set_velocity(30000.0); // 不可达目标 → 深度饱和
+    sleep(Duration::from_millis(5)).await;
+
+    let mut saw_saturated = false;
+    for _ in 0..5 {
+        bus.motor(1).unwrap().set_velocity(30000.0); // 续租，避免读到租约到期后的 0
+        let frame = recv_command(&mut peer).await;
+        let raw = slot_current(&frame, 0);
+        assert!(raw <= 5000, "current {raw} exceeds limit 5000");
+        saw_saturated |= raw == 5000;
+    }
+    assert!(saw_saturated, "loop should reach the configured limit");
+    bus.shutdown().await;
+}
+
+// ---------------------------------------------------------------- 命令租约
+
+/// 反馈喂食器：每 5ms 注入一帧所有电机的反馈，让电机保持"在线"，
+/// 从而把「租约到期归零」与「离线保护归零」区分开。
+fn spawn_feedback(yield_tx: mpsc::Sender<CanFrame>, esc_ids: Vec<u8>) -> JoinHandle<()> {
+    tokio::spawn(async move {
+        let mut ticker = interval(Duration::from_millis(5));
+        ticker.set_missed_tick_behavior(MissedTickBehavior::Skip);
+        let fb = EscFeedback { angle_raw: 0, speed_rpm: 0, current_raw: 0, temperature_c: 30 };
+        loop {
+            ticker.tick().await;
+            for &id in &esc_ids {
+                if yield_tx.send(encode_feedback_frame(id, &fb)).await.is_err() {
+                    return;
+                }
+            }
+        }
+    })
+}
+
+/// 一次性 `set_velocity` 在租约内出力，租约到期后必须自动归零；
+/// 重新下发又能恢复出力——这就是"命令是租约"契约的可执行规范。
+#[tokio::test(start_paused = true)]
+async fn command_lease_expires_and_renews() {
+    let (bus_link, mut peer) = CanLink::pair(256);
+    let feeder = spawn_feedback(peer.outgoing_tx.clone(), vec![1]);
+    let bus = spawn_bus(bus_link, vec![tuned(1, 1.0)], BusOptions::default()).unwrap();
+    let motor = bus.motor(1).unwrap().clone();
+
+    // 1) 下发后 30ms 内（< 50ms 租约）应看到非零电流。
+    motor.set_velocity(3000.0);
+    let mut live = false;
+    for _ in 0..30 {
+        if slot_current(&recv_command(&mut peer).await, 0) != 0 {
+            live = true;
+            break;
+        }
+    }
+    assert!(live, "租约内应输出非零电流");
+
+    // 2) 沉默 200ms（> 50ms 租约）→ 必须强制归零。
+    sleep(Duration::from_millis(200)).await;
+    // 排空沉默期间积压的帧：其中前段仍带着租约到期前的旧命令。
+    while peer.incoming_rx.try_recv().is_ok() {}
+    sleep(Duration::from_millis(10)).await;
+    for _ in 0..5 {
+        let raw = slot_current(&recv_command(&mut peer).await, 0);
+        assert_eq!(raw, 0, "租约到期后必须归零，实测 {raw}");
+    }
+
+    // 3) 续租 → 恢复出力。
+    motor.set_velocity(3000.0);
+    let mut renewed = false;
+    for _ in 0..30 {
+        if slot_current(&recv_command(&mut peer).await, 0) != 0 {
+            renewed = true;
+            break;
+        }
+    }
+    assert!(renewed, "续租后应恢复非零电流");
+
+    feeder.abort();
+    bus.shutdown().await;
+}
+
+// ---------------------------------------------------------------- 组帧与路由
+
+#[tokio::test(start_paused = true)]
+async fn current_commands_route_to_group_slots() {
+    let (bus_link, mut peer) = CanLink::pair(256);
+    let configs = (1..=5).map(|id| tuned(id, 1.0)).collect();
+    let bus = spawn_bus(bus_link, configs, BusOptions::default()).unwrap();
+
+    bus.motor(3).unwrap().set_effort_raw(1234);
+    bus.motor(5).unwrap().set_effort_raw(-567);
+    send_feedback(&peer, &(1..=5).collect::<Vec<_>>()).await;
+    sleep(Duration::from_millis(5)).await;
+
+    let mut saw_200 = false;
+    let mut saw_1ff = false;
+    for _ in 0..20 {
+        // 续租两条直发命令，避免读到租约到期后的 0 槽。
+        bus.motor(3).unwrap().set_effort_raw(1234);
+        bus.motor(5).unwrap().set_effort_raw(-567);
+        let frame = recv_command(&mut peer).await;
+        match frame.id {
+            0x200 if !saw_200 => {
+                assert_eq!(frame.data, [0, 0, 0, 0, 0x04, 0xD2, 0, 0], "esc3 slot = 1234");
+                saw_200 = true;
+            }
+            0x1FF if !saw_1ff => {
+                // -567 = 0xFDC9（i16 补码，大端）。
+                assert_eq!(frame.data, [0xFD, 0xC9, 0, 0, 0, 0, 0, 0], "esc5 slot = -567");
+                saw_1ff = true;
+            }
+            _ => {}
+        }
+        if saw_200 && saw_1ff {
+            break;
+        }
+    }
+    assert!(saw_200, "no 0x200 frame observed");
+    assert!(saw_1ff, "no 0x1FF frame observed");
+
+    // disable 后槽位清零。
+    bus.motor(3).unwrap().disable();
+    let zeroed = wait_until(200, || {
+        try_find_frame(&mut peer, |frame| frame.id == 0x200 && slot_current(frame, 2) == 0)
+    })
+    .await;
+    assert!(zeroed, "esc3 slot should return to 0 after disable");
+    bus.shutdown().await;
+}
+
+/// 非阻塞地扫一眼通道里已有的帧。
+fn try_find_frame(peer: &mut CanLink, pred: impl Fn(&CanFrame) -> bool) -> bool {
+    while let Ok(frame) = peer.incoming_rx.try_recv() {
+        if pred(&frame) {
+            return true;
+        }
+    }
+    false
+}
+
+// ---------------------------------------------------------------- 反馈 → 状态
+
+#[tokio::test]
+async fn feedback_updates_state_with_direction() {
+    let (bus_link, peer) = CanLink::pair(64);
+    let bus = spawn_bus(bus_link, vec![tuned(2, -1.0)], BusOptions::default()).unwrap();
+
+    // 两帧正向跨圈：8000 → 100，电调侧圈数 ≈ 1.0122。
+    let fb = EscFeedback { angle_raw: 8000, speed_rpm: 600, current_raw: -300, temperature_c: 47 };
+    peer.outgoing_tx.send(encode_feedback_frame(2, &fb)).await.unwrap();
+    let fb2 = EscFeedback { angle_raw: 100, ..fb };
+    peer.outgoing_tx.send(encode_feedback_frame(2, &fb2)).await.unwrap();
+    sleep(Duration::from_millis(50)).await;
+
+    let st = bus.motor(2).unwrap().state();
+    assert_eq!(st.rotor_angle_raw, 100);
+    assert!((st.rotor_speed_rpm + 600.0).abs() < 1e-3); // direction = -1
+    assert_eq!(st.effort_raw, 300);
+    assert_eq!(st.temperature_c, 47);
+    assert_eq!(st.feedback_count, 2);
+    let esc_rev = 1.0 + 100.0 / 8192.0;
+    assert!(
+        (st.rotor_revolutions + esc_rev).abs() < 1e-3,
+        "revolutions = {}",
+        st.rotor_revolutions
+    );
+    // 输出轴换算由 `OutputShaft` 负责（见 motor-core gearbox 单测）。
+    bus.shutdown().await;
+}
+
+// ---------------------------------------------------------------- 生命周期
+
+#[tokio::test(start_paused = true)]
+async fn shutdown_stops_tasks_and_closes_link() {
+    let (bus_link, mut peer) = CanLink::pair(128);
+    // 不接 plant，直接验证任务生命周期。
+    let bus = spawn_bus(bus_link, vec![tuned(1, 1.0)], BusOptions::default()).unwrap();
+    bus.motor(1).unwrap().set_velocity(1000.0);
+    sleep(Duration::from_millis(20)).await;
+    // 有命令帧在流动。
+    assert!(peer.incoming_rx.recv().await.is_some());
+
+    bus.shutdown().await;
+    // 排空残留缓冲帧后应立即得到 None（发送端已全部退出）；
+    // 若任务仍在运行，帧会持续流入并触发超时。
+    loop {
+        match timeout(Duration::from_millis(100), peer.incoming_rx.recv()).await {
+            Ok(None) => break,
+            Ok(Some(_)) => {} // 排空残留缓冲帧
+            Err(elapsed) => panic!("bus tasks still running after shutdown (waited {elapsed:?})"),
+        }
+    }
+}
+
+#[test]
+fn spawn_rejects_bad_configs() {
+    let link = || CanLink::pair(8).0;
+    assert_eq!(spawn_bus(link(), vec![], BusOptions::default()).err(), Some(EscBusError::NoMotors));
+    assert_eq!(
+        spawn_bus(link(), vec![tuned(2, 1.0), tuned(2, -1.0)], BusOptions::default()).err(),
+        Some(EscBusError::DuplicateEscId(2))
+    );
+    let mut bad = tuned(1, 1.0);
+    bad.direction = 0.0;
+    let err = spawn_bus(link(), vec![bad], BusOptions::default()).err();
+    assert!(
+        matches!(err, Some(EscBusError::InvalidConfig { .. })),
+        "expected InvalidConfig, got {err:?}"
+    );
+}
+
+// ---------------------------------------------------------------- 增益热更新
+
+/// 自动整定的真机后端靠这条路径逐次试验：不重启总线，只换增益。
+/// 契约：① 读取即得到最新增益；② 换增益后控制器**状态复位**（无旧积分残留）；
+/// ③ 限幅等安全字段不受影响。
+#[tokio::test(start_paused = true)]
+async fn velocity_gains_can_be_hot_swapped() {
+    let (bus_link, plant_link) = CanLink::pair(256);
+    let plant = spawn_plant(plant_link, &[1], Duration::from_millis(1));
+    let cfg = tuned(1, 1.0);
+    let limit = i32::from(cfg.current_limit);
+    let bus = spawn_bus(bus_link, vec![cfg.clone()], BusOptions::default()).unwrap();
+    let motor = bus.motor(1).unwrap().clone();
+
+    // ① 初始增益来自 EscConfig（含前馈）。
+    assert_eq!(bus.with_policy(|policy| policy.velocity_gains(motor.id()).unwrap()), tuned_gains());
+
+    // 让旧增益的积分先积累起来（大静差 + 深度饱和）。
+    motor.set_velocity(9000.0);
+    hold(&motor, 9000.0, 200).await;
+    let stale = bus.with_policy(|policy| policy.velocity_gains(motor.id()).unwrap());
+
+    // ② 热更新：控制器被重建。
+    let swapped = VelocityGains::new(1.0, 0.0, 0.0, 0.0);
+    bus.with_policy(|policy| policy.set_velocity_gains(motor.id(), swapped));
+    assert_eq!(bus.with_policy(|policy| policy.velocity_gains(motor.id()).unwrap()), swapped);
+    assert_ne!(bus.with_policy(|policy| policy.velocity_gains(motor.id()).unwrap()), stale);
+
+    // 新增益生效：误差 e 时输出 = kp·e = e（无前馈、无积分），并仍被限幅夹住。
+    motor.set_velocity(30_000.0);
+    let saturated =
+        hold_until(500, &motor, 30_000.0, || i32::from(motor.state().effort_raw) >= limit).await;
+    assert!(saturated, "effort = {} 未达到限幅 {}", motor.state().effort_raw, limit);
+
+    // ③ 限幅仍是启动时的 current_limit：热更新不得放宽安全边界。
+    let effort = i32::from(motor.state().effort_raw);
+    assert_eq!(effort, limit, "饱和值必须正好是 current_limit");
+    assert_eq!(
+        bus.with_policy(|policy| policy.velocity_gains(motor.id()).unwrap()),
+        swapped,
+        "热更新后增益保持不变"
+    );
+
+    plant.abort();
+    bus.shutdown().await;
+}

crates/esc-bus/tests/harness_parity.rs

@@ -0,0 +1,102 @@
+//! 语义一致性：同步评估 harness 与异步 `EscBus` 闭环必须给出同一个答案。
+//!
+//! 自动整定跑在 [`sim_harness::simulate`]（同步、无通道）上，而实车跑的是
+//! `EscBus` 的 1 kHz 发送循环。若两者的限幅 / 物理帧 / 控制器语义漂移，
+//! 整定出来的增益就只是"对仿真有效"。本测试把两条路径放在同一组参数与
+//! 同一条场景下比较稳态与 effort。
+//!
+//! 允许的差异来自**离散化细节**（异步侧每拍实测 `dt`、反馈比命令晚一拍），
+//! 因此比较的是稳态量级而不是逐点相等。
+
+#![allow(clippy::unwrap_used, clippy::expect_used)]
+
+use std::time::Duration;
+
+use can::CanLink;
+use esc_bus::{BusOptions, EscBus, EscConfig};
+use experiment::Scenario;
+use motor::{MotorFeedback, VelocityDrive};
+use motor_control::{MotorPolicy, VelocityGains};
+use motor_model::PlantParams;
+use sim_harness::{LoopLimits, simulate, spawn_plant};
+use tokio::time::sleep;
+
+/// 与 `PlantParams::gm3508` 匹配的增益（ff = 16384 / 9254）。
+const GAINS: VelocityGains = VelocityGains::new(8.0, 2.0, 0.0, 16384.0 / 9254.0);
+const TARGET_RPM: f32 = 3000.0;
+const HOLD_MS: u64 = 2000;
+/// 稳态采样窗口（虚拟时间，毫秒）。
+const SAMPLE_FROM_MS: u64 = 1500;
+
+/// 同步路径：最后 500 ms 的稳态统计。
+fn sync_steady_state() -> (f32, f32) {
+    let scenario = Scenario::step(TARGET_RPM, HOLD_MS as f32 / 1000.0);
+    let trace = simulate(GAINS, &PlantParams::gm3508(), &scenario, LoopLimits::gm3508())
+        .expect("simulation must succeed");
+    let window = trace.window(SAMPLE_FROM_MS as f32 / 1000.0, HOLD_MS as f32 / 1000.0);
+    let mean_effort =
+        window.effort_raw().iter().map(|&raw| f32::from(raw)).sum::<f32>() / window.len() as f32;
+    (window.mean_rpm(), mean_effort)
+}
+
+/// 异步路径：`EscBus` + 假电调，逐拍续租直到 2 秒（虚拟时间）。
+async fn async_steady_state() -> (f32, f32) {
+    let (bus_link, plant_link) = CanLink::pair(512);
+    let plant = spawn_plant(plant_link, &[1], Duration::from_millis(1));
+    let mut cfg = EscConfig::gm3508("front_left", 1, 1.0);
+    cfg.current_limit = LoopLimits::gm3508().current_limit_raw;
+    let mut policy = MotorPolicy::new();
+    policy.configure(cfg.esc_id, cfg.current_limit, GAINS);
+    let bus =
+        EscBus::spawn(bus_link, vec![cfg], BusOptions::default(), policy).expect("bus must start");
+    let motor = bus.motor(1).expect("motor 1 exists").clone();
+
+    // 命令是租约：逐拍重发（5 ms 节拍模拟 1 kHz 控制循环）。
+    let mut waited = 0u64;
+    let mut effort_sum = 0.0f32;
+    let mut rpm_sum = 0.0f32;
+    let mut samples = 0u32;
+    while waited < HOLD_MS {
+        motor.set_velocity(TARGET_RPM);
+        if waited >= SAMPLE_FROM_MS {
+            let state = motor.state();
+            effort_sum += f32::from(state.effort_raw);
+            rpm_sum += state.rotor_speed_rpm;
+            samples += 1;
+        }
+        sleep(Duration::from_millis(5)).await;
+        waited += 5;
+    }
+
+    plant.abort();
+    bus.shutdown().await;
+    (rpm_sum / samples as f32, effort_sum / samples as f32)
+}
+
+#[tokio::test(start_paused = true)]
+async fn synchronous_harness_matches_async_closed_loop() {
+    let (sync_rpm, sync_effort) = sync_steady_state();
+    let (async_rpm, async_effort) = async_steady_state().await;
+
+    // 稳态转速：两条路径都应收敛到目标附近（理想模型 + 精确前馈 → 稳态无差）。
+    let rpm_tolerance = 0.05 * TARGET_RPM;
+    assert!(
+        (sync_rpm - async_rpm).abs() < rpm_tolerance,
+        "steady rpm mismatch: sync {sync_rpm}, async {async_rpm}"
+    );
+    assert!(
+        (sync_rpm - TARGET_RPM).abs() < rpm_tolerance,
+        "sync steady state off target: {sync_rpm}"
+    );
+    assert!(
+        (async_rpm - TARGET_RPM).abs() < rpm_tolerance,
+        "async steady state off target: {async_rpm}"
+    );
+
+    // effort：前馈主导，两条路径量级必须接近（±20% 或 ±300 raw 取大者）。
+    let effort_tolerance = (0.2 * sync_effort.abs()).max(300.0);
+    assert!(
+        (sync_effort - async_effort).abs() < effort_tolerance,
+        "steady effort mismatch: sync {sync_effort}, async {async_effort}"
+    );
+}