doc/robotics: clarify wheel_diameter, axle_track

Add tips for practical experiments to validate the dimensions

doc/api/robotics.rst

@@ -10,7 +10,8 @@
 
     .. rubric:: Driving for a given distance or by an angle
 
-    Use these commands to drive a given distance, or turn by a given angle.
+    Use the following commands to drive a given distance, or turn by a
+    given angle.
 
     This is measured using the internal rotation sensors. Because wheels may
     slip while moving, the traveled distance and angle are only estimates.
@@ -57,3 +58,33 @@
 
     .. autoattribute:: pybricks.robotics.DriveBase.heading_control
         :annotation:
+
+    .. rubric:: Measuring and validating the robot dimensions
+
+    As a first estimate, you can measure the ``wheel_diameter`` and the
+    ``axle_track`` with a ruler. Because it is hard to see where the wheels
+    effectively touch the ground, you can estimate the ``axle_track`` as
+    the distance between the midpoint of the wheels.
+
+    In practice, most wheels compress slightly under the weight of your robot.
+    To verify, make your robot drive 1000 mm using ``my_robot.straight(1000)``
+    and measure how far it really traveled. Compensate as follows:
+
+        - If your robot drives **not far enough**, **decrease** the
+          ``wheel_diameter`` value slightly.
+        - If your robot drives **too far**, **increase** the
+          ``wheel_diameter`` value slightly.
+
+    Motor shafts and axles bend slightly under the load of the
+    robot, causing the ground contact point of the wheels to be closer to the
+    midpoint of your robot. To verify, make your robot turn 360 degrees
+    using ``my_robot.turn(360)`` and check that it is back in the same place:
+
+        - If your robot turns **not far enough**, **increase** the
+          ``axle_track`` value slightly.
+        - If your robot turns **too far**, **decrease** the ``axle_track``
+          value slightly.
+
+    When making these adjustments, always adjust the
+    ``wheel_diameter`` first, as done above. Be sure to test both turning
+    and driving straight after you are done.

pybricks/robotics.py

@@ -42,8 +42,8 @@ class DriveBase:
             right_motor (Motor):
                 The motor that drives the right wheel.
             wheel_diameter (:ref:`dimension`): Diameter of the wheels.
-            axle_track (:ref:`dimension`): Distance between the midpoints of
-                                           the two wheels.
+            axle_track (:ref:`dimension`): Distance between the points where
+                both wheels touch the ground.
         """
 
     def drive(self, drive_speed, turn_rate):