diff --git a/doc/index.rst b/doc/index.rst index a3439895..fdf0c6d8 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -400,3 +400,78 @@ This uses the effort command interface for the cart's degree of freedom on the r ros2 launch gz_ros2_control_demos pendulum_example_position.launch.py ros2 run gz_ros2_control_demos example_position + + +Creating a Custom Launch File +============================= + +To get started with your own launch file using `gz_ros2_control`, refer to the example launch files in the repository: + +`Example launch files `_ + +Basic Elements +-------------- + +1. **Launching the Gazebo simulator** + +You can use the ``gz_sim.launch.py`` file provided by ``gz_ros2_control`` to launch Gazebo. Here's an example: + +.. code-block:: python + + gz_sim = IncludeLaunchDescription( + PythonLaunchDescriptionSource(gz_sim_launch), + launch_arguments={ + 'gz_args': ['-r -v4 empty.sdf'], + 'on_exit_shutdown': 'true' + }.items() + ) + +Explanation of flags: + +- ``-r``: Starts the simulator immediately. +- ``-v4``: Sets the logging verbosity to level 4. + +2. **Launching the ros_gz_bridge and publishing the `/clock` topic** + +It is essential to publish the ``/clock`` topic for the ``controller_manager`` to function correctly: + +.. code-block:: python + + gz_bridge = Node( + package="ros_gz_bridge", + executable="parameter_bridge", + arguments=['/clock@rosgraph_msgs/msg/Clock[gz.msgs.Clock'], + parameters=[{ + "qos_overrides./tf_static.publisher.durability": "transient_local" + }], + output="screen", + ) + +.. warning:: + + If you **do not** publish the ``/clock`` topic, the ``controller_manager`` will issue warnings or errors such as: + + .. code-block:: console + + [gazebo-1] [WARN] [1744219953.983130822] [controller_manager]: No clock received, using time argument instead! Check your node's clock configuration (use_sim_time parameter) and if a valid clock source is available. + +Timing Issues +------------- + +By default, the ``controller_manager`` launched by ``gz_ros2_control`` has ``use_sim_time=true``. If for any reason this is set to ``false``, it will fall back to the system clock. + +This results in logs like: + +.. code-block:: console + + [gazebo-1] [INFO] [1744209678.974210234] [gz_ros_control]: Loading controller_manager + [gazebo-1] [INFO] [1744209679.000651931] [controller_manager]: Using Steady (Monotonic) clock for triggering controller manager cycles. + +Eventually leading to a fatal error: + +.. code-block:: console + + [gazebo-1] terminate called after throwing an instance of 'std::runtime_error' + [gazebo-1] what(): can't compare times with different time sources + +Ensure ``use_sim_time`` is correctly set to ``true`` when working with simulation time to avoid such mismatches.