diff --git a/ur_simulation_gz/doc/index.rst b/ur_simulation_gz/doc/index.rst new file mode 100644 index 0000000..da09385 --- /dev/null +++ b/ur_simulation_gz/doc/index.rst @@ -0,0 +1,19 @@ +ur_simulation_gz +================ + +This package contains configurations and example files for Gazebo simulation of Universal Robots manipulators. + +Structure of the repository +--------------------------- + +To set up the simulation the used files are: + +- ``urdf/ur_gz.ros2_control.xacro`` - macro for ros2_control configuration, defining the initial joint positions and the hardware interface plugin for the simulation +- ``urdf/ur_gz.urdf.xacro`` - main file that contains the robot description, defines reference for the Gazebo world and initializes ros2_control Gazebo plugin. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + installation + usage diff --git a/ur_simulation_gz/doc/installation.rst b/ur_simulation_gz/doc/installation.rst new file mode 100644 index 0000000..2c4a505 --- /dev/null +++ b/ur_simulation_gz/doc/installation.rst @@ -0,0 +1,49 @@ +Installation +============ + +Skip any of below steps is not applicable. + +Setup ROS2 Workspace +-------------------- + +1. Create a colcon workspace: + +.. code-block:: console + + $ export COLCON_WS=~/workspaces/ur_gz + $ mkdir -p $COLCON_WS/src + +.. note:: + Feel free to change ``~/workspaces/ur_gz`` to whatever absolute path you want. + +.. note:: + + Over time you will probably have multiple ROS workspaces, so it makes sense to them all in a subfolder. + + Also, it is good practice to put the ROS version in the name of the workspace, for different tests you could just add a suffix to the base name ``ur_gz``. + +2. Download the required repositories and install package dependencies: + +.. code-block:: console + + $ cd $COLCON_WS + $ git clone -b ros2 https://github.com/UniversalRobots/Universal_Robots_ROS2_GZ_Simulation.git src/ur_simulation_gz + $ vcs import --input src/ur_simulation_gz/ur_simulation_gz-not-released.rolling.repos src # only required for rolling + $ rosdep update && rosdep install --ignore-src --from-paths src -y + +Configure and build Workspace +----------------------------- + +To configure and build the workspace execute following commands: + +.. code-block:: console + + $ source /opt/ros/rolling/setup.bash # necessary after installing gz-sim-vendor + $ cd $COLCON_WS + $ colcon build --symlink-install + +and finally source your workspace before launching anything else + +.. code-block:: console + + $ source $COLCON_WS/install/setup.bash diff --git a/ur_simulation_gz/doc/resources/gz_simulation_custom_world.png b/ur_simulation_gz/doc/resources/gz_simulation_custom_world.png new file mode 100644 index 0000000..fb2c9f1 Binary files /dev/null and b/ur_simulation_gz/doc/resources/gz_simulation_custom_world.png differ diff --git a/ur_simulation_gz/doc/resources/gz_simulation_moveit.png b/ur_simulation_gz/doc/resources/gz_simulation_moveit.png new file mode 100644 index 0000000..701ff4f Binary files /dev/null and b/ur_simulation_gz/doc/resources/gz_simulation_moveit.png differ diff --git a/ur_simulation_gz/doc/resources/test_world.sdf b/ur_simulation_gz/doc/resources/test_world.sdf new file mode 100644 index 0000000..e87158b --- /dev/null +++ b/ur_simulation_gz/doc/resources/test_world.sdf @@ -0,0 +1,158 @@ + + + 0 0 -9.8000000000000007 + 5.5644999999999998e-06 2.2875799999999999e-05 -4.2388400000000002e-05 + + + 0.001 + 1 + 1000 + + + 0.400000006 0.400000006 0.400000006 1 + 0.699999988 0.699999988 0.699999988 1 + true + + + 0.29999999999999999 1 0.050000000000000003 0 0 0 + + + + 0.16666 + 0 + 0 + 0.16666 + 0 + 0.16666 + + 1 + 0 0 0 0 0 0 + + + + + 0.050000000000000003 0.050000000000000003 0.050000000000000003 + + + + + + + + + + + + + + 0.050000000000000003 0.050000000000000003 0.050000000000000003 + + + + 0.300000012 0.300000012 0.300000012 1 + 0.699999988 0.699999988 0.699999988 1 + 1 1 1 1 + + + 0 0 0 0 0 0 + false + + true + false + + + 0 1 0.050000000000000003 0 0 0 + + + + 0.16666 + 0 + 0 + 0.16666 + 0 + 0.16666 + + 1 + 0 0 0 0 0 0 + + + + + 0.050000000000000003 0.050000000000000003 0.050000000000000003 + + + + + + + + + + + + + + 0.050000000000000003 0.050000000000000003 0.050000000000000003 + + + + 0.300000012 0.300000012 0.300000012 1 + 0.699999988 0.699999988 0.699999988 1 + 1 1 1 1 + + + 0 0 0 0 0 0 + false + + true + false + + + -0.29999999999999999 1 0.050000000000000003 0 0 0 + + + + 0.16666 + 0 + 0 + 0.16666 + 0 + 0.16666 + + 1 + 0 0 0 0 0 0 + + + + + 0.050000000000000003 0.050000000000000003 0.050000000000000003 + + + + + + + + + + + + + + 0.050000000000000003 0.050000000000000003 0.050000000000000003 + + + + 0.300000012 0.300000012 0.300000012 1 + 0.699999988 0.699999988 0.699999988 1 + 1 1 1 1 + + + 0 0 0 0 0 0 + false + + true + false + + + diff --git a/ur_simulation_gz/doc/resources/ur_controllers_test.yaml b/ur_simulation_gz/doc/resources/ur_controllers_test.yaml new file mode 100644 index 0000000..24f7461 --- /dev/null +++ b/ur_simulation_gz/doc/resources/ur_controllers_test.yaml @@ -0,0 +1,37 @@ +controller_manager: + ros__parameters: + update_rate: 500 # Hz + + joint_state_broadcaster: + type: joint_state_broadcaster/JointStateBroadcaster + + joint_trajectory_controller: + type: joint_trajectory_controller/JointTrajectoryController + + +joint_trajectory_controller: + ros__parameters: + joints: + - alice_shoulder_pan_joint + - alice_shoulder_lift_joint + - alice_elbow_joint + - alice_wrist_1_joint + - alice_wrist_2_joint + - alice_wrist_3_joint + command_interfaces: + - position + state_interfaces: + - position + - velocity + state_publish_rate: 100.0 + action_monitor_rate: 20.0 + allow_partial_joints_goal: false + constraints: + stopped_velocity_tolerance: 0.2 + goal_time: 0.0 + alice_shoulder_pan_joint: { trajectory: 0.2, goal: 0.1 } + alice_shoulder_lift_joint: { trajectory: 0.2, goal: 0.1 } + alice_elbow_joint: { trajectory: 0.2, goal: 0.1 } + alice_wrist_1_joint: { trajectory: 0.2, goal: 0.1 } + alice_wrist_2_joint: { trajectory: 0.2, goal: 0.1 } + alice_wrist_3_joint: { trajectory: 0.2, goal: 0.1 } diff --git a/ur_simulation_gz/doc/usage.rst b/ur_simulation_gz/doc/usage.rst new file mode 100644 index 0000000..c468bbe --- /dev/null +++ b/ur_simulation_gz/doc/usage.rst @@ -0,0 +1,94 @@ +Usage +===== + +Launch Files +------------ + +To launch the simulation, two files can be used: + +- ``launch/ur_sim_control.launch.py`` +- ``launch/ur_sim_moveit.launch.py`` + +They both start Gazebo, but only the second launches MoveIt! together with it, allowing to plan motions using either MoveGroup interfaces or the Motion Planning panel in Rviz. + +So, if only Gazebo and Rviz are needed: + +.. code-block:: console + + $ ros2 launch ur_simulation_gz ur_sim_control.launch.py ur_type:=ur10e + +Which can be tested by using a test script from ``ur_robot_driver`` (if installed), in a new terminal: + +.. code-block:: console + + $ ros2 launch ur_robot_driver test_joint_trajectory_controller.launch.py + +If we also want to be able to use MoveIt!, then: + +.. code-block:: console + + $ ros2 launch ur_simulation_gz ur_sim_moveit.launch.py ur_type:=ur10e + +.. image:: resources/gz_simulation_moveit.png + :width: 95% + :alt: Gazebo with MoveIt! + +.. note:: + + All the additional launch arguments are described in the launch files themselves. + +Customization +------------- + +Beyond the default usage, the package offers some customization options. + +Custom Description +^^^^^^^^^^^^^^^^^^ + +To use a custom robot / scene description, the launch argument ``description_file`` can be specified, which allows to pass the absolute path of a custom description to both launchers. Together with it, it could be useful to choose a custom Rviz configuration file and the launch argument ``rviz_config_file`` can be passed for that. An example of their usage: + +.. code-block:: console + + $ ros2 launch ur_simulation_gz ur_sim_control.launch.py ur_type:=ur10e description_file:="/home/ubuntu/ur_gz_test.urdf.xacro" rviz_config_file:="/home/ubuntu/rviz_test.rviz" + +tf_prefix +^^^^^^^^^ + +Also here, like in the driver package, it is possible to specify a tf_prefix using the ``tf_prefix`` launch argument, but for this package this is not the only step required. Since controller loading is handled differently, it is necessary to define a custom controllers file with the desired tf_prefix. Assuming ``tf_prefix:="alice_"``, an example of such file could be: + +.. literalinclude:: resources/ur_controllers_test.yaml + :language: yaml + :emphasize-lines: 15-20, 32-37 + +To load the newly defined file, it is possible to specify its absolute path with the ``controllers_file`` argument. Together with it the desired prefix should be also be specified as argument, like in the following example: + +.. code-block:: console + + $ ros2 launch ur_simulation_gz ur_sim_control.launch.py ur_type:=ur10e tf_prefix:="alice_" controllers_file:="/home/ubuntu/ur_controllers_test.yaml" + +.. note:: + + The ``tf_prefix`` argument is not available for ``ur_sim_moveit.launch.py``, since it would require a custom definition of the moveit config package for properly setting it up. + +Custom World +^^^^^^^^^^^^ + +The last customization option allows to instantiate the robot in a proper setup instead of an empty world, like the given launch files do by default. The first step to create a complete simulation is to define a world file (.sdf): for this example we can use a simple custom world ``test_world.sdf``, located it in ``ur_gz_simulation/doc/resources``. For more details about building worlds in Gazebo, it's possible to check the `related tutorial `_. +To use the new world changes it's enough to specify its absolute path in the ``world_file`` argument: + + +.. code-block:: console + + $ ros2 launch ur_simulation_gz ur_sim_control.launch.py ur_type:=ur10e world_file:=/doc/resources/test_world.sdf + +or using MoveIt! + +.. code-block:: console + + $ ros2 launch ur_simulation_gz ur_sim_moveit.launch.py ur_type:=ur10e world_file:=/doc/resources/test_world.sdf + +In this way, when launching the simulation, Gazebo will use the indicated custom world instead of the default empty, like in the following picture. + +.. image:: resources/gz_simulation_custom_world.png + :width: 95% + :alt: Gazebo custom world