Setup Guide — ROS 2 (Physical AI Tools)

Overview

This guide shows how to set up and operate OMX using Physical AI Tools (Web UI). Follow the steps to prepare repositories, configure Docker, and run the teleoperation node.

INFO

System Requirements

Recommended OS	Ubuntu
Hardware requirement	NVIDIA GPU (CUDA-capable)

Software Setup

Prerequisites

• Operating System: Any Linux distribution

  • The container runs Ubuntu 24.04 + ROS 2 Jazzy
  • The Host OS version does not need to match.

• Docker Engine

  • Install using the official Docker guide

  • After installation:

    sudo usermod -aG docker $USER
    sudo systemctl enable docker
    docker run hello-world

• Git

  sudo apt install git

• NVIDIA Container Toolkit

  • Follow the official installation guide

    • Required steps:

      1. Configure the production repository
      2. Install nvidia-container-toolkit
      3. Configure Docker runtime using nvidia-ctk
      4. Restart Docker daemon

    • For detailed configuration, see the Docker configuration guide

Docker Volume Configuration

The Docker container uses volume mappings for hardware access, development, and data persistence:

volumes:
  # Hardware and system access
  - /dev:/dev
  - /tmp/.X11-unix:/tmp/.X11-unix:rw
  - /tmp/.docker.xauth:/tmp/.docker.xauth:rw

  # Development and data directories
  - ./workspace:/workspace
  - ../:/root/ros2_ws/src/open_manipulator/

TIP

Store your development code in /workspace to preserve your codes.

Set up Open Manipulator Docker Container

1. Start the Docker Container:

Clone the repository:

USER PC

git clone https://github.com/ROBOTIS-GIT/open_manipulator

Start the Open Manipulator container with the following command:

cd open_manipulator/docker && ./container.sh start

2. Set up launch file port

Enter the Open Manipulator Docker container:

USER PC

./container.sh enter

INFO

First, connect only the 'Leader' USB to the port, then check and copy the OpenRB serial ID.

USER PC or USER PC 🐋 OPEN MANIPULATOR

ls -al /dev/serial/by-id/

As shown in the image below, paste the serial ID you noted above into the port name parameter for the [leader] then save.

USER PC 🐋 OPEN MANIPULATOR

sudo nano ~/ros2_ws/src/open_manipulator/open_manipulator_bringup/launch/omx_l_leader_ai.launch.py

# omx_l_leader_ai.launch.py
DeclareLaunchArgument(
    'port_name',
    default_value='/dev/serial/by-id/{your_leader_serial_id}',
    description='Port name for hardware connection.',
)

INFO

Second, connect only the 'Follower' USB to the port, then check and copy the OpenRB serial ID.

USER PC or USER PC 🐋 OPEN MANIPULATOR

ls -al /dev/serial/by-id/

As shown in the image below, paste the serial ID you noted above into the port name parameter for the [follower], then save.

USER PC 🐋 OPEN MANIPULATOR

sudo nano ~/ros2_ws/src/open_manipulator/open_manipulator_bringup/launch/omx_f_follower_ai.launch.py

# omx_f_follower_ai.launch.py
DeclareLaunchArgument(
    'port_name',
    default_value='/dev/serial/by-id/{your_follower_serial_id}',
    description='Port name for hardware connection.',
)

INFO

Ultimately, it will be changed as shown below.

🎉 Open Manipulator Container Setup Complete!

Please exit the Docker container and return to your host terminal for the next steps.

Set up Physical AI Tools Docker Container

1. Start the Docker container

Clone the repository along with all required submodules:

USER PC

git clone --recurse-submodules https://github.com/ROBOTIS-GIT/physical_ai_tools.git

Start the Physical AI Tools Docker container with the following command:

cd physical_ai_tools/docker && ./container.sh start

2. Configure camera topics

If you are using more than one camera or want to use a custom camera, list the available camera topics and choose the one you want to use:

Enter the Physical AI Tools Docker container:

USER PC

./container.sh enter

list the available topics to find your camera stream:

USER PC

ros2 topic list

And open the configuration file and update it as described below:

USER PC 🐋 PHYSICAL AI TOOLS

sudo nano ~/ros2_ws/src/physical_ai_tools/physical_ai_server/config/omx_f_config.yaml

Then update the fields outlined in red in the UI to point to your desired camera topic.

INFO

Note: The topic you set must always end with compressed
(for example, camera1/image_raw/compressed).

🎉 Physical AI Tools Container Setup Complete!

Click the button below to start Imitation Learning.

Imitation Learning
Overview