Merge pull request #111 from YuZhong-Chen/feat/ur5_ws

UR5 Workspace (Only support physical robot)

Author: j3soon

README.md

@@ -93,6 +93,7 @@ The docker image of the template workspace is share by most of the workspace, al
 | [Unitree Go2](https://j3soon.github.io/ros2-essentials/go2-ws/) | ✔️ | ❌️ | Simulation only | [Yu-Zhong Chen](https://github.com/YuZhong-Chen), [Assume Zhan](https://github.com/Assume-Zhan), [Johnson Sun](https://github.com/j3soon) |
 | [Unitree H1](https://j3soon.github.io/ros2-essentials/h1-ws/) | ✔️ | ❌️ | Simulation only | [Johnson Sun](https://github.com/j3soon) |
 | [Hello Robot Stretch 3](https://j3soon.github.io/ros2-essentials/stretch3-ws/) | ✔️ | ❌️ | Simulation only | [@JustinShih0918](https://github.com/JustinShih0918), [Johnson Sun](https://github.com/j3soon) |
+| [Universal Robots UR5](https://j3soon.github.io/ros2-essentials/ur5-ws/) | ✔️ | ❌️ | Real-world support (CB3 only) | [Yu-Zhong Chen](https://github.com/YuZhong-Chen) |
 
 If you have trouble using a workspace, please [open an issue](https://github.com/j3soon/ros2-essentials/issues) and tag the current maintainers mentioned above.
 

docs/mkdocs.yml

@@ -230,4 +230,5 @@ nav:
     - go2-ws/index.md
     - h1-ws/index.md
     - stretch3-ws/index.md
+    - ur5-ws/index.md
   - dependencies.md

docs/ur5-ws/assets/ursim-external-control-running.png

@@ -0,0 +1,187 @@
+# Universal Robots UR5
+
+[![GitHub code](https://img.shields.io/badge/code-blue?logo=github&label=github)](https://github.com/j3soon/ros2-essentials/tree/main/ur5_ws)
+[![GitHub last commit](https://img.shields.io/github/last-commit/j3soon/ros2-essentials?path=ur5_ws)](https://github.com/j3soon/ros2-essentials/commits/main/ur5_ws)
+
+[![DockerHub image](https://img.shields.io/badge/dockerhub-j3soon/ros2--ur5--ws-important.svg?logo=docker)](https://hub.docker.com/r/j3soon/ros2-ur5-ws/tags)
+![Docker image arch](https://img.shields.io/badge/arch-amd64-blueviolet)
+![Docker image version](https://img.shields.io/docker/v/j3soon/ros2-ur5-ws)
+![Docker image size](https://img.shields.io/docker/image-size/j3soon/ros2-ur5-ws)
+
+This workspace provides a ROS 2 Humble environment for controlling **Universal Robots UR5** manipulators. It includes the official [Universal_Robots_ROS2_Driver](https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver), description packages, **OnRobot RG2** gripper support, **servo control**, and **pose tracking**.
+
+> Please note that this workspace has only been tested on the UR5 (CB3 version). In theory, it can support other models with minor configuration adjustments; please feel free to modify the settings as needed for your specific use case.
+
+## Start Container
+
+> Make sure your system meets the [system requirements](https://j3soon.github.io/ros2-essentials/#system-requirements) and have followed the [setup instructions](https://j3soon.github.io/ros2-essentials/#setup) before using this workspace.
+
+Run the following commands in a Ubuntu desktop environment. If you are using a remote server, make sure you're using a terminal within a remote desktop session (e.g., VNC) instead of SSH (i.e., don't use `ssh -X` or `ssh -Y`).
+
+```sh
+cd ~/ros2-essentials/ur5_ws/docker
+docker compose build
+xhost +local:docker
+docker compose up -d
+# The initial build will take a while, please wait patiently.
+```
+
+> If your user's UID is `1000`, you may use `docker compose pull` instead of `docker compose build`.
+
+The commands in the following sections assume that you are inside the Docker container:
+
+```sh
+# in a new terminal
+docker exec -it ros2-ur5-ws bash
+```
+
+If the initial build failed, rebuild the workspace inside the container:
+
+```sh
+cd /home/ros2-essentials/ur5_ws
+rm -rf build install
+colcon build --symlink-install
+```
+
+To stop and remove the container:
+
+```sh
+docker compose down
+```
+
+
+## Simulation with URSim (CB3)
+
+To test without hardware, run **URSim CB3** with the External Control URCap in Docker:
+
+```sh
+cd ~/ros2-essentials/ur5_ws/docker/ursim
+docker compose up
+```
+
+This starts a UR5 simulator at `192.168.56.101` (VNC on port 5900, Web on 6080). The ports 5900 and 6080 are forwarded to localhost, please change them in `docker/ursim/compose.yaml` if those ports conflict with existing services. Open <http://localhost:6080/vnc.html?host=localhost&port=6080> in your browser to access the URSim interface.
+
+> ⚠️ Important: If you plan to switch to the physical robot, you must run `docker compose down` to remove the virtual network first. Failing to do so will cause IP address conflicts.
+
+URSim provides an interface identical to the physical robot, making it ideal for rapid testing. However, please note that unlike `Gazebo` or `IsaacSim`, URSim does not possess a realistic physics engine. Therefore, it is not suitable for simulations requiring high physical fidelity.
+
+Regarding the RG2 gripper: although it is not explicitly modeled in URSim, our control script operates via Digital I/O. Consequently, there is no need to disable the gripper configuration when running URSim; the code will execute without errors.
+
+Since URSim aims to faithfully replicate the real robot's behavior, you should follow all the steps outlined in the subsequent sections, including calibration and bring-up.
+
+## Setup Robot
+
+> For URSim users, the settings are already pre-configured in the docker compose file, so you can skip this step.
+
+Please refer to the [official installation](https://docs.universal-robots.com/Universal_Robots_ROS2_Documentation/doc/ur_client_library/doc/setup/robot_setup.html) guide. If the robot has been configured previously, you can typically skip this step.
+
+For network setup, please refer to [this section](https://docs.universal-robots.com/Universal_Robots_ROS2_Documentation/doc/ur_client_library/doc/setup/network_setup.html) for network configuration.
+
+## Robot Calibration
+
+To improve accuracy, run the calibration correction and save the result to the workspace description config:
+
+```sh
+cd /home/ros2-essentials/ur5_ws
+./scripts/ur5_calibration.sh
+```
+
+You only need to run this once for each robot. This creates `default_kinematics.yaml` which is required for the subsequent steps.
+
+## Bring Up Robot
+
+Use the script:
+
+```sh
+cd /home/ros2-essentials/ur5_ws
+./scripts/ur5_bringup.sh
+```
+
+Or run the launch file directly:
+
+```sh
+ros2 launch ur_robot_driver ur_control.launch.py \
+    ur_type:=ur5 \
+    use_rg2_gripper:=true \
+    robot_ip:=192.168.56.101 \
+    launch_rviz:=true
+```
+
+> Set `use_rg2_gripper` parameter to **false** to disable the RG2 gripper.
+
+Quick test for gripper actuation:
+
+```sh
+# true = open, false = close
+ros2 topic pub --once /rg2/command std_msgs/msg/Bool "{data: true}"
+```
+
+After bringing up the robot, make sure to click `Play` in the UR interface to start the control loop.
+
+In the UR interface, go to `Home > Program Robot > Empty Program > Program > Structure > URCaps > External Control` and then click the Play button.
+
+![](assets/ursim-external-control-running.png)
+
+The UR interface control program will automatically stop if the ROS2 bring up node is stopped or crashes for safety reasons. If that happens, simply restart the bring up node and click `Play` again.
+
+## Launch MoveIt 2
+
+Launch MoveIt 2 for a quick test. You can move the arm by dragging the end-effector (EE) to a target position in RViz2, then clicking `Plan & Execute`.
+
+```sh
+ros2 launch ur_moveit_config ur_moveit.launch.py \
+    launch_rviz:=true \
+    use_rg2_gripper:=true
+```
+
+> Ensure the robot driver is already running before testing.
+
+## Servo Control
+
+The **ur_servo_control** package provides a simple example for controlling end-effector (EE) velocity. Please ensure the robot driver is launched before testing.
+
+```sh
+ros2 launch ur_servo_control ur_servo.launch.py
+```
+
+You can control the robot arm by publishing target velocities to the `/servo_node/delta_twist_cmds` topic.
+
+For an implementation example within a ros node, refer to `ur5_ws/src/ur_servo_control/ur_servo_control/ur_servo_control.py`. Please be careful when selecting the reference frame. Use the following command to launch it:
+
+```sh
+ros2 launch ur_servo_control ur_servo_control.launch.py
+```
+
+The default velocities above are set to 0, you can modify the linear/angular velocities (`twist_msg.twist.{linear|angular}.{x|y|z}`) in `publish_servo_command_callback` in `ur5_ws/src/ur_servo_control/ur_servo_control/ur_servo_control.py`. But note that a constant velocity command will cause the robot to keep moving, which may be dangerous for real robot control (but fine for URSim testing).
+
+## Pose Tracking
+
+The **ur_pose_tracking** package provides an interface for controlling the end-effector (EE) position.
+
+```sh
+# In terminal 1 (Launch the servo node):
+ros2 launch ur_servo_control ur_servo.launch.py
+# In terminal 2:
+ros2 launch ur_pose_tracking ur_pose_tracking.launch.py
+```
+
+You can control the robot arm by publishing target pose to the `/target_pose` topic.
+
+For application integration, it is recommended to refer to the **servo control implementation within the ros node**. To perform a quick test, please use the following command:
+
+```sh
+ros2 topic pub --once /target_pose geometry_msgs/msg/PoseStamped "{header: {frame_id: 'world', stamp: {sec: 0, nanosec: 0}}, pose: {position: {x: -0.3, y: 0.0, z: 0.5}, orientation: {x: -0.35, y: 0.01, z: 0.93, w: -0.05}}}"
+```
+
+> Note: This implementation does not account for singularities or collision avoidance and only supports linear paths between points. Consequently, it is ideal for high-density trajectory points. If your input points are sparse or require complex path planning and obstacle avoidance, please use the MoveIt planner instead.
+
+## Troubleshooting
+
+If you encounter issues on reproducing the examples above, consider remove all containers (`docker compose down` for URSim and workspace) and try again.
+
+## References
+
+- [Universal Robots ROS 2 Documentation](https://docs.universal-robots.com/Universal_Robots_ROS2_Documentation/)
+  - [Robot Setup](https://docs.universal-robots.com/Universal_Robots_ROS2_Documentation/doc/ur_client_library/doc/setup/robot_setup.html)
+  - [Setup URSim with Docker](https://docs.universal-robots.com/Universal_Robots_ROS2_Documentation/doc/ur_client_library/doc/setup/ursim_docker.html)
+- [Universal_Robots_ROS2_Driver](https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver)

docs/ur5-ws/index.md

@@ -35,13 +35,13 @@ services:
         # TODO: Set the USER_UID
         USER_UID: "${USER_UID:-1000}"
         # TODO: Set CUDA Toolkit version or set to "" if not using CUDA Toolkit
-        # CUDA_TOOLKIT_VERSION: ""
+        {PLACEHOLDER_#}CUDA_TOOLKIT_VERSION: "{PLACEHOLDER}"
         # TODO: Set Isaac Sim version or set to "" if not using Isaac Sim
-        # ISAAC_SIM_VERSION: "5.0.0"
+        {PLACEHOLDER_#}ISAAC_SIM_VERSION: "{PLACEHOLDER}"
         # TODO: Set Isaac Lab version or set to "" if not using Isaac Lab
-        # ISAAC_LAB_VERSION: "2.3.2"
+        {PLACEHOLDER_#}ISAAC_LAB_VERSION: "{PLACEHOLDER}"
         # TODO: Set to "YES" if using Isaac ROS or set to "" if not using Isaac ROS
-        # ISAAC_ROS: ""
+        {PLACEHOLDER_#}ISAAC_ROS: "{PLACEHOLDER}"
         # TODO: Set to "YES" if using Cartographer or set to "" if not using Cartographer
         {PLACEHOLDER_#}CARTOGRAPHER: "{PLACEHOLDER}"
         # TODO: Set to "YES" if using RTAB-Map or set to "" if not using RTAB-Map

tests/diff_base/docker/compose.yaml

@@ -0,0 +1,14 @@
+#!/bin/bash -e
+
+# Get the directory of this script.
+# Reference: https://stackoverflow.com/q/59895
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd)"
+DOCKER_DIR="${SCRIPT_DIR}/../docker"
+
+# Normally, USER_UID is set during repo setup and works fine with the Docker CLI. 
+# We need to manually write to .env because some devcontainer versions do not source ~/.bashrc,
+# leaving the environment variables undeclared.
+touch "${DOCKER_DIR}/.env"
+awk '!/^USER_UID=/' "${DOCKER_DIR}/.env" > "${DOCKER_DIR}/.env.tmp"
+echo "USER_UID=$(id -u)" >> "${DOCKER_DIR}/.env.tmp"
+mv "${DOCKER_DIR}/.env.tmp" "${DOCKER_DIR}/.env"

ur5_ws/.devcontainer/create_env.sh

@@ -0,0 +1,25 @@
+/* Reference: https://aka.ms/devcontainer.json */
+{
+    "name": "TODO",
+    "dockerComposeFile": "../docker/compose.yaml",
+    "service": "ur5-ws",
+    // Set the USER_UID
+    "initializeCommand": "\"${localWorkspaceFolder}\"/.devcontainer/create_env.sh",
+    // Workspace settings
+    "workspaceFolder": "/home/ros2-essentials/ur5_ws",
+    // Vscode extensions
+    "customizations": {
+        "vscode": {
+            "extensions": [
+                "ms-vscode.cpptools",
+                "ms-vscode.cpptools-themes",
+                "twxs.cmake",
+                "leojhonsong.python-extension-pack",
+                "eamodio.gitlens",
+                "mhutchie.git-graph",
+                "streetsidesoftware.code-spell-checker",
+                "ranch-hand-robotics.rde-pack"
+            ]
+        }
+    }
+}

ur5_ws/.devcontainer/devcontainer.json

@@ -0,0 +1,13 @@
+# Visual Studio Code
+.vscode
+
+# ROS2 basic directories
+/build
+/install
+/log
+
+# Hard Links
+/docker/modules
+
+# Docker environment variables
+/docker/.env

ur5_ws/.gitignore

@@ -0,0 +1,3 @@
+# ROS 2 Essentials Workspace
+
+Please visit <https://j3soon.github.io/ros2-essentials/> for documentation.

ur5_ws/README.md

@@ -0,0 +1,49 @@
+# Setup paths in `~/.profile` to allow unified environment variable across login/non-login shells
+# set PATH so it includes user's private bin if it exists
+if [ -d "$HOME/bin" ] ; then
+    PATH="$HOME/bin:$PATH"
+fi
+# set PATH so it includes user's private bin if it exists
+if [ -d "$HOME/.local/bin" ] ; then
+    PATH="$HOME/.local/bin:$PATH"
+fi
+
+# Source global ROS2 environment
+source /opt/ros/$ROS_DISTRO/setup.bash
+# Source colcon-argcomplete
+source /usr/share/colcon_argcomplete/hook/colcon-argcomplete.bash
+# Optionally perform apt update if it has not been executed yet
+if [ -z "$( ls -A '/var/lib/apt/lists' )" ]; then
+    echo "apt-get update has not been executed yet. Running sudo apt-get update..."
+    sudo apt-get update
+fi
+# Optionally perform rosdep update if it has not been executed yet
+if [ ! -d $HOME/.ros/rosdep/sources.cache ]; then
+    echo "rosdep update has not been executed yet. Running rosdep update..."
+    rosdep update --rosdistro $ROS_DISTRO
+    cd $ROS2_WS
+    # Ref: https://docs.ros.org/en/humble/Tutorials/Intermediate/Rosdep.html
+    rosdep install --from-paths src --ignore-src -y -r
+fi
+# Optionally build the workspace if it has not been built yet
+if [ ! -f $ROS2_WS/install/setup.bash ]; then
+    echo "Workspace has not been built yet. Building workspace..."
+    cd $ROS2_WS
+    # TODO: If command `arch` outputs `aarch64`, consider adding `--packages-ignore <package>` to ignore x86 packages
+    # Ref: https://docs.ros.org/en/humble/Tutorials/Beginner-Client-Libraries/Creating-Your-First-ROS2-Package.html
+    if [ $(arch) == "aarch64" ]; then
+        colcon build --symlink-install
+    else
+        colcon build --symlink-install
+    fi
+    echo "Workspace built."
+fi
+# Source gazebo environment
+# Ref: https://classic.gazebosim.org/tutorials?tut=ros2_installing&cat=connect_ros#InstallGazebo
+if [ $(arch) == "x86_64" ]; then
+  source /usr/share/gazebo/setup.bash
+fi
+# TODO: Source other workspace environments as underlay
+# Source workspace environment
+source $ROS2_WS/install/setup.bash
+echo "Successfully built workspace and configured environment variables."