# 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](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
```

### Build Containers

1. **URSim Container**  
   This builds a simulator with the UR External Control URCap installed:
   ```bash
   docker build -t ursim:latest URSim
   ```

2. **ROS 2 Humble Container**  
   Includes ROS 2, Universal Robots drivers, and developer tools:
   ```bash
   docker build -t ros2_humble:latest ROS2_humble
   ```

### Create a Docker Bridge Network
```bash
docker network create ros_ursim
```

### Run Both Containers

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

- ROS 2 Humble:
  ```bash
  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):
```bash
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:
```bash
ros2 topic echo /joint_states
```

---
## Installation Instructions for the Interface

1. **Source ROS 2**
   ```bash
   source /opt/ros/humble/setup.bash
   ```

2. **Install Required Python Libraries**
   ```bash
   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**
   ```bash
   git clone <this_repo>
   cd workspace
   colcon build
   source install/setup.bash
   ```

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, 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.

---

[^1]: [What is Docker?](https://docs.docker.com/get-started/)
[^2]: [WSL2 & Docker Networking](https://stackoverflow.com/questions/65426891)
[^3]: [USB Device in Docker](https://stackoverflow.com/questions/46467295)
[^4]: [Cisco VPN and WSL2](https://github.com/Microsoft/WSL/issues/4277)
[^5]: macOS is not tested—use Linux or Windows for reliability.