# OSC–ROS 2 Interface ## Description This repository provides an interface that connects OSC with ROS 2. It allows controlling robotic manipulators using OSC messages. --- ## Prerequisites Either: - **Operating System:** Ubuntu 22.04 recommended with ROS 2 installed - **Docker:** Ensure Docker and Docker CLI are installed and running - [Install for Windows](https://docs.docker.com/desktop/setup/install/windows-install/) - [Install for Ubuntu](https://docs.docker.com/engine/install/ubuntu/) - [Install for macOS](https://docs.docker.com/desktop/setup/install/mac-install/) Windows users: run `winget install Docker.DockerCli` to install the Docker CLI. --- ## Using Docker for ROS 2 and URSim ### Verify Docker Installation Run the test container: ```bash docker run --rm hello-world ``` In this repository there are three folders, two of them are Docker containers. The first Docker container to be installed will be the [`URSim`](./URSim) Docker container. A Docker container consists of a file describing what the operating system of the Docker container looks like (and from which Docker container it is derived). Our URSim Docker container is derived from the latest [`e-series`](https://hub.docker.com/r/universalrobots/ursim_e-series) URSim container. The only modification added to it is the installation of the [`external-control`](https://github.com/UniversalRobots/Universal_Robots_ExternalControl_URCap) urcaps. All this is stated in [`URSim/Dockerfile`](./URSim/Dockerfile). The second Docker container in this repository is the [`ROS 2_Humble`](./ROS 2_Humble) container. From its name it contains the ROS 2 operating system and environment. Its [`Dockerfile`](./ROS 2_Humble/Dockerfile) is also relatively simple. It iterates over the [`ros-humble-desktop-full`](https://github.com/UniversalRobots/Universal_Robots_ROS 2_Driver) container by installing the [`ros-humble-ur`](https://hub.docker.com/r/osrf/ros/tags?name=humble-desktop-full) package as well as other utilities for network scanning ([`nmap`](https://nmap.org/)), text editing ([`neovim`](https://neovim.io/)) and terminal multiplexing ([`tmux`](https://github.com/tmux/tmux/wiki)). # Starting the Docker containers To start using these Docker containers together a bridge network must be established first. ```bash docker network create ros_ursim ``` This command created the bridge network with the name `ros_ursim`. This name can be then used with the `--network` flag when running a container to include that container within this network. Now the URSim container can be built using the follwoing command ```bash docker build -t ursim:latest URSim ``` This command builds the container defined in [`URSim/Dockerfile`](./URSim/Dockerfile) with the `ursim:latest` tag, so that we can easily run it later. The same can be done for the ROS 2_Humble container ```bash docker build -t ros2_humble:latest ROS 2_Humble ``` After all the containers are successfully built and the bridge network is established we can now start both containers. On one terminal run the following command to start the URSim container ```bash docker run -it --name URSIM -p 6080:6080 -p50002:50002 --network ros_ursim ursim:latest ``` When successfully started this container will print its IP address in the terminal. Note this down: ``` IP address of the simulator ``` On another terminal run ``` docker run -it --name ROS --network ros_ursim -p50002:50002 -p8000:8000 -p7000:7000 -p5005:5005 ros2_humble:latest ``` Also note the IP address, using `hostname` ``` hostname -I ``` With both containers running we can now open the URSim interface on any browser by going to this address: ``` http://localhost:6080/vnc.html ``` It should now open the `VNC` interface with a big `connect` button. Press the connect button and you should be able to see the UR10e teachpendant interface. Add a payload of 0.5 kg and start the robot. Now we must enable ROS 2 to control this. Go to `New...`>`Program` to create a new program for the robot. Within this program, click on `URCaps`>`External Control` to allow control from outside the simulation. Under `Installation`>`URCaps`>`External Control`, input the IP address of the ROS 2 container and give it a name (ROS perhaps). Save this program so you don't have to repeat these steps, but don't run it yet as we have not initiated ROS 2 communication. In the ROS 2 container, source the ROS 2 environment. ``` source /opt/ros/humble/setup.bash ``` Next, launch the driver for communication with the UR simulation, with the IP address of the UR container ``` ros2 launch ur_robot_driver ur10e.launch.py robot_ip:= ``` Now, from the VNC interface, we can start the external control program by clicking on the play button in the bottom right of the screen. To run other ROS 2 programs to send commands to the UR10e, we must use a third terminal and access the ROS 2 container again. First we must find the container ID of our ROS 2 container. ``` docker ps ``` Use the appropriate container ID to launch bash within that container. We need the container ID of the ros2_humble container. ``` docker exec -it ROS /bin/bash ``` Once inside, we again must source the ROS 2 environment ``` source /opt/ros/humble/setup.bash ``` Finally, we can run ROS 2 scripts to control the robot. For example ``` ros2 launch ur_robot_driver test_scaled_joint_trajectory_controller.launch.py ``` If everything worked, this should either move the robot or complain about it being in a strange position. --- ## Installation Instructions for the Interface 1. **Source ROS 2** ```bash source /opt/ros/humble/setup.bash ``` 2. **Build the Workspace** ```bash cd workspace colcon build source install/setup.bash ``` Now you should find three new folders in your directory: log, build and install. You can check with `ls` ```bash workspace/ ├── src ├── build ├── install └── log ``` 4. **Run the Interface** ```bash ros2 run osc_ros2 interface ``` --- ## Interface Setup The script will guide you through the setup: - **URDF File**: Choose whether to load a URDF to enable kinematics. - **Cost Mask**: Let the interface know which coordinates you want to control. - **Topic Name**: On which topic is your robot listening for JointTrajectories? - **Log/State IP & Ports**: Enter where logs and joint state OSC messages should be sent. - **Command Port**: Set the port to listen for incoming OSC commands. - **Limits**: Define workspace limits (x/y/z) and joint limits if desired. - **Refresh Rate**: Choose how often the interface updates (Hz). ### URDF File You will be asked whether you want to use an URDF. Most commertial robots come with an URDF but if you don't have a URDF you can enter `n`. If you have a URDF enter the path to it. This way he interface can find and use it. If you are using the simulation of the ur10e you can use the URDF file for the ur10e in this repository. The robot strucute will now be printent out in the terminl. You can check if this is the correct robot. Some of the following options will only be asked if you did enter a URDF. You can skip them if you did't. ### Cost Mask (only with URDF) Here you can bestimmen which coordinates of your commands will be used to move the robot. Since a robot with two joints can only follow two coordinates you can use a maximum of two coordinates. For each coordinate you wan tto use enter a `1`, for the coordinates you dont want to use enter a `0`. ## Topic Name for JointTrajectories Enter to which topic name to which the interface should send the trajectories. On this topic your robot sould be listening for JointTrajectory messages. Otherwise the trajectories will go nowhere. The default is `/scaled_joint_trajectory_controller/joint_trajectory` which works for the ur10e. ## Log/State IP & Ports Enter the IP addresses and port on which you want to recieve the logs and joint states as OSC messages. The default IP adress it `127.0.0.1` which is the localhost, so the system you're running this interface on. ## Command Port Next enter the port on which the interface should listen for your OSC messages. ## Limits (x,y,z only with URDF) The interace asks for workspace and end-effector limits only if a URDF was provided. For each coordinate you can set lower and upper limits. If you don't want to set a limit eter a `x`. The robot will not be constrained in this coordinates direction. A coommon limit is to set the lower z limit to 0 such that the manipulator does not move into the floor. Now you can also add joint limits. If you have a URDF provided the current joint limits will be shown. You can enter new joint limits if you want. For the ur10e at the Ligeti Center it is helpfull to set the joint limits of ## Refresh Rate Enter the refreshrate. This is the rate at which the interface will check for new OSC commands and executes them. --- # Usage ## Supported OSC Commands | Address | Data Format | Description | |-------------------------------|-----------------------------------------------------------|----------------------------------------| | `/joint_positions` | `[q1, ..., qN]` or `[q1, ..., qN, duration]` | Move all joints | | `/joint_position/{joint}` | `q1` or `[q1, duration]` | Set one joint only | | `/tcp_coordinates` | `[x, y, z, roll, pitch, yaw]` or with duration | Move to Cartesian pose | | `/joint_trajectory` | `[[q1,...], [q2,...], ...]` | Follow a joint-space trajectory | | `/cartesian_trajectory` | `[[x1,...], [x2,...], ...]` | Follow a Cartesian-space trajectory | | `/speed_scaling` | `float` (e.g., 0.5 -> 50% of max speed) | Adjust execution speed | --- ## Example Usage An example patch in PureData is provided (`/workspace/src/6_DOF_example.pd`) that allows control of a 6-DOF robot with sliders via OSC. --- [^1]: [What is Docker?](https://docs.docker.com/get-started/) [^2]: [WSL2 & Docker Networking](https://stackoverflow.com/questions/65426891) [^3]: [Cisco VPN and WSL2](https://github.com/Microsoft/WSL/issues/4277)