Docs Reference Workspace repo
Docs menu

Troubleshooting

Problems seen on the cars, by symptom, with the cause and the fix, and the method that finds most faults quickly.

Start with the doctor. Most problems in this list are one of its checks:

ros2 run racerbot_doctor doctor

A drive command passes through a fixed chain of topics. Echo each one in order while driving with LB held; the first one that stays silent or stays at zero is where the chain breaks.

ros2 topic echo /joy --field buttons        # LB is index 4
ros2 topic echo /teleop --field drive       # manual commands
ros2 topic echo /drive --field drive        # autonomy commands
ros2 topic echo /ackermann_cmd --field drive
ros2 topic echo /commands/motor/speed
ros2 topic echo /commands/servo/position

If the last two change with the input, ROS is working and the fault is below it: the battery, the VESC’s power or firmware settings, or the wiring. Check the topic chain before suspecting hardware. On these cars, several apparent hardware faults turned out to be two publishers on one topic.

By symptom

Symptom Cause Fix
Holding LB does nothing and /joy is silent The F710 is in DirectInput mode, which creates no joystick device; or the user is not in the input group Set the switch to X and restart bringup. sudo usermod -aG input $USER, then log out and in.
/joy publishes but LB never shows 1 at index 4 A different gamepad layout Check the button and axis numbers with ros2 topic echo /joy before assuming them
An autonomy node publishes /drive but the car never moves, with no errors teleop_launch.py is running, and /teleop always wins at the mux Stop teleop. Run one control layer.
/ackermann_cmd stays at zero with no teleop running LB is not held, or the node’s /joy is stale Hold LB. Check ros2 topic hz /joy.
The servo does nothing while the VESC connects with fault_code: 0 Servo output is disabled in the VESC’s own firmware settings Stop bringup, connect VESC Tool over USB, enable the servo output under App Settings, write it, restart bringup. ROS cannot change this setting.
The servo twitches when a test command is published by hand Two publishers on one topic: teleop’s neutral command and the manual one Stop ackermann_to_vesc_node before publishing raw commands, or test through the gamepad
Permission denied on /dev/sensors/vesc or /dev/input/js0 The terminal’s session started before the user joined the group Open a new login session
pkill -f joy_teleop also stops joy_node and bringup joy_node’s command line contains joy_teleop.yaml Stop control layers with Ctrl+C. To stop one node by pattern, use pkill -f "__node:=joy_teleop".
Package ... not found The terminal has not sourced the workspace Source both setup files
A mapping run saved the racing line but no map.pgm map_saver timed out between /map updates, every 5 s The run retries three times and continues. Rebuild the map from the saved pose graph if needed.
auto_map_race_launch.py never moves: waiting for waypoints_file to be loaded gap_follow_node exited, so no lap was recorded ros2 node list to confirm, then read why it exited. One cause: corner_speed above max_speed.
A mapping run refuses to hand over to pure pursuit The racing line is too tight for the planner’s steering limit, or too close to a wall Read the numbers it reports. A refusal on a tight course is correct.
slam_toolbox starts but no map frame appears No scans or no odom transform reaching it Check ros2 topic hz /scan and ros2 run tf2_ros tf2_echo odom base_link
The particle filter aborts on its first scan range_libc was built without CUDA Rebuild it with WITH_CUDA=ON
/odom reads negative speed while driving forward The odometry sign fix is in both the code and the YAML, or in neither vesc_to_odom.cpp matches upstream, and the vesc_to_odom_node gain in vesc.yaml is negative
The car pulls to one side with the stick centred The servo centre is off The odometry calibration wizard’s drive-straight step
A new node’s callback never fires, though the topic is listed and its publisher runs Incompatible QoS: a reliable subscriber on a best-effort publisher, or a transient-local subscriber on a volatile one Compare both sides with ros2 topic info <topic> --verbose. See QoS and timing.
A YAML change has no effect after relaunching The workspace was built without --symlink-install, so install/ holds a copy Rebuild the package, or rebuild once with --symlink-install
imu_bridge refuses to start with Expected IMU calibration at a path The car’s imu/car.yaml is missing, or the car could not be identified See Set up the workspace
A launch stops with CarMismatchError RACERBOT_CAR names the other car on a registered Jetson unset RACERBOT_CAR in that terminal
A launch stops with UnknownCarError The Jetson is not in machines.yaml, or RACERBOT_CAR is unset on a development computer Set RACERBOT_CAR=rb1 or rb2 on a development computer; register a new Jetson’s serial
A launch stops with TuningOverlayError A file in the car’s tuning/ folder relaxes a safety setting or lacks a # why: comment Fix the tuning file. The guard is never turned off.
/imu/status reads fault A failed gravity check, an all-zero IMU, or stale data; reason names which See IMU fusion
The car stops with mpc_miss_latched Three late or failed MPC solves in a row Release LB and press it again. If it repeats, check top for CPU load. See MPC.
The race never starts: the filter never reaches the start pose The car is not on the saved start spot See Race a saved map

Problems specific to one algorithm are on that algorithm’s page: Follow the gap, Pure pursuit, SLAM and localization and IMU fusion. The workspace’s full record, with the diagnostic trail for each, is docs/troubleshooting.mdGitHub.

When something new goes wrong

  1. Run the doctor.
  2. Follow the topic chain above to find the first broken link.
  3. Record the run before trying again, so the next attempt can be compared. See Record a run.
  4. Change one thing at a time.

Checked against car 1 commit 881c409 and car 2 commit 779c060, before the two workspaces merged.