steervo: pot over-travel + convergence-watchdog protections

Protect the steering pot (which rips off its coupling if driven past range):
- OVER_TRAVEL fault (new STEER_STATUS fault bit 0x40): keyed on the RAW pot
  crossing beyond a calibrated end stop + margin, since pot_to_angle_cdeg
  clamps the reported angle and would otherwise hide an over-travel. Latches
  hard if it happens while ACTIVE; refuses to start the motor if already past.
- Convergence watchdog: reframe stall detection from "did the pot move?" to
  "is |error| shrinking?", so a motor pushing while error grows (inverted-sign
  runaway) faults too — not just a jammed motor.

steervo host tests 28/28 (3 new). can-ids.md documents the new fault bit.

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

Author: Ballistyxx

docs/protocols/can-ids.md

@@ -61,7 +61,7 @@ fault bit `SETPOINT_STALE`, and stays in READY until fresh frames resume.
 | Offset | Size | Field | Notes |
 |---|---|---|---|
 | 0 | 1 | `state` | 0 INIT · 1 READY · 2 ACTIVE · 3 FAULT · 4 CALIBRATING |
-| 1 | 1 | `fault_bits` | bit0 `POT_RANGE` · bit1 `POT_FROZEN` · bit2 `STALL` · bit3 `SETPOINT_STALE` · bit4 `TALON_LOST` · bit5 `NOT_CALIBRATED` |
+| 1 | 1 | `fault_bits` | bit0 `POT_RANGE` · bit1 `POT_FROZEN` · bit2 `STALL` · bit3 `SETPOINT_STALE` · bit4 `TALON_LOST` · bit5 `NOT_CALIBRATED` · bit6 `OVER_TRAVEL` (pot driven past a calibrated end stop — latched) |
 | 2 | 2 | `measured_cdeg` (int16) | Current angle from the pot (calibrated). |
 | 4 | 1 | `output_pct` (int8) | Motor command, −100…+100. |
 | 5 | 1 | `seq_echo` (uint8) | `seq` of the last accepted `STEER_SET`. |

firmware/common/kart_common/kart_can.h

@@ -94,6 +94,7 @@ constexpr uint8_t kSteerFaultStall = 1 << 2;
 constexpr uint8_t kSteerFaultSetpointStale = 1 << 3;
 constexpr uint8_t kSteerFaultTalonLost = 1 << 4;
 constexpr uint8_t kSteerFaultNotCalibrated = 1 << 5;
+constexpr uint8_t kSteerFaultOverTravel = 1 << 6;  // pot past a calibrated stop
 
 struct SteerStatus {
   SteerState state;

firmware/steervo/lib/steervo/steer_controller.cpp

@@ -83,6 +83,14 @@ bool SteerController::on_cal(kart::SteerCalCmd cmd, uint16_t pot_raw) {
   return false;
 }
 
+bool SteerController::raw_over_travel(uint16_t raw) const {
+  if (!cal_.valid) return false;
+  int32_t lo = cal_.raw_left < cal_.raw_right ? cal_.raw_left : cal_.raw_right;
+  int32_t hi = cal_.raw_left < cal_.raw_right ? cal_.raw_right : cal_.raw_left;
+  int32_t m = cfg_.over_travel_margin_raw;
+  return (int32_t)raw < lo - m || (int32_t)raw > hi + m;
+}
+
 int16_t SteerController::clamp_to_soft_limits(int16_t setpoint_cdeg) const {
   int32_t lo = cal_.angle_left_cdeg + cfg_.soft_limit_margin_cdeg;
   int32_t hi = cal_.angle_right_cdeg - cfg_.soft_limit_margin_cdeg;
@@ -104,6 +112,16 @@ float SteerController::tick(uint32_t now_ms, uint16_t pot_raw) {
     measured_cdeg_ = pot_to_angle_cdeg(cal_, pot_raw);
   }
 
+  // Over-travel: the steering went past a calibrated end stop. If the motor was
+  // actively driving, this is a hard latched fault (it should have held inside
+  // the soft limits) — cut power and require inspection. If the motor was not
+  // driving (e.g. hand-moved during setup), don't latch, but block activation
+  // below until the pot comes back inside range.
+  bool over_travel_now = raw_over_travel(pot_raw);
+  if (over_travel_now && state_ == kart::SteerState::kActive) {
+    over_travel_fault_ = true;
+  }
+
   if (hard_faulted()) {
     state_ = kart::SteerState::kFault;
     last_output_ = 0.0f;
@@ -132,7 +150,8 @@ float SteerController::tick(uint32_t now_ms, uint16_t pot_raw) {
     enable_ = false;
   }
 
-  bool want_active = enable_ && fresh && cal_.valid;
+  // Never (re)start the motor while the pot is sitting past a stop.
+  bool want_active = enable_ && fresh && cal_.valid && !over_travel_now;
   if (!want_active) {
     if (state_ == kart::SteerState::kActive) {
       pid_.reset();
@@ -149,30 +168,33 @@ float SteerController::tick(uint32_t now_ms, uint16_t pot_raw) {
   float error = (float)(target - measured_cdeg_);
   float out = pid_.update(error, 10);  // caller runs a fixed 100 Hz tick
 
-  // Stall detection: sustained near-saturated output with no movement.
+  // Convergence watchdog: while pushing hard the |error| must keep shrinking.
+  // A jammed motor (no movement) holds |error| constant; a wrong-way runaway
+  // (e.g. inverted feedback sign / swapped motor leads) grows it. Either way,
+  // if we push for stall_timeout_ms without making stall_min_delta_cdeg of
+  // progress, fault and cut the motor — this catches a runaway *before* it
+  // reaches a stop, in addition to the over-travel guard above.
+  int32_t abs_err = error < 0.0f ? (int32_t)-error : (int32_t)error;
   bool pushing = (out > cfg_.stall_output_frac * cfg_.output_limit) ||
                  (out < -cfg_.stall_output_frac * cfg_.output_limit);
   if (pushing) {
     if (!stall_window_open_) {
       stall_window_open_ = true;
       stall_window_start_ms_ = now_ms;
-      stall_window_start_cdeg_ = measured_cdeg_;
-    } else {
-      int16_t delta = (int16_t)(measured_cdeg_ - stall_window_start_cdeg_);
-      if (delta < 0) delta = (int16_t)-delta;
-      if (delta >= cfg_.stall_min_delta_cdeg) {
-        // It is moving; restart the window.
-        stall_window_start_ms_ = now_ms;
-        stall_window_start_cdeg_ = measured_cdeg_;
-      } else if ((uint32_t)(now_ms - stall_window_start_ms_) >=
-                 cfg_.stall_timeout_ms) {
-        stall_fault_ = true;
-        state_ = kart::SteerState::kFault;
-        pid_.reset();
-        stall_window_open_ = false;
-        last_output_ = 0.0f;
-        return 0.0f;
-      }
+      stall_window_start_abserr_ = abs_err;
+    } else if (stall_window_start_abserr_ - abs_err >=
+               cfg_.stall_min_delta_cdeg) {
+      // Error is shrinking: the loop is converging. Restart the window.
+      stall_window_start_ms_ = now_ms;
+      stall_window_start_abserr_ = abs_err;
+    } else if ((uint32_t)(now_ms - stall_window_start_ms_) >=
+               cfg_.stall_timeout_ms) {
+      stall_fault_ = true;
+      state_ = kart::SteerState::kFault;
+      pid_.reset();
+      stall_window_open_ = false;
+      last_output_ = 0.0f;
+      return 0.0f;
     }
   } else {
     stall_window_open_ = false;
@@ -186,6 +208,7 @@ uint8_t SteerController::fault_bits() const {
   uint8_t bits = 0;
   if (pot_range_fault_) bits |= kart::kSteerFaultPotRange;
   if (stall_fault_) bits |= kart::kSteerFaultStall;
+  if (over_travel_fault_) bits |= kart::kSteerFaultOverTravel;
   if (setpoint_stale_) bits |= kart::kSteerFaultSetpointStale;
   if (talon_lost_) bits |= kart::kSteerFaultTalonLost;
   if (!cal_.valid) bits |= kart::kSteerFaultNotCalibrated;

firmware/steervo/lib/steervo/steer_controller.h

@@ -27,8 +27,13 @@ struct SteerConfig {
   int16_t soft_limit_margin_cdeg = 100;
   uint32_t setpoint_timeout_ms = kart::kSteerSetTimeoutMs;
   uint32_t stall_timeout_ms = 800;
-  float stall_output_frac = 0.9f;   // of output_limit
-  int16_t stall_min_delta_cdeg = 25;
+  float stall_output_frac = 0.9f;       // of output_limit
+  int16_t stall_min_delta_cdeg = 25;    // min error improvement to "still converging"
+  // Pot protection: a raw reading this far beyond a calibrated end stop means
+  // the steering has been driven past its safe range (the #1 way to rip the
+  // pot off its coupling). Caught on the RAW value because pot_to_angle_cdeg
+  // clamps the reported angle at the stops and would otherwise hide it.
+  uint16_t over_travel_margin_raw = 80;
 };
 
 class SteerController {
@@ -63,8 +68,13 @@ class SteerController {
   int16_t measured_cdeg() const { return measured_cdeg_; }
 
  private:
-  bool hard_faulted() const { return pot_range_fault_ || stall_fault_; }
+  bool hard_faulted() const {
+    return pot_range_fault_ || stall_fault_ || over_travel_fault_;
+  }
   int16_t clamp_to_soft_limits(int16_t setpoint_cdeg) const;
+  // True when the raw pot is beyond a calibrated end stop by more than the
+  // over-travel margin (only meaningful once calibrated).
+  bool raw_over_travel(uint16_t raw) const;
 
   SteerConfig cfg_;
   Pid pid_;
@@ -76,6 +86,7 @@ class SteerController {
   // fault-clear path via STEER_CAL).
   bool pot_range_fault_ = false;
   bool stall_fault_ = false;
+  bool over_travel_fault_ = false;
   // Soft conditions
   bool setpoint_stale_ = false;
   bool talon_lost_ = false;
@@ -90,10 +101,13 @@ class SteerController {
   int16_t measured_cdeg_ = 0;
   float last_output_ = 0.0f;
 
-  // Stall detection window
+  // Convergence watchdog window: while the motor pushes hard, the |error| must
+  // keep shrinking. If it does not (jammed = stall, or growing = wrong-way
+  // runaway) for stall_timeout_ms, fault. Tracks the |error| the window opened
+  // at; resets whenever the loop makes stall_min_delta_cdeg of progress.
   bool stall_window_open_ = false;
   uint32_t stall_window_start_ms_ = 0;
-  int16_t stall_window_start_cdeg_ = 0;
+  int32_t stall_window_start_abserr_ = 0;
 
   // In-progress calibration capture (committed to cal_ on SAVE_EXIT).
   PotCalibration cal_capture_{0, 0, 0, 0, 0, false};

firmware/steervo/test/test_steer_controller/test_steer_controller.cpp

@@ -197,6 +197,73 @@ void test_movement_resets_stall_window() {
   }
 }
 
+void test_runaway_wrong_way_faults() {
+  // Motor pushes (saturated) but the pot moves AWAY from the target: an
+  // inverted-sign runaway. The convergence watchdog must fault even though the
+  // pot IS moving (the old movement-only stall check would have missed this).
+  SteerConfig cfg;
+  cfg.kp = 1.0f;  // saturate on any error
+  cfg.stall_timeout_ms = 800;
+  SteerController c(cfg);
+  c.set_calibration(test_cal());
+  c.tick(0, 2048);
+
+  uint16_t pot = 2048;  // 0 deg
+  bool faulted = false;
+  uint32_t t = 10;
+  for (; t < 2000; t += 10) {
+    feed_setpoint(c, 1000, t);  // want +10 deg (right of center)
+    c.tick(t, pot);
+    // Runaway: drifts left (away from the +target), staying inside the pot
+    // range so this is the watchdog firing, not over-travel / pot-range.
+    if (t % 50 == 0 && pot > 1600) pot -= 10;
+    if (c.state() == SteerState::kFault) {
+      faulted = true;
+      break;
+    }
+  }
+  TEST_ASSERT_TRUE(faulted);
+  TEST_ASSERT_TRUE(c.fault_bits() & kart::kSteerFaultStall);
+  TEST_ASSERT_TRUE(t >= cfg.stall_timeout_ms);
+}
+
+// -------------------- over-travel (pot protection) --------------------
+
+void test_over_travel_while_active_is_latched_fault() {
+  SteerController c = make_ready();
+  feed_setpoint(c, 1500, 105);
+  c.tick(110, 2048);
+  TEST_ASSERT_EQUAL((int)SteerState::kActive, (int)c.state());
+
+  // Pot driven past the right stop (raw_right=3072, margin 80 -> >3152),
+  // still a plausible ADC reading (not a rail), so this is over-travel.
+  feed_setpoint(c, 1500, 118);
+  TEST_ASSERT_EQUAL_FLOAT(0.0f, c.tick(120, 3200));
+  TEST_ASSERT_EQUAL((int)SteerState::kFault, (int)c.state());
+  TEST_ASSERT_TRUE(c.fault_bits() & kart::kSteerFaultOverTravel);
+  TEST_ASSERT_FALSE(c.fault_bits() & kart::kSteerFaultPotRange);  // not a rail
+
+  // Latched: a return to a valid in-range reading does not clear it.
+  feed_setpoint(c, 0, 130);
+  TEST_ASSERT_EQUAL_FLOAT(0.0f, c.tick(140, 2048));
+  TEST_ASSERT_EQUAL((int)SteerState::kFault, (int)c.state());
+}
+
+void test_over_travel_while_idle_blocks_activation_without_latching() {
+  SteerController c = make_ready();  // READY, motor never driven
+  // Pot sitting past the stop while idle (e.g. hand-moved during setup).
+  feed_setpoint(c, 1500, 105);
+  TEST_ASSERT_EQUAL_FLOAT(0.0f, c.tick(110, 3200));
+  TEST_ASSERT_EQUAL((int)SteerState::kReady, (int)c.state());  // refused, not faulted
+  TEST_ASSERT_FALSE(c.fault_bits() & kart::kSteerFaultOverTravel);
+
+  // Back inside range: the motor may now activate (no latch held it down).
+  feed_setpoint(c, 1500, 120, 1);
+  float out = c.tick(125, 2048);
+  TEST_ASSERT_EQUAL((int)SteerState::kActive, (int)c.state());
+  TEST_ASSERT_TRUE(out > 0.0f);
+}
+
 // -------------------- status reporting --------------------
 
 void test_status_reflects_state_and_seq_echo() {
@@ -280,6 +347,9 @@ int main(int, char **) {
   RUN_TEST(test_setpoint_clamped_to_soft_limits);
   RUN_TEST(test_stall_faults_after_sustained_saturated_output);
   RUN_TEST(test_movement_resets_stall_window);
+  RUN_TEST(test_runaway_wrong_way_faults);
+  RUN_TEST(test_over_travel_while_active_is_latched_fault);
+  RUN_TEST(test_over_travel_while_idle_blocks_activation_without_latching);
   RUN_TEST(test_status_reflects_state_and_seq_echo);
   RUN_TEST(test_calibration_sequence_commits_and_enables);
   RUN_TEST(test_incomplete_calibration_does_not_commit);