OSC_ROS2/README.md

OSC–ROS 2 Interface

Description

This repository provides an interface that connects OSC with ROS 2. It allows coltroling 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

Build Containers

1. URSim Container
   This builds a simulator with the UR External Control URCap installed:

   docker build -t ursim:latest URSim
   

2. ROS 2 Humble Container
   Includes ROS 2, Universal Robots drivers, and developer tools:

   docker build -t ros2_humble:latest ROS2_humble
   

Create a Docker Bridge Network

docker network create ros_ursim

Run Both Containers

• URSim:

  docker run -it --rm -e ROBOT_MODEL=UR10 -p 6080:6080 --network ros_ursim ursim:latest
  

• ROS 2 Humble:

  docker run -it --rm --network ros_ursim -p 8000:8000/udp ros2_humble:latest
  

Open the simulator in your browser:

http://localhost:6080/vnc.html

---

Connecting to Simulation

Launch the robot driver (replace x with correct IP):

ros2 launch ur_robot_driver ur_control.launch.py ur_type:=ur10e robot_ip:=172.18.0.x

Use hostname -i inside each container to retrieve IPs.

On the teach pendant or URSim, set the ROS 2 container’s IP in the External Control URCap.

---

Check Connection

You can test if data is flowing correctly with:

ros2 topic echo /joint_states

---

Installation Instructions for the Interface

1. Source ROS 2

   source /opt/ros/humble/setup.bash
   

2. Install Required Python Libraries

   pip install numpy==1.23.5 scipy==1.10.1 matplotlib==3.6.3 spatialmath-python==1.0.0 roboticstoolbox-python==1.0.1
   

3. Clone and Build the Workspace

   git clone <this_repo>
   cd workspace
   colcon build
   source install/setup.bash
   

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, joint limits, etc.
• 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).

---

Supported OSC Commands

Address	Data Format	Description
/joint_positions	[q1, ..., qN] or [q1, ..., qN, duration]	Move all joints
/joint_positions/{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 that allows the user to control a 6-DOF robot with sliders via OSC.

---