improve docs around usage of extracted calibration info (#1214)

Author: cpsiff

ur_robot_driver/doc/installation/robot_setup.rst

@@ -69,11 +69,11 @@ Prepare the ROS PC
 For using the driver make sure it is installed (either by the debian package or built from source
 inside a colcon workspace).
 
+.. _calibration_extraction:
+
 Extract calibration information
 -------------------------------
 
-.. _calibration_extraction:
-
 Each UR robot is calibrated inside the factory giving exact forward and inverse kinematics. To also
 make use of this in ROS, you first have to extract the calibration information from the robot.
 
@@ -87,5 +87,11 @@ For this, there exists a helper script:
    $ ros2 launch ur_calibration calibration_correction.launch.py \
    robot_ip:=<robot_ip> target_filename:="${HOME}/my_robot_calibration.yaml"
 
+.. note::
+   The robot must be powered on (can be idle) before executing this script.
+
+
 For the parameter ``robot_ip`` insert the IP address on which the ROS pc can reach the robot. As
 ``target_filename`` provide an absolute path where the result will be saved to.
+
+See :ref:`ur_robot_driver_startup` for instructions on using the extracted calibration information.

ur_robot_driver/doc/usage/startup.rst

@@ -28,6 +28,7 @@ Allowed ``ur_type`` strings: ``ur3``, ``ur3e``, ``ur5``, ``ur5e``, ``ur10``, ``u
 Other important arguments are:
 
 
+* ``kinematics_params_file`` (default: *None*) - Path to the calibration file extracted from the robot, as described in :ref:`calibration_extraction`.
 * ``use_mock_hardware`` (default: *false* ) - Use simple hardware emulator from ros2_control. Useful for testing launch files, descriptions, etc.
 * ``headless_mode`` (default: *false*) - Start driver in :ref:`headless_mode`.
 * ``launch_rviz`` (default: *true*) - Start RViz together with the driver.
@@ -72,6 +73,31 @@ Depending on the :ref:`robot control mode<operation_modes>` do the following:
 
 .. _continuation_after_interruptions:
 
+Verify calibration info is being used correctly
+-----------------------------------------------
+
+.. _verify_calibration:
+
+If you passed a path to an extracted calibration via the *kinematics_params_file*
+parameter, ensure that the loaded calibration matches that of the robot by inspecting the console
+output after launching the ``ur_robot_driver``. If the calibration does not match, you will see an error:
+
+.. code-block::
+
+  [INFO] [1694437690.406932381] [URPositionHardwareInterface]: Calibration checksum: 'calib_xxxxxxxxxxxxxxxxxxx'
+  [ERROR] [1694437690.516957265] [URPositionHardwareInterface]: The calibration parameters of the connected robot don't match the ones from the given kinematics config file.
+
+With the correct calibration you should see:
+
+.. code-block::
+
+  [INFO] [1694437690.406932381] [URPositionHardwareInterface]: Calibration checksum: 'calib_xxxxxxxxxxxxxxxxxxx'
+  [INFO] [1694437690.516957265] [URPositionHardwareInterface]: Calibration checked successfully.
+
+Alternatively, search for the term *checksum* in the console output after launching the driver.
+Verify that the printed checksum matches that on the final line of your extracted calibration file.
+
+
 Continuation after interruptions
 --------------------------------