repository·rolling·Indexed 43 days ago
https://github.com/universalrobots/universal_robots_ros2_descriptionOfficial ROS 2 description files (URDF/Xacro) and 3D meshes for Universal Robots manipulators. Provides kinematic and visual representations for simulation and visualization tools like RViz, supporting Humble, Jazzy, and Rolling distributions. Includes Xacro macros for robot parameterization, integration with ros2_control, and detailed specifications for robot base frames, flange, and tool0.
The ur_description package no longer automatically adds the ros2_control tag to the robot's URDF. This responsibility has moved to the driver or simulation repositories.
While the ros2_control tag is removed from the description package, ur_description still provides:
mock_hardware with the robot.The URDF model utilizes three distinct frames at the robot's base to satisfy ROS standards, controller compatibility, and kinematic library requirements. Understanding which one to use is critical for accurate coordinate transformations.
base_link: The root link of the kinematic chain. It follows REP-103, where the forward direction is defined as the direction the arm points in an all-zero joint configuration.base: The frame used by the robot controller (Polyscope 5/X) to represent the Base feature. It shares the same position as base_link but is rotated by 180 degrees around the Z-axis (following REP-199).base as your reference frame, not base_link.base_link_inertia: A frame used to hold meshes and inertia data. Because some libraries (like KDL) do not support inertia on the root link, the base_link is kept empty, and all mass/geometry properties are attached to base_link_inertia. This frame has the same rotation as base.Kinematic Chain Structure:
base_link
├ base
└ base_link_inertia
└ shoulder_link
└ upper_arm_link
└ forearm_link
└ wrist_1_link
└ wrist_2_link
└ wrist_3_link
├ flange
└ tool0The ur_description package uses Xacro macros to provide kinematic and visual descriptions of Universal Robots manipulators. Instead of defining each robot model from scratch, you should include the urdf/ur_macro.xacro macro in your own project. This macro allows you to parameterize the robot using specific configuration files for kinematics, joint limits, physical parameters, and visual meshes.
To properly configure a robot, you must pass the paths to four specific configuration files as arguments to the macro:
kinematics_params (points to a default_kinematics.yaml or equivalent).joint_limit_params (points to a joint_limits.yaml).physical_params (points to a physical_parameters.yaml for simulation tuning like inertia).visual_params (points to a visual_params.yaml for mesh selection).An example of a standalone robot scene can be found in urdf/ur.urdf.xacro.
<!-- Example of how the macro is typically used in an external project -->
<xacro:include filename="$(find ur_description)/urdf/ur_macro.xacro" />
<xacro:ur_robot
kinematics_params="$(find ur_description)/config/ur5e/default_kinematics.yaml"
joint_limit_params="$(find ur_description)/config/ur5e/joint_limits.yaml"
physical_params="$(find ur_description)/config/ur5e/physical_parameters.yaml"
visual_params="$(find ur_description)/config/ur5e/visual_params.yaml" />The package provides macros to help integrate Universal Robots with ros2_control. While the specific control method (Driver, Gazebo, or Mock) is defined in the respective control repository, ur_description provides the necessary building blocks:
urdf/inc/ur_joint_control.xacro: Macro for describing the joints' control structure (interfaces).urdf/inc/ur_sensors.xacro: Macro for describing the robot's sensors for ros2_control.urdf/ros2_control_mock_hardware.xacro: A complete Xacro providing the control description specifically for mock_hardware.urdf/ur_mocked.urdf.xacro: An example file combining the kinematic description with the control description for a controlled robot.When attaching custom tools or end-effectors to the robot, choose between the flange and tool0 frames based on your requirements:
flange: The intended frame for attaching custom tool frames or end-effectors. If you are using a gripper's xacro:macro, you should typically specify flange as the parent_frame.tool0: The tool frame as calculated via forward kinematics. In an all-zero tool configuration, this frame is equivalent to the tool frame shown on the control box/teach pendant.The URDF now expects mesh offsets to be defined with all 6 degrees of freedom (DOF). The visual_parameters.yaml files must contain the full mesh_offset entries for all 6 dimensions.
Old visual_parameters.yaml files that do not contain the complete 6-DOF structure will not be accepted by the URDF parser and must be updated.
Mesh offsets for the shoulder and elbow, which were previously located in physical_parameters.yaml, have been moved to the visual_parameters.yaml files.
When updating your configuration, ensure that mesh offsets are now defined within the visual_parameters.yaml context.
launch/view_ur.launch.xml provides an abstraction for quickly visualizing a robot. Instead of manually passing four different configuration file paths, you can use a single ur_type argument. The launch file uses this argument to automatically resolve the paths to the correct urXX configuration directories.To visualize a robot model, install this repository into your ROS 2 workspace and use the ur_description launch file. You can specify which robot model to display by passing the ur_type argument to the launch command.
Example for a UR5e robot:
ros2 launch ur_description view_ur.launch.xml ur_type:=ur5eTo visualize a different model, replace ur5e with the desired ur_type (e.g., ur3e, ur5, ur10e, etc.).
In recent versions of ur_description, the shoulder_radius: ... and similar joint radius definitions have been removed from the physical_parameters.yaml files. Consequently, the parsing logic for these parameters has also been removed from urdf/inc/ur_common.xacro.
If you are maintaining a modified version of the package, ensure you are not attempting to use old physical_parameters.yaml files with the new parser, as this will cause failures.
The repository supports multiple ROS 2 distributions. Ensure you are using the correct branch for your installed distribution:
humble branch.jazzy branch.rolling branch.Released packages for these distributions can be found on the ROS index.