wall_clean: parameterize cruise arc by radius, not angular rate

Replace the arc_omega (rad/s) parameter with arc_radius (m) and derive the
turn rate each tick as omega = v_cruise / arc_radius. Specifying the radius
makes the arc shape independent of cruise speed: the robot traces the same
path whether it cruises fast or slow. Default arc_radius=1.5 m reproduces the
old 0.1 rad/s at the default v_cruise=0.15. Backoff retrace is unaffected (it
still uses the arc rate captured at contact). Docs updated.

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

Author: kaiaai

docs/wall-follow-bump-out.md

@@ -22,7 +22,7 @@ A 20 Hz loop cycles three states:
 
 | State | Motion | Leaves when |
 |---|---|---|
-| **CRUISE** | forward `v_cruise` + gentle **right** arc `-arc_omega` (drifting into the wall) | a bumper fires → BACKOFF |
+| **CRUISE** | forward `v_cruise` + gentle **right** arc of radius `arc_radius` (drifting into the wall) | a bumper fires → BACKOFF |
 | **BACKOFF** | **backs OUT along the arc it drove in on** (see below), for `backoff_s` | timer elapses → TURN |
 | **TURN** | rotate **left** in place at `turn_speed`, by an angle that depends on which bumper hit | angle reached → CRUISE |
 
@@ -39,7 +39,8 @@ once it's actually following the wall.
 
 ## Backing out along the entry arc
 
-CRUISE curves into the wall on an arc (radius `v_cruise/arc_omega`). On contact,
+CRUISE curves into the wall on an arc of radius `arc_radius` (turn rate
+`v_cruise/arc_radius`). On contact,
 BACKOFF **retraces that arc in reverse** rather than reversing in a straight
 line. **Why:** retracing keeps the robot on the strip of floor it just drove
 through, so pulling out of a contact is far less likely to wedge it somewhere
@@ -72,7 +73,7 @@ retunes the *running* robot with no relaunch — see the
 | `clean.<name>` | Default | Meaning |
 |---|---|---|
 | `v_cruise` | 0.15 | forward cleaning speed (m/s) |
-| `arc_omega` | 0.1 | gentle right-arc rate while cruising (rad/s) |
+| `arc_radius` | 1.5 | cruise arc radius into the wall (m); turn rate is `v_cruise/arc_radius`, so the arc shape is speed-independent |
 | `v_back` | 0.10 | back-out reverse speed (m/s) |
 | `backoff_s` | 0.5 | back-out duration (s) → distance `v_back·backoff_s` |
 | `turn_speed` | 0.7 | angular speed while turning left (rad/s) |
@@ -88,7 +89,7 @@ set at launch).
 # 1. teleop-aim the robot at the wall, then:
 ros2 launch oomwoo_clean wall_clean_bump_out.launch.py use_sim_time:=true
 # 2. tune live while it runs (persists for next launch too):
-kaia set clean.arc_omega 0.15
+kaia set clean.arc_radius 1.0
 kaia set clean.turn_left_deg 80
 ```
 

src/oomwoo_clean/launch/wall_clean_bump_out.launch.py

@@ -44,7 +44,7 @@
 # name -> built-in default; each is overridable by kaia (clean.<name>) then :=
 CLEAN_PARAMS = {
     'v_cruise': 0.15,       # forward cleaning speed (m/s)
-    'arc_omega': 0.1,        # gentle right-arc rate while cruising (rad/s)
+    'arc_radius': 1.5,       # cruise arc radius into the wall (m); omega=v_cruise/r
     'v_back': 0.10,         # backoff reverse speed (m/s)
     'backoff_s': 0.5,       # backoff duration (s)
     'turn_speed': 0.7,      # angular speed while turning left (rad/s)

src/oomwoo_clean/oomwoo_clean/wall_clean_node.py

@@ -33,8 +33,8 @@
   both       -> medium (head-on)
 
 All motion values are ROS parameters: the launch seeds them from
-`kaia set clean.*`, and they are live -- `ros2 param set /wall_clean arc_omega
-0.03` retunes the running robot without a relaunch.
+`kaia set clean.*`, and they are live -- `ros2 param set /wall_clean arc_radius
+2.0` retunes the running robot without a relaunch.
 
 Interfaces:
   subscribes  bumper_left/contact   ros_gz_interfaces/Contacts
@@ -79,7 +79,7 @@ class WallClean(Node):
     def __init__(self) -> None:
         super().__init__('wall_clean')
         self.v_cruise = self.declare_parameter('v_cruise', 0.15).value
-        self.arc_omega = self.declare_parameter('arc_omega', 0.1).value
+        self.arc_radius = self.declare_parameter('arc_radius', 1.5).value
         self.v_back = self.declare_parameter('v_back', 0.10).value
         self.backoff_s = self.declare_parameter('backoff_s', 0.5).value
         self.turn_speed = self.declare_parameter('turn_speed', 0.7).value
@@ -113,7 +113,7 @@ def __init__(self) -> None:
         self.state = CRUISE
         self.until = self.get_clock().now()
         self.create_timer(1.0 / hz, self._tick)
-        # live tuning: `ros2 param set /wall_clean arc_omega 0.03`
+        # live tuning: `ros2 param set /wall_clean arc_radius 2.0`
         self.add_on_set_parameters_callback(self._on_params)
         self.get_logger().info(
             'wall_clean: reactive right-wall cleaning -- Ctrl-C to stop')
@@ -123,8 +123,8 @@ def _on_params(self, params) -> SetParametersResult:
         for p in params:
             if p.name == 'v_cruise':
                 self.v_cruise = p.value
-            elif p.name == 'arc_omega':
-                self.arc_omega = p.value
+            elif p.name == 'arc_radius':
+                self.arc_radius = p.value
             elif p.name == 'v_back':
                 self.v_back = p.value
             elif p.name == 'backoff_s':
@@ -158,12 +158,18 @@ def _drive(self, lin, ang) -> None:
         msg.angular.z = float(ang)
         self.pub.publish(msg)
 
+    def _cruise_omega(self) -> float:
+        # Arc rate from the chosen radius: omega = v / r. Driving it from
+        # arc_radius (rather than a fixed omega) keeps the arc SHAPE constant
+        # at any cruise speed -- same path whether cruising fast or slow.
+        return self.v_cruise / max(self.arc_radius, 1e-3)
+
     def _tick(self) -> None:
         now = self.get_clock().now()
         if self.state == CRUISE:
             # forward + gentle RIGHT arc, drifting toward the wall on the right;
             # the very first leg (teleop-aimed approach) drives dead straight
-            arc = 0.0 if self._first_leg else -self.arc_omega
+            arc = 0.0 if self._first_leg else -self._cruise_omega()
             self._drive(self.v_cruise, arc)
             left = self._pressed(self._bump_left_t, now)
             right = self._pressed(self._bump_right_t, now)
@@ -178,7 +184,7 @@ def _tick(self) -> None:
             # Back OUT along the entry arc, reversed. Reversing a differential-
             # drive path exactly means negating BOTH linear and angular velocity,
             # so at the backoff speed the retrace rate is -entry_arc scaled by
-            # v_back/v_cruise (same path curvature v_cruise/arc_omega, opposite
+            # v_back/v_cruise (same path curvature, radius arc_radius, opposite
             # travel direction). A straight first leg (entry_arc 0) backs straight.
             retrace = -self._entry_arc * self.v_back / max(self.v_cruise, 1e-3)
             self._drive(-self.v_back, retrace)