246 lines
10 KiB
Markdown
246 lines
10 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
|
||
```
|
||
|
||
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 installtion 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 [`ROS2_humble`](./ROS2_humble) container. From its name it contains the ROS2 operating system and environment. Its [`Dockerfile`](./ROS2_humble/Dockerfile) is also relatively simple. It iterates over the [`ros-humble-desktop-full`](https://github.com/UniversalRobots/Universal_Robots_ROS2_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)).
|
||
|
||
# Usage
|
||
|
||
To start using these docker containers together a bridge network must be established first.
|
||
|
||
```bash
|
||
docker network create ros_ursim # The name of the network is `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 ROS2_humble container
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
docker run -it --rm -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 --rm --network ros_ursim 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 ROS2 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 ROS2 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 ROS2 communication.
|
||
|
||
In the ROS2 container, source the ROS2 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 ur_control.launch.py ur_type:=ur10e 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 ROS2 programs to send commands to the UR10e, we must use a third terminal and access the ROS2 container again. First we must find the container ID of our ROS2 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 <container_id> /bin/bash
|
||
```
|
||
|
||
Once inside, we again must source the ROS2 environment
|
||
```
|
||
source /opt/ros/humble/setup.bash
|
||
```
|
||
|
||
Finally, we can run ROS2 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. **Install Required Python Libraries**
|
||
```bash
|
||
pip install numpy==1.22.4 scipy==1.7.3 spatialmath-python==1.1.14 roboticstoolbox-python==1.1.1 osc4py3
|
||
```
|
||
if an error occurs during installation run:
|
||
```bash
|
||
python3 -m pip install --upgrade pip setuptools wheel
|
||
```
|
||
and try again.
|
||
|
||
If you don't have pip installed run
|
||
|
||
```bash
|
||
sudo apt update
|
||
sudo apt install python3-pip
|
||
```
|
||
|
||
3. **Clone and Build the Workspace**
|
||
```bash
|
||
git clone <this_repo>
|
||
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
|
||
|
||
|
||
---
|
||
|
||
## 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) |