154 lines
4.5 KiB
Markdown
154 lines
4.5 KiB
Markdown
|
||
# 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.
|