Universal_Robots_ROS2_Description

This repository contains description files and meshes for Universal Robots manipulators.

Build status

ROS2 Distro	Branch	Build status	Released packages
Humble	humble		ur_description
Iron	iron		ur_description
Jazzy	rolling		ur_description
Rolling	rolling		ur_description

A more detailed build status shows the state of all CI workflows inside this repo. Please note that the detailed view is intended for developers, while the one here should give end users an overview of the current released state.

License

The UR20 meshes and UR30 meshes constitutes “Graphical Documentation” the use of which is subject to and governed by our “Terms and Conditions for use of Graphical Documentation”.

Universal Robots’ Terms and Conditions for use of Graphical Documentation do not fully comply with OSI’s definition of Open Source, but they do allow you to use, modify and share “Graphical Documentation”, including UR20 and UR30 meshes, subject to certain restrictions.
If you have any questions regarding this license or if this license doesn’t fit your use-case, please contact legal@universal-robots.com.

All other content is licensed under the BSD-3-Clause license

Structure of the repository

The most relevant files are:

• urdf/ur_macro.xacro - macro file with UR-manipulator description. This file is usually included into external projects to visualize and configure UR manipulators properly. An example how to use this macro is in urdf/ur.urdf.xacro file.
• urdf/ur.ros2_control.xacro - definition of manipulator’s joints and interfaces for ros2_control framework.

Testing description of a manipulator

To visualize the robot install this repository to you workspace and execute the following:

ros2 launch ur_description view_ur.launch.py ur_type:=ur5e

To test other descriptions change the ur_type argument.

Package / Description structure

This package uses one description for all robots. The different robot variants are configured using four configuration files. These files can also be changed for further customizing a description.

Basically, the description can be modified using configuration values stored in four files:

• config/urXX/default_kinematics.yaml - This contains the calibration values as they can be extracted from the robot. Changing these values with the one extracted from a real robot will result in a description matching the real robot exactly (w.r.t the tool0 frame). It is highly recommended to use matching kinematic values in real-world applications.
• config/urXX/joint_limits.yaml - If you’d like to further restrict the robot’s joint limits, these limits can be modified there.
• config/urXX/physical_parameters.yaml - Everything regarding physics simulation parameters (e.g. inertia poses and values) can be tuned here
• config/urXX/visual_parameters.yaml - Some users change certain visual aspects, e.g. replacing the cap on the wrist_3_link. This config file specifies which meshes (both, visual and collision) should be used.

The four configuration files have to be passed to ur_macro.urdf (more specific to the macro defined in that file) which is done inside the ur.urdf.xacro. Contents of the files are parsed inside ur_common.xacro.

Arguments that have to be passed to the main ur.urdf.xacro file are:

• kinematics_params - Filename to the default_kinematics.yaml (or equivalent specific kinematics) file
• joint_limit_params - Filename to the joint_limits.yaml file
• physical_params - Filename to the physical_parameters.yaml file
• visual_params - Filename to the visual_params.yaml file

The launchfile launch/view_ur.launch.py abstracts these four parameters to one ur_type argument which will basically replace the urXX part of the paths as shown in the picture above.

Creating your own description including this description

In real-world applications you will most probably have a more complex description consisting of more objects than just the robot. It is recommended to create a separate ROS package containing this particular description. Inside this description you could also store your robot-specific kinematics parameters file.

As mentioned above, see the urdf/ur.urdf.xacro file as an example to integrate a UR robot into your scene description. Basically, you could create a copy of that file and extend it with the modifications from your specific scene.

Contributing Guidelines

Thank you for your interest in contributing to Universal_Robots_ROS2_Description. Whether it’s a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.

Please read through this document before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution.

Reporting Bugs/Feature Requests

We welcome you to use the GitHub issue tracker to report bugs or suggest features.

When filing an issue, please check [existing open][issues], or [recently closed][closed-issues], issues to make sure somebody else hasn’t already reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:

• A reproducible test case or series of steps
• The version of our code being used
• Any modifications you’ve made relevant to the bug
• Anything unusual about your environment or deployment

Contributing via Pull Requests

Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:

1. You are working against the latest source on the master branch.
2. You check existing open, and recently merged, pull requests to make sure someone else hasn’t addressed the problem already.
3. You open an issue to discuss any significant work - we would hate for your time to be wasted.

To send us a pull request, please:

1. Fork the repository.
2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
3. Ensure local tests pass.
4. Commit to your fork using clear commit messages.
5. Send a pull request, answering any default questions in the pull request interface.
6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.

GitHub provides additional documentation on forking a repository and creating a pull request.

Licensing

Any contribution that you make to this repository will be under the 3-Clause BSD License, as dictated by that license.