System architecture

Every component of the stack is a ROS 2 node, and nodes communicate only through topics. The topic graph is therefore the whole system: nothing calls another package’s functions, and nothing shares memory. A drive command flows one way, through ackermann_mux, to the motor.

The drive chain

1. joy_node reads the F710 and publishes /joy.
2. The control layer publishes a steering angle and speed: joy_teleop on /teleop, or an autonomy node on /drive.
3. ackermann_mux chooses one input and publishes it as /ackermann_cmd.
4. ackermann_to_vesc_node converts the speed to motor ERPM and the steering angle to a servo position, using the car’s calibration from its calibration/vesc.yaml, and publishes /commands/motor/speed and /commands/servo/position.
5. vesc_driver_node sends those over USB to the VESC, which drives the motor and the steering servo.

How the mux chooses

ackermann_mux has two inputs, each with a priority and a timeout set in mux.yaml:

An input is active while its last message is less than 0.2 s old. Each time a message arrives, the mux forwards it to /ackermann_cmd only if no active input has a higher priority. So /drive reaches the motor only while /teleop has been silent for 0.2 s. When both inputs go silent, the mux publishes nothing; it does not send a zero.

joy_teleop repeats its last command at 20 Hz even with LB released, a message every 50 ms. /teleop therefore never times out while teleop_launch.py runs, which is why teleop and autonomy must never run together.

From speed and angle to motor and servo

ackermann_to_vesc_node converts each /ackermann_cmd with two straight lines, using the calibration in the /** block of the car’s calibration/vesc.yaml, which bringup loads on top of the shared vesc.yaml:

erpm_msg.data = speed_to_erpm_gain_ * cmd->drive.speed + speed_to_erpm_offset_;
servo_msg.data = steering_to_servo_gain_ * cmd->drive.steering_angle + steering_to_servo_offset_;

On car 1, a command of 2.0 m/s and 0.20 rad (left) gives $\text{ERPM}=3650\times 2.0=7300$ and $u=-0.83\times 0.20+0.366=0.200$.

vesc_driver_node then clips each command to its limits before sending it to the VESC: the servo to servo_min and servo_max, the speed to ±23,250 ERPM. It publishes the clipped servo value on /sensors/servo_position_command, so the difference between /commands/servo/position and that topic shows when the steering is being clipped.

double servo_clipped(servo_limit_.clip(servo->data));
vesc_.setServo(servo_clipped);
servo_sensor_msg.data = servo_clipped;
servo_sensor_pub_->publish(servo_sensor_msg);

Every steering limit in the workspace must fit inside the servo range, or the servo clips it without any warning in the driving node’s log. test_steering_limits_fit_servo.py checks this for each car.

Beside the chain

Everything else in the figure produces the inputs the control layer decides from, and none of it can move the car.

• Wheel odometry. vesc_driver_node publishes the VESC’s state on /sensors/core, from which vesc_to_odom_node estimates how far the car has moved and publishes /odom and the odom → base_link transform. See Wheel odometry.
• IMU. imu_bridge_node calibrates the VESC’s IMU (/sensors/imu/raw) and the BNO085 read by bno_i2c_bridge, each on its own. vehicle_state_node is the node that fuses the two IMUs, with each other and with /odom, into /odom/fused, /steering/measured and gyro odometry. See IMU fusion.
• Mapping and localization. slam_toolbox builds the map from /scan and the odom → base_link transform, and publishes /map and the map → odom transform. On a saved map, the particle filter localizes the car from /scan and /odom instead, and publishes /pf/viz/inferred_pose. See SLAM and localization.
• Watching. The dashboard, the run recorder and the doctor read topics and publish no drive command.

urg_node publishes the LiDAR’s /scan independently of everything else, and /scan, /odom and /joy reach the driving nodes directly, as the line in each blue box lists.

Two launch layers

Every mode starts with two launches in separate terminals.

The split has two consequences. Bringup can stay running while control layers are swapped, so the VESC and LiDAR connections never close. And two control layers must never run together: teleop would always win at the mux, and two autonomy nodes would fight over /drive. auto_map_race_launch.py is the one launch that starts bringup itself.

Bringup is defined in bringup_launch.pyGitHub, with its shared parameters in f1tenth_stack/config/: vesc.yaml, sensors.yaml, mux.yaml and joy_teleop.yaml. For vesc.yaml, sensors.yaml and joy_teleop.yaml it loads the car’s file of the same name from its profile’s calibration/ folder on top, so the servo map, speed gains, LiDAR connection and full-stick steering are each car’s own. Bringup stops before starting any node if the car cannot be identified, or if a USB device that belongs to the other car is plugged in.

Automatic mapping and racing

During auto_map_race_launch.py, gap_follow and pure_pursuit both run, but neither publishes on /drive. A supervisor, auto_map_race_node, forwards one of them:

The supervisor, gap_follow and pure_pursuit each keep their own LB check.

Topics

These are the topics with bringup and one control layer running.

vehicle_state_node also publishes /steering/measured and /odom/imu, which only record_run records. See IMU fusion.

To see why a car is not doing what the code says, compare /drive, /teleop and /ackermann_cmd. The first two are what each source wants, and the third is what won. Each topic’s delivery settings, rate and timeout are on QoS and timing.

Packages

The local packages are this workspace’s own code. Vendored and submodule packages come from upstream projects.

The upstream F1TENTH repositories have no Jazzy branch yet. Everything is built from their humble and humble-devel sources against Jazzy.