🔄 Angular Velocity Calibration

1. Course Introduction

Verify the rotation angle calculation accuracy of the A1 Pro chassis wheel odometry (computed from the chassis MCU encoder and front wheel steering mechanism), and perform precise calibration of the angular velocity scale correction factor.

🎯 Course Objectives

1. Understand the angular velocity calibration principle and calculation formulas based on the Ackermann steering chassis

2. Master the calibration operation process using the calibrate_angular_A1P node combined with ground angle markers

3. Master the persistence method for writing the optimal angular velocity correction factor to the low-level driver parameter configuration file a1_driver.yaml

2. Preparation

2.1 Start the Chassis Comprehensive Driver

Open a terminal and run the following command to start all A1 Pro chassis drivers and the EKF fusion localization node:

ros2 launch yahboomcar_bringup yahboomcar_bringup_A1_launch.py

2.2 Prepare Ground Initial Markers

• Use tape to lay out a crosshair or a clear reference direction line on open ground;

• Place the robot on the marked line with the vehicle's longitudinal center axis strictly parallel to the reference line, and record the initial heading direction.

3. Calibration Process

3.1 Start the Angular Velocity Calibration Program

Run the calibration test node in a new terminal:

xxxxxxxxxx
ros2 run yahboomcar_bringup calibrate_angular_A1P

The calibration node will listen to the real-time rotation quaternion from odom -> base_footprint in the TF tree and convert it to yaw angle.

3.2 Trigger Rotation Test

In another terminal, trigger the test via ROS 2 dynamic parameters:

xxxxxxxxxx
ros2 param set /calibrate_angular start_test True

The default test target angle is 360° (one full circle). The robot will turn counterclockwise in a circular path while moving forward with a preset angular velocity (default 1.0 rad/s). When the odometry accumulated rotation angle reaches 360°, the robot will automatically decelerate and stop.

3.3 Compare with Actual Physical Angle on Ground

After the robot comes to a complete stop, observe the angle between the robot's current physical heading and the initial reference direction line on the ground:

• Ideal state: The vehicle has rotated exactly one full circle (360°), and the heading direction is perfectly parallel and aligned with the ground reference line;

• Under-rotated (actual rotation < 360°): The heading stopped before reaching the target position;

• Over-rotated (actual rotation > 360°): The vehicle stopped after rotating past the reference line.

3.4 Calculate and Dynamically Adjust the Correction Factor

The calibration program and chassis driver accumulate rotation angle by integrating angular velocity. The angle increment is multiplied by the correction factor (i.e., determined rotation angle = raw angular displacement × correction factor):

• Writing a factor greater than 1.0: Angular velocity feedback is amplified, and the odometry considers the vehicle to be rotating faster, reaching 360° earlier and stopping earlier (the actual physical rotation angle of the robot becomes smaller);

• Writing a factor less than 1.0: Angular velocity feedback is reduced, and the odometry considers the vehicle to be rotating slower, delaying the stop (the actual physical rotation angle of the robot becomes larger).

Therefore, based on the actual physical rotation angle on the ground and the expected target angle (360°), the new correction factor calculation formula is:

xxxxxxxxxx
New Correction Factor = Current Factor × (Actual Physical Rotation Angle / Target Rotation Angle)

Parameter Adjustment Examples and Calculations:

• Scenario 1: Over-rotated (actual rotation angle > 360°) Target rotation set to 360.0°, current factor is 1.0, robot rotated past the reference line and stopped at 370.0° (over-rotated by 10°):

  xxxxxxxxxx
  New Factor = 1.0 × (370.0 / 360.0) ≈ 1.0278 (increase the factor)
  

  After increasing the factor from 1.0 to 1.0278, the odometry accumulation becomes faster, the robot will brake and stop earlier, and the actual rotation angle will decrease accordingly, stopping precisely on the 360° reference line.

• Scenario 2: Under-rotated (actual rotation angle < 360°) Target rotation set to 360.0°, current factor is 1.0, robot stopped early at 350.0° before reaching the target (still 10° short):

  xxxxxxxxxx
  New Factor = 1.0 × (350.0 / 360.0) ≈ 0.9722 (decrease the factor)
  

  After decreasing the factor from 1.0 to 0.9722, the odometry accumulation becomes slower, and the robot needs to rotate a bit more to reach 360°, thus compensating for the angle and precisely aligning with the reference line.

Dynamically set the new factor via command line (example of increasing to 1.0278):

xxxxxxxxxx
ros2 param set /calibrate_angular odom_angular_scale_correction 1.0278

3.5 Multiple Verifications and Convergence

Move the robot back to the starting point and align with the reference line. Run ros2 param set /calibrate_angular start_test True again. Observe whether the robot's heading precisely aligns with the initial reference line when it stops with the new factor applied. Repeat until the visual physical angle error is within 2°.

4. Persist the Correction Factor to Driver Configuration

After calibration, to ensure the low-level driver automatically applies the settings on every boot or launch, write the optimal calibrated factor to the driver_node parameter configuration file:

Parameter file path:

xxxxxxxxxx
$HOME/yahboomcar_ros2_ws/yahboomcar_ws/src/yahboomcar_bringup/param/a1_driver.yaml

Open a1_driver.yaml, find the odom_angular_scale_z configuration item and modify it to the final calibrated value (e.g., 1.0278):

xxxxxxxxxx
driver_node:
  ros__parameters:
    # ...
    # Chassis angular velocity odometry scale correction factor (new calibrated value)
    odom_linear_scale_x: 1.0
    odom_angular_scale_z: 1.0278
    # ...

xxxxxxxxxx
cd ~/yahboomcar_ros2_ws/yahboomcar_ws
colcon build --packages-select yahboomcar_bringup
source install/setup.bash

5. Using rqt_reconfigure for GUI Parameter Tuning

In addition to the command line, you can also use rqt_reconfigure provided by ROS 2 for visual real-time parameter tuning and test triggering:

xxxxxxxxxx
ros2 run rqt_reconfigure rqt_reconfigure

5.1 Calibration Node Parameter Description

The /calibrate_angular node panel contains the following key parameters:

6. Core Source Code and Algorithm Principle Analysis

Source code path:

xxxxxxxxxx
$HOME/yahboomcar_ros2_ws/yahboomcar_ws/src/yahboomcar_bringup/yahboomcar_bringup/calibrate_angular_A1P.py

6.1 Angle Integration and Closed-Loop Control Logic

xxxxxxxxxx
def on_timer(self):
    if self.is_testing:
        current_angle = self.get_odom_angle() # Get current yaw angle from TF
        if current_angle is None:
            return
        
        # 1. Normalize angle increment and accumulate with correction factor
        delta = self.normalize_angle(current_angle - self.last_angle)
        self.turn_angle += delta * odom_scale
        self.last_angle = current_angle
        
        target = test_angle * self.direction
        error = target - self.turn_angle
        
        # 2. Ackermann chassis linear velocity + angular velocity coordinated control
        if abs(error) > tolerance:
            move_cmd = Twist()
            move_cmd.linear.x = abs(linear_speed)       # Maintain forward linear velocity
            move_cmd.angular.z = copysign(speed, error) # Steering angular velocity
            self.cmd_vel_pub.publish(move_cmd)
        else:
            # 3. Target rotation angle reached, publish stop
            self.cmd_vel_pub.publish(Twist())
            self.is_testing = False

6.2 Source Code and Driver Activation Mechanism Analysis

• Why increasing the correction factor actually results in smaller rotation: In the calibration program, the accumulated rotation angle condition is turn_angle = sum(delta) * odom_scale. When the robot stops, the actual rotation angle of the odometry is target / odom_scale. Therefore, when odom_scale > 1.0 (increased factor), the denominator becomes larger for the actual required rotation angle, and the vehicle only needs to rotate a smaller angle for the program to determine the target is reached and stop; conversely, when odom_scale < 1.0 (decreased factor), the vehicle must rotate a larger angle to reach the target.

• Low-level driver activation mechanism: In Ackman_driver_A1P.py, the driver node scales the angular velocity feedback with angular_z * odom_angular_scale_z in real time, and participates in the trapezoidal dead-reckoning _integrate_and_publish_odom. After persisting the angular velocity calibration factor to a1_driver.yaml, it can significantly improve the heading accumulation drift issue during Nav2 path tracking and rotation obstacle avoidance.