Stop “Ghost Commands” on Bad Wi-Fi: ros2_kinematic_guard for `/cmd_vel` safety
Detects stale commands and burst jitter where traditional heartbeats fail.
ZC Liu's ros2_kinematic_guard addresses a critical safety gap for ROS 2 mobile robots operating over unreliable Wi-Fi or 5G links—'ghost commands' that arrive late or in bursts after the robot's state has changed. Traditional heartbeat/timeout mechanisms can detect silence but miss stale commands, burst delivery, and timing inconsistencies. The guard sits between the incoming `/cmd_vel` stream and the robot controller, maintaining a short local window of previous and current commands plus odometry. It computes a lightweight NARH-lite residual (R_NAR) that measures timing consistency, stale-command risk, acceleration/jerk limits, and command-vs-odom coherence. When R_NAR exceeds a critical threshold, the guard enters a deterministic state machine: RED_BRAKE → BRAKE_AND_RESYNC → RESYNCING. This cuts motion instantly, flushes poisoned command windows, waits for a fresh command/odom window, then releases control. At the default 20 Hz guard loop, intervention occurs within ~50 ms.
The project includes a complete 'Bad-Wi-Fi pressure test loop' with three nodes: `jitter_injector_node.py` (creates delayed/duplicated/bursty/replayed commands), `kinematic_guard_node.py` (computes R_NAR and outputs protected `safe_cmd_vel`), and `synthetic_odom_provider.py` (virtual robot body publishing `/odom`). Users can launch the test with a single command and monitor guard status topics. The guard does not modify DDS, QoS, or network settings—it adds a safety layer that catches failure modes traditional methods miss, such as stale commands (often missed by heartbeats), burst/jitter (detected via residual spikes), and stale replay (detected via timing + odom conflict). For teams running mobile robots over unreliable links, this offers a practical, drop-in safety mechanism without complex middleware tuning.
- Guards against stale commands, burst jitter, and timing inconsistencies using a NARH-lite residual metric.
- State machine brakes and resyncs within 50ms at 20Hz guard loop, cutting motion when unsafe.
- Includes a jitter injector and synthetic odometry for testing without a real robot.
Why It Matters
For ROS 2 robots on unstable networks, ensures safe motion by filtering unsafe commands in real-time.