Pre-run checklist

Run this checklist at the start of every session and after any change to code or configuration. It takes about two minutes. It supplements the club’s vehicle testing procedure (SOP-TECH-02), which governs every run on hardware.

Before power

• The battery is charged, undamaged, and handled as set out in SOP-TECH-01.
• The car is on a stand with its wheels off the ground for the first run of new or changed code.
• The F710’s switch is set to X (XInput) and the gamepad is switched on.
• Everyone present knows where the battery switch is, and one person can reach it.
• For an autonomy run, one person stands at the battery switch for the whole run.

Run the doctor

racerbot_doctor checks every device layer by layer: USB, kernel driver, device file and permissions, ROS driver process, message rate, message content. It stops at the first broken layer of each device and prints a fix for it. It only reads: it never publishes on a topic and never opens the VESC’s or LiDAR’s serial port, the camera or the gamepad, so it is safe to run at any time.

Terminal 1, the hardware drivers:

source /opt/ros/jazzy/setup.bash
source ~/racerbot-ws/install/setup.bash
ros2 launch f1tenth_stack bringup_launch.py

Terminal 2:

source /opt/ros/jazzy/setup.bash
source ~/racerbot-ws/install/setup.bash
ros2 run racerbot_doctor doctor

Why layer by layer. A device works only if every layer under it works: a ROS driver cannot publish from a device file that does not exist, and the file does not exist without the kernel driver. Checking from the bottom up, and stopping at the first failure, names the cause rather than its symptoms. An unplugged VESC fails at USB, and the doctor skips the device file, the driver process and the message rate above it, instead of reporting four failures that all mean “unplugged”.

The car is ready when the last line reads 0 FAIL. A WARN does not stop a run, but read it. Without bringup running, the doctor checks only the hardware layers and reports the ROS layers as INFO, not as failures.

The source is src/racerbot_doctor/GitHub. Every threshold is in racerbot_doctor/car.py, next to a note saying where it comes from.

Read the report

The exit code is 0 when nothing failed, 1 when something failed, and 2 when the doctor itself crashed, so scripts can use it.

What each section checks

Battery

The doctor reads the pack voltage that the VESC measures, published as voltage_input on /sensors/core. The cars use 3S LiPo packs.

The VESC sees only the total voltage, so one weak cell can hide behind a healthy total. Check cells with a balance checker before charging.

When LB does nothing

Start teleop_launch.py as well, then run the doctor while holding LB and pushing the left stick. A Drive path section follows the command hop by hop, /joy → /teleop → /ackermann_cmd → /commands/motor/speed, and names the first hop that goes quiet. If it ends with PASS motor command, ROS is working and the fault is below it: the battery switch, the ESC power or the motor wiring.

Limitations

• The doctor cannot tell whether the F710 gamepad itself is switched on, because the USB receiver looks the same either way. Press a button while ros2 topic echo /joy runs if in doubt.
• Without root it cannot see another user’s process holding the VESC’s serial port.
• The battery reading has not been checked against a multimeter.