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
  • Install for Ubuntu
  • Install for macOS

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:

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 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 URSim container. The only modification added to it is the installation of the external-control urcaps. All this is stated in 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 package as well as other utilities for network scanning (nmap), text editing (neovim) and terminal multiplexing (tmux).

Starting the Docker containers

To start using these Docker containers together a bridge network must be established first.

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

docker build -t ursim:latest URSim

This command builds the container defined in 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

docker build -t ros2_humble:latest ROS2_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

docker run --name URSIM -it -p 6080:6080 --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 

<IP>

On another terminal run

docker run -it --name ROS --network ros_ursim -p50002-50100:50002-50100 -p5005-8000:5005-8000 -v ./workspace:/workspace 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:=<ur.controller.ip.address>

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

   source /opt/ros/humble/setup.bash
   

2. Build the Workspace

   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

workspace/
├── srcdocker run --name URSIM
├── build
├── install
└── log

4. Run the Interface

   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.

---