|
1 | 1 | # Universal Robots ROS2 Driver |
2 | 2 |
|
3 | | -Alpha version of the ROS2 Universal Robots driver. Should be transferred to the Universal Robots org when ready. |
| 3 | +Beta version of the ROS2 Universal Robots driver. Should be transferred to the Universal Robots org when ready. |
4 | 4 |
|
5 | | -## General driver information |
6 | | -Driver currently only supports position joint interface which means only position-based controllers can be used with |
7 | | -the ROS2 driver. [Universal Robots Client Library](https://github.com/UniversalRobots/Universal_Robots_Client_Library) includes also |
8 | | -velocity-based control whose support will be addressed in additional development of ROS2 driver. |
9 | 5 |
|
10 | | -## Requirements |
| 6 | +## Packages in the Repository: |
11 | 7 |
|
12 | | -Follow the [instructions](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver#setting-up-a-ur-robot-for-ur_robot_driver) in the paragraph |
13 | | -[`Prepare the robot` ](https://github.com/UniversalRobots/Universal_Robots_ROS_Driver#prepare-the-robot) |
| 8 | + - `ur_bringup` - launch file and run-time configurations, e.g. controllers. |
| 9 | + - `ur_controllers` - implementations of controllers specific for UR robots. |
| 10 | + - `ur_dashboard_msgs` - package defining messages used by dashboard node. |
| 11 | + - `ur_description` - description files for the UR robots: meshes, URDF/XACRO files, etc. |
| 12 | + - `ur_moveit` - example MoveIt configuration for UR robots. |
| 13 | + - `ur_robot_driver` - driver / hardware interface for communication with UR robots. |
14 | 14 |
|
15 | | -## Build Instructions |
16 | 15 |
|
17 | | -To build this package follow the [instructions](https://index.ros.org/doc/ros2/Tutorials/Workspace/Creating-A-Workspace/) for installation of ROS2. |
| 16 | +## Getting Started |
18 | 17 |
|
19 | | -After installation create a ROS Foxy workspace: |
20 | | -``` |
21 | | -cd $HOME |
22 | | -mkdir -p ws_driver/src |
23 | | -cd ws_driver |
24 | | -source /opt/ros/$ROS_DISTRO/setup.bash |
| 18 | +1. [Install ROS2 Foxy](https://index.ros.org/doc/ros2/Installation/Foxy/Linux-Install-Debians/). |
25 | 19 |
|
26 | | -colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release |
| 20 | +2. Create a new ROS2 workspace: |
| 21 | + ``` |
| 22 | + export COLCON_WS=~/workspace/ros_ws_foxy_ur_driver |
| 23 | + mkdir -p $COLCON_WS/src |
| 24 | + ``` |
27 | 25 |
|
28 | | -``` |
| 26 | +3. Pull relevant packages, install dependencies, compile, and source the workspace by using: |
| 27 | + ``` |
| 28 | + cd $COLCON_WS |
| 29 | + git clone [email protected]:PickNikRobotics/Universal_Robots_ROS2_Driver.git src/Universal_Robots_ROS2_Driver --branch develop |
| 30 | + vcs import src --skip-existing --input src/Universal_Robots_ROS2_Driver/Universal_Robots_ROS2_Driver.repos |
| 31 | + rosdep install --ignore-src --from-paths src -y -r |
| 32 | + colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release |
| 33 | + source install/setup.bash |
| 34 | + ``` |
29 | 35 |
|
30 | | -Clone this repo into the `src/` directory, then: |
| 36 | +**NOTE**: If you are a ROS2 beginner and get lost consult the [references - section](#references). |
31 | 37 |
|
32 | | -``` |
33 | | -# Clone source-based dependencies into src/ directory |
34 | | -vcs import --skip-existing --input src/Universal_Robots_ROS2_Driver/.repos.yaml src |
35 | 38 |
|
36 | | -# Install package-based dependencies |
37 | | -rosdep install -y --rosdistro $ROS_DISTRO --ignore-src --from-paths src |
| 39 | +## How to Use the ROS2 Driver for UR Robots |
38 | 40 |
|
39 | | -# Build sources |
40 | | -source /opt/ros/$ROS_DISTRO/setup.bash |
41 | | -colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release |
42 | | -``` |
43 | | -Source the workspace: |
| 41 | +For starting the driver there are three main launch files in the `ur_bringup` package. |
44 | 42 |
|
45 | | -``` |
46 | | -cd ~/ws_driver |
47 | | -source install/setup.bash |
48 | | -``` |
| 43 | + - `ur_control.launch.py` - starts ros2_control node including hardware interface, joint state broadcaster and a controller. This launch file also starts `dashboard_client` if real robot is used. |
| 44 | + - `ur_moveit.launch.py` - start everything from `ur_control.launch.py` plus an example scenario with [MoveIt2](https://moveit.ros.org/). |
| 45 | + - `ur_dashboard_client.launch.py` - start the dashboard client for UR robots. |
49 | 46 |
|
50 | | -Start the driver: |
| 47 | +Also, there are predefined launch files for all supported types of UR robots. |
51 | 48 |
|
52 | | -``` |
53 | | -ros2 launch ur_ros2_control_demos ur5_e_system_position_only.launch.py |
54 | | -``` |
| 49 | +The arguments for launch files can be listed using `ros2 launch ur_bringup <launch_file_name>.launch.py --show-args`. |
| 50 | +The most relevant arguments are the following: |
55 | 51 |
|
56 | | -Start the `joint_state_controller`: |
| 52 | + - `ur_type` (*mandatory*) - a type of used UR robot (*ur3*, *ur3e*, *ur5*, *ur5e*, *ur10*, *ur10e*, or *ur16e*). |
| 53 | + - `robot_ip` (*mandatory*) - IP address by which the root can be reached. |
| 54 | + - `use_fake_hardware` (default: *false*) - use simple hardware emulator from ros2_control. |
| 55 | + Useful for testing launch files, descriptions, etc. See explanation below. |
| 56 | + - `fake_sensor_commands` (default: *false*) - enables setting sensor values for the hardware emulators. |
| 57 | + Useful for offline testing of controllers. |
| 58 | + - `robot_controller` (default: *joint_trajectory_controller*) - controller for robot joints to be started. |
| 59 | + Available controllers: *joint_trajectory_controller*, *scaled_joint_trajectory_controller*. |
| 60 | + Note: *joint_state_broadcaster*, *speed_scaling_state_broadcaster*, *force_torque_sensor_broadcaster*, and *io_and_status_controller* will always start. |
57 | 61 |
|
58 | | -``` |
59 | | -ros2 control load_start_controller joint_state_controller |
60 | | -``` |
| 62 | + *HINT*: list all loaded controllers using `ros2 control list_controllers` command. |
61 | 63 |
|
62 | | -Start the `forward_command_controller`: |
| 64 | +**NOTE**: The package can simulate hardware with the ros2_control `FakeSystem`. This emulator enables an environment for testing of "piping" of hardware and controllers, as well as testing robot's descriptions. For more details see [ros2_control documentation](https://ros-controls.github.io/control.ros.org/) for more details.. |
63 | 65 |
|
64 | | -``` |
65 | | -ros2 control load_start_controller forward_command_controller_position |
66 | | -``` |
| 66 | +### Example Commands for Testing the Driver |
67 | 67 |
|
68 | | -## Run a test node |
69 | | -Run a test node which will publish joint commands on /forward_command_controller_position/commands (std_msgs::msg::Float64MultiArray) |
70 | | -after checking the current joint states (to create minimal increment for safety). The node commands increment of 0.1 radians for each |
71 | | -joint. The commands are incremented in regards to /joint_states found when the node is run. |
| 68 | +1. To start the robot driver and controllers, use: |
| 69 | + ``` |
| 70 | + ros2 launch ur_bringup ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy use_fake_hardware:=true |
| 71 | + ``` |
| 72 | + For an offline test with the emulated hardware you can just copy-paste this line. |
| 73 | + To run on the hardware, write the IP address of your robot and omit the `use_fake_hardware` argument. |
72 | 74 |
|
73 | | -``` |
74 | | -ros2 run ur_ros2_control_demos test_driver |
75 | | -``` |
| 75 | + **NOTE**: If controllers are not starting automatically, i.e., the robot state is not shown in rviz, you can start them manually: |
| 76 | + ``` |
| 77 | + ros2 control load_controller --state joint_state_broadcaster |
| 78 | + ros2 control load_controller --state joint_trajectory_controller |
| 79 | + ``` |
76 | 80 |
|
77 | | -## Contributor guidelines |
78 | | -Code is auto-formatted with clang-format 10 whenever a git commit is made. Please ensure these dependencies are installed so pre-commit formatting works: |
| 81 | + To check the controllers' state use `ros2 control list_controllers` command. |
79 | 82 |
|
80 | | -`pip3 install pre-commit` |
81 | | -`sudo apt install clang-format-10` |
| 83 | +2. Send some goal to the Joint Trajectory Controller by using a demo node from [ros2_control_demos](https://github.com/ros-controls/ros2_control_demos) package by starting the following command in another terminal: |
| 84 | + ``` |
| 85 | + ros2 launch ur_bringup test_joint_trajectory_controller.launch.py |
| 86 | + ``` |
| 87 | + After a few seconds the robot should move. |
82 | 88 |
|
83 | | -Prepare the pre-commit formatting to run like this: |
| 89 | +3. To test another controller, simply define it using `robot_controller` argument: |
| 90 | + ``` |
| 91 | + ros2 launch ur_bringup ur_control.launch.py ur_type:=ur5e robot_ip:=yyy.yyy.yyy.yyy robot_controller:=scaled_joint_trajectory_controller use_fake_hardware:=true |
| 92 | + ``` |
| 93 | + And send the command using demo node: |
| 94 | + ``` |
| 95 | + ros2 launch ur_bringup test_scaled_joint_trajectory_controller.launch.py |
| 96 | + ``` |
| 97 | + After a few seconds the robot should move (or jump when using emulation). |
| 98 | + |
| 99 | +4. To test the driver with example MoveIt-setup, start `ur_control` launch file and then start MoveIt using the following command: |
| 100 | + ``` |
| 101 | + ros2 launch ur_bringup ur_moveit.launch.py ur_type:=ur5e robot_ip:="xxx.xxx" use_fake_hardware:=true |
| 102 | + ``` |
| 103 | + Now you should be able to use MoveIt Plugin in rviz2 to plan and execute trajectories with the robot. |
| 104 | + **NOTE**: This results in two instances of rviz2. You can safely close the one without *MotionPlanning* panel. |
| 105 | + |
| 106 | + If you have **issues** shows the correct configuration5 of the robot, try removing and re-adding *MotionPlanning* display. |
| 107 | + |
| 108 | + |
| 109 | +## Expected Changes in the Near Future |
84 | 110 |
|
85 | | -`pre-commit install` |
| 111 | +- Using upstream `force_torque_sensor_broadcaster` (ros-controls/ros2_controllers#152) |
| 112 | +- Trajectory control currently only supports position commands. In the future, velocity control will be added. |
| 113 | + |
| 114 | + |
| 115 | +## Contributor Guidelines |
| 116 | +Code is auto-formatted with clang-format 10 whenever a git commit is made. Please ensure these dependencies are installed so pre-commit formatting works: |
| 117 | + ``` |
| 118 | + pip3 install pre-commit |
| 119 | + sudo apt install clang-format-10 |
| 120 | + ``` |
| 121 | + |
| 122 | +Prepare the pre-commit formatting to run like this: |
| 123 | + ``` |
| 124 | + pre-commit install` |
| 125 | + ``` |
86 | 126 |
|
87 | 127 |
|
88 | | -## Stuff to add |
| 128 | +## References |
89 | 129 |
|
90 | | -1. Explation of packages |
91 | | -2. How to start: |
92 | | - - Simple simulation with FakeSystem |
93 | | - - Hardware |
| 130 | +Here are some useful references for developing with ROS2: |
94 | 131 |
|
95 | | -3. How to test: |
96 | | - - Using forward_command_controller |
97 | | - - Using joint_trajectory_controller |
| 132 | + - [Official ROS2 Tutorials](https://index.ros.org/doc/ros2/Tutorials/) |
| 133 | + * [Luanchfile](https://index.ros.org/doc/ros2/Tutorials/Launch-Files/Creating-Launch-Files/) |
| 134 | + * [Package](https://index.ros.org/doc/ros2/Tutorials/Creating-Your-First-ROS2-Package/) |
| 135 | + * [Parameters](https://index.ros.org/doc/ros2/Tutorials/Parameters/Understanding-ROS2-Parameters/) |
| 136 | + * [Workspace](https://index.ros.org/doc/ros2/Tutorials/Workspace/Creating-A-Workspace/) |
| 137 | + - [Example ROS packages](https://github.com/ros2/examples) |
| 138 | + - [Colcon Documentation](https://colcon.readthedocs.io/en/released/#) |
| 139 | + - [ROS2 Design Documentation](https://design.ros2.org/) |
| 140 | + - [ROS2 Launch Architecture](https://github.com/ros2/launch/blob/master/launch/doc/source/architecture.rst) |
0 commit comments