These docs are public and open source.Edit on GitHub
TROUBLESHOOTING / DIAGNOSTICS
SENSOR DIAGNOSTICS.
Before you swap a part, ask the car. These ROS 2 commands show whether the driver is up, which topics are live, and what each sensor is publishing. Run them on the car or from your laptop over the same network.
ros2 node listros2 topic echoRViz views
01 / IS THE STACK UP?
FIRST CHECKS.
Start with the graph. If nodes or topics are missing, the driver isn't up or your shells aren't talking to it yet.
bashros2 node list # the driver's nodes should be here ros2 topic list # /scan /drive /imu /odom /camera /joy
| Symptom | Likely cause | Fix |
|---|---|---|
| Empty node/topic list | Workspace not sourced in this shell, or the services are down. | source ~/ros2_ws/install/setup.bash + racecar service status |
| Missing ROS package | Dependencies not installed. | rosdep install --from-paths src --ignore-src -r -y |
| Port / process in use | A launch was started twice. | pkill -f ros2 # then relaunch |
02 / PROBE EACH SENSOR
PER-SENSOR CHECKS.
//LiDAR
bashros2 topic list | grep scan # is /scan there? ros2 topic echo /scan # live returns? ls -l /dev/serial/by-id/ # is the device node present?
//Camera
bashls /dev/video* # device node exists? ros2 topic list | grep image # image topics live? ros2 topic echo /camera --once # JPEG bytes; best-effort QoS ros2 topic bw /camera # bandwidth, ~3-4 MB/s when healthy
//IMU + odometry
bashros2 topic list | grep imu # /imu present? ros2 topic hz /imu # ~200 Hz when streaming ros2 topic hz /odom # ~200 Hz, moves when the wheels do
No data from a sensor usually means a loose USB lead or no power before it means a dead part. The symptom pages walk each one: LiDAR empty scan, camera no feed.
03 / SEE IT
VIEWS IN RVIZ.
When a topic is publishing but the numbers don't tell you enough, put it on screen.
bashros2 launch osracer_rviz view_lidar.launch.py # laser scan ros2 launch osracer_rviz view_image.launch.py # camera image ros2 launch osracer_debug debug_lidar.launch.py # lidar + frames ros2 launch osracer_debug debug_image.launch.py # image pipeline
04 / IT MOVES WRONG
DRIVE + STEER FAULTS.
//RC won't control the car
| Cause | Fix |
|---|---|
| Wrong mode | SWB not up. Up is manual. See Remote control. |
| Controller link | Reseat or replace the USB cable from the hub to the controller. |
//Drives the wrong way
| Cause | Fix |
|---|---|
| Motor wiring reversed | Forward gives reverse: swap any two motor leads. |
| Servo off-centre | Wheels not symmetric left/right. Re-centre on the trim, see Servo center. |
| Encoder jumps | Odometry jumps after a known distance: reseat the encoder cable. |
//Steering weak or stuck
| Cause | Fix |
|---|---|
| Servo fault | Noise or jamming, hard to turn by hand: replace with a standard PWM servo. |
| Servo power | Measure the servo supply: should be 4.8–6 V. If not, check the power module. |
| Mechanical jam | Power off and turn the wheels by hand; clear debris or a damaged bearing. |